SCIM2 Bulk Operations¶

Follow the topics given below to understand how Bulk operations can be used when you manage resources in the SCIM2 API.

The SCIM2 API allows you to send multiple resource operations in a single request. That is, you can add new records (POST data), replace an existing record (PUT data), update elements of an existing record (PATCH data), and delete records (DELETE data) in bulk. These bulk operations are supported for managing users and groups with the SCIM API in WSO2 Identity Server.

Manage users in bulk¶

You can use the bulk operations to add, remove, update, and replace users in bulk.

Info

The examples given below show individual resource operations (POST, PATCH, PUT, or DELETE) handled in a single request. However, note that a single request can execute a combination of operation types simultaneously.

Add users¶

Given below is an example request payload to manage users in bulk. This request includes an array of operations that adds multiple new users.

{
   "failOnErrors":1,
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
   "Operations": [
       {
           "method": "POST",
           "path": "/Users",
           "bulkId": "qwerty",
           "data": {
               "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
               "userName": "Kim",
               "password":"kim123",
               "name": {
                   "givenName": "Kim",
                   "familyName": "Berry"
               }
           }
       },
       {
           "method": "POST",
           "path": "/Users",
           "bulkId": "ytrewq",
           "data": {
               "schemas": [
                   "urn:ietf:params:scim:schemas:core:2.0:User",
                   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
                   ],
               "name": {
                   "givenName": "Smith",
                   "familyName": "Berry"
               },
               "userName": "smith",
               "password": "smith123",
               "emails": [
                   {
                       "type": "home",
                       "value": "[email protected]",
                       "primary": true
                   },
                   {
                       "type": "work",
                       "value": "[email protected]"
                   }
               ],
               "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                   "employeeNumber": "1234A",
                   "manager": {
                       "value": "Taylor"
                   }
               }
           }
       }
   ]
}

The parameters in the request body are explained below.

Main parameters

Parameter	Required/Optional	Description
`failOnErrors`	Optional	The number of errors that will be accepted by WSO2 IS before returning the response. Possible values: An integer.
`schemas`	Required	This is the schema that is required for sending bulk requests: `urn:ietf:params:scim:api:messages:2.0:BulkRequest`.
`operations`	Required	Array of operations. To add multiple new users, add an array of POST operations. You can include any number of operations in one bulk request. The parameters that can be used for the operation are explained below.

Operation parameters

Parameter	Required/Optional	Description
`method`	Required	The method that should be used in the operation. Possible value:`POST`.
`path`	Required	Add this path to specify that a new user is being added. Possible value:`/Users`.
`bulkid`	Required	A unique identifier for the bulk operation. The bulkid is required for POST operations. Possible value: An integer value.
`data`	Required	Specify the details of the new user that should be added. The parameters that can be used for this “data” object are explained below.

Data parameters

Parameter	Required/Optional	Description
`schemas`	Required	Specify the list of SCIM2 user schemas to which the new user should be linked. Possible values: `urn:ietf:params:scim:schemas:core:2.0:User` `urn:ietf:params:scim:schemas:enterprise:2.0:User` `urn:scim:wso2:schema`
`{attribute_name}`	Required	The name of the attribute that will be updated. Possible values: User attributes as per the SCIM protocol.

Update users¶

Given below is an example request payload to update users in bulk. This request includes an array of operations that updates multiple details of multiple users.

{
   "failOnErrors":1,
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
   ],
   "Operations":[
      {
         "method":"PATCH",
         "path":"/Users/e67906fb-308f-4b15-89bd-0ab6e3d996e5",
         "data":{
            "Operations":[
               {
                  "op":"replace",
                  "path":"name",
                  "value":{
                     "givenName":"john",
                     "familyName":"Anderson"
                  }
               },
               {
                  "op":"add",
                  "path":"nickName",
                  "value":"shaggy"
               }
            ]
         }
      },
      {
         "method":"PATCH",
         "path":"/Users/b1781d25-bde5-460a-a58a-8fe8dbfd8487",
         "data":{
            "Operations":[
               {
                  "op":"remove",
                  "path":"emails[type eq home]"
               }
            ]
         }
      }
   ]
}

The parameters in the request body are explained below.

Main parameters

Parameter	Required/Optional	Description
`failOnErrors`	Optional	The number of errors that will be accepted by WSO2 IS before returning the response. Possible values: An integer.
`schemas`	Required	This is the schema that is required for sending bulk requests: `urn:ietf:params:scim:api:messages:2.0:BulkRequest`.
`operations`	Required	Array of operations. To update multiple users, add an array of PATCH operations. You can include any number of operations in one bulk request. The parameters that can be used for the operation are explained below.

Operation parameters

Parameter	Required/Optional	Description
`method`	Required	The method that should be used in the operation. Possible Value:`PATCH`.
`path`	Required if `op` is `remove`. Optional if `op` is `add` or `replace`.	Add this path to specify the new user that is being updated. Possible Value:`/Users/{user_id}`.
`bulkid`	Optional	A unique identifier for the bulk operation. The bulkid is required for POST operations. Possible Value: An integer value.
`data`	Required	Specify the details of the new user that should be updated. The parameters that can be used for this “data” object are explained below.

Data parameters

Parameter	Required/Optional	Description
`op`	Required	The operation that should be applied to the existing user’s data. Possible Values: `add` `replace` `remove` See SCIM2 Patch Operations for details on how to define patch operations.
`path`	Required if `op` is `remove`. Optional if `op` is `add` or `replace`	The path to the resource (user attribute) that should be updated. For example, if the name of the user is to be updated, the path should be “name”.
`value`	Required if `op` is `remove`. Optional if `op` is `add` or `replace`.	The value of the parameter specified by the `path`. For example, if the path is “name”, the value should be the actual name. See SCIM2 Patch Operations for details on how to define values for the patch operations.

Replace users¶

Given below is an example request payload to replace existing users in bulk. This request includes an array of operations that replace multiple users.

{
   "failOnErrors":1,
   "schemas":["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
   "Operations":[
       {
           "method": "PUT",
           "path": "/Users/e67906fb-308f-4b15-89bd-0ab6e3d996e5",
           "bulkId": "qwerty",
           "data":{
               "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
               "userName": "Kim",
               "name": {
                   "givenName": "John",
                   "familyName": "Berry"
               },
               "emails": [
                   {
                       "type": "home",
                       "value": "[email protected]"
                   }
               ]
           }
       },
       {
           "method": "PUT",
           "path": "/Users/b1781d25-bde5-460a-a58a-8fe8dbfd8487",
           "bulkId":"ytrewq",
           "data":{
               "schemas":[
               "urn:ietf:params:scim:schemas:core:2.0:User",
               "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
               ],
               "userName":"smith",
               "name": {
                   "givenName": "Smith",
                   "familyName": "Berry"
               },
               "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User":{
                   "employeeNumber": "12345"
               }
           }
       }
   ]
}

The parameters in the request body are explained below.

Main parameters

Parameter	Required/Optional	Description
`failOnErrors`	Optional	The number of errors that will be accepted by WSO2 IS before returning the response. Possible values: An integer.
`schemas`	Required	This is the schema that is required for sending bulk requests: `urn:ietf:params:scim:api:messages:2.0:BulkRequest`.
`operations`	Required	Array of operations. To replace multiple users, add an array of PUT operations. You can include any number of operations in one bulk request. The parameters that can be used for the operation are explained below.

Operation parameters

Parameter	Required/Optional	Description
`method`	Required	The method that should be used in the operation. Possible value:`PUT`.
`path`	Required	Add this path to specify the existing user that should be replaced by the new user information that is added. Possible value:`/Users/{user_id}`.
`bulkid`	Optional	A unique identifier for the bulk operation. The bulkid is required for POST operations. Possible value: An integer value.
`data`	Required	Specify the new user details that should be used to replace the existing user specified in the path. The parameters that can be used for this “data" object are explained below.

Data parameters

Parameter	Required/Optional	Description
`schemas`	Required	Specify the list of SCIM2 user schemas where the new user details should replace the existing user specified by the path. Possible values: `urn:ietf:params:scim:schemas:core:2.0:User` `urn:ietf:params:scim:schemas:enterprise:2.0:User` `urn:scim:wso2:schema`
`{attribute_name}`	Required	The name of the attribute that will be replaced. Possible values: User attributes as per the SCIM protocol.

Delete users¶

Given below is an example request payload to delete existing users in bulk. This request includes an array of operations that delete multiple users.

{
   "failOnErrors":1,
   "schemas":["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
   "Operations":[
       {
           "method": "DELETE",
           "path": "/Users/e67906fb-308f-4b15-89bd-0ab6e3d996e5" 
       },
       {
           "method": "DELETE",
           "path": "/Users/b1781d25-bde5-460a-a58a-8fe8dbfd8487"
       }
   ]
}

The parameters in the request body are explained below.

Main parameters

Parameter	Required/Optional	Description
`failOnErrors`	Optional	The number of errors that will be accepted by WSO2 IS before returning the response. Possible values: An integer.
`schemas`	Required	This is the schema that is required for sending bulk requests: `urn:ietf:params:scim:api:messages:2.0:BulkRequest`.
`operations`	Required	Array of operations. To delete multiple users, add an array of DELETE operations. You can include any number of operations in one bulk request. The parameters that can be used for the operation are explained below.

Operation parameters

Parameter	Required/Optional	Description
`method`	Required	The method that should be used in the operation. Possible value:`DELETE`.
`path`	Required	Add this path to specify the existing user that should be deleted. Possible value:`/Users/{user_id}`.

Manage user groups in bulk¶

You can use bulk operations to add, update, replace, and delete user groups in bulk.

Info

The examples given below show individual resource operations (POST, PATCH, PUT, or DELETE) handled in a single request. However, note that a single request can execute a combination of operation types simultaneously.

Add user groups¶

Given below is an example request payload to add user groups in bulk. This request includes an array of operations that adds multiple new user groups.

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
   "Operations": [
      {
           "method": "POST",
           "path": "/Groups",
           "bulkId": "ytrewq",
           "data": {
               "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
               "displayName": "TourGuides",
               "members": [
                   {
                     "type": "User",
                     "value": "3633c988-69bf-48fc-978a-83dfde12695f"
                   }
               ]
           }
       },
              {
           "method": "POST",
           "path": "/Groups",
           "bulkId": "ytrewq",
           "data": {
               "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
               "displayName": "SLTourGuides",
               "members": [
                   {
                     "type": "User",
                     "value": "3633c988-69bf-48fc-978a-83dfde12695f"
                   },
                   {
                     "type": "User",
                     "value": "40390b19-54c9-4e77-b223-fe31d55e59e0"
                   }
               ]
           }
       }
    ]
}

The parameters in the request body are explained below.

Main parameters

Parameter	Required/Optional	Description
`failOnErrors`	Optional	The number of errors that will be accepted by WSO2 IS before returning the response. Possible values: An integer.
`schemas`	Required	This is the schema that is required for sending bulk requests: `urn:ietf:params:scim:api:messages:2.0:BulkRequest`.
`operations`	Required	Array of operations. To add multiple new user groups, add an array of POST operations. You can include any number of operations in one bulk request. The parameters that can be used for the operation are explained below.

Operation parameters

Parameter	Required/Optional	Description
`method`	Required	The method that should be used in the operation. Possible Value:`POST`.
`path`	Required	Add this path to specify that a new user group that should be added. Possible Value:`/Group`.
`bulkid`	Optional	A unique identifier for the bulk operation. The bulkid is required for POST operations. Possible Value: An integer value.
`data`	Required	Specify the details of the new user group that should be added. The parameters that can be used for this “data” object are explained below.

Data parameters

Parameter	Required/Optional	Description
`displayName`	Required	The display name of the user group.
`members`	Optional	An array of member users.
`display`	Required if `members` is used.	The display name of a user assigned to the group. Possible values: The username.
`value`	Required if `members` is used.	The ID of the user. Possible values: The user ID.

Update groups¶

Given below is an example request payload to update user groups in bulk. This request includes an array of operations that update multiple details in multiple user groups.

{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
   ],
   "Operations":[
      {
         "method":"PATCH",
         "path":"/Groups/46887262-2ba1-4cee-b3ef-64549423e0b0",
         "data":{
            "Operations":[
               {
                  "op":"replace",
                  "path":"members",
                  "value":[
                     {
                        "display":"smith",
                        "value":"ba1db5ff-8062-415b-bc78-5f79738d00ea"
                     }
                  ]
               }
            ]
         }
      },
      {
         "method":"PATCH",
         "path":"/Groups/18d04a36-0894-4f71-bdc4-2610fcc6ae42",
         "data":{
            "Operations":[
               {
                  "op":"add",
                  "path":"members",
                  "value":[
                     {
                        "display":"smith",
                        "value":"ba1db5ff-8062-415b-bc78-5f79738d00ea"
                     }
                  ]
               },
               {
                  "op":"remove",
                  "path":"members[value eq \"3633c988-69bf-48fc-978a-83dfde12695f\"]"
               }
            ]
         }
      }
   ]
}

The parameters in the request body are explained below.

Main parameters

Parameter	Required/Optional	Description
`failOnErrors`	Optional	The number of errors that will be accepted by WSO2 IS before returning the response. Possible values: An integer.
`schemas`	Required	This is the schema that is required for sending bulk requests: `urn:ietf:params:scim:api:messages:2.0:BulkRequest`.
`operations`	Required	Array of operations. To update multiple user groups, add an array of PATCH operations. You can include any number of operations in one bulk request. The parameters that can be used for the operation are explained below.

Operation parameters

Parameter	Required/Optional	Description
`method`	Required	The method that should be used in the operation. Possible Value:`PATCH`.
`path`	Required	Add this path to specify the user group that should be updated. Possible Value:`/Group/{group_id}`.
`bulkid`	Optional	A unique identifier for the bulk operation. The bulkid is required for POST operations. Possible Value: An integer value.
`data`	Required	Specify the details that should be updated for the user group specified in the path. The parameters that can be used for this “data” object are explained below.

Data parameters

Parameter	Required/Optional	Description
`op`	Required	The operation that should be applied to the existing user group. Possible values: `add` `replace` `remove` See SCIM2 Patch Operations for details on how to define patch operations.
`path`	Required if `op` is `remove`. Optional if `op` is `add` or `replace`.	Specify “members” as the path. Possible values: `members`
`value`	Required if `op` is `add` or `replace`.	An array of users that belong to the group.

Data operation value parameters

`display`	Required if `path is set to members.`	The display name of the user, who is a member. Possible values: The username.
`value`	Required if `path is set to members.`	The user ID of the member user. Possible values: The user ID.

Replace groups¶

Given below is an example request payload to replace existing user groups in bulk. This request includes an array of operations that replace multiple user groups.

{
   "failOnErrors":1,
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
   ],
   "Operations":[
      {
         "method":"PUT",
         "path":"/Groups/46887262-2ba1-4cee-b3ef-64549423e0b0",
         "data":{
            "displayName":"TourGuides",
            "members":[
               {
                  "display":"Alice",
                  "value":"3633c988-69bf-48fc-978a-83dfde12695f"
               }
            ]
         }
      },
      {
         "method":"PUT",
         "path":"/Groups/18d04a36-0894-4f71-bdc4-2610fcc6ae42",
         "data":{
            "displayName":"SLTourGuides",
            "members":[
               {
                  "display":"Alice",
                  "value":"3633c988-69bf-48fc-978a-83dfde12695f"
               }
            ]
         }
      }
   ]
}

The parameters in the request body are explained below.

Main parameters

Parameter	Required/Optional	Description
`failOnErrors`	Optional	The number of errors that will be accepted by WSO2 IS before returning the response. Possible values: An integer.
`schemas`	Required	This is the schema that is required for sending bulk requests: `urn:ietf:params:scim:api:messages:2.0:BulkRequest`.
`operations`	Required	Array of operations. To replace multiple user groups, add an array of PUT operations. You can include any number of operations in one bulk request. The parameters that can be used for the operation are explained below.

Operation parameters

Parameter	Required/Optional	Description
`method`	Required	The method that should be used in the operation. Possible value:`PUT`.
`path`	Required	Add this path to specify the existing user group that should be replaced by the new information that is added. Possible value:`/Groups/{group_id}`.
`bulkid`	Optional	A unique identifier for the bulk operation. The bulkid is required for POST operations. Possible value: An integer value.
`data`	Required	Specify the new group details that should be used to replace the existing user group specified in the path. The parameters that can be used for this “data" object are explained below.

Data parameters

Parameter	Required/Optional	Description
`displayName`	Required	The display name of the user group.
`members`	Required	Array of member users.
`display`	Required	The display name of a user assigned to the group. Possible values: The username.
`value`	Required	The ID of the user. Possible values: The user ID.

Delete users¶

Given below is an example request payload to delete existing user groups in bulk. This request includes an array of operations that delete multiple user groups.

{
   "schemas":["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
   "Operations":[
       {
           "method": "DELETE",
           "path": "/Groups/46887262-2ba1-4cee-b3ef-64549423e0b0" 
       },
       {
           "method": "DELETE",
           "path": "/Groups/18d04a36-0894-4f71-bdc4-2610fcc6ae42"
       }
   ]
}

The parameters in the request body are explained below.

Main parameters

Parameter	Required/Optional	Description
`failOnErrors`	Optional	The number of errors that will be accepted by WSO2 IS before returning the response. Possible values: An integer.
`schemas`	Required	This is the schema that is required for sending bulk requests: `urn:ietf:params:scim:api:messages:2.0:BulkRequest`.
`operations`	Required	Array of operations. To delete multiple user groups, add an array of PUT operations. You can include any number of operations in one bulk request. The parameters that can be used for the operation are explained below.

Operation parameters

Parameter	Required/Optional	Description
`method`	Required	The method that should be used in the operation. Possible value:`DELETE`.
`path`	Required	Add this path to specify the existing user group that should be deleted. Possible value:`/Groups/{group_id}`.