REST API for Documents

Extract ZIP File into a Folder

post

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

Requests that a ZIP file be extracted to a folder.

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

The request body defines details of how the files will be extracted from the ZIP file.

Root Schema : FileExtractZipBody

Type: object

The request body defines how the files in the zip are extracted.

Show Source

destinationID(optional): string

Specify the globally unique identifier (GUID) of the destination folder to extract files. By default the zip contents will be extracted to the same folder as the zip file.
duplicateResolution(optional): string
Specify how name conflicts between the zip contents and existing files are handled during zip extraction, the default is ResolveDuplicates:
- ResolveDuplicates the extraction will resolve the conflicting name to append a number new file name.
- ReviseDuplicates the extraction will create a new revision of the conflicting document.
- SkipDuplicates the extraction will skip the conflicting file name

{
    "description":"The request body defines how the files in the zip are extracted.",
    "properties":{
        "destinationID":{
            "type":"string",
            "description":"Specify the globally unique identifier (GUID) of the destination folder to extract files. By default the zip contents will be extracted to the same folder as the zip file."
        },
        "duplicateResolution":{
            "type":"string",
            "description":"Specify how name conflicts between the zip contents and existing files are handled during zip extraction, the default is <code>ResolveDuplicates</code>:<ul><li><code>ResolveDuplicates</code> the extraction will resolve the conflicting name to append a number new file name.</li><li><code>ReviseDuplicates</code> the extraction will create a new revision of the conflicting document.</li><li><code>SkipDuplicates</code> the extraction will skip the conflicting file name</li></ul>"
        }
    }
}

Example Request (application/json)

{
    "duplicateResolution":"SkipDuplicates",
    "destinationID":"F4C639F3689B23DC9ADAA8CFC0E6EC85DE64738F6108"
}

Response

Supported Media Types

application/json
application/xml

200 Response

The response body contains information about the extraction job.

Root Schema : FileExtractZipResponse

Type: object

The response body includes information about the zip extraction job.

Show Source

destinationID(optional): string

The GUID of the folder where the zip will be extracted.
errorCode(optional): string

An error code of zero (0) indicates no errors.
id(optional): string

The GUID of the zip file to be extracted.
jobId(optional): string

The GUID of the extraction job.
Location(optional): string

The URL to access the status for this job.
type(optional): string

Item type file.

{
    "description":"The response body includes information about the zip extraction job.",
    "properties":{
        "Location":{
            "type":"string",
            "description":"The URL to access the status for this job."
        },
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        },
        "id":{
            "type":"string",
            "description":"The GUID of the zip file to be extracted."
        },
        "destinationID":{
            "type":"string",
            "description":"The GUID of the folder where the zip will be extracted."
        },
        "jobId":{
            "type":"string",
            "description":"The GUID of the extraction job."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>file</code>."
        }
    }
}

Example Response (application/json)

{
    "Location":"OCMHost/documents/api/1.2/files/D9D9A930B13B25738ACC428B3C6239D683D39CFFC811/_extract/ZX-857509DEBFD7422FFD8D1BF081A9748F1642699937903",
    "destinationID":"F4C639F3689B23DC9ADAA8CFC0E6EC85DE64738F6108",
    "errorCode":"0",
    "id":"D9D9A930B13B25738ACC428B3C6239D683D39CFFC811",
    "jobId":"ZX-857509DEBFD7422FFD8D1BF081A9748F1642699937903",
    "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.

404 Response

File ID is not found.

Examples

After uploading a zip containing 3 images, the following example will create an extraction job to extract the images into the same folder as the uploaded zip.

POST .../files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "Location": "{OCEHost}/documents/api/1.2/files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract/ZX-E83150A29A911D33321FE8A9A6C5814F1643066913096",
    "destinationID": "F80BA045E86F1651028073CA910CABD1145F5DE8845B",
    "errorCode": "0",
    "id": "DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317",
    "jobId": "ZX-E83150A29A911D33321FE8A9A6C5814F1643066913096",
    "type": "file"
}

Example 2

After uploading a zip containing 3 images and creating a folder to extract to, the following example will create an extraction job to extract the images into the specified folder.

POST .../files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract

Request Header

None.

Request Body

{
    "destinationID": "F1DDD707F795A50AADBCCCAB5EB016D8E77A30902D7D"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "Location": "{OCEHost}/documents/api/1.2/files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract/ZX-1032527C9CEAC3CFB0BD3BA8C45BD3EA1643125120730",
    "destinationID": "F1DDD707F795A50AADBCCCAB5EB016D8E77A30902D7D",
    "errorCode": "0",
    "id": "DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317",
    "jobId": "ZX-1032527C9CEAC3CFB0BD3BA8C45BD3EA1643125120730",
    "type": "file"
}

Example 3

After uploading a zip containing 3 images and creating a folder to extract to, the following example will create an extraction job to extract the images into the specified folder and create new versions of existing files.

POST .../files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract

Request Header

None.

Request Body

{
    "destinationID": "F1DDD707F795A50AADBCCCAB5EB016D8E77A30902D7D",
    "duplicateResolution": "ReviseDuplicates"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "Location": "{OCEHost}/documents/api/1.2/files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract/ZX-D51C9BDBAED077E16488336117420E231643125878509",
    "destinationID": "F1DDD707F795A50AADBCCCAB5EB016D8E77A30902D7D",
    "errorCode": "0",
    "id": "DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317",
    "jobId": "ZX-D51C9BDBAED077E16488336117420E231643125878509",
    "type": "file"
}

Example 4

This example will fail because the specified folder does not exist.

POST .../files/DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317/_extract

Request Header

None.

Request Body

{
    "destinationID": "F1DDD707F795A50AADBCCCAB5EB016D8E77A30902D8D",
    "duplicateResolution": "ReviseDuplicates"
}

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "destinationID": "F1DDD707F795A50AADBCCCAB5EB016D8E77A30902D8D",
    "errorCode": "-16",
    "errorKey": "!csBulkExtractionUnableToInitJob!csFldDoesNotExist,F1DDD707F795A50AADBCCCAB5EB016D8E77A30902D8D",
    "errorMessage": "Unable to initialize extraction job. 'F1DDD707F795A50AADBCCCAB5EB016D8E77A30902D8D' does not exist.",
    "errorType": "file",
    "id": "DC765D5CD846E67B395AE676435D1DBF0C5B3FCDE317",
    "title": "Unable to initialize extraction job. 'F1DDD707F795A50AADBCCCAB5EB016D8E77A30902D8D' does not exist.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}