PrizmDoc Server will expect a source document to be provided for each new viewing session using one of three available methods. The specific method of transfer used for a particular document is specified during the creation of the viewing session, so it is possible to use multiple transfer methods in your application. You can transfer your document to PrizmDoc Server by sending it explicitly with a HTTP PUT request or by specifying a file location, such as an HTTP URL or a local filename, so that PrizmDoc Server can retrieve it.

The best transfer method for your application will likely depend on the original location of your documents. For example, if your source documents are stored in a database, the HTTP PUT request is likely the most efficient method as you’ll be able to read the data out of the database and copy it directly to the request body, eliminating the need to write the document to a file. If your source documents are already hosted and accessible from an HTTP URL, PrizmDoc Server can download the file directly thus eliminating any intermediate transfers. Finally, if your source documents already exist on the server that is hosting PrizmDoc Server then providing the local path to each file is a good option.

The following sections provide some specific information about each transfer method. Additional information can also be found in the Viewing Sessions topic.

HTTP PUT Request

The PUT request is considered the default method of transferring source documents to PrizmDoc Server. It provides the most independent method of transferring documents because the data is sent directly to PrizmDoc Server, largely reducing the chances of a failure as compared to the other methods.

The request has the following format:

PUT ViewingSession/u{ViewingSessionID}/SourceFile?FileExtension={ext}

The document data should be included directly in the request body. This request should be made after the HTTP POST request to create a viewing session and before the HTTP POST to start a viewing session.

HTTP URL

PrizmDoc Server supports downloading a document from an HTTP or HTTPS URL. The URL must either be publicly accessible, or at least accessible over the internal network to which PrizmDoc Server is connected.

The HTTP PUT request is not required if this transfer method. Instead, some JSON properties in the body of the HTTP POST request to create a new viewing session must be set appropriately. These specific properties are described below. See the PrizmDoc Server API topic for more details about other JSON properties set in this request.

To enable the HTTP URL transfer method, set the documentSource JSON property to http. This will inform PrizmDoc Server to expect a valid URL to be specified by the externalId JSON property. Set the externalId JSON property to the HTTP URL of your document. PrizmDoc Server will require a valid extension be provided as well. You can set the extension explicitly with the documentExtension JSON property. If documentExtension is not set, PrizmDoc Server will attempt to extract an extension from the end of the URL resource name. For example:

POST /ViewingSession
{
    "documentSource": "http",
    "externalId": "http://localhost/osha.pdf",
    "documentExtension": "pdf"
}

When PrizmDoc Server receives the POST request to create the viewing session, it will begin downloading the document asynchronously in a background thread while the request returns with a status of 200 OK. Because the document download occurs asynchronously within PrizmDoc Server, it is possible that the retrieval process will fail without any immediate feedback. In this case, the viewing session will be stopped, and any request in the context of the same viewing session will return in error with a status code of 580 and HTTP reason of Document download failed.

For additional security, there are user-configurable properties in the central configuration file called viewing.sessionConstraints.externalId.regex and viewing.sessionConstraints.documentExtension.regex that can be used to restrict values coming in from the externalId and documentExtension JSON properties, respectively. Any values that do not pass these filters will cause the viewing session to be stopped immediately. See the Central Configuration topic for details about this and other configuration properties.

There is a user-configurable timeout value that PrizmDoc Server will use when it sends the GET HTTP request to download the document. This timeout value is specified in pcc.config under the property DocumentAcquisitionTimeout. The default value is 25 seconds. See the PrizmDoc Server Configuration topic for details about other user-configurable properties.

For additional security, there is a user-configurable property in pcc.config called ViewingSessionPropertyExternalId that can be used to restrict values coming in from the externalId JSON property. Any values that do not pass this filter will cause the viewing session to be stopped immediately. See the PrizmDoc Server Configuration topic for details about this and other configuration properties.

Local File

The third option to transfer documents makes use of the local file system to make your documents available to PrizmDoc Server. This option is enabled by setting the documentSource JSON property to file. This will inform PrizmDoc Server to expect a valid local file name to be specified by the externalId JSON property. Set the externalId JSON property to the filename of your document. PrizmDoc Server will require a valid extension be provided as well. You can set the extension explicitly with the documentExtension JSON property. If documentExtension is not set, PrizmDoc Server will attempt to extract an extension from the end of the filename given.

POST /ViewingSession
{
    "documentSource": "file",
    "externalId": "myDocumentStore\\osha.pdf",
    "documentExtension": "pdf"
}

For security purposes, only partial/relative paths and filenames are supported in externalId. Rooted paths are not supported. Instead, the root directory where your documents will exist should be specified in pcc.config using the UserDocumentFolder property. PrizmDoc Server will combine the root directory in this property with the value it receives in externalId. If, when combined, a relative path in externalId takes the current directory outside of the directory specified in UserDocumentFolder, or any other invalid path is used, the transfer will fail.

The following are examples of valid values for externalId:

• "sample.doc"

• "docFolder\\sample.doc" (Windows)

• "docFolder/sample.doc" (Linux)

When PrizmDoc Server receives the POST request to create the viewing session, it will copy the document asynchronously in a background thread while the request returns with a status of OK. Because the document is copied asynchronously within PrizmDoc Server, it is possible that the retrieval process will fail without any immediate feedback. In this case, the viewing session will be stopped, and any request in the context of the same viewing session will return in error with a status code of 580 and HTTP reason of Document download failed.

For additional security, there are user-configurable properties in the central configuration file called viewing.sessionConstraints.externalId.regex and viewing.sessionConstraints.documentExtension.regex that can be used to restrict values coming in from the externalId and documentExtension JSON properties, respectively. Any values that do not pass these filters will cause the viewing session to be stopped immediately. See the Central Configuration topic for details about this and other configuration properties.

There is a user-configurable timeout value that PrizmDoc Server will use when it copies the document. This timeout value is specified in pcc.config under the property DocumentAcquisitionTimeout. The default value is 25 seconds. See the PrizmDoc Server Configuration topic for details about other user-configurable properties.

For additional security, there is a user-configurable property in pcc.config called ViewingSessionPropertyExternalId that can be used to restrict values coming in from the externalId JSON property. Any values that do not pass this filter will cause the viewing session to be stopped immediately. See the PrizmDoc Server Configuration topic for details about this and other configuration properties.