PrizmDoc® v14.1 Release - Updated
PrizmDoc / API Reference / PrizmDoc Server REST API / Application Development / Work Files
In This Topic
    Work Files
    In This Topic

    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

    URL Description
    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 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

    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.

    Request Parameters

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

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

    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). The FileExtension parameter may only accept alpha-numeric characters. 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.
    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 - 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.

    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

    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.

    Request Parameters

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

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

    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 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

    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 prizmdoc_server_base_url/PCCIS/V1/WorkFile/{fileId}{?ContentDispositionFilename}
    
    

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

    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 as a URL-encoded string, without extension, to be used in the Content-Disposition response header (the file extension will be appended automatically). The default is file-<fileId>. GreekΑΒΓΔ

    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
    Content-Disposition Specifies 'attachment' disposition, RFC-2183 compatible filename parameter and, if ContentDispositionFilename was specified in the request, RFC-8187 compatible filename* parameter, allowing the use of non-ASCII filenames. attachment; filename="Greek____.pdf"; filename*=UTF-8''Greek%CE%91%CE%92%CE%93%CE%94.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](#post-json) 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 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

    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 prizmdoc_server_base_url/PCCIS/V1/WorkFile/{fileId}/Info
    
    

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

    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.

    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:
    Loading credentials from a shared credentials file:
    Loading credentials from environment variables:

    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.