1. REST API for Content Capture
  2. Tasks
  3. Attachments

Update an Attachment

put

/capture/api/v1.1/documents/{docId}/attachments/{attId}

This operation is used to modify an attachment. It allows for both the attachment data, and its content, to be modified in a single operation.

The request body of the operation requires at least the attachment parameter. The content parameter is optional, and only necessary if a change of the attachment contents is desired.

The attachment object of the request bodies essentially patches the attachment with the attributes that are both present in the request body and updatable. A merge-patch media sub-type isn't used to be consistent with other operations that cannot use a merge-patch. Even though a merge-patch isn't used, just the desired changes are required in the request body, and therefore, just the fields that are being updated need to be present. The updatable attributes are:

  • title
  • type
  • comment

An update to either the title or comment is a simple string change. An update to the attachment type (type) requires setting its value to a different attachment type object. The object must contain either the id attribute or the name attribute, or it can contain both. Only one attribute is necessary because the names are unique in the procedure definition. To clear a current attachment type, its value in the document object must be set to null.

The attachment object must also contain its stateToken. This is necessary to ensure the object is still the same that is being updated. The stateToken will be different if it was was already updated from the last time it was requested. This ensures there aren't concurrent updates, and prevents overwriting of data.

It is an error if the attachment is not attached to the given document.

Note: The OAuth token used in this request must represent an account that has been granted explict access to the step in which this document presently resides. It makes no difference if the account represents a Capture Administator or a Capture User.

Request

Supported Media Types
Path Parameters
Header Parameters

  • A header used to prevent Cross-Site Request Forgery (CSRF) attacks. The only supported value is XMLHttpRequest.

Form Parameters

  • This is an attachment object. The Content-Type of the mulitpart must be used and must identify the application encoding used for the string value. This must be application/json.

    The attachment object must also contain its stateToken that represents its believed current state. If the supplied stateToken does not match the attachment's current stateToken, the update operation will result in an error.

  • This is the actual attachment content, for instance, an updated image as a result of processing.

    The Content-Type of the mulitpart must identify the type of file. And, the Content-Disposition must contain the filename.

Back to Top

Response

Supported Media Types

200 Response

The attachment, containing any updates.

Body ()
Root Schema : Attachment
Type: object
Title: Attachment

An Attachment in Capture is a file that contains auxiliary content for a Document. In essence, its structure is very similar to that of a Document; however, there are no metadata fields.

Show Source
Nested Schema : batch
Type: object

The Capture Batch that contains this attachment's parent document.

Match All
Show Source
  • Capture Batch
    Title: Capture Batch

    A collection of documents in Capture that represent a unit of work in a procedure.

Nested Schema : createdBy
Type: object

The user that created the attachment.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : step
Type: object

The current processing step, if any, this attachment's parent document is undergoing.

Match All
Show Source
Nested Schema : type
Type: object

The attachment type that has been assigned to this attachment.

Match All
Show Source
  • Attachment Type
    Title: Attachment Type

    An Attachment Type can be used to categorize, and provides process filtering, of attachents of documents.

Nested Schema : updatedBy
Type: object

The last user that updated the attachment.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : Capture Batch
Type: object
Title: Capture Batch

A collection of documents in Capture that represent a unit of work in a procedure.

Show Source
  • createdBy

    The user that created the batch.

  • This identifies when the batch was created. The date/time in ISO-8601 Date Time format (yyyy-MM-dd'T'HH:mm:ss.SSSZ) UTC, governed by RFC 3339.

  • The current error message of the batch, if any.

    If the batch is in the ERROR state, this will contain the error message detailing why the batch failed processing. This message will remain until the batch re-enters processing.

  • The unique identifier of the batch.

  • links
  • lock

    If the batch is locked (by a user creating/editing the batch or if Capture is currently processing the batch), this object will contain information about the lock. The state of the batch determines if this object exists.

  • The name given to the batch.

    When Capture creates a batch, the name is some defined prefix and a sequence number. For example, inv_4781

  • User supplied general notes associated with a batch.

  • Minimum Value: 0
    Maximum Value: 10
    Default Value: 0

    A user specified priority of the batch.

    This value is used prioritize the batch for a user's attention. Its used to filter and sort batches for viewing in the client.

  • procedure

    The Capture Procedure associated with this batch.

  • Default Value: READY

    The current state of the batch.

    • READY - The standard resting state of a batch. It is available to be locked by a client.
    • LOCKED - The batch is locked by a client for editing, such as adding/removing documents and setting metadata field values.
    • ERROR - An error occurred during processing. It is available to be locked by a client for edits to correct processing errors.
    • PROCESSING - Capture is presently processing the batch. The batch is in one of the jobs defined in the Capture procedure.

  • The current status assigned to the batch.

    The status values are defined in the procedure and can be assigned during batch creation, and during transitions between processing jobs.

  • updatedBy

    The last user that updated the batch. This can be the Capture system.

  • This identifies when the last time the batch was updated. The date/time in ISO-8601 Date Time format (yyyy-MM-dd'T'HH:mm:ss.SSSZ) UTC, governed by RFC 3339.

Nested Schema : createdBy
Type: object

The user that created the batch.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : lock
Type: object

If the batch is locked (by a user creating/editing the batch or if Capture is currently processing the batch), this object will contain information about the lock. The state of the batch determines if this object exists.

Show Source
Nested Schema : procedure
Type: object

The Capture Procedure associated with this batch.

Match All
Show Source
Nested Schema : updatedBy
Type: object

The last user that updated the batch. This can be the Capture system.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : User Information
Type: object
Title: User Information

This object contains information about a given user of Capture.

Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Show Source
Nested Schema : lockedBy
Type: object

If the batch is locked within a Capture Client instance, this attribute will contain the user that locked the batch.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : step
Type: object

If Capture is currently processing the batch, this object will contain current processing step the batch is undergoing.

Match All
Show Source
Nested Schema : Procedure Step
Type: object
Title: Procedure Step

A step in a procedure flow.

Show Source

  • The unique identifier of the step within the procedure.

  • The name given to the step when created. For instance, the name of the processing job or commit profile.

  • The type of step. Some example include: External Processor, TIFF Conversion Processor, Asset Lookup Processor, etc.

Nested Schema : Capture Procedure
Type: object
Title: Capture Procedure

A Capture Procedure defines metadata and procesing steps of a flow.

Show Source
Nested Schema : Attachment Type
Type: object
Title: Attachment Type

An Attachment Type can be used to categorize, and provides process filtering, of attachents of documents.

Show Source

400 Response

Bad Request

The request could not be processed because it contains missing or invalid information, such as a validation error on an input field or a missing required value. The response will be an Error Detail object.

403 Response

Forbidden

The request was valid and was understood, but the server is refusing action. This may be due to the account not having the necessary permissions for a resource, or attempting a prohibited action (e.g. creating a duplicate item where only one is allowed). The response will be an Error Detail object.

404 Response

Not Found

The request includes a resource URI that does not exist. The response will be an Error Detail object.

409 Response

Conflict

This response indicates the request conflicts with current state of the target resource. The response will be an Error Detail object.

Generally, an error response of 412 (Precondition Failed) will be returned. But a Conflict can occur when there are simultaneous edits on a resource.

412 Response

Precondition Failed

The server does not meet one of the preconditions of the request. The response will be an Error Detail object.

This error response is used specifically when the stateToken used in the request body does not match the current stateToken of the resource.

500 Response

Internal Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request. The response will be an Error Detail object.

Back to Top

Examples

Example 1:

The following example shows how to get an attachment.

curl -X PUT -H 'Accept: application/json' 'https://host:port/content/capture/api/v1/documents/dcf65d45-4f53-4f82-998c-5e189de1b6a1/attachments/b22046ce-2c30-49b3-b734-25f62dea5403'

This updates the attachment with the ID of 'b22046ce-2c30-49b3-b734-25f62dea5403' for the document with the ID 'dcf65d45-4f53-4f82-998c-5e189de1b6a1' to change its title. The request body for this operation is a content type of multipart/form-data. So, the example shows the raw HTTP PUT.

Request Body

PUT /capture/api/v1/documents/dcf65d45-4f53-4f82-998c-5e189de1b6a1 HTTP/1.1
Host: server.example.com:443
X-Requested-With: XmlHttpRequest
Authorization: Basic c3N2cmludC5tdGFkbWluOndlbGNvbWUx
Content-Length: 218
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="attachment"
Content-Type: application/json

{
    "title": "Notes Title",
    "stateToken": "340f804ff4118f2f419bc3ca87ef1213"
}
----WebKitFormBoundary7MA4YWxkTrZu0gW

Response Body

{
    "id": "27d68830-ee2d-4b75-9b75-e2feeeb11909",
    "documentId": "dcf65d45-4f53-4f82-998c-5e189de1b6a1",
    "title": "Notes Title",
    "batch": {
        "id": "864",
        "name": "ep_53"
    },
    "step": {
        "id": "a82321c2-f288-4545-8795-e3c0f035f7ba",
        "name": "Find Invoice Date",
        "type": "External Processor"
    },
    "type": {
        "id": "1d3340ca-3fcb-43f7-9304-89cfedb1ac69",
        "name": "Invoice Notes"
    },
    "stateToken": "23421e50c982fad3d8375737a1c46eee",
    "mediaType": "text/plain",
    "sourceName": "notes5.txt",
    "size": 4815,
    "createdBy": {
        "name": "ssvrint.mtadmin"
    },
    "createdDate": "2021-09-19T20:05:14.215Z",
    "updatedBy": {
        "name": "ssvrint.mtadmin"
    },
    "updatedDate": "2021-09-19T20:05:14.215Z",
    "links": [
        {
            "rel": "canonical",
            "href": "http://server.example.com/documents/dcf65d45-4f53-4f82-998c-5e189de1b6a1/attachments/27d68830-ee2d-4b75-9b75-e2feeeb11909",
            "method": "GET",
            "mediaType": "application/json"
        },
        {
            "rel": "urn:oce:capture:attachment-content",
            "href": "http://server.example.com/documents/dcf65d45-4f53-4f82-998c-5e189de1b6a1/attachments/27d68830-ee2d-4b75-9b75-e2feeeb11909/content",
            "method": "GET",
            "mediaType": "text/plain"
        }
    ]
}
Back to Top