Create Role

Audience: Low-code Engineers

Skill Prerequisites: Actions, Tokens

Creates a new security role in the current portal. You can set its name, description, role group, status and a few options, and save the new role's ID in a token.

To give the role to a user afterwards, use Grant User Role. For how roles are used in Plant an App, see Roles.

Typical Use Cases

• Create a role for each new customer, team or project, for example Customer - [CompanyName]
• Set up the roles an application needs when it's installed on a new portal
• Create a role and grant it to the current user in the same flow

Don't use it to

• Give a user a role. Use Grant User Role instead.
• Change a role that already exists. Use Update Role instead.
• Create a role group. This action only puts the role in a group that already exists.

Related Actions

Action Name	Description
Update Role	Changes the name, description, group, status or options of a role.
Delete Role	Deletes a role.
Grant User Role	Adds a user to a role.
Revoke User Role	Removes a user from a role.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Role Name	The name of the new role, for example Customer - [CompanyName]. A role with this name can't already exist in the portal.	Yes	empty string	Yes
Role Description	The description of the new role.	Yes	empty string	No
Role Group Identifier	The role group to put the role in, as a group name or group ID. The group must already exist in the portal. Leave it empty, or use -1, for no group.	Yes	empty string (no group)	No
Role Status	The status of the role: Pending, Disabled or Approved. In expression mode, use -1 (Pending), 0 (Disabled) or 1 (Approved). If it's empty or not recognized, the role is created as Disabled. See Considerations.	Yes	empty string (Disabled)	No
Add to existing users	true to also give the role to the users already in the portal. See Considerations.	Yes	false	No
Auto Assign	true to give the role to every user who registers from now on. Because of a product bug, the value of Is Public is used instead. See Considerations.	Yes	false	No
Is Public	true to make the role public, so users can subscribe to it themselves from their profile.	Yes	false	No
Output Token Name	The name of a token to save the new role's ID in, for example NewRoleId. Use it later as [NewRoleId].	No	empty string	No

Output Parameters Reference

Parameter	Description
Output Token Name	The ID of the new role, for example 42. The token has the name you entered, for example [NewRoleId]. It's only set if you entered a name.

Considerations

• There's no permission check in the action. Anyone who can run it can create roles in the portal, including public or auto-assigned ones. Only put it where administrators or other trusted users can reach it.
• Set Role Status to Approved. If you leave it empty, the role is created as Disabled, and a disabled role doesn't grant anything. A value the action doesn't recognize, such as Active or approved in lowercase, is also treated as Disabled without an error. Status names are case-sensitive. Numbers other than -1, 0 and 1 are saved as they are.
• Auto Assign reads Is Public. Because of a product bug, the action uses the value of Is Public for both settings. If Auto Assign has any value and Is Public is empty, the action fails with Incorrect value ... provided for the Auto Assign parameter!. In practice, a role is auto-assigned only when both Auto Assign has a value and Is Public is true, and then it's also public.
• Add to existing users depends on Auto Assign. The action passes the setting to DNN, and DNN only adds existing users to roles that are auto-assigned. With the bug above, that means Is Public must also be true.
• Boolean values must be true or false. Values like yes or 1 make the action fail with Incorrect value ... provided for the ... parameter!. Case doesn't matter.
• Duplicate names fail. If a role with the same name exists in the portal, the action fails with Create Role : A role with this name already exists.
• The role group must exist. A group name or ID that isn't found makes the action fail with A invalid role group name (...) was provided. or A invalid role group id (...) was provided. Group names aren't case-sensitive.
• Other role settings aren't available. The security mode, RSVP code, icon and billing settings aren't parameters. They keep DNN's defaults, and the role has no billing. Change them in the DNN role settings if you need them.
• Avoid role names that are only numbers. Other actions, like Update Role and Delete Role, treat a number as a role ID, so you can't find a role called 2024 by its name.
• Errors are shown to administrators with the technical message, for example Create Role : No value provided for the role name!. Other users see a general error message.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Create an approved role for a customer

This action creates an approved role for a company in the Customers role group and saves its ID in [NewRoleId]. The role isn't public and isn't auto-assigned.

{
    "Title": "Create Role",
    "ActionType": "CreateRole",
    "Description": "Create a role for the new customer",
    "Parameters": {
        "RoleName": "Customer - [CompanyName]",
        "RoleDescription": "Users of [CompanyName]",
        "RoleGroupIdentifier": "Customers",
        "RoleStatus": "1",
        "AddToExistingUsers": "",
        "AutoAssign": "",
        "IsPublic": "false",
        "OutputTokenName": "NewRoleId"
    }
}

After it runs, you can use [NewRoleId] in Grant User Role to add the current user to the role.

Revised 09/27/2026