Jump to

• Request
• Response
• Examples

Get Status of a Bulk Download Job

get

/documents/api/1.2/folders/{folderId}/_download/{jobId}

Returns the status of a bulk download job.

Request

Supported Media Types

• application/json
• application/xml

Path Parameters

• folderId: string

  Globally unique identifier (GUID) for the folder. If the referenced folder is the user's home folder, the value for folderId is self.

• jobId: string

  Globally unique identifier (GUID) for the bulk download job.

Back to Top

Response

Supported Media Types

• application/json
• application/xml

200 Response

The request was fulfilled.

Body ()

Root Schema : FolderStatusBulkZipResponse

Type: object

The response body includes information about the bulk zip job.

Show Source

• completed(optional): boolean
  A boolean indicating if the job in complete
• completedPercentage(optional): integer
  A number between 0 and 100, capturing how much of the process has been completed.
• details(optional): object BulkZipFileDetails
  Information about the zip file.
• errorCode(optional): string
  An error code of zero (0) indicates no errors.
• items(optional): object BulkZipItemsDetails
  Optional array of files globally unique identifiers that are not copied to the zip file.
• links(optional): object BulkZipLinkDetails
  Links for a completed job.
• progress(optional): string
  The state of the job. This can be one of the following: SUCCEEDED,FAILED,PROCESSING,PENDING,ABORTED,BLOCKED.

{
    "description":"The response body includes information about the bulk zip job.",
    "type":"object",
    "properties":{
        "completed":{
            "type":"boolean",
            "description":"A boolean indicating if the job in complete"
        },
        "completedPercentage":{
            "type":"integer",
            "description":"A number between 0 and 100, capturing how much of the process has been completed."
        },
        "details":{
            "$ref":"#/definitions/BulkZipFileDetails"
        },
        "items":{
            "$ref":"#/definitions/BulkZipItemsDetails"
        },
        "links":{
            "$ref":"#/definitions/BulkZipLinkDetails"
        },
        "progress":{
            "type":"string",
            "description":"The state of the job. This can be one of the following: SUCCEEDED,FAILED,PROCESSING,PENDING,ABORTED,BLOCKED."
        },
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        }
    }
}

Nested Schema : BulkZipFileDetails

Type: object

Information about the zip file.

Show Source

• filename(optional): string
  The suggested filename when the zip is downloaded.
• filesize(optional): integer
  The file size of zip to be downloaded.

{
    "description":"Information about the zip file.",
    "properties":{
        "filename":{
            "type":"string",
            "description":"The suggested filename when the zip is downloaded."
        },
        "filesize":{
            "type":"integer",
            "description":"The file size of zip to be downloaded."
        }
    }
}

Nested Schema : BulkZipItemsDetails

Type: object

Optional array of files globally unique identifiers that are not copied to the zip file.

Show Source

• error(optional): string
  Currently states Item not available.
• id(optional): string
  The globally unique identifier of the file not copied to the zip.

{
    "description":"Optional array of files globally unique identifiers that are not copied to the zip file.",
    "properties":{
        "id":{
            "type":"string",
            "description":"The globally unique identifier of the file not copied to the zip."
        },
        "error":{
            "type":"string",
            "description":"Currently states <code>Item not available</code>."
        }
    }
}

Nested Schema : BulkZipLinkDetails

Type: object

Links for a completed job.

Show Source

• href(optional): string
  The URL to download the zip file.
• mediaType(optional): string
  The format of the download, this will be application/zip
• method(optional): string
  The method to access the URL, this will be GET
• rel(optional): string
  The relation, this will be enclosure

{
    "description":"Links for a completed job.",
    "properties":{
        "href":{
            "type":"string",
            "description":"The URL to download the zip file."
        },
        "rel":{
            "type":"string",
            "description":"The relation, this will be <code>enclosure</code>"
        },
        "method":{
            "type":"string",
            "description":"The method to access the URL, this will be <code>GET</code>"
        },
        "mediaType":{
            "type":"string",
            "description":"The format of the download, this will be <code>application/zip</code>"
        }
    }
}

Example Response (application/json)

{
    "completed":true,
    "completedPercentage":100,
    "details":{
        "filename":"OCE-20210303.zip",
        "filesize":27811
    },
    "errorCode":0,
    "links":{
        "href":"OCEHost/documents/api/1.2/folders/FE7DA518D17AA5E46E282D9A1B02AE3398E71823807D/_download/43C4798AB49E496B53A27D99F3CE768F1614800841210/package",
        "rel":"enclosure",
        "method":"GET",
        "mediaType":"application/zip"
    },
    "progress":"SUCCEEDED",
    "type":"folder"
}

400 Response

The request is invalid as described by the error returned.

403 Response

Forbidden if the user does not have read permission.

Back to Top

Examples

The following example requests the status on a completed job.

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "completed": "true",
    "completedPercentage": "100",
    "details": {
        "filename": "OCE-20210305.zip",
        "filesize": "774987"
    },
    "errorCode": "0",
    "links": [
        {
            "href": "[OCEHost]/documents/api/1.2/folders/FE7DA518D17AA5E46E282D9A1B02AE3398E71823807D/_download/11E666917053923171255718EFB36B481614961716028/package",
            "rel": "enclosure",
            "method": "GET",
            "mediaType": "application/zip"
        }
    ],
    "progress": "SUCCEEDED",
    "type": "folder"
}

Example 2

The following example requests the status on a completed job, but several files are not copied to the zip:

GET .../folders/FE7DA518D17AA5E46E282D9A1B02AE3398E71823807D/_download/945B2A631ED396410B04ADC5E814EC8B1614898571312

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "completed": "true",
    "completedPercentage": "100",
    "details": {
        "filename": "OCE-20210304.zip",
        "filesize": "8024"
    },
    "errorCode": "0",
    "items": [
        {
            "id": "DC034C1C970D99900684230D1480C189B284D1C79D21",
            "error": "Item not available."
        },
        {
            "id": "D4B22A83BED696112AC9748463A9AA0BDDE61F516AC1",
            "error": "Item not available."
        }
    ],
    "links": [
        {
            "href": "[OCEHost]/documents/api/1.2/folders/FE7DA518D17AA5E46E282D9A1B02AE3398E71823807D/_download/945B2A631ED396410B04ADC5E814EC8B1614898571312/package",
            "rel": "enclosure",
            "method": "GET",
            "mediaType": "application/zip"
        }
    ],
    "progress": "SUCCEEDED",
    "type": "folder"
}

Example 3

The following example requests the status on a in-process job:

GET .../folders/FE7DA518D17AA5E46E282D9A1B02AE3398E71823807D/_download/BF18AE4AC6F86C9247AD2E2CED0092021614899361960

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "completed": "false",
    "completedPercentage": "45",
    "details": {
        "filename": "OCE-20210304.zip",
        "filesize": "0"
    },
    "errorCode": "0",
    "progress": "PROCESSING",
    "type": "folder"
}

Example 4

The following example requests the status on a job owned by a different user. The error returned is not very detailed to prevent data exposure:

GET .../folders/FE7DA518D17AA5E46E282D9A1B02AE3398E71823807D/_download/BF18AE4AC6F86C9247AD2E2CED0092021614899361960

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "errorCode": "-96",
    "errorKey": "!csBulkdownloadUnableToGetStatusJob",
    "errorMessage": "There is no bulkdownload job for the specified job Id.",
    "errorType": "folder",
    "title": "There is no bulkdownload job for the specified job Id.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Back to Top