Posted Mar 05 by Peng Qiu.
Updated Mar 05.

This guide walks you through two resources related to batch operations in Documentum REST Services.

Last activity Mar 05 by Peng Qiu.
54 views. 0 comments.

Overview

The Batches and Batch Capabilities resources are provided since Documentum REST Services 7.2. Through the Batches resource, clients are able to execute a bunch of operations through one HTTP request with options, e.g., in a transaction or not.

The Batch Capabilities resource tells clients what features are supported by the Batch resource.

Find the batch resources

If you make a GET request to Repository resource, two link relations related to batch operations will be found:

  • http://identifiers.emc.com/linkrel/batches
  • http://identifiers.emc.com/linkrel/batch-capabilities
{
    "id": 2,
    "name": "REPO1",
    "description": "",
    "auth-protocol": "",
    "servers": [
        ...
    ],
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/batches",
            "href": "http://localhost:8080/dctm-rest/repositories/REPO1/batches"
        },
        {
            "rel": "http://identifiers.emc.com/linkrel/batch-capabilities",
            "href": "http://localhost:8080/dctm-rest/repositories/REPO1/batch-capabilities"
        },
        ...
    ]
}

Batch capabilities resource

The Batch capabilities resource only supports the GET method. The response indicates which resources can or cannot be put in a batch.

enter image description here

Note that the value both in elements transactions, sequence and on-error means either mode of using that feature is supported when executing a batch in a REST server. The detailed definition for these features will be introduced in the next section.

Batches resource

The Batches resource supports only the HTTP POST method. The server will execute a batch and send back the response until the batch execution is done.

Batch parameters and representation

REST Services provide the following parameters for the client to specify how the server executes a batch.

  • transaction

Since there can be many operations defined in one batch, clients can decide whether to put all operations in a transaction, or execute them separately. Valid values are true(default) and false.

  • sequential

For a non-transactional batch, the server will decide the execution sequence according to this property. True means the server should execute the operations one by one with the submitted sequence. Otherwise, the server may try to execute operations in parallel despite the original order. For a transactional batch, this value will be ignored. Valid values are true(default) and false.

  • on-error

This property is applicable only for a sequentially executed and non-transactional batch. In this case, if the server fails on one operation, the server has two options to finish the batch: fail immediately, or continue on for unfinished operations. Valid values are fail(default) and continue.

For a transactional batch, a failed operation will rollback the whole batch. For a non-sequential and non-transactional batch, since the operations are not executed in order, the value of on-error will be ignored.

  • return-request

This parameter defines whether to return the request message together with the response. Valid values are true and false(default).

Besides the global parameters described above, detailed information for each operation is also needed, e.g., request URI, http method, or even the operation request body. All information for a batch request will be included in a representation as follows.

<?xml version="1.0" encoding="UTF-8"?>
<batch xmlns="http://identifiers.emc.com/vocab/documentum">
    <description>a sample batch</description>
    <transactional>false</transactional>
    <sequential>true</sequential>
    <on-error>continue</on-error>
    <return-request>true</return-request>
    <operations>
        <operation id="op1">
            <description>get a document</description>
            <request method="GET" uri="/repositories/REPO1/objects/08000002800022e5">
                <header name="Content-Type" value="application/xml" />
                <header name="Accept" value="application/json" />
            </request>
        </operation>
        <operation id="op2">
            <request method="POST" uri="/repositories/REPO1/folders/0c00000280000105/objects">
                <header name="Content-Type" value="application/xml" />
                <header name="Accept" value="application/json" />
                <entity>...</entity>
                <attachment>
                    <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="..." />
                </attachment>
            </request>
        </operation>
    </operations>
</batch>

Note that:

  • Each operation must have an unique id within the whole batch
  • The operation must have a request defined, and the request must have method and uri.
  • Specific headers of a request can be defined in the element header.
  • Contents in entity is the request body of this request.
  • The attachment defines the attachment content id for the multipart batch, which can embed the binary content in a single batch request.

After execution, the server will still return a batch representation in the response. It contains the request information, as well as the results of the requested operations.

Request and response

The following is a sample of batch request and response in XML.

Request body:

enter image description here

Response body:

enter image description here

Multipart contents

If one or more operations need to send a binary content (for example, creating an object or a document with content), you will have two choices.

One is embedding multipart contents in the entity part of each operation, while the Content-Type of the whole request can still be set to application/xml or application/json. For example, you can compose an XML batch like this:

<?xml version="1.0" encoding="UTF-8"?>
<batch>
  <return-request>true</return-request>
  <operations>
    <operation id="id-100">
      <description>create object with content</description>
      <request method="POST" uri="/repositories/REPO/folders/0c00208080000107/objects">
        <header name="Content-Type" value="multipart/form-data; boundary=frontier"/>
        <header name="Accept" value="application/vnd.emc.documentum+xml"/>
        <entity>


--frontier
Content-Disposition: form-data; name="metadata"
Content-Type: application/vnd.emc.documentum+xml

<object><properties><object_name>my-test-doc</object_name></properties></object>
--frontier
Content-Disposition: form-data; name="binary"
Content-Type: text/plain

this is binary content
--frontier--
        </entity>
      </request>
    </operation>
  </operations>
</batch>

This batch contains only one operation, where an object is meant to be created. Just like a simple non-batch request, both the metadata and the content are sent as form-data and separated by a boundary named frontier. Note that when sending multipart contents in the entity with XML representation, it can not be wrapped with CDATA. It must be escaped as a normal XML string.

The other choice to send multipart contents is building the entire batch request as a multipart request. The batch representation itself is in a part, and the rest binary contents are in the following parts with the same sequence as defined in the batch operations.

In this scenario, the Content-Type must be Multipart/Related. And it has several parameters:

  • boundary (required)
    The boundary is used to separate the parts.
  • type (required)
    Describe the media type of request wrapped in the multipart/related, it must be application/xop+xml or application/jop+json.
  • start (optional)
    From which part the batch starts. It refers to Content-ID of the part headers. All other parts will be ignored, until the part whose Content-ID header equals to the value of the 'start' parameter. If the 'start' parameter is not provided, then the first part is the 'start' part. And the 'start' part must be the batch request itself.
  • start-info (required)
    The media type of the 'start' part. It must be application/vnd.emc.documentum+xml or application/vnd.emc.documentum+json.

A sample multipart batch in JSON can be found below:

enter image description here

Note that an extra element attachment is introduced to link an operation with one or more parts of content.

Here is another request body in XML. In this instance, the operation id-100 contains two attachments whose IDs are id-100-content-1 and id-100-content-2.

--frontier
Content-Type: application/xop+xml; type="application/vnd.emc.documentum+xml"
Content-ID: batch
Content-disposition: form-data; name=batch

<?xml version="1.0" encoding="UTF-8"?>
<batch>
  <transactional>true</transactional>
  <sequential>true</sequential>
  <operations>
    <operation id="id-100">
      <request method="POST" uri="/repositories/REPO/folders/0c00208080000107/objects">
        <header name="Content-Type" value="application/vnd.emc.documentum+xml"/>
        <header name="Accept" value="application/vnd.emc.documentum+xml"/>
        <entity>
          <object><properties><object_name>my-test-doc</object_name></properties></object>
        </entity>
        <attachments>
          <attachment><xop:Include xmlns:xop='http://www.w3.org/2004/08/xop/include' href='cid:id-100-content-1'/></attachment>
          <attachment><xop:Include xmlns:xop='http://www.w3.org/2004/08/xop/include' href='cid:id-100-content-2'/></attachment>
        </attachments>
      </request>
    </operation>
    <operation id="id-101">
      <request method="POST" uri="/repositories/REPO/folders/0c00208080000107/objects">
        <header name="Content-Type" value="application/vnd.emc.documentum+xml"/>
        <header name="Accept" value="application/vnd.emc.documentum+xml"/>
        <entity>
          <object><properties><object_name>my-test2-doc</object_name></properties></object>
        </entity>
        <attachment><xop:Include xmlns:xop='http://www.w3.org/2004/08/xop/include' href='cid:id-101-content'/></attachment>
      </request>
    </operation>
  </operations>
</batch>

--frontier
Content-Type: text/plain
Content-ID: id-100-content-1
Content-disposition: form-data; name=id-100-content-1

i'm the content of id-100-1

--frontier
Content-Type: text/plain
Content-ID: id-100-content-2
Content-disposition: form-data; name=id-100-content-2

i'm the content of id-100-2

--frontier
Content-Type: text/plain
Content-ID: id-101-content
Content-disposition: form-data; name=id-101-content

i'm the content of id-101

--frontier-- 

Troubleshooting

To send a batch request to the Batches resource, you may reuse any client lib or tools or even existed code. The batch operation request has the same format as sending the request to that resource directly. You just need to put the single request headers in the “header” sections of each batch operation request, and put the whole single request body as a string value in the “entity” section. Vice versa, the operation response's headers are put in the “header” sections of each batch operation response, together with the response body in the “entity” as the string value.

However, for a multipart batch request, you have to compose the request body by yourself. For example, if you are using Spring RestTemplate as a client lib, you have to implement your own HttpMessageConverter to handle the request, because the media type “multipart/related” are not supported by default. Or you can use any technology, if only it follows both the multipart protocol and the batch representation requirement.

Here are some tips for troubleshooting if you have problems using batch resources.

  • Check the Batches resource response for the error messages, and the server log. Or even turn on the
    trace log for more detailed information
  • Following the develop guide to change the batch configurations
  • Change the batch properties, e.g. change the non-transactional and non-sequential batch to transactional or sequential
  • For a multipart batch, trying to resend as a simple batch without the attachments
  • Reduce the batch operations count for a single batch

Table of Contents

Your comment

To leave a comment, please sign in.