User Group Management Action Commands

Each command entry begins with a root command that specifies whether a set of actions applies to an individual user, or to a user group. Use the usergroup root command to manage user groups. You can operate on a maximum of 10 user-groups per request.

The do list for a usergroup entry specifies the series of steps to complete for the group. The steps can perform group-management operations (create, delete, update) or membership operations (add and remove members and entitlements). You can add product profiles to a user group, giving all user group members the related entitlements.

Management Step Actions for User Groups

• To create, update or delete a group, specify createUserGroup, updateUserGroup, or deleteUserGroup steps in the do list for a usergroup entry.

• To change provisioning through group membership, specify the add and remove steps in the do list for a usergroup entry to update the membership lists for the user group.

createUserGroup:

Creates a user group, or updates the description if the named group already exists group. There can be only one create operation for a given usergroup command entry, and it must be the first step.

{
  "createUserGroup": {
    "name": "string",
    "description": "string",
    "option": "string"
  }
}

• name: string; Required. The name of the user group.
• description: string; Optinal. The description of the usergroup.
• option: string, possible values: {ignoreIfAlreadyExists, updateIfAlreadyExists}; Optional for createUserGroup action. Specifies how to perform the create operation when a user group with the given name already exists in the user database.
  • ignoreIfAlreadyExists: If the user group already exists, ignore the create step but process any other steps in the command entry for this user.
  • updateIfAlreadyExists: If the user group already exists, update the description of the existing group with the provided value (if any), but ignore the name value. After the update, process any other steps in the command entry for this group.

updateUserGroup:

Updates the name or description user group. Both fields are optional.

See user-group-information for individual field descriptions.

{
  "updateUserGroup": {
    "name": "string",
    "description": "string"
  }
}

deleteUserGroup:

Deletes an existing user group. No further steps are performed after deletion.

{
  "deleteUserGroup": {
  }
}

Adding and removing memberships for a user group

A group has two membership lists: users who are members of the group, and product profiles for which the group has access. In the add and remove actions, supply the user option with a list of users to update the group membership, and the productConfiguration option with a list of product profile names.

• When you add a user to the group, that user gains entitlement for all member product profiles. When you remove a user from the group, that user loses the associated entitlements (unless they have individual access).

• When you add a product profile, all of the member users gain the associated entitlements. When you remove a product profile, all of the users in the user group lose the associated entitlements (unless they have individual access). Please note that you cannot use the add command if the user-group has more than 200,000 users.

• When a group has isReadOnly set to true, you cannot add or remove users from the group however you can add or remove product profiles.

NOTE: Use the group resource to retrieve information about defined groups.

Each step can add or remove up to 10 memberships in one command entry using the user and productConfiguration options. Specify users by email, and product profiles by name.

{
  "usergroup": "DevOps",
  "do": [
     {
      "add": {
        "user": [
          "user1@myCompany.com"
        ],
        "productConfiguration": [
          "Profile1_Name"
        ],
      }
     },
     {
      "remove": {
        "user": [
          "user2@myCompany.com"
        ],
        "productConfiguration": [
          "Profile2_Name"
        ],        
       }
     }
  ]
}

Usergroup command request body schema

[
  {
    "do": [
      {
         "createUserGroup": {
           "option": "string",
           "description": "string"
         }
      },
      {
        "updateUserGroup": {
          "name": "string",
          "description": "string"
        }
      },
      {
        "deleteUserGroup" : {}
      },
      {
        "add": {
          "user": [
            "string"
          ],
          "productConfiguration": [
            "string"
           ]
       },
      }
      {
        "remove": {}
      }
   ],
    "requestID": "string",
    "usergroup": "string"
  }
]

User-group action examples

Add a product profile and a user to a user group, and remove another product profile and user.

{
  "usergroup": "DevOps",
  "do": [
      {
        "add": {
         "user": [
           "user1@myCompany.com"
         ],
          "productConfiguration": [
            "Profile1_Name"
         ] 
        } 
      },
      {
        "remove": {
          "user": [
            "user2@myCompany.com"
           ],
          "productConfiguration": [
            "Profile2_Name"
         ]
         }
       }
  ]
}

Update a usergroup’s name and description.

{
  "usergroup": "DevOps",
  "do": [
    {
      "updateUserGroup" : {
        "description": "Devops group description",
        "name": "DevOps Team"
      }
    }
  ]
}

Update a usergroup and add production profile.

{
  "usergroup": "DevOps",
  "do": [
    {
      "updateUserGroup" : {
         "description": "Devops group description",
         "name": "DevOps Team"
       }
      },
    {
      "add": {
        "user": [
          "user1@myCompany.com"
        ]
       }
     }
  ]
}

Delete a usergroup.

[
  {
    "requestID": "dsctesting",
    "usergroup": "DevOps Team",
    "do": [
      {
        "deleteUserGroup": {
        }
      }
    ]
  }
]