sys.users
This package contains some utilities to manage system user records.
activate(user)
Changes the status of the user to active. If the user was active already, nothing will be done.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
user |
yes |
The user to activate. |
Returns
sys.data.Record - The activated user object.
Exceptions
badRequest
If user is not a valid object.
notFound
If no user is found in the database for the given user object.
Samples
// creates a user, deactivate, activate and deletes it
var user = sys.data.createRecord('sys.users');
user.field('firstName').val('User1');
user.field('lastName').val('Test');
user.field('email').val('user1@test.com');
user.field('sendWelcomeEmail').val(false);
sys.users.addGroup(user, 'Group1', true);
// if we want to save the user's password we need to add
user.field('authentication.passwordExpired').val(false);
user.field('authentication.generatePassword').val(false);
// otherwise those fields values will be TRUE by default, and the API will skip the password fields
var userPassword = '1234567890'
user.field('authentication.password').val(userPassword);
user.field('authentication.passwordConfirmation').val(userPassword);
user.field('authentication.newPassword').val(userPassword);
// now we save the user and it will be created in the app at this point
user = sys.data.save(user);
log('user id: '+user.id());
// deactivate user
user = sys.users.deactivate(user);
log('user status: '+user.status());
// activate user
user = sys.users.activate(user);
log('user status: '+user.status());
// finally remove the user
sys.data.remove(user);
deactivate(user)
Changes the status of the user to inactive. If user was inactive already, nothing will be done.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
user |
yes |
The user to deactivate. |
Returns
sys.data.Record - The deactivated user object.
Exceptions
badRequest
If user is not a valid user object.
notFound
If no user is found in the database for the given user object.
Samples
// creates a user, deactivates and deletes it
var user = sys.data.createRecord();
user.field('firstName').val('User1');
user.field('lastName').val('Test');
user.field('email').val('user1@test.com');
user.field('sendWelcomeEmail').val(false);
sys.users.addGroup(user, 'Group1', true);
// now we save the user and it will be created in the app at this point
user = sys.data.save(user);
log('user id: '+user.id());
// deactivate user
user = sys.users.deactivate(user);
log('user status: '+user.status());
// finally remove the user
sys.data.remove(user);
resetPassword(user, options)
Resets the password of a specific user. In case the user is blocked then it will be reactivated.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
user |
yes |
The user to reset password. |
||
options |
|
no |
These options allow to configure operation. Available option is:
|
Returns
object - The following object is returned:
{
userId: '...',
userEmail: '...',
resetCode: '...',
link: '...'
}
Where userId and userEmail are fields related to the affected user in the operation.
resetCode is the code auto-generated to reset password and link is the URL in which
user needs to set password settings.
Samples
// reset password for user and notified about it by email
var user = sys.data.findOne('sys.users', 'user@company.com');
var result = sys.users.resetPassword(user, {notify: true});
log('Reset password result: ' + JSON.stringify(result));
addIdentityProvider(userId, identityProviderIdOrName, externalId)
Enables an identity provider to the given user. If the identity provider was already enabled for that user, the external ID will be updated.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
userId |
|
yes |
The ID of the user to enable the identity provider. |
|
identityProviderIdOrName |
|
yes |
The ID or name of the identity provider to enable. |
|
externalId |
|
no |
The ID of the user in the identity provider. It is optional. |
Returns
sys.data.Record - The updated user object.
Exceptions
badRequest
If userId or identityProviderIdOrName are not valid.
notFound
If no user is found in the database for the given user ID or no identity provider with the given ID or name.
Samples
// creates a user, adds an identity provider, and deletes it
var user = sys.data.createRecord();
user.field('firstName').val('User1');
user.field('lastName').val('Test');
user.field('email').val('user1@test.com');
user.field('sendWelcomeEmail').val(false);
sys.users.addGroup(user, 'Group1', true);
// now we save the user and it will be created in the app at this point
user = sys.data.save(user);
log('user id: '+user.id());
// add identity provider
user = sys.users.addIdentityProvider(user.id(), 'slack', user.email());
log('identity provider added');
// finally remove the user
sys.data.remove(user);
removeIdentityProvider(userId, identityProviderIdOrName)
Disables an identity provider to the given user. If the identity provider wasn’t already enabled for that user, it doesn’t do anything.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
userId |
|
yes |
The ID of the user to disable the identity provider. |
|
identityProviderIdOrName |
|
yes |
The ID or name of the identity provider to disable. |
Returns
sys.data.Record - The updated user object.
Exceptions
badRequest
If userId or identityProviderIdOrName are not valid.
notFound
If no user is found in the database for the given user ID.
Samples
// creates a user, adds an identity provider, removes it, and deletes the user
var user = sys.data.createRecord();
user.field('firstName').val('User1');
user.field('lastName').val('Test');
user.field('email').val('user1@test.com');
user.field('sendWelcomeEmail').val(false);
sys.users.addGroup(user, 'Group1', true);
// now we save the user and it will be created in the app at this point
user = sys.data.save(user);
log('user id: '+user.id());
// add identity provider
user = sys.users.addIdentityProvider(user.id(), 'slack', user.email());
log('identity provider added');
// remove identity provider
user = sys.users.removeIdentityProvider(user.id(), 'slack');
log('identity provider removed');
// finally remove the user
sys.data.remove(user);
containsGroup(userRecord, groupIdOrNameOrLabel)
Checks if the user record belongs to the given group.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
userRecord |
yes |
The user record to check group. |
||
groupIdOrNameOrLabel |
|
yes |
The ID or name or label of the group to check. |
Returns
boolean - True if the user belongs to the specified group.
Samples
// check if the user belongs to the admins group
var user = sys.data.findOne('sys.users', {email: 'user@company.com'});
var isAdmin = sys.users.containsGroup(user, 'admins');
log('Is it admin? ' + isAdmin);
isPrimaryGroup(userRecord, groupIdOrNameOrLabel)
Checks if the primary group of the user record is the given group.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
userRecord |
yes |
The user record to check group. |
||
groupIdOrNameOrLabel |
|
yes |
The ID or name or label of the group to check. |
Returns
boolean - True if specified group is the primary one.
Samples
// check if admins group is the primary one
var user = sys.data.findOne('sys.users', {email: 'user@company.com'});
var isPrimary = sys.users.isPrimaryGroup(user, 'admins');
log('Is it primary? ' + isPrimary);
getPrimaryGroup(userRecord)
Retrieves the primary group of the user.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
userRecord |
yes |
The user record to retrieve group. |
Returns
object - An object with the attributes ID, name and label
Samples
// check if admins group is the primary one
var user = sys.data.findOne('sys.users', {email: 'user@company.com'});
var primaryGroup = sys.users.getPrimaryGroup(user);
log('Group: ' + JSON.stringify(primaryGroup));
addGroup(userRecord, groupIdOrNameOrLabel, primary)
Adds a group to the specified record user.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
userRecord |
yes |
The user record to add group. |
||
groupIdOrNameOrLabel |
|
yes |
The ID or name or label of the group to be added. |
|
primary |
|
no |
True if the group to be added is the primary one. |
Samples
// add admins group as primary.
var user = sys.data.findOne('sys.users', {email: 'user@company.com'});
sys.users.addGroup(user, 'admins', true);
sys.data.save(user);
log('Contains group: ' + sys.users.containsGroup(user, 'admins'));
removeGroup(userRecord, groupIdOrNameOrLabel)
Removes the user record from the given group
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
userRecord |
yes |
The user record to remove group. |
||
groupIdOrNameOrLabel |
|
yes |
The ID or name or label of the group to be removed. |
Samples
// remove admins group.
var user = sys.data.findOne('sys.users', {email: 'user@company.com'});
sys.users.removeroup(user, 'admins');
sys.data.save(user);
log('Contains group: ' + sys.users.containsGroup(user, 'admins'));
getEndpointConfiguration(userRecord, endpointName)
Retrieves configuration of the specified user endpoint if exists
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
userRecord |
yes |
The user record to to retrieve endpoint configuration. |
||
endpointName |
|
yes |
The name of the endpoint to retrieve configuration. |
Samples
// retrieve http endpoint configuration
var user = sys.data.findOne('sys.users', {email: 'user@company.com'});
var config = sys.users.getEndpointConfiguration(user, 'http');
log('Http endpoint configuration: ' + JSON.stringify(config));