K2 4.7 behavioral change to the Role Include functionality
KB001740
PRODUCT
With the release of K2 4.7 the Role Include feature has been deprecated. The ability to exclude a role item in Workspace > Management Console by unchecking the Include check box is no longer possible. The Include check box has been removed.
Current K2 behavior
A group or user could be added to a role created in K2 Workspace > [Server]> [WorkflowServer] > Roles, and individual users were excluded from the role by unchecking the Include check box as shown below.
Behavior in K2 4.7
If a user or group is included in the role they are a role participant. To disable group, user or SmartObject participation, the user or individual role item must be removed from the role for the same affect.
Excluding a role item via the API (SourceCode.Security.UserRoleManager.Management) has also changed. Previously you used the Role.Include.Add method to include a group or user in a role. Now you must use the Role.RoleItem.Add method.
The change in behavior in K2 4.7 requires existing K2 environments that have excluded a role item either by unchecking the Include check box in the Workspace > Management Console or through the API to be manually updated before upgrading to K2 4.7. See below for more details on the required steps.
Pre K2 4.7 Upgrade configuration required
A. In Workspace:
Before upgrading to K2 4.7 one of the following options need to be performed in K2 Workspace> Management Console> [Server]> [WorkflowServer] > Roles.
- Include the excluded role item by checking the Include check box
- Delete the role item from the role
- Delete the role. This may only be deleted if there are no process instances using the exclusion of the role item.
If the upgrade is run before manually changing the configuration of a role that has exclusions, the installer stops and displays a message that role items have been excluded and the upgrade cannot proceed. Cancel the upgrade, make the change to the role in K2 Workspace, and start the upgrade again.
Installer message: Roles are found that use the Exclude functionality. Setup cannot continue until you remove the excluded users or groups from the following roles: Designers. For more information see KB001740.
B. K2 API
Previously, you were required to create the role, add a role item and then specify if the role item was included. With the deprecation of the Include functionality, the role need only be created and then a role item added.
You may receive the following error message, which indicates that you are using the older API method and must update it to use the new API.
You must update your code by replacing the line of code in RED with the line of code in GREEN.
{
UserRoleManager urm = new UserRoleManager();
//Create a connection to the User Role Manager Service
urm.CreateConnection();
urm.Connection.Open("Integrated=True;IsPrimaryLogin=True;Authenticate=True;EncryptedPassword=False;Host=" + _serverName + ";Port=" + _hostServerPort);
//-------------------------- User Role Management ---------------------------------------------------
SourceCode.Security.UserRoleManager.Management.Role QARole = new SourceCode.Security.UserRoleManager.Management.Role();
//--------------------------- Verify if Role Exists -------------------------------------------------
/*
Creates a role with a number of users. First checks if Role exists and if not then role is created
*/
Role[] SearchRole = urm.GetRoles(RoleName);//Creates an array if items from the Role Collection
if (SearchRole.Length == 0) // If the specified role does not exist then it will be created and the user added to the role
{
QARole.Name = RoleName;
QARole.Description = RoleDescription;
QARole.IsDynamic = true;
QARole.Include.Add(new GroupItem("K2:" + UserDomain + "\" + GroupName));
QARole.RoleItems.Add(new UserItem("K2:" + UserDomain + "\" + GroupName));
urm.CreateRole(QARole);
}
//Refresh the SearchRole array and then obtain the Role Guid.
SearchRole = urm.GetRoles(RoleName);
Guid RoleGuid = SearchRole[0].Guid;
}
