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.
You need to specify the following information in the request payload.
Parameter | Required/Optional | Description |
---|---|---|
failOnErrors |
Optional | The number of errors that will be accepted by WSO2 IS before returning the response. Specify 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 | Specify the array of POST, PUT, PATCH, and/or DELETE operations that should be used to update the information.
Note: You can include any number of operations in one bulk request. See the instructions given below to define the required operations. |
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
{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
isremove
. Optional ifop
isadd
orreplace
.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
path
Required if op
isremove
. Optional ifop
isadd
orreplace
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
isremove
. Optional ifop
isadd
orreplace
.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
{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
path
Required if op
isremove
. Optional ifop
isadd
orreplace
.Specify “members” as the path. Possible values: members
value
Required if op
isadd
orreplace
.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}
.