Work Files

PrizmDoc v12.2 - March 9, 2017

Work Files

Collapse All

API Reference > PrizmDoc Server RESTful API > Work Files

The work file service is a temporary storage system which allows you to upload file input and download file output. Each work file has a unique fileId which can be used to pass that file as input to a process or viewing session or to download the raw bytes of the file.

Work files should not be used for archival storage. All work files are temporary and, by default, will be deleted 24 hours after creation.

Available URLs

POST /PCCIS/V1/WorkFile when body is file bytes	Creates a work file resource from file bytes (used to upload input files).
POST /PCCIS/V1/WorkFile when body is JSON	Creates a "package" work file from a set of existing work files. Used to prepare a set of dependent files for viewing or processing (e.g. CAD with XREF).
GET /PCCIS/V1/WorkFile/{fileId}	Gets the file bytes associated with a work file resource (used to download output files).
GET /PCCIS/V1/WorkFile/{fileId}/Info	Gets metadata information about a work file resource.

POST /PCCIS/V1/WorkFile when body is file bytes

Creates a work file resource from file bytes (used to upload input files).

Example:

POST /PCCIS/V1/WorkFile
Content-Type: application/octet-stream

<<file bytes>>

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fileId": "Xe6zv3dH0kVSzLuaNhd32A",
    "fileExtension": "pdf",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Request

Request Headers

Name Description

Name	Description
`Content-Type`	We recommend you use the value `application/octet-stream` to explicitly indicate that you are uploading file bytes. If you do not provide a value, `application/octet-stream` is assumed by default.
`Accusoft-Affinity-Token`	Used to ensure that this work file will be assigned to the same machine in the cluster as another existing resource (work file, process, or viewing session). If provided, the value must be the `affinityToken` of another existing resource. If not provided, an `affinityToken` will be randomly assigned to each work file created whenever there is more than one server in the cluster.

Content-Type

We recommend you use the value application/octet-stream to explicitly indicate that you are uploading file bytes.

If you do not provide a value, application/octet-stream is assumed by default.

Accusoft-Affinity-Token

Used to ensure that this work file will be assigned to the same machine in the cluster as another existing resource (work file, process, or viewing session).

If provided, the value must be the affinityToken of another existing resource.

If not provided, an affinityToken will be randomly assigned to each work file created whenever there is more than one server in the cluster.

Request Parameters

POST /PCCIS/V1/WorkFile{?FileExtension,MinSecondsAvailable}

Name Type Description Example

Name	Type	Description	Example
`FileExtension`	string	File extension of the file being uploaded without any leading period. Only required when the file type cannot be automatically detected (e.g. `csv`, `tsv`, `txt`, `eml`) or when automatic format detection has been explicitly disabled. Note that, if we are able to detect the file type automatically, the detected type will always be used and this value will be ignored.	`pdf`
`MinSecondsAvailable`	integer	The minimum number of seconds this work file must remain available. The actual lifetime may be longer.	`300`

FileExtension

string

File extension of the file being uploaded without any leading period.

Only required when the file type cannot be automatically detected (e.g. csv, tsv, txt, eml) or when automatic format detection has been explicitly disabled.

Note that, if we are able to detect the file type automatically, the detected type will always be used and this value will be ignored.

pdf

MinSecondsAvailable

integer

The minimum number of seconds this work file must remain available. The actual lifetime may be longer.

300

Request Body

The bytes of the file being uploaded.

Successful Response

JSON with metadata about the newly created work file.

Response Headers

Name	Value
`Content-Type`	`application/json`

Response Body

{
    "fileId": "Xe6zv3dH0kVSzLuaNhd32A",
    "fileExtension": "pdf",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Name Type Description

fileId string The unique id of the new work file resource, often used later as input to a viewing session or process.

fileExtension string The file extension assigned to this resource which indicates what type of file we understand it to be.

Name	Type	Description
`fileId`	string	The unique id of the new work file resource, often used later as input to a viewing session or process.
`fileExtension`	string	The file extension assigned to this resource which indicates what type of file we understand it to be.
`affinityToken`	string	A value used to identify which machine in the cluster this work file resides on. Only present when there is more than one machine in the cluster. A work file is only accessible to another resource if that resource resides on the same machine in the cluster. You can ensure that other resources you create (work files, viewing sessions, and processes) are assigned to the same machine by passing this value in an `Accusoft-Affinity-Token` request header when submitting the POST to create the other resource.

affinityToken

string

A value used to identify which machine in the cluster this work file resides on. Only present when there is more than one machine in the cluster.

A work file is only accessible to another resource if that resource resides on the same machine in the cluster. You can ensure that other resources you create (work files, viewing sessions, and processes) are assigned to the same machine by passing this value in an Accusoft-Affinity-Token request header when submitting the POST to create the other resource.

Error Responses

Status Code JSON errorCode Description

400

Status Code	JSON errorCode	Description
400	-	There was a problem with an input parameter: `FileExtension` was required and not provided `FileExtension` was an invalid value `MinSecondsAvailable` was not a number
405	-	An HTTP method other than POST was used.
580	`UnrecognizedFileFormat`	The file type of the uploaded bytes could not be automatically detected. You will need to manually specify a `FileExtension`. If you are getting this error for every file type which you upload, it is possible that automatic format detection needs to be enabled on your server.

There was a problem with an input parameter:

FileExtension was required and not provided
FileExtension was an invalid value
MinSecondsAvailable was not a number

405 - An HTTP method other than POST was used.

580 UnrecognizedFileFormat The file type of the uploaded bytes could not be automatically detected. You will need to manually specify a FileExtension. If you are getting this error for every file type which you upload, it is possible that automatic format detection needs to be enabled on your server.

POST /PCCIS/V1/WorkFile when body is JSON

Creates a "package" work file from a set of existing work files, defining one file in the set as the primary file for viewing and content conversion.

This special type of work file is particularly useful for CAD drawings which are made up of multiple files (such as dwg files which use other files via XREF).

Example:

POST /PCCIS/V1/WorkFile
Content-Type: application/json
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

{
    "primaryPath": "master.dwg",
    "items": [
        { "fileId": "CVBuD7DbQYNoJDqByGierQ", "path": "master.dwg" },
        { "fileId": "5qTYa3gzN9gYUb5SzqUhqg", "path": "parts/a.dwg" },
        { "fileId": "o1bLJwFGxf9QGuTkyrOqig", "path": "parts/b.dwg" }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fileId": "nkG9fiAmj27X3MhqGdbsXA",
    "primaryPath": "master.dwg",
    "items": [
        { "fileId": "CVBuD7DbQYNoJDqByGierQ", "path": "master.dwg" },
        { "fileId": "5qTYa3gzN9gYUb5SzqUhqg", "path": "parts/a.dwg" },
        { "fileId": "o1bLJwFGxf9QGuTkyrOqig", "path": "parts/b.dwg" }
    ],
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Request

Request Headers

Name Description

Name	Description
`Content-Type`	You must use the value `application/json` to indicate that you are assembling a new work file from a set of existing work files rather than simply uploading file bytes. If you forget to specify a `Content-Type` of `application/json`, we will assume you are attempting to upload file bytes.
`Accusoft-Affinity-Token`	Whenever there is more than one machine in the cluster, you will need to ensure that all of the work files in the set reside on to the same machine. To do this, upload the first file in the set, get the `affinityToken` in the response, and then use that value in an `Accusoft-Affinity-Token` request header for every subsequent work file POST, including this final POST to assemble a work file for the entire set.

Content-Type

You must use the value application/json to indicate that you are assembling a new work file from a set of existing work files rather than simply uploading file bytes.

If you forget to specify a Content-Type of application/json, we will assume you are attempting to upload file bytes.

Accusoft-Affinity-Token

Whenever there is more than one machine in the cluster, you will need to ensure that all of the work files in the set reside on to the same machine. To do this, upload the first file in the set, get the affinityToken in the response, and then use that value in an Accusoft-Affinity-Token request header for every subsequent work file POST, including this final POST to assemble a work file for the entire set.

Request Parameters

POST /PCCIS/V1/WorkFile{?MinSecondsAvailable}

Name	Type	Description	Example
`MinSecondsAvailable`	integer	The minimum number of seconds this work file must remain available. The actual lifetime may be longer.	`300`

Request Body

A JSON object which specifies:

which work files are in the set
what their local paths would be
which path should be considered the primary entry point for viewing or conversion

For example:

{
    "primaryPath": "master.dwg",
    "items": [
        { "fileId": "CVBuD7DbQYNoJDqByGierQ", "path": "master.dwg" },
        { "fileId": "5qTYa3gzN9gYUb5SzqUhqg", "path": "parts/a.dwg" },
        { "fileId": "o1bLJwFGxf9QGuTkyrOqig", "path": "parts/b.dwg" }
    ]
}

Name	Type	Description
`primaryPath`	string	Required. The primary entry point for viewing or conversion. This value must match the `path` value of one of the objects in the `items` array.
`items`	array	Required. The work files which are to be included in the set and what their local paths would be.

items

Name	Type	Description
`fileId`	string	Required. The `fileId` of a work file to be included in the set.
`path`	string	Required. A path value for this file in the set. Typically this is just the relative path of this file in relation to the primary file. Each item in the set must have a unique `path` value.

Successful Response

JSON with metadata about the new work file resource, the most important part being a new fileId which you can use to represent the entire set of files.

Response Headers

Name	Value
`Content-Type`	`application/json`

Response Body

{
    "fileId": "nkG9fiAmj27X3MhqGdbsXA",
    "primaryPath": "master.dwg",
    "items": [
        { "fileId": "CVBuD7DbQYNoJDqByGierQ", "path": "master.dwg" },
        { "fileId": "5qTYa3gzN9gYUb5SzqUhqg", "path": "parts/a.dwg" },
        { "fileId": "o1bLJwFGxf9QGuTkyrOqig", "path": "parts/b.dwg" }
    ],
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Name	Type	Description
`fileId`	string	The unique id of this new "package" work file, intended to be used as input to a viewing session or process which needs to consume the entire package as a single document.
`primaryPath`	string	The primary entry point which will be used for viewing or conversion.
`items`	array	The work files which are included in the set and their assigned paths.
`affinityToken`	string	A value used to identify which machine in the cluster this work file resides on. Only present when there is more than one machine in the cluster. A work file is only accessible to another resource if that resource resides on the same machine in the cluster. You can ensure that other resources you create (work files, viewing sessions, and processes) are assigned to the same machine by passing this value in an `Accusoft-Affinity-Token` request header when submitting the POST to create the other resource.

Error Responses

Status Code	JSON errorCode	Description
480	`"MissingInput"`	A required input was not provided. See the `errorDetails` in the response.
480	`"InvalidInput"`	One of the input values was invalid. Possible causes: `MinSecondsAvailable` was not a number. `primaryPath` did not match the `path` of any of the `items`. See the `errorDetails` in the response.
480	`"ValueMustBeUnique"`	One or more of the `path` values in the `items` array was non-unique.
580	`UnrecognizedFileFormat`	This will occur if you forget to specify a `Content-Type` of `application/json` when making your request. If no `Content-Type` is specified (or if any value other than `application/json` is specified), we will understand you to be making a request to upload file bytes rather than giving us JSON instructions to create a new work file from a set of existing work files. And, since we do not automatically detect JSON as a file format, this is the error which is returned. If you are trying to create a work file from a set of existing work files (as described in this section), make sure you set the request `Content-Type` header to `application/json`.

GET /PCCIS/V1/WorkFile/{fileId}

Gets the file bytes associated with a work file resource (used to download output files).

Example:

GET /PCCIS/V1/WorkFile/Xe6zv3dH0kVSzLuaNhd32A
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

HTTP/1.1 200 OK
Content-Type: application/pdf

<<file bytes>>

Request

Request Headers

Name	Description
`Accusoft-Affinity-Token`	If there is more than one machine in the cluster (an `affinityToken` was provided in the response to the initial POST request to create the work file), then this header must be set to the `affinityToken` of the work file you are trying to access.

Request Parameters

GET /PCCIS/V1/WorkFile/{fileId}{?ContentDispositionFilename}

Name Type Description Example

fileId string Required. The fileId of the work file whose file bytes you want to download. Xe6zv3dH0kVSzLuaNhd32A

Name	Type	Description	Example
`fileId`	string	Required. The `fileId` of the work file whose file bytes you want to download.	`Xe6zv3dH0kVSzLuaNhd32A`
`ContentDispositionFilename`	string	The filename which will be used in the response Content-Disposition header, but without any file extension. The file extension will be supplied for you automatically. For example, if you specified a `ContentDispositionFilename` of `FinancialReport` and the `fileExtension` for the work file was `"pdf"`, then the response would contain the following header: `Content-Disposition: attachment; filename=FinancialReport.pdf` If you do not specify a value, a filename will be used which is based upon the `fileId` of the work file, for example: `Content-Disposition: attachment; filename=file-Xe6zv3dH0kVSzLuaNhd32A.pdf`	`FinancialReport`

ContentDispositionFilename

string

The filename which will be used in the response Content-Disposition header, but without any file extension. The file extension will be supplied for you automatically.

For example, if you specified a ContentDispositionFilename of FinancialReport and the fileExtension for the work file was "pdf", then the response would contain the following header:

Content-Disposition: attachment; filename=FinancialReport.pdf

If you do not specify a value, a filename will be used which is based upon the fileId of the work file, for example:

Content-Disposition: attachment; filename=file-Xe6zv3dH0kVSzLuaNhd32A.pdf

FinancialReport

Successful Response

The raw bytes of the file.

Response Headers

Name Description Example

Content-Type The MIME type of the file being downloaded. application/pdf

Name	Description	Example
`Content-Type`	The MIME type of the file being downloaded.	`application/pdf`
`Content-Disposition`	Set to `attachment` with a filename based on the `ContentDispositionFilename` parameter or the `fileId` and using the `fileExtension` for this work file. See the `ContentDispositionFilename` request parameter.	`attachment; filename=file-Xe6zv3dH0kVSzLuaNhd32A.pdf`

Content-Disposition

Set to attachment with a filename based on the ContentDispositionFilename parameter or the fileId and using the fileExtension for this work file.

See the ContentDispositionFilename request parameter.

attachment; filename=file-Xe6zv3dH0kVSzLuaNhd32A.pdf

Response Body

The raw bytes of the file.

Error Responses

Status Code	JSON errorCode	Description
400	`"InvalidInput"`	One of the input values was invalid. Possible causes: `Accusoft-Affinity-Token` was invalid. See the `errorDetails` in the response.
480	`"DataNotAvailable"`	No file bytes exist for download. This can occur if you attempt to download the file bytes for a "package" work file which merely groups a set of related work files under a single `fileId`.
404	-	No work file existed for the given `fileId`.
405	-	An HTTP method other than GET was used.

GET /PCCIS/V1/WorkFile/{fileId}/Info

Gets metadata information about a work file resource, the same information returned in the original POST request which created the work file.

Example:

GET /PCCIS/V1/WorkFile/Xe6zv3dH0kVSzLuaNhd32A/Info
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fileId": "Xe6zv3dH0kVSzLuaNhd32A",
    "fileExtension": "pdf",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Request

Request Headers

Name	Description
`Accusoft-Affinity-Token`	If there is more than one machine in the cluster (an `affinityToken` was provided in the response to the initial POST request to create the work file), then this header must be set to the `affinityToken` of the work file you are trying to access.

Request Parameters

GET /PCCIS/V1/WorkFile/{fileId}/Info

Name	Type	Description	Example
`fileId`	string	Required. The `fileId` of the work file you need information about.	`Xe6zv3dH0kVSzLuaNhd32A`

Successful Response

JSON with information about the work file.

Response Headers

Name	Value
`Content-Type`	`application/json`

Response Body

For simple work files:

{
    "fileId": "Xe6zv3dH0kVSzLuaNhd32A",
    "fileExtension": "pdf",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Name	Type	Description
`fileId`	string	The unique id of this resource.
`fileExtension`	string	File extension assigned to this resource, indicating what type of file we understand it to be.
`affinityToken`	string	A value used to identify which machine in the cluster this work file resides on. Only present when there is more than one machine in the cluster.

For "package" work files:

{
    "fileId": "nkG9fiAmj27X3MhqGdbsXA",
    "primaryPath": "master.dwg",
    "items": [
        { "fileId": "CVBuD7DbQYNoJDqByGierQ", "path": "master.dwg" },
        { "fileId": "5qTYa3gzN9gYUb5SzqUhqg", "path": "parts/a.dwg" },
        { "fileId": "o1bLJwFGxf9QGuTkyrOqig", "path": "parts/b.dwg" }
    ],
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Name	Type	Description
`fileId`	string	The unique id of this resource.
`primaryPath`	string	The primary entry point which will be used for viewing or conversion.
`items`	array	The work files which are included in the set and their assigned paths.
`affinityToken`	string	A value used to identify which machine in the cluster this work file resides on. Only present when there is more than one machine in the cluster.

Error Responses

Status Code	Description
404	No work file existed for the given `fileId`.
405	An HTTP method other than GET was used.

Send Feedback