Permission Integrations

Introduction

Permission integrations can be split into two types - the Add/Remove type and the List type.

Add/Remove Permission Integrations

There maybe situations where maintaining the list of users per group is required to be managed by users who do not have full permission to access the Permission Manager - eg Head of team/department etc.  Using the APIs available below it would be possible to create a form which checks which users are assigned to a group - adds new users to a group and removes users from a group.  Using this functionality can empower teams to maintain their own groups of users, ensuring they are up to date, or be included as part of an internal starters and leavers process.

• List Users - replicates Permission manager to return a list of all Users
• List Users (for assignment) 
• List Users by Search - returns a list of users according to a specified search term
• List Groups - replicates Permission manager to return a list of User Groups
• List Users in Groups - enable a list of users for an existing defined group to be created (eg all users for Parking etc)

  • This is limited to 200 returns.

• List Groups for User - replicates Permission manager to return a list of all Groups for a given User by email (useful for permission audits) 
• Add User to Groups - adding a new user to an existing Group
• Remove User From Groups - removing a user from an existing group
• Is User in Groups - checks if user is in a group to use it in display and route conditions. Works just in integration v2

Token used

• List Users, List Users(for Assignment), List Users By Search and List Users In Groups will populate: Email, Name, ID, UCRN
• List Groups and List Groups For Users will populate: Name, ID
• Add User To Groups and Remove User From Groups won't populate any token.
• is User in Groups will populate by default the field  is_in_group but there is an option to change it with the Default token option.

Note: When using Add User To Groups and Remove User From Groups the integrations will prompt you to enter the User Email and the User Groups from which you would like to add or remove the user. You may use tokens here for the User Email field of this integration as passed from a form, ie a form could create a list of users, and then the selected user could be removed from a group.

Once you have created this integration by pressing submit, you then need to add the integration to the stage of the process. The integration will run on submission.

List Permission Integrations

You can use List type permission integrations and apply them as lookups to select fields in a form in order that the select field display a list of users or groups. They can also be employed to complete a given task, for example to assign the next stage of a process using a select field in a form. 

1. List Users, List Users by Search and List Groups integrations when added as a lookup to a select field will give you a list of users or groups for your domain.
This can be used to select an officer for the next stage - or to identify the email of the officer etc in order to send an email
 

can be used in a form to provide a list of available users which can then pull through further information to be used in the form, by having an input field of {search}
 

Note: List Users will return a maximum of 1000 users
 

2. List Users in Groups and List Groups for User when selected during the making of the integration will prompt you to enter User Groups or User Emails respectively. Using tokens here may be useful particular when using a List Groups for User integration. You must also apply this to a select field as a lookup. 

In the above example the group is defined within the permission integration and when used as a look up on the form it will produce a list of users in this group if the lookup is assigned to a field called {stage1user}, then you can use this integration to populate a hidden field {stage1user:Email} and use this email address as required in the process

3. List Users by Search can be added as a lookup to a select field to return a set of users based on a search parameter. To set this up, follow these steps:

• Create a new permissions integration set to List Users by Search

• In the 'User search' field, enter the token of the field you wish to be used as the search parameter

• In the form, add a select field with the list source set to 'lookup' and select the integration you just created,

• Add a text field with the data name of the token you defined in the 'User search' field

• When filling out the form, entering a search term will populate the select field with the list of users that match the search term entered (note: there is a limit of 10 users that will be displayed in the results; users that are only members of the 'All Authenticated Users' group will not display) 

• You can also retrieve the Email, Name, UCRN and ID of the user selected

List Users by Search form set up example:

Listing chosen permission groups

If you wish to list a limited number of permission groups of your choosing, you can use a 'List Groups for User' permissions integration. By creating a fake user, which is in all of the groups that you wish to appear, you can create a list of groups of your choice in the form.

Using a Permission integration for display or route clause

The "Is User in Groups" can be used to check if a user if in a defined group/s to then be used in a route or display condition
 

1. For a display condition - create a permission integration using "Is User in Groups"
2. Where the highlighted {user_email} is a field on your form that captures the potential form fillers email address this could be a free fill field or more likely would be a hidden field populated  by a token (eg via Dash login) and the User Group is the group permission your form filler must have to see the relevant details on a form
    
3. Create the relevant form and ensure that the Default token is included as this will be used on the form to populate with 'true' or 'false', and this is the field that will then be used on which to base the conditional display  (NOTE: Integrations v2 must be applied in Form settings)
4. On filling the form - if the user does not have the correct permissions they will seeBut if they are in the relevant permission group then they will see
    

Adding the integration to a select field as a lookup

In the settings for this field choose 'Lookup' as the List Source. Then in the Lookup select field underneath on the settings, choose the integration

This enables tasks to be assigned to relevant team based on selections made within a form.

Note: The Test Assistant can be used to identify which users/groups etc will be returned by each permission integration

 

Further useful reading: 

• Using Permission groups for Task Assignment
• Using Active Directory to restrict groups

 

top of page