!!! Overview
[{$pagename}] 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:
* [HTTP POST]
* [HTTP PUT]
* [HTTP PATCH]
* [HTTP DELETE].

[{$pagename}] 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 Client]s 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.

%%prettify 
{{{
"status": {
  "code": "201"
}
}}} /%

The following is an example of a status in a failed operation.
%%prettify 
{{{
"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'.
%%prettify 
{{{
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.
%%prettify 
{{{
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.
%%prettify 
{{{
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.
%%prettify 
{{{
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.
%%prettify 
{{{
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.
%%prettify 
{{{
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:
%%prettify 
{{{
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.
%%prettify 
{{{
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.
%%prettify 
{{{
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.
%%prettify 
{{{
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.
%%prettify 
{{{
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:
[{ReferringPagesPlugin before='*' after='\n' }]