Users

Purpose¶

Platform 6 user (P6User) enquiry and update.

A collection of methods to list and maintain the users of your Platform 6 instance

A read-only P6User object has the following structure:

Type	Name
String	email
String	firstName
String	lastName
String	jsonProfile
Map[String:String]	properties
List[P6PermissionSet]	permissionSetDetails

The read-only P6PermissionSet object has the following structure:

Type	Name
String	name
String	description
List[String]	permissions

User.AssociationType is an enumeration with the following values:

USER
UNIT
BRANCH
SIBLINGS

Additional Instance Permissions¶

In order for your Platform 6 instance to access the centralized user repository of P6Auth, your Platform 6 Integration definition will require additional permissions.

The required permissions for each method are listed below.

Methods¶

Binding name: p6.users

Tip

Easy P6USer creation using the tap() method and showing the JSON String format of this object

def user = new P6User().tap {
    email = 'usr@server.com'
    firstName = 'Firstname'
}

user['lastName'] = 'Lastname'

println user

associate¶

Required permissions

[instance]:users=edit

Associates the given user email with your instance.

Syntax

P6User p6.users.associate(String userEmail, List[String] assignedPermissionSetNames, String orgTreePath)

This will send an account activation email to the user allowing them to select a password and login.

The assignedPermissionSetNames will be used to assign an initial set of permissions for the associated used and your instance.

The optional orgTreePath argument allows the newly associated user to be automatically assigned to the given path in the instances organisational tree.

Note

If using the ‘DEV’ infrastructure you must modify the resource property as follows: email.setpassword.url: “https://dev.portal.amalto.com/#/set-password” Otherwise a new user following the activation email link will fail to set an initial password

Example

Associating a new user with your instance and assigning them the InvoiceApprover permission

p6.users.associate('user@server.com',['InvoiceApprover'])

p6.users.associate('user@server.com',['InvoiceApprover'], '/server/path/to')

associate¶

Required permissions

[instance]:users=edit

Associates the given new user email with your instance.

Syntax

P6User p6.users.associate(String userEmail, String ssoConnectionId)

This will create a new user with the given email address as though they were created by an auto-provisioning Single Sign On

Example

p6.users.associate('user@server.com', 'ssoConnectionId')

disassociate¶

Required permissions

[instance]:users=edit

Disassociate the given user email from your instance.

Syntax

P6User p6.users.disassociate(String userEmail)

Note

If the user is not associated with any other instance following this action, the User is deleted from the central repository.

Example

Disassociate a given user printing their details when complete

println 'Disassociated user: ' + p6.users.disassociate('user@server.com')

remove¶

Required permissions

*:users=delete

Remove the given user email

Syntax

P6User p6.users.remove(String userEmail)

Warning

This requires a super admin level permission as the given user may be associated with other Platform 6 instances other than your own! Consider using disassociate instead.

Example

p6.users.remove("user@server.com")

exists¶

Required permissions

[instance]:users=read("./*")

Checks if the given user email is associated with your instance.

Syntax

boolean p6.users.exists(String userEmail)

Example

if (p6.users.exists("user@server.com")) {
    // todo
}

get¶

Required permissions

[instance]:users=read("./*")

Gets the P6User associated with your instance given the user’s email address.

Syntax

P6User p6.users.get(String userEmail)

Example

println p6.users.get("user@server.com")

getOrgPaths¶

Required permissions

[instance]:users=read("./*") and [instance]:orgs=read

Gets the organisational tree path(s) assigned to the given userEmail.

Syntax

List<String> p6.users.getOrgPaths(String userEmail, P6User.AssociationType type)

Example

Gets the org paths representing the positions they hold within the organisational tree and all positions in the tree branches beneath

def userEmail = 'user@server.com'
def lstPaths = p6.users.getOrgPaths(userEmail, P6User.AssociationType.BRANCH)

getAll¶

Required permissions

[instance]:users=read("./*")

Lists all the users associated with your instance.

Syntax

List<P6User> getAll()

Example

def lstUsers = p6.users.getAll()
lstUsers.each {
    println "User: $it"
}

updatePermissions¶

Required permissions

[instance]:users=edit

The permissions supplied via assignedPermissionSetNames will be used to replace all permissions the given user email has for your instance.

Syntax

P6User p6.users.updatePermissions(String userEmail, List[String] assignedPermissionSetNames)

Example

p6.users.updatePermissions('user@server.com', ['ApproverDelegate', 'InvoiceApprover'])

updateProfile¶

Required permissions

*:users=edit

Update the profile of the given user email

Syntax

P6User p6.users.updateProfile(
    String userEmail,
    String firstName,
    String lastName,
    String jsonProfile,
    Properties properties
)

Warning

This requires a super admin level permission as the given user may be associated with other Platform 6 instances other than your own!

Example

p6.users.updateProfile('user@server.com', 'Firstname','Lastname', null, ['title':'Mr', 'city':'Exeter', 'random': 'anything!'])

generateIdentityTokens¶

Required permissions

[instance]:identitytoken=build

Generates one or more identity tokens from the given idTokens list.

Syntax

void p6.users.generateIdentityTokens(
    boolean identitiesMustExist,
    int ttlHours,
    List<Tuple2<String, Map<String, String>>> idClaims,
    Closure<Boolean> identityNotify
)

The results are delivered via the identityNotify closure which must return true to continue.

Set identitiesMustExist to validate the user is associated with this instance via P6 Auth
Set ttlHours to a value that the generated tokens will be valid for

Note

Identity tokens are typically used as a query parameter within a magic link that can be sent to a user via email

Warning

The optional claims (passed as a Map)that will be encoded within the generated identity token cannot exceed 512 characters in length and there is a limit of 16 claims per identity

Example

Generate tokens for two users with TTL of 1 hour and send them HTML email with embedded magic link

// Note: The claims `customernumber` and `accountref` will be available to the identity receiver (REST route for example)

def ids = [
        new Tuple2('user1@server.com', [customernumber:'093459273472345-987',accountref:'AJH9876']),
        new Tuple2('user2@server.com', [customernumber:'093459273472345-985',accountref:'AJB9846'])
]

p6.users.generateIdentityTokens(false, 1, ids) { identity, token ->
    def html = p6.fm.process(p6.resource.get("email-template"), [name:'Lastname', token:token])
    p6.email.sendHtmlEmail('user@server.com', identity, html, [subject:'Message From Platform6'])
}

DSL via HTTP Endpoints¶

The Users DSL functions are also available via a pre-built set of HTTP endpoints that can be inspected with Swagger:

Users Endpoints