Create Or Update User – creating and changing user accounts from an action¶
The command "Create Or Update User" creates a user account or changes an existing one: user name, password, roles, profile record, lock, password expiry and the links to external sign-in providers. This page is for administrators who build actions for onboarding, imports or the synchronisation of accounts with another system.
1. At a glance¶
| Purpose | Create a user, or change the account of an existing user |
| Typical use | An onboarding form that creates the account of a new employee; a nightly import that locks the accounts of people who left |
| Where in the editor | Toolbar menu "Data" → "Create Or Update User" |
| Needs a user interface | No |
| Needs a current record | No – but the expressions can read it |
| Changes the current record | No |
| Permissions of the running user | "Add User" for a new user, "Edit User" for an existing one, plus "Reset User Password" when a password is set |
| Related | Delete User, Users, Create Entity Record |
2. Settings¶
Tab "General" – below "Display Name", "Description" and "Execution Condition" (see Actions):
| Setting | Meaning | Default / Required |
|---|---|---|
| "User Identifier" | Expression that returns the id or the user name of the user to change | Empty: a new user is created |
| "User Id Variable" | A variable of the action that receives the id of the created or changed user | Empty: the id is not stored |
Tab "Values To Set" – one row per property to write. Each row has a "Property" and a "Value" (an expression). Only the properties that have a row are written; everything else on the account stays as it is.
| Property | Value | An empty value |
|---|---|---|
| "Password" | The new password as text. It must meet the password policy. | Is ignored – the password stays |
| "User Name" | The name the user signs in with. Must not be used by another user. | Is ignored – the name stays |
| "Roles" | The roles assigned directly: ids or names, separated by commas, or a JSON array. Ids and names can be mixed. Replaces the current roles. | Removes all roles |
| "Profile RecId" | The RecId of the record of the user profile entity that belongs to this user | Removes the link of the current profile record |
| "Locked" | true locks the account, false unlocks it |
Unlocks the account |
| "Password Expires" | true or false, see Users |
Switches the expiry off |
| "Password Expires At" | The moment the password expires | Clears the moment |
Tab "Ext Assignments" – the links to external sign-in providers:
| Setting | Meaning | Default / Required |
|---|---|---|
| "Remove Other Assignments" | Removes every link to a provider that is not listed below | Off |
| Rows with "Authentication Provider" and "Claim Value" | A provider and the value of the claim that identifies the user at that provider (see Authentication providers). The claim value is an expression. | None |
A new user needs at least the property "User Name".
3. Behaviour¶
- All expressions are evaluated against the current record and the variables of the action.
- Without "User Identifier" (or if it returns an empty value), a new user is created. If the user name is already taken, the command fails – it does not change the existing user. With "User Identifier", the user with this id is changed; if no user has this id, the user with this user name. If there is none, the command fails.
- Before anything is written, the command checks the permissions of the user the action runs for, the password against the password policy, that every role exists and that the profile record exists. If one of these checks fails, nothing is changed.
- The account is saved immediately, also while a sketch is open – like saving in the user editor.
- "Roles": every entry must match exactly one role, by id or by name (the comparison ignores upper and lower case). A name that two roles share must be given as id.
- "Profile RecId": the id of the user is written into the user id field of this profile record. Any other profile record that was linked to the user before is unlinked first, so a user always has at most one profile record. If the record was linked to another user, it now belongs to this user. The business rules of the profile entity run as for any save.
- Ext Assignments: a row for a provider the user is already linked to replaces its claim value; a row for a new provider adds a link. Rows without a provider or with an empty claim value are skipped. With "Remove Other Assignments", all other links are removed – with no rows at all, that removes every link.
- After success, the id of the user is written into "User Id Variable", if one is selected – also for a new user. Following commands can use it, for example to store it on a record.
- If the command fails, the action ends with an error. The reason is written to the log and to the protocol of the run; the user sees no message.
4. Examples¶
Onboarding. An employee form has the fields "Login", "Department" and "Start password". A button runs an action with:
- Create Or Update User without "User Identifier", with the rows "User Name" = field "Login",
"Password" = field "Start password", "Roles" =
Default User, Sales, "Password Expires" =trueand "Password Expires At" = a moment in the past, and "User Id Variable" = the variable "New user". The employee record stays the current record. - Update Entity Record writes the variable "New user" into the field "Account" of the employee record and saves it.
- Create Entity Record for the entity "UserProfile" with name and mail address of the employee and the variable "New user" in the user id field of the profile, without "Show Form", saved.
The employee signs in with the start password and has to choose their own at once.
Locking leavers. A scheduled action iterates over the employees whose leaving date has passed and
runs Create Or Update User with "User Identifier" = field "Login" and a single row "Locked" =
true. Nothing else on the accounts changes.
Single sign-on only. For a user who signs in only through Microsoft Entra ID, set no password, add a row in "Ext Assignments" with the provider and the object id of the user as claim value, and switch on "Remove Other Assignments".
5. Limitations¶
- An account created by the command gets no profile record of its own. Create one, as in the example, or link an existing one with "Profile RecId" – without a profile record the user has no mail address and cannot reset their password.
- Locking an account also ends the browser sessions that are already open, but only at their next re-check, see Users.
- A failure ends the action. There is no error variable that would let the action continue.
- The command cannot set or reset the two-factor authentication of a user.