You are here

You are here

REST API - Task API

As the name implies the Task API exposes SpringCM services as tasks that can be executed and monitored programmatically.  The Task API includes methods for document generation, document manipulation, advanced search and other long running document operations.

Using the Task API

Tasks are asynchronous and are invoked and monitored in the following way:

  1. A POST request is made passing a Task object to the corresponding Task endpoint to initiate a task operation.  There is a specific task object that corresponds to each task operation endpoint and the properties of the task objects will vary significantly depending on the operation being invoked.  Generally, only a subset of the properties of a Task are required to invoke the operation.
  2. A result object is returned for any Task initiation POST request.  The result objects will vary based on the Task being invoked, however result objects have some commonalities:
    1. An Href property that contains a URI that will uniquely identify the task invocation.  A GET request can be made to this URI to get the status of the task operation and retrieve the results.  For a longer running task, GETs to this URI can be periodically polled to get the current status and results of the task operation.
    2. The Status parameter that indicates the state or result of the operation.  Statuses for most tasks include:  Processing, Success, and Failure.  Some tasks may have specialized statuses, see the Task API documentation for more information.
    3. Result properties that will vary based on the task. 
  3. Some tasks will allow the operation to be canceled.  This is done via a DELETE request to the task URI.

Note:  Although SpringCM’s Advanced Workflow engine is a long running series of tasks, it is not exposed via the Task API.  The engine’s workflows, work items, and queues are considered objects and are exposed in the Object API as opposed to the Task API.

Document Search Tasks - "Contract" in the document name - Sample Request

{
headers:  Accept: 'application/json' 
uri: https://apina11.springcm.com/v201411/documentsearchtasks
method: POST
json:
{
  "Title":"Contract"
}

Document Search Tasks - "Contract" in the document name - Sample Response

{
  "Status": "Success",
  "Result": {
    "Items": [
      {
        "Name": "Company ABC Contract.pdf",
        "CreatedDate": "2015-04-21T15:54:28.653Z",
        "CreatedBy": "klitwin@springcm.com",
        "UpdatedDate": "2015-05-03T17:59:35.41Z",
        "UpdatedBy": "klitwin@springcm.com",
        "Description": "",
        "ParentFolder": {
          "Href": "https://apina11.springcm.com/v201411/folders/7506bd38-4e91-df11-9372-001cc448da6a"
        },
        "HistoryItems": {
          "Href": "https://apina11.springcm.com/v201411/documents/e0db92b0-3ee8-e411-a9d7-3863bb335c14/historyitems"
        },
        "AccessLevel": {
          "See": true,
          "Read": true,
          "Write": true,
          "Move": true,
          "Create": true,
          "SetAccess": true
        },
        "PageCount": 1,
        "Lock": {
          "Href": "https://apina11.springcm.com/v201411/documents/e0db92b0-3ee8-e411-a9d7-3863bb335c14/lock"
        },
        "PreviewUrl": "https://na11.springcm.com/atlas/documents/preview.aspx?aid=6410&lduid=e0db92b0-3ee8-e411-a9d7-3863bb335c14",
        "Versions": {
          "Href": "https://apina11.springcm.com/v201411/documents/e0db92b0-3ee8-e411-a9d7-3863bb335c14/versions"
        },
        "ShareLinks": {
          "Href": "https://apina11.springcm.com/v201411/documents/e0db92b0-3ee8-e411-a9d7-3863bb335c14/sharelinks"
        },
        "DocumentProcessTrackingActivities": {
          "Href": "https://apina11.springcm.com/v201411/documents/e0db92b0-3ee8-e411-a9d7-3863bb335c14/documentprocesstrackingactivities"
        },
        "DocumentReminders": {
          "Href": "https://apina11.springcm.com/v201411/documents/e0db92b0-3ee8-e411-a9d7-3863bb335c14/documentreminders"
        },
        "DownloadDocumentHref": "https://apidownloadna11.springcm.com/v201411/documents/e0db92b0-3ee8-e411-a9d7-3863bb335c14",
        "Href": "https://apina11.springcm.com/v201411/documents/e0db92b0-3ee8-e411-a9d7-3863bb335c14"
      },
      {
        "Name": "Company XYZ Contract.pdf",
        "CreatedDate": "2010-12-07T15:47:27.23Z",
        "CreatedBy": "cvanhorn@springcm.com",
        "UpdatedDate": "2010-12-07T15:47:27.23Z",
        "UpdatedBy": "cvanhorn@springcm.com",
        "Description": "",
        "ParentFolder": {
          "Href": "https://apina11.springcm.com/v201411/folders/aea58e35-5801-e011-9c1a-001cc448e3c7"
        },
        "HistoryItems": {
          "Href": "https://apina11.springcm.com/v201411/documents/c512034a-1902-e011-9c1a-001cc448e3c7/historyitems"
        },
        "AccessLevel": {
          "See": true,
          "Read": true,
          "Write": true,
          "Move": true,
          "Create": true,
          "SetAccess": true
        },
        "PageCount": 3,
        "Lock": {
          "Href": "https://apina11.springcm.com/v201411/documents/c512034a-1902-e011-9c1a-001cc448e3c7/lock"
        },
        "PreviewUrl": "https://na11.springcm.com/atlas/documents/preview.aspx?aid=6410&lduid=c512034a-1902-e011-9c1a-001cc448e3c7",
        "Versions": {
          "Href": "https://apina11.springcm.com/v201411/documents/c512034a-1902-e011-9c1a-001cc448e3c7/versions"
        },
        "ShareLinks": {
          "Href": "https://apina11.springcm.com/v201411/documents/c512034a-1902-e011-9c1a-001cc448e3c7/sharelinks"
        },
        "DocumentProcessTrackingActivities": {
          "Href": "https://apina11.springcm.com/v201411/documents/c512034a-1902-e011-9c1a-001cc448e3c7/documentprocesstrackingactivities"
        },
        "DocumentReminders": {
          "Href": "https://apina11.springcm.com/v201411/documents/c512034a-1902-e011-9c1a-001cc448e3c7/documentreminders"
        },
        "DownloadDocumentHref": "https://apidownloadna11.springcm.com/v201411/documents/c512034a-1902-e011-9c1a-001cc448e3c7",
        "Href": "https://apina11.springcm.com/v201411/documents/c512034a-1902-e011-9c1a-001cc448e3c7"
      }
    ],
    "Href": "https://apina11.springcm.com/v201411/documentsearchtasks/1fe928eb-26ac-48e7-93c3-fe2e229c77a6/Result",
    "Offset": 0,
    "Limit": 20,
    "First": "https://apina11.springcm.com/v201411/documentsearchtasks/1fe928eb-26ac-48e7-93c3-fe2e229c77a6/Result",
    "Last": "https://apina11.springcm.com/v201411/documentsearchtasks/1fe928eb-26ac-48e7-93c3-fe2e229c77a6/Result",
    "Total": 2
  },
  "Href": "https://apina11.springcm.com/v201411/documentsearchtasks/1fe928eb-26ac-48e7-93c3-fe2e229c77a6"
}

Copy Document Tasks - Initiate Copy - Sample Request

headers:  Accept: 'application/json' 
uri: https://apina11.springcm.com/v201411/copytasks
method: POST
json:
{
  "DocumentsToCopy": [
    {
      "Href": "https://apina11.springcm.com/v201411/documents/e0db92b0-3ee8-e411-a9d7-3863bb335c14"
    }
  ],
  "DestinationFolder": {
    "Href": "https://apina11.springcm.com/v201411/folders/16caaf38-4e91-df11-9372-001cc448da6a"
  }
}

Copy Document Tasks - Initiate Copy - Sample Response

{
  "Status": "Processing",
  "Href": "https://apina11.springcm.com/v201411/copytasks/95a91709-4a73-492f-9f36-11e18fd81b19"
}

Copy Document Tasks - Check Status - Sample Request

headers:  Accept: 'application/json' 
uri: https://apina11.springcm.com/v201411/copytasks/95a91709-4a73-492f-9f36-11e18fd81b19
method: GET

Copy Document Tasks - Check Status - Sample Response

{
  "DocumentResults": [
    {
      "Href": "https://apina11.springcm.com/v201411/documents/b11b6fc3-e4f1-e411-a9d7-3863bb335c14"
    }
  ],
  "FolderResults": [],
  "FailedDocuments": [],
  "FailedFolders": [],
  "Status": "Success",
  "Href": "https://apina11.springcm.com/v201411/copytasks/95a91709-4a73-492f-9f36-11e18fd81b19"
}

Document Generation Tasks

Many of the task operations will result in a new document being created.  For these tasks, there are two options for how the resulting document is handled:

  1. Document is stored in SpringCM – The new document is intended to be created and stored as a permanent document in SpringCM.  In this case, there are two required fields that must be passed in the task request object: DestinationDocumentName and DestinationFolder.  When the task successfully completes, the result object will have a ResultDocument property that contains a document object representing the newly created document in SpringCM.
  2. Document is only downloaded – The new document is not stored in SpringCM and is intended only to be used by the calling application.  In this case, the document is created in temporary storage and can be downloaded via the API for 24 hours (check this). If the DestinationDocumentName and DestinationFolder are not specified in the task request, the document will not be stored in SpringCM and will only be available for download via a GET request to the result objects DownloadUrl property.  This download is secured and may only be accessed by passing an access token in the context of the user that initiated the task operation (check this too).  
Merging PDF's - Initiate Merge - Sample Request

headers:  Accept: 'application/json' 
uri: https://apina11.springcm.com/v201411/documentmergetasks
method: POST
json:
{
  "DocumentsToMerge": [
    {
      "Href": "https://apiqana11.springcm.com/v201411/documents/ac0de547-e5f1-e411-a9d7-3863bb335c14"
    },
    {
      "Href": "https://apiqana11.springcm.com/v201411/documents/b11b6fc3-e4f1-e411-a9d7-3863bb335c14"
    }
  ],
  "DeleteOriginals": true,
  "DestinationFolder": {
    "Href": "https://apiqana11.springcm.com/v201411/folders/16caaf38-4e91-df11-9372-001cc448da6a"
  },
  "DestinationDocumentName": "Final Contract.pdf"
}

Merging PDF's - Initiate Merge - Sample Response

{
  "Status": "Processing",
  "Href": "https://apina11.springcm.com/v201411/documentmergetasks/e4b9ddcf-205d-464e-ad28-687fa2c2f6f1"
}

Merge Document Tasks - Check Status - Sample Request

headers:  Accept: 'application/json' 
uri: https://apina11.springcm.com/v201411/documentmergetasks/e4b9ddcf-205d-464e-ad28-687fa2c2f6f1
method: GET

Merge Document Tasks - Check Status - Sample Response

{
  "ResultDocument": {
    "Name": "Final Contract.pdf",
    "CreatedDate": "2015-05-03T23:00:34.003Z",
    "CreatedBy": "klitwin@springcm.com",
    "UpdatedDate": "2015-05-03T23:00:34.003Z",
    "UpdatedBy": "klitwin@springcm.com",
    "Description": "",
    "ParentFolder": {
      "Href": "https://apina11.springcm.com/v201411/folders/16caaf38-4e91-df11-9372-001cc448da6a"
    },
    "HistoryItems": {
      "Href": "https://apina11.springcm.com/v201411/documents/88ffac33-e8f1-e411-a9d7-3863bb335c14/historyitems"
    },
    "AccessLevel": {
      "See": true,
      "Read": true,
      "Write": true,
      "Move": true,
      "Create": true,
      "SetAccess": true
    },
    "PageCount": 2,
    "Lock": {
      "Href": "https://apina11.springcm.com/v201411/documents/88ffac33-e8f1-e411-a9d7-3863bb335c14/lock"
    },
    "PreviewUrl": "https://na11.springcm.com/atlas/documents/preview.aspx?aid=6410&lduid=88ffac33-e8f1-e411-a9d7-3863bb335c14",
    "Versions": {
      "Href": "https://apina11.springcm.com/v201411/documents/88ffac33-e8f1-e411-a9d7-3863bb335c14/versions"
    },
    "ShareLinks": {
      "Href": "https://apina11.springcm.com/v201411/documents/88ffac33-e8f1-e411-a9d7-3863bb335c14/sharelinks"
    },
    "DocumentProcessTrackingActivities": {
      "Href": "https://apina11.springcm.com/v201411/documents/88ffac33-e8f1-e411-a9d7-3863bb335c14/documentprocesstrackingactivities"
    },
    "DocumentReminders": {
      "Href": "https://apina11.springcm.com/v201411/documents/88ffac33-e8f1-e411-a9d7-3863bb335c14/documentreminders"
    },
    "DownloadDocumentHref": "https://apidownloadna11.springcm.com/v201411/documents/88ffac33-e8f1-e411-a9d7-3863bb335c14",
    "Href": "https://apina11.springcm.com/v201411/documents/88ffac33-e8f1-e411-a9d7-3863bb335c14"
  },
  "Status": "Success",
  "Href": "https://apina11.springcm.com/v201411/documentmergetasks/e4b9ddcf-205d-464e-ad28-687fa2c2f6f1"
}