Skip to content

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

Method: P6User associate(String userEmail, List[String] assignedPermissionSetNames, String orgTreePath)

Associates the given user email with your instance. 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.

Required permissions: [instance]:users=edit

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

Method: P6User associate(String userEmail, String ssoConnectionId)

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

Required permissions: [instance]:users=edit

Method: P6User disassociate(String userEmail)

Disassociate the given user email from your instance.

Note

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

Required permissions: [instance]:users=edit

Method: P6User 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.

Required permissions: *:users=delete

Method: boolean exists(String userEmail)

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

Required permissions: [instance]:users=read(“./*”)

Method: P6User get(String userEmail)

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

Required permissions: [instance]:users=read(“./*”)

Method: List<String> getOrgPaths(String userEmail, P6User.AssociationType type)

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

Required permissions: [instance]:users=read(“./*”) and [instance]:orgs=read

Method: List<P6User> getAll()

Lists all the users associated with your instance.

Required permissions: [instance]:users=read(“./*”)

Method: P6User updatePermissions(String userEmail, List[String] assignedPermissionSetNames)

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

Required permissions: [instance]:users=edit

Method: P6User updateProfile(String userEmail, String firstName, String lastName, String jsonProfile, Properties properties)

Required permissions: *:users=edit

Warning

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

Method: void generateIdentityTokens(boolean identitiesMustExist, int ttlHours, List<Tuple2<String, Map<String, String>>> idClaims, Closure<Boolean> identityNotify)

Generates one or more identity tokens from the given idTokens list. 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

Required permissions: [instance]:identitytoken=build

Examples

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

def user = new P6User().tap {
    email = 'simon.temple+test1@amalto.com'
    firstName = 'Simon'
}

user['lastName'] = 'Temple'

println user

// Listing all P6Users

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

// Test a user exists before reading their details
def userEmail = 'simon.temple+test1@amalto.com'
if (p6.users.exists(userEmail)) {
    println p6.users.get(userEmail)
}

// Gets the org paths representing the positions they hold within the organisational tree and all positions in the tree branches beneath
def userEmail = 'simon.temple+test1@amalto.com'
def lstPaths = p6.users.getOrgPaths(userEmail, P6User.AssociationType.BRANCH)

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

p6.users.associate('simon.temple+dsl@amalto.com',['InvoiceApprover'])

// Disassociate a given user printing their details when complete

println 'Disassociated user: ' + p6.users.disassociate('simon.temple+dsl@amalto.com')

// Update the profile and permissions for user simon.temple

println 'Updated user permissions: ' + p6.users.updatePermissions('simon.temple@amalto.com', ['ApproverDelegate', 'InvoiceApprover'])

println 'Updated user profile: ' + p6.users.updateProfile('simon.temple@amalto.com', 'Simon','Temple', null, ['title':'Mr', 'city':'Exeter', 'random': 'anything!'])

// 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('simon.temple@sidetrade.com', [customernumber:'093459273472345-987',accountref:'AJH9876']),
        new Tuple2('stemple@sidetrade.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:'Simon', token:token])
    p6.email.sendHtmlEmail('simon.temple@amalto.com', identity, html, [subject:'Message From Platform6'])
}

Users 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