SetUserGroup
- Last UpdatedOct 29, 2026
- 2 minute read
SetUserGroup is a built-in function that sets the security group for a specified user. It can either overwrite or append to the user's current list of assigned groups.
|
Function |
Group |
Execution |
String Exp. |
Windows |
Windows Embedded |
IoT View |
Thin Clients |
Mobile Access |
|---|---|---|---|---|---|---|---|---|
|
SetUserGroup |
Security |
Synchronous |
No |
Supported |
Supported |
Not supported |
Supported |
Not supported |
Syntax
SetUserGroup(strUserName,strGroupName,optNumAppend)
SetUserGroup ( strUserName , strGroupName { | , { optNumAppend | 0 | 1 } } )
strUserName
The name of the user that will have its group set.
strGroupName
The name of the group to be set for the specified user. To specify multiple groups, separate them with commas.
optNumAppend
A numerical flag that indicates how the group should be set:
|
Value |
Description |
|---|---|
|
0 |
Overwrite the user's current list of assigned groups. |
|
1 |
Append to the user's current list of assigned groups. |
This parameter is optional; if no value is specified, the default value is 0.
Return value
This function returns one of the following possible values:
|
Value |
Description |
|---|---|
|
-1 |
Internal error. |
|
0 |
Group set successfully. |
|
1 |
Invalid number of parameters. |
|
2 |
Wrong data type for parameter. |
|
3 |
The specified user does not exist. |
|
4 |
The specified group does not exist. |
|
5 |
Failed to save changes to the Security System configuration file. |
|
6 |
Invalid user (that is, the Runtime user option is not selected for the specified user). |
|
7 |
Invalid group (that is, the Runtime group option is not selected for the specified group). |
|
8 |
The current user does not have sufficient privileges to make changes (that is, the current user does not belong to a group that has the Edit Security System option selected). |
|
9 |
The current security mode (for example, Domain) does not allow user groups to be changed. |
Notes
This function does not send events to the Event Logger.
You should avoid calling this function too frequently during project run time — for example, as part of a For loop that repeats in a matter of milliseconds. By default, the security settings are saved synchronously (that is, after each change is made), and too frequent saves can decrease runtime performance and/or cause the project development environment to freeze.
As a workaround, you can change the default behavior and configure your project to save the security settings asynchronously, at a specified interval. To do this, manually edit your project file (<project name>.app) to add the following settings:
[SecuritySystem]
EnableAsyncSavingForBuiltInFunctions=1
[Options]
SecuritySystemAutoSaveInterval=<in minutes, default is 5, minimum is 1>
Asynchronous saving applies to the following built-in functions:
-
BlockUser
-
CreateUser
-
RemoveUser
-
SetPassword
-
SetUserGroup
-
UnblockUser
If you enable asynchronous saving as described above and then call any of these functions to make changes to the security settings during project run time, those changes will be applied immediately but they might not be saved when the project is stopped.
In contrast, if you use the project development environment to make changes to the security settings during project run time, those changes are always saved synchronously regardless of whether asynchronous saving is enabled.
Examples
Set the user "John" to the group "Admin":
SetUserGroup("John","Admin")
Set the user "Bob" to the groups "Admin" and "Operator":
SetUserGroup("Bob","Admin,Operator",0)
Add the current user to the group "Maintenance":
SetUserGroup(UserName,"Maintenance",1)