Overview#

SCIM Bulk Request operation enables SCIM Clients to send a potentially large collection of SCIM Resource Operations in a single request.

The body of a bulk operation contains a set of HTTP Resource operations using one of the API supported HTTP methods:

SCIM Bulk Request is OPTIONAL

The following Singular Attribute is defined in addition to the common attributes defined in SCIM core schema.

failOnErrors#

An Integer specifying the number of errors that the SCIM Service Provider will accept before the operation is terminated and an error response is returned. OPTIONAL

The following Complex Multi-valued Attribute is defined in addition to the common attributes defined in core schema.

  • Operations - Defines operations within a bulk job. Each operation corresponds to a single HTTP request against a Resource endpoint. REQUIRED.
  • method - The HTTP method of the current operation. Possible values are POST, PUT, PATCH or DELETE. REQUIRED.
  • bulkId - The transient identifier of a newly created Resource, unique within a bulk request and created by the SCIM Client. The bulkId serves as a surrogate Resource id enabling SCIM Clients to uniquely identify newly created Resources in the Response and cross reference new Resources in and across operations within a bulk request. REQUIRED when method is POST.
  • version - The current Resource version. Version is REQUIRED if the Service Provider supports ETags and the method is PUT, DELETE, or PATCH.
  • path - The Resource's relative path. If the method is POST the value must specify a Resource type endpoint; e.g., /Users or /Groups whereas all other method values must specify the path to a specific Resource; e.g., /Users/2819c223-7f76-453a-919d-413861904646. REQUIRED in a request.
  • data - The Resource data as it would appear for a single POST, PUT or PATCH Resource operation. REQUIRED in a request when method is POST, PUT and PATCH.
  • location - The Resource endpoint URL. REQUIRED in a response, except in the event of a POST failure.
  • status - A complex type that contains information about the success or failure of one operation within the bulk job. REQUIRED in a response.
    • code - The HTTP response code that would have been returned if a single HTTP request would have been used. REQUIRED.
    • description - A human readable error message. REQUIRED when an error occurred.

If a bulk job is processed successfully the HTTP response code 200 OK MUST be returned, otherwise an appropriate HTTP Status Code MUST be returned.

The SCIM Service Provider MUST continue performing as many changes as possible and disregard partial failures. The SCIM Client MAY override this behavior by specifying a value for failOnErrors attribute. The failOnErrors attribute defines the number of errors that the SCIM Service Provider should accept before failing the remaining operations returning the response.

To be able to reference a newly created Resource the attribute bulkId MUST be specified when creating new Resources. The bulkId is defined by the SCIM Client as a surrogate identifier in a POST operation. The SCIM Service Provider MUST return the same bulkId together with the newly created Resource. The bulkId can then be used by the SCIM Client to map the SCIM Service Provider id with the bulkId of the created Resource.

There can be more then one operation per Resource in each bulk job. The Service SCIM Client MUST take notice of the unordered structure of JSON and the SCIM Service Provider can process operations in any order. For example, if the Service SCIM Client sends two PUT operations in one request, the outcome is non-deterministic.

The SCIM Service Provider response MUST include the result of all processed operations. A location attribute that includes the Resource's end point MUST be returned for all operations excluding failed POSTs. The status attribute includes information about the success or failure of one operation within the bulk job. The attribute status MUST include the code attribute that holds the HTTP response code that would have been returned if a single HTTP request would have been used. If an error occurred the status MUST also include the description attribute containing a human readable explanation of the error.

"status": {
  "code": "201"
}

The following is an example of a status in a failed operation.

"status": {
  "code": "400",
  "description": "Request is unparseable, syntactically incorrect, or violates schema."
}

The following example shows how to add, update, and remove a user. The failOnErrors attribute is set to '1' indicating the SCIM Service Provider should return on the first error. The POST operation's bulkId value is set to 'qwerty' enabling the SCIM Client to match the new User with the returned Resource id '92b725cd-9465-4e7d-8c16-01f8e146b87a'.

POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...

{
  "schemas":[
    "urn:scim:schemas:core:1.0"
  ],
  "failOnErrors":1,
  "Operations":[
    {
      "method":"POST",
      "path":"/Users",
      "bulkId":"qwerty",
      "data":{
        "schemas":[
          "urn:scim:schemas:core:1.0"
        ],
        "userName":"Alice"
      }
    },
    {
      "method":"PUT",
      "path":"/Users/b7c14771-226c-4d05-8860-134711653041",
      "version":"W\/\"3694e05e9dff591\"",
      "data":{
        "schemas":[
          "urn:scim:schemas:core:1.0"
        ],
        "id":"b7c14771-226c-4d05-8860-134711653041",
        "userName":"Bob"
      }
    },
    {
      "method":"PATCH",
      "path":"/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
      "version":"W\/\"edac3253e2c0ef2\"",
      "data":{
        "schemas":[
          "urn:scim:schemas:core:1.0"
        ],
        "id":"5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
        "userName":"Dave",
        "meta":{
          "attributes":[
            "nickName"
          ]
        }
      }
    },
    {
      "method":"DELETE",
      "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b",
      "version":"W\/\"0ee8add0a938e1a\""
    }
  ]
}

The SCIM Service Provider returns the following response.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "Operations": [
        {
            "location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
            "method": "POST",
            "bulkId": "qwerty",
            "version": "W\/\"oY4m4wn58tkVjJxK\"",
            "status": {
                "code": "201"
            }
        },
        {
            "location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041",
            "method": "PUT",
            "version": "W\/\"huJj29dMNgu3WXPD\"",
            "status": {
                "code": "200"
            }
        },
        {
            "location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
            "method": "PATCH",
            "version": "W\/\"huJj29dMNgu3WXPD\"",
            "status": {
                "code": "200"
            }
        },
        {
            "location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b",
            "method": "DELETE",
            "status": {
                "code": "200"
            }
        }
    ]
}

The following response is returned if an error occurred when attempting to create the User 'Alice'. The SCIM Service Provider stops processing the bulk operation and immediately returns a response to the SCIM Client. The response contains the error and any successful results prior to the error.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "Operations": [
    {
      "method": "POST",
      "bulkId": "qwerty",
      "status": {
        "code": "400",
        "description": "Request is unparseable, syntactically incorrect, or violates schema."
      }
    }
  ]
}

If the failOnErrors attribute is not specified or the SCIM Service Provider has not reached the error limit defined by the SCIM Client the SCIM Service Provider will continue to process all operations. The following is an example in which all operations failed.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "Operations": [
    {
      "method": "POST",
      "bulkId": "qwerty",
      "status": {
        "code": "400",
        "description": "Request is unparseable, syntactically incorrect, or violates schema."
      }
    },
    {
      "location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041",
      "method": "PUT",
      "status": {
        "code": "412",
        "description": "Failed to update as user changed on the server since you last retrieved it."
      }
    },
    {
      "location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
      "method": "PATCH",
      "status": {
        "code": "412",
        "description": "Failed to update as user changed on the server since you last retrieved it."
      }
    },
    {
      "location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b",
      "method": "DELETE",
      "status": {
        "code": "404",
        "description": "Specified resource; e.g., User, does not exist."
      }
    }
  ]
}

The SCIM Client can, within one bulk operation, create a new User, a new Group and add the newly created User to the newly created Group. In order to add the new User to the Group the SCIM Client MUST use the surrogate id attribute, bulkId, to reference the User. The bulkId attribute value MUST be pre-pended with the literal "bulkId:"; e.g., if the bulkId is 'qwerty' the value is “bulkId:qwerty”. The SCIM Service Provider MUST replace the string “bulkId:qwerty” with the permanent Resource id once created.

The following example creates a User with the userName 'Alice' and a Group with the displayName 'Tour Guides' with Alice as a member.

POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "Operations": [
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "qwerty",
      "data": {
        "schemas": [
          "urn:scim:schemas:core:1.0"
        ],
        "userName": "Alice"
      }
    },
    {
      "method": "POST",
      "path": "/Groups",
      "bulkId": "ytrewq",
      "data": {
        "schemas": [
          "urn:scim:schemas:core:1.0"
        ],
        "displayName": "Tour Guides",
        "members": [
          {
            "type": "user",
            "value": "bulkId:qwerty"
          }
        ]
      }
    }
  ]
}

The SCIM Service Provider returns the following response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "Operations": [
    {
      "location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
      "method": "POST",
      "bulkId": "qwerty",
      "version": "W\/\"4weymrEsh5O6cAEK\"",
      "status": {
        "code": "201"
      }
    },
    {
      "location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
      "method": "POST",
      "bulkId": "ytrewq",
      "version": "W\/\"lha5bbazU3fNvfe5\"",
      "status": {
        "code": "201"
      }
    }
  ]
}

A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f-4109-8486-d5c6a331660a') returns the following:

GET /v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8

HTTP/1.1 200 OK
Content-Type: application/json
Location: https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
ETag: W/"lha5bbazU3fNvfe5"

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
  "displayName": "Tour Guides",
  "meta": {
    "created":"2011-08-01T18:29:49.793Z",
    "lastModified":"2011-08-01T20:31:02.315Z",
    "location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
    "version": "W\/\"lha5bbazU3fNvfe5\""
  },
  "members": [
    {
      "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
      "type": "user"
    }
  ]
}

Extensions that include references to other Resources MUST be handled in the same way by the SCIM Service Provider. The following example uses the bulkId attribute within the enterprise extension managerId attribute.

POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "Operations": [
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "qwerty",
      "data": {
        "schemas": [
          "urn:scim:schemas:core:1.0"
        ],
        "userName": "Alice"
      }
    },
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "ytrewq",
      "data": {
        "schemas": [
          "urn:scim:schemas:core:1.0",
          "urn:scim:schemas:extension:enterprise:1.0"
        ],
        "userName": "Bob",
        "urn:scim:schemas:extension:enterprise:1.0": {
          "employeeNumber": "11250",
          "manager": {
            "managerId": "batchId:qwerty",
            "displayName": "Alice"
          }
        }
      }
    }
  ]
}

The SCIM Service Provider MUST try to resolve circular cross references between Resources in a single bulk job but MAY stop after a failed attempt and instead return the status code 409 Conflict. The following example exhibits the potential conflict.

POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...

{
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "Operations": [
    {
      "method": "POST",
      "path": "/Groups",
      "bulkId": "qwerty",
      "data": {
        "schemas": [
          "urn:scim:schemas:core:1.0"
        ],
        "displayName": "Group A",
        "members": [
          {
            "type": "group",
            "value": "bulkId:ytrewq"
          }
        ]
      }
    },
    {
      "method": "POST",
      "path": "/Groups",
      "bulkId": "ytrewq",
      "data": {
        "schemas": [
          "urn:scim:schemas:core:1.0"
        ],
        "displayName": "Group B",
        "members": [
          {
            "type": "group",
            "value": "bulkId:qwerty"
          }
        ]
      }
    }
  ]
}

If the SCIM Service Provider resolved the above circular references the following is returned from a subsequent GET request.

GET /v1/Groups?filter=displayName sw 'Group'
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8

HTTP/1.1 200 OK
Content-Type: application/json

{
  "totalResults": 2,
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
  "Resources": [
    {
      "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
      "schemas": [
        "urn:scim:schemas:core:1.0"
      ],
      "displayName": "Group A",
      "meta": {
        "created":"2011-08-01T18:29:49.793Z",
        "lastModified":"2011-08-01T18:29:51.135Z",
        "location":"https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
        "version":"W\/\"mvwNGaxB5SDq074p\""
      },
      "members": [
        {
          "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
          "type": "group"
        }
      ]
    },
    {
      "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
      "schemas": [
        "urn:scim:schemas:core:1.0"
      ],
      "displayName": "Group B",
      "meta": {
        "created":"2011-08-01T18:29:50.873Z",
        "lastModified":"2011-08-01T18:29:50.873Z",
        "location":"https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
        "version":"W\/\"wGB85s2QJMjiNnuI\""
      },
      "members": [
        {
          "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
          "type": "group"
        }
      ]
    }
  ]
}

The SCIM Service Provider MUST define a limit on how many operations can be sent in one bulk request. The SCIM Service Provider MUST also define the max payload size of a bulk request. If either limits are exceeded the SCIM Service Provider MUST return the HTTP response code 413 Request Entity Too Large. The returned response must also include the attributes maxOperations and maxPayloadSize with the limits accepted by the SCIM Service Provider.

In the following example the SCIM Client sent a request that exceeded the SCIM Service Provider's max payload size 1 megabyte.

POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: 4294967296

…

HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json
Location: https://example.com/v1/Bulk/yfCrVJhFIJagAHj8

{
  "maxOperations": 1000,
  "maxPayload": 1048576
}

More Information#

There might be more information for this subject on one of the following:

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-5) was last changed on 22-May-2016 04:30 by jim