Introduction

The work file REST API provides a temporary storage system 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).

Example

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

<<file bytes>>

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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

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

Request

Request Headers

Request Parameters

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

Request Body

The bytes of the file being uploaded.

Successful Response

JSON with metadata about the newly created work file.

Response Headers

Response Body

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

Error Responses

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 prizmdoc_server_base_url/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" }
    ]
}

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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

Request Parameters

POST prizmdoc_server_base_url/PCCIS/V1/WorkFile{?MinSecondsAvailable}

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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" }
    ]
}

Items

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

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="
}

Error Responses

GET /PCCIS/V1/WorkFile/{fileId}

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

Example

Get work file with default filename

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="file-Xe6zv3dH0kVSzLuaNhd32A.pdf"

<<file bytes>>

Get work file with non-ASCII character in the filename

GET prizmdoc_server_base_url/PCCIS/V1/WorkFile/Xe6zv3dH0kVSzLuaNhd32A?ContentDispositionFilename=GreekΑΒΓΔ
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

NOTE: See the Base URL for PrizmDoc Server topic for more information.

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="file-Xe6zv3dH0kVSzLuaNhd32A.pdf"; filename*=UTF-8''Greek%CE%91%CE%92%CE%93%CE%94.pdf`

<<file bytes>>

Request

Request Headers

Request Parameters

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

Successful Response

The raw bytes of the file.

Response Headers

Response Body

The raw bytes of the file.

Error Responses

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 prizmdoc_server_base_url/PCCIS/V1/WorkFile/Xe6zv3dH0kVSzLuaNhd32A/Info
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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

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

Request

Request Headers

Request Parameters

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

Successful Response

JSON with information about the work file.

Response Headers

Response Body

For simple work files

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

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="
}

Error Responses

Sharing Work Files within a Cluster

It might be useful to share workfiles between servers within the PrizmDoc Server Cluster, so that it would be possible to scale and recycle cluster instances without losing workfiles. For example, if an instance that was used to successfully upload a workfile goes down, another instance can process this workfile without the need to re-upload it.

Sharing using AWS S3

PrizmDoc Server supports workfile sharing using AWS S3 buckets. In this case the Workfile Service will store the workfile's metadata in the MySQL database, and the workfile in the S3 bucket. In order to enable the sharing, it is necessary to configure the database and S3 bucket accordingly, and set the corresponding Central Configuration parameters:

• database.connectionString
• workFiles.sharedStorage.type
• workFiles.sharedStorage.s3BucketName
• workFiles.sharedStorage.path

Please see the "Work Files" section of the Central Configuration page for more information.
Please note that it is necessary to configure the IAM policy to grant access to the Amazon S3 Bucket for programmatic access. The following sample IAM policy grants programmatic read-write access to the arn:aws:s3:::<bucket_name> bucket:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "S3Bucket",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": [
                "arn:aws:s3:::<bucket_name>"
            ]
        },
        {
            "Sid": "S3Objects",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket_name>/*"
            ]
        }
    ]
}

The policy is separated into two parts because the ListBucket action requires permissions on the bucket while the other actions require permissions on the objects in the bucket. You must use two different Amazon Resource Names (ARNs) to specify bucket-level and object-level permissions. The first Resource element specifies arn:aws:s3:::<bucket_name> for the ListBucket action so that applications can list all objects in the test bucket. The second Resource element specifies arn:aws:s3:::<bucket_name>/* for the GetObject, PutObject, and DeletObject actions so that applications can read, write, and delete any objects in the test bucket.

NOTE: If workFiles.sharedStorage.type is set to s3, the WorkFile Service will check connection to the central database, and ensure the S3 bucket and path are non-empty. If any of those conditions are not met, the service will log an error and fail to initialize, making PrimDoc unhealthy.

Additional S3 Notes

You must handle Amazon Web Services credentials in one of the available ways that are provided on the following pages:

Loading credentials in Node.js from IAM Roles for EC2:

• http://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-iam.html

Loading credentials from a shared credentials file:

• http://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html

Loading credentials from environment variables:

• http://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html

Error Responses

If the WorkFile Service fails to connect to the database or S3 while processing any of above mentioned POST/GET requests, it will return HTTP 580 with InternalError in the JSON error code and log the corresponding error.