Jump to

• Request
• Response
• Examples

Get Status of an Extraction Job

get

/documents/api/1.2/files/{fileId}/_extract/{jobId}

Returns the status of an extraction job

Request

Supported Media Types

• application/json
• application/xml

Path Parameters

• fileId: string

  Globally unique identifier (GUID) of the ZIP file to be extracted into a folder

• jobId: string

  Globally unique identifier (GUID) for the extraction job.

Query Parameters

• includeIgnoredItemDetails: boolean

  An optional boolean value that defaults to true. If false the ignoredItems array is not included in the response

• includeSkippedItemDetails: boolean

  An optional boolean value that defaults to true. If false the skippedItems array is not included in the response

Back to Top

Response

Supported Media Types

• application/json
• application/xml

200 Response

The request was fulfilled.

Body ()

Root Schema : FileStatusExtractZipResponse

Type: object

The response body includes information about the zip extract 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.
• filesCreated(optional): integer
  The number of files created by the extraction job.
• filesIgnored(optional): integer
  The number of files ignored by the extraction job.
• filesNameAdjusted(optional): integer
  The number of extracted file names that were renamed by the extraction job.
• filesOverwritten(optional): integer
  The number of existing files that were over written by the extraction job.
• filesProcessed(optional): integer
  The number of files processed by the extraction job.
• filesSkipped(optional): integer
  The number of files not extracted by the extraction job.
• filesVersioned(optional): integer
  The number of existing files that had the version increased by the extraction job.
• ignoredItems(optional): object ignoredItems
  An array of zip filenames that were ignored by the extraction job.
• message(optional): string
  A brief message about the status of the extraction job.
• progress(optional): string
  A word indicating the state of the extraction job. Possibilities include:

  • SUCCEEDED -- Job Completed Successfully
  • FAILED -- Job Failed
  • PROCESSING -- Job is processing
  • PENDING -- Job is pending
  • ABORTED -- Job aborted

  .
• skippedItems(optional): object skippedItems
  An array of zip filenames that were skipped by the extraction job.

{
    "description":"The response body includes information about the zip extract job.",
    "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."
        },
        "progress":{
            "type":"string",
            "description":"A word indicating the state of the extraction job. Possibilities include: <ul><li><code>SUCCEEDED</code> -- Job Completed Successfully</li><li><code>FAILED</code> -- Job Failed</li><li><code>PROCESSING</code> -- Job is processing</li><li><code>PENDING</code> -- Job is pending</li><li><code>ABORTED</code> -- Job aborted</li></ul>."
        },
        "message":{
            "type":"string",
            "description":"A brief message about the status of the extraction job."
        },
        "filesProcessed":{
            "type":"integer",
            "description":"The number of files processed by the extraction job."
        },
        "filesIgnored":{
            "type":"integer",
            "description":"The number of files ignored by the extraction job."
        },
        "filesCreated":{
            "type":"integer",
            "description":"The number of files created by the extraction job."
        },
        "filesNameAdjusted":{
            "type":"integer",
            "description":"The number of extracted file names that were renamed by the extraction job."
        },
        "filesVersioned":{
            "type":"integer",
            "description":"The number of existing files that had the version increased by the extraction job."
        },
        "filesOverwritten":{
            "type":"integer",
            "description":"The number of existing files that were over written by the extraction job."
        },
        "filesSkipped":{
            "type":"integer",
            "description":"The number of files not extracted by the extraction job."
        },
        "skippedItems":{
            "type":"object",
            "description":"An array of zip filenames that were skipped by the extraction job.",
            "allOf":{
                "$ref":"#/definitions/FilesSkippedIgnoredByExtractZip"
            }
        },
        "ignoredItems":{
            "type":"object",
            "description":"An array of zip filenames that were ignored by the extraction job.",
            "allOf":{
                "$ref":"#/definitions/FilesSkippedIgnoredByExtractZip"
            }
        }
    }
}

Nested Schema : ignoredItems

Type: object

An array of zip filenames that were ignored by the extraction job.

Match All

Show Source

• object FilesSkippedIgnoredByExtractZip
  Information about why a file was not extracted by the extraction job

{
    "type":"object",
    "description":"An array of zip filenames that were ignored by the extraction job.",
    "allOf":{
        "$ref":"#/definitions/FilesSkippedIgnoredByExtractZip"
    }
}

Nested Schema : skippedItems

Type: object

An array of zip filenames that were skipped by the extraction job.

Match All

Show Source

• object FilesSkippedIgnoredByExtractZip
  Information about why a file was not extracted by the extraction job

{
    "type":"object",
    "description":"An array of zip filenames that were skipped by the extraction job.",
    "allOf":{
        "$ref":"#/definitions/FilesSkippedIgnoredByExtractZip"
    }
}

Nested Schema : FilesSkippedIgnoredByExtractZip

Type: object

Information about why a file was not extracted by the extraction job

Show Source

• error(optional): string
  A brief error message about the status of this item.
• id(optional): string
  The filename in the zip that was not extracted.
• type(optional): string
  The object type, file or directory that was not extracted.

{
    "description":"Information about why a file was not extracted by the extraction job",
    "properties":{
        "id":{
            "type":"string",
            "description":"The filename in the zip that was not extracted."
        },
        "type":{
            "type":"string",
            "description":"The object type, <code>file</code> or <code>directory</code> that was not extracted."
        },
        "error":{
            "type":"string",
            "description":"A brief error message about the status of this item."
        }
    }
}

Example Response (application/json)

{
    "completed":"true",
    "completedPercentage":"100",
    "errorCode":"0",
    "filesCreated":"3",
    "filesIgnored":"0",
    "filesNameAdjusted":"0",
    "filesOverwritten":"0",
    "filesProcessed":"3",
    "filesSkipped":"0",
    "filesVersioned":"0",
    "message":"Zip processing completed",
    "progress":"SUCCEEDED",
    "type":"file"
}

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 gets the status a completed extraction job.

GET .../files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract/ZX-E83150A29A911D33321FE8A9A6C5814F1643066913096

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "completed": "true",
    "completedPercentage": "100",
    "errorCode": "0",
    "filesCreated": "0",
    "filesIgnored": "0",
    "filesNameAdjusted": "0",
    "filesOverwritten": "0",
    "filesProcessed": "3",
    "filesSkipped": "0",
    "filesVersioned": "0",
    "message": "Zip processing completed",
    "progress": "SUCCEEDED",
    "type": "file"
}

Example 2

The following example gets the status a completed extraction job, but the files were skipped as the files were already present in the folder.

GET .../files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract/ZX-930F35D291CEA348255D1974A84CB3571643127919210

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "completed": "true",
    "completedPercentage": "100",
    "errorCode": "0",
    "filesCreated": "0",
    "filesIgnored": "0",
    "filesNameAdjusted": "0",
    "filesOverwritten": "0",
    "filesProcessed": "0",
    "filesSkipped": "3",
    "filesVersioned": "0",
    "message": "Zip processing completed",
    "progress": "SUCCEEDED",
    "skippedItems": [
        {
            "id": "exif-xmp.jpg",
            "type": "file",
            "error": "Entry skipped - existing file with same name in folder"
        },
        {
            "id": "Mugs.jpg",
            "type": "file",
            "error": "Entry skipped - existing file with same name in folder"
        },
        {
            "id": "Mugs.png",
            "type": "file",
            "error": "Entry skipped - existing file with same name in folder"
        }
    ],
    "type": "file"
}

Example 3

The following example gets the status on an in-process extraction job.

GET .../files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract/ZX-930F35D291CEA348255D1974A84CB3571643127919210

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "completed": "false",
    "completedPercentage": "25",
    "errorCode": "0",
    "filesCreated": "0",
    "filesIgnored": "1",
    "filesNameAdjusted": "0",
    "filesOverwritten": "0",
    "filesProcessed": "0",
    "filesSkipped": "0",
    "filesVersioned": "0",
    "message": "Processing entry 6image/./exif-xmp.jpg",
    "progress": "PROCESSING",
    "type": "file"
}

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 .../files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract/ZX-930F35D291CEA348255D1974A84CB3571643127919210

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "errorCode": "-96",
    "errorKey": "!csCloudBulkExtractionRequestJobNotValid",
    "errorMessage": "Extraction job ID not valid.",
    "errorType": "file",
    "title": "Extraction job ID not valid.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Back to Top