Skip to content

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": [
                   {
                       "value": "[email protected]",
                   },
                   {
                       "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}.

Top