PrizmDoc v13.3 - Updated
Viewing Sessions
API Reference > PrizmDoc Server RESTful API > Viewing Sessions

Viewing Sessions

To initiate a view, the following RESTful operations should be performed as detailed in the PrizmDoc Server Sample discussion.

Available URLs

URL Description
POST /PCCIS/V1/ViewingSession Creates a new viewing session.
GET /PCCIS/V1/ViewingSession/u{viewingSessionId} Gets information about a viewing session.
PUT /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceFile Uploads the source document to be used for a viewing session.
PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/original When viewing a comparison of two source documents, uploads the first of the two source documents.
PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/revised When viewing a comparison of two source documents, uploads the second of the two source documents.
PUT /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceRef Attach an existing work file (or, when doing comparison, two work files) as the source document to be used for a viewing session.
GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceFile Downloads the source document in use for a viewing session.
GET /v2/viewingSessions/{viewingSessionId}/sourceFile/original When viewing a comparison of two documents, downloads the first of the two source documents.
GET /v2/viewingSessions/{viewingSessionId}/sourceFile/revised When viewing a comparison of two documents, downloads the second of the two source documents.
GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/FileId Gets the work file id for the source document in use for a viewing session.
POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/Notification/SessionStarted Ensures PrizmDoc has started the process of converting a viewing session's source document to HTML.
POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/Notification/SessionStopped Invalidates a viewing session so that it can no longer be used.
DELETE /PCCIS/V1/ViewingSession/u{viewingSessionId} Deletes a viewing session.

POST /PCCIS/V1/ViewingSession

Creates a new viewing session. At a high level, a viewing session takes a source document as input and produces HTML page content and document text as output.

Request

Request Headers

Name Description
Content-Type Should be application/json
Accusoft-Affinity-Hint Some sort of string value which uniquely identifies the source document you intend to use for the viewing session. Used to ensure that two viewing sessions created with the same Accusoft-Affinity-Hint are very likely to be handled by the same server, increasing the chances that cached output is reused for viewing sessions of the same source document. See Optimizing Cache Performance for Cluster Mode.
Accusoft-Affinity-Token When you intend to use an existing work file as the source document via a subsequent call to PUT /SourceRef, the affinityToken of the existing work file. Required only when you intend to use an existing work file as the source document.

Request Body

Successful Response

Response Body

JSON with metadata about the created viewing session.

Error Responses

Some error responses will have a JSON body with an errorCode and errorDetails:

Status Code JSON errorCode Description
480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
480 "InputNotSupportedWithServerCachineEnabled" Can occur when minSecondsAvailable is specified when serverCaching is not set to "none". See errorDetails in the response body.

Some error responses will include an error message in an Accusoft-Status-Message header.

Example

Request

POST prizmdoc_server_base_url/PCCIS/V1/ViewingSession
Content-Type: application/json

{
    "tenantId": "my application name",
    "externalId": "my-unique-document-name.docx",
    "render": {
        "html5": {
            "alwaysUseRaster": false
        }
    },
    "minSecondsAvailable": 1500,
    "watermarks": [
        {
            "type": "text",
            "opacity": 0.6,
            "text": "jdoe\n67.79.169.114\n11/13/2014 2:24 PM\NOT FOR DISTRIBUTION",
            "color": "red",
            "fontFamily": "Consolas",
            "fontSize": "16pt",
            "fontWeight": "bold",
            "verticalAlign": "bottom",
            "horizontalAlign": "right"
        }
    ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
    "viewingSessionId":"GcIsIsEGbLV2_V9yy4NzmK2HB-JuLOH--A9sZ16cla9txO0ZDBGfq1G4kKu0r_GyEps4wWCvDwn4dpnZAR76Uw"
    "affinityToken":" S2ZqtGi9vUAXBgdmM/PNNpCM4CApe9NxLIp/4QnAHlg="
}

GET /PCCIS/V1/ViewingSession/u{viewingSessionId}

Returns the metadata associated with a valid, active viewing session. The properties returned will be those provided in the POST request that created the viewing session.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Successful Response

JSON metadata about the viewing session:

Error Responses

Status Code Reason Phrase Description
500 Internal Server Error Can occur if you forget to prefix the {viewingSessionId} portion of the URL with u, or if you simply request an invalid {viewingSessionId}.
403 The session is invalid or has expired You requested a valid {viewingSessionId} but it is no longer available.

Example

Request

GET prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ...

Response

HTTP/1.1 200
Content-Type: application/json

{
    "origin": {},
    "render": {
    "flash": {
        "optimizationLevel": 1
    },
    "html5": {
        "alwaysUseRaster": false,
        "rasterResolution": 150
    }
    },
    "password": null,
    "watermarkText": null,
    "externalId": null,
    "attachmentIndex": 0,
    "attachmentDisplayName": null,
    "tenantId": null,
    "creationTime": "2015-10-14T11:55:32.6521255Z",
    "countOfInitialPages": 0,
    "documentSource": null,
    "documentExtension": "help",
    "serverCaching": "full",
    "startConverting": null,
    "contentType": null,
    "pageContentEncryption": null,
    "watermarks": []
}

PUT /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceFile?FileExtension={FileExtension}

Uploads the source document to be viewed.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.
{FileExtension} Required for text-based formats (such as txt, csv, html). File extension of the document being uploaded. This parameter may or may not be required depending on the file type and whether Format Detection is enabled. Note that the extension must not include the leading period (for example, csv is accepted but .csv will return an error). Extensions are not case sensitive. Note: If Format Detection is disabled, then FileExtension is always required.

If Format Detection is enabled (the default), the use of FileExtension is as follows:

Request Body

The bytes of the source document.

Successful Response

A simple HTTP 200 status code indicating the file was received.

Error Responses

Some error responses will have a JSON body with an errorCode and errorDetails:

Status Code JSON errorCode Description
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because one or more files (original and/or revised) have already been provided for comparison.

Some error responses will include an error message in an Accusoft-Status-Message header:

Status Code Accusoft-Status-Message Header Description
580 "Unrecognized File Format" Occurs when the file format cannot be automatically detected. To avoid this, provide an explicit FileExtension query string parameter for this kind of file. This most-commonly occurs with text-based source documents where we require an explicit FileExtension to know the file format (such as txt, csv, or html). You may need to create a new viewing session for the PUT to succeed.

Example

Request

PUT prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../SourceFile?FileExtension=doc

<<file bytes>>

Response

HTTP/1.1 200 OK

PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/original

Used when viewing a comparison of two documents, uploads the first of the two documents, the original document.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Request Body

The bytes of the original document (for comparison with a revised document).

Successful Response

A simple HTTP 200 status code indicating the file was received.

Error Responses

Status Code JSON errorCode Description
404 No viewing session with the provided viewingSessionId could be found.
480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
480 "CannotChangeDocument" The viewing session already has an original document assigned.
480 "UnsupportedFormatForComparison" The uploaded file was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files).
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document has already been provided.
480 "FeatureNotLicensed" The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

Example

Request

PUT prizmdoc_server_base_url/v2/viewingSessions/XYZ.../sourceFile/original

<<file bytes>>

Response

HTTP/1.1 200 OK

PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/revised

Used when viewing a comparison of two documents, uploads the second of the two documents, the revised document.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Request Body

The bytes of the revised document (for comparison with an original document).

Successful Response

A simple HTTP 200 status code indicating the file was received.

Error Responses

Status Code JSON errorCode Description
404 No viewing session with the provided viewingSessionId could be found.
480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
480 "CannotChangeDocument" The viewing session already has a revised source document assigned.
480 "UnsupportedFormatForComparison" The uploaded file was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files).
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document has already been provided.
480 "FeatureNotLicensed" The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

Example

Request

PUT prizmdoc_server_base_url/v2/viewingSessions/XYZ.../sourceFile/revised

<<file bytes>>

Response

HTTP/1.1 200 OK

PUT /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceRef

Attach an existing work file (or, when doing comparison, two work files) as the source document to be used for a viewing session.

Using a source reference can be particularly useful when you want to avoid repeatedly uploading the same source file to the back end.

Request

Request Headers

Name Description
Content-Type Must be application/json

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Request Body when assigning reference for a single document

Request Body when comparing two documents

Successful Response

A simple HTTP 200 status code.

Error Responses

Status Code JSON errorCode Description
480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
480 "NotFound" The given work file has expired or does not exist. See errorDetails in the response body.
480 "CannotChangeDocument" The viewing session already has a source document assigned. See errorDetails in the response body.
480 "UnsupportedFormatForComparison" One of the files provided for comparison was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files). See errorDetails in the response body.
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you have already provided a source document and then attempt to provide an original and revised document pair, or vice versa, you will receive this error.
480 "FeatureNotLicensed" The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

Examples

Assigning a single source document
PUT prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../SourceRef
Content-Type: application/json

{
   "refType": "workFile",
   "fileId": "CVBuD7DbQYNoJDqByGierQ",
}
HTTP/1.1 200 OK

Assigning two documents to be viewed as a comparison
PUT prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../SourceRef
Content-Type: application/json

{
    "refType": "comparison",
    "original": {
       "refType": "workFile",
       "fileId": "CVBuD7DbQYNoJDqByGierQ",
    },
    "revised": {
       "refType": "workFile",
       "fileId": "5qTYa3gzN9gYUb5SzqUhqg",
    }
}
HTTP/1.1 200 OK

GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceFile?ContentDispositionFilename={ContentDispositionFilename}

Gets the source document in use for a viewing session.

The response will set the Content-Type header to the most-specific MIME type it can or application/octet-stream otherwise.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.
{ContentDispositionFilename} Name to use for the filename attribute in the Content-Disposition response header. By default, the value will be SourceFile.<ext>, where <ext> is the appropriate file extension (such as doc or docx).

Response

The raw bytes of the viewing session's source document.

Example

Request

GET prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../SourceFile?ContentDispositionFilename=MonthlySalesReport

Response

200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=MonthlySalesReport.docx

<<file bytes>>

GET /v2/viewingSessions/{viewingSessionId}/sourceFile/original?contentDispositionFilename={contentDispositionFilename}

When viewing a comparison of two documents, gets the original document used in the comparison. The document returned will be an identical copy of the document originally provided.

The response will set the Content-Type header to the most-specific MIME type it can or application/octet-stream otherwise.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.
{contentDispositionFilename} Name to use for the filename attribute in the Content-Disposition response header. By default, the value will be OriginalSourceFile.<ext>, where <ext> is the appropriate file extension (such as doc or docx).

Successful Response

The raw bytes of the first of the two documents being viewed as a comparison, the original document.

Error Responses

Status Code JSON errorCode Description
404 No viewing session with the provided viewingSessionId could be found.
480 "DocumentNotProvidedYet" An original document has not been provided to the viewing session yet.
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document was provided for viewing, so there will never be an original comparison document to get.

Example

Request

GET prizmdoc_server_base_url/v2/viewingSessions/XYZ.../sourceFile/original?contentDispositionFilename=OldMonthlySalesReport

Response

200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=OldMonthlySalesReport.docx

<<file bytes>>

GET /v2/viewingSessions/{viewingSessionId}/sourceFile/revised?contentDispositionFilename={contentDispositionFilename}

When viewing a comparison of two documents, gets the revised document used in the comparison. The document returned will be an identical copy of the document originally provided.

The response will set the Content-Type header to the most-specific MIME type it can or application/octet-stream otherwise.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.
{contentDispositionFilename} Name to use for the filename attribute in the Content-Disposition response header. By default, the value will be RevisedSourceFile.<ext>, where <ext> is the appropriate file extension (such as doc or docx).

Successful Response

The raw bytes of the second of the two documents being viewed as a comparison, the revised document.

Error Responses

Status Code JSON errorCode Description
404 No viewing session with the provided viewingSessionId could be found.
480 "DocumentNotProvidedYet" A "revised" document has not been associated with the viewing session yet.
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document was provided for viewing, so there will never be a revised comparison document to get.

Example

Request

GET prizmdoc_server_base_url/v2/viewingSessions/XYZ.../sourceFile/revised?contentDispositionFilename=NewMonthlySalesReport

Response

HTTP/1.1 200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=NewMonthlySalesReport.docx

<<file bytes>>

GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/FileId

Gets the work file id of the source document in use for a viewing session.

Regardless of how the source document was provided or acquired, internally PrizmDoc will always ensure a work file exists for the source document. This URL allows you to get the work file id for a viewing session's source document. This can be helpful if you want to create a new viewing session using the same source document; you can simply create the new viewing session and then attach the existing work file to it as the source document (see PUT /SourceRef).

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Successful Response

JSON with the work file id.

Error Responses

Status Code JSON errorCode Description
480 DocumentNotProvidedYet Occurs when you create a viewing session with a documentSource of "api" but have not yet made the API call(s) necessary to provide the source document.

Example

Request

GET prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../FileId

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "fileId": "1OGayKFk2dGtC8jhOtSknw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/Notification/SessionStarted

Ensures PrizmDoc has started the process of converting a viewing session's source document to HTML.

The User-Agent header should be set to an appropriate browser string to enable the PrizmDoc Server to begin generating the correct content for the Viewer.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Request Headers

Name Description
Content-Type Should be application/json.
User-Agent Browser user agent string which PrizmDoc uses to generate the most-appropriate content for the viewer.

Request Body

Successful Response

A simple HTTP 200 status code indicating the session has been started.

Error Responses

Status Code Description
500 Can occur if your request body is not JSON. Make sure your JSON contains at least an empty object ({}).

Example

Request

POST prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../Notification/SessionStarted
Content-Type: application/json

{
}

Response

HTTP/1.1 200 OK

POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/Notification/SessionStopped

Invalidates a viewing session so that it can no longer be used.

Invalidating a viewing session can be useful when:

  1. A viewing session has been created but something prevents your application from being able to provide a source document for the viewing session
  2. An end user has finished using a viewing session and no additional access to the viewing session should be allowed

When you invalidate a viewing session, you must provide a JSON body which specifies what HTTP status code and reason phrase should be returned as an error for future requests to the invalidated viewing session. This allows you to control what sort of HTTP response other people or applications will receive if they make requests to your invalidated viewing session.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Request Headers

Name Description
Content-Type Should be application/json.

Request Body

Successful Response

A simple HTTP 200 status code indicating the session has been stopped.

Example

Request

POST prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../Notification/SessionStopped
Content-Type: application/json

{
    "httpStatus": 418,
    "endUserMessage": "My custom end user error message"
}

Response

HTTP/1.1 200 OK

Then, if any future requests are made to the viewing session, the response will be:

HTTP/1.1 418 My custom end user error message
Accusoft-Status-Message: My custom end user error message
Accusoft-Status-Number: 580

DELETE /PCCIS/V1/ViewingSession/u{viewingSessionId}

Deletes a viewing session. Only possible for viewing sessions created with serverCaching set to "none".

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Successful Response

HTTP 204 indicating the session was deleted.

Error Responses

Status Code JSON errorCode Description
404 No viewing session with the provided {viewingSessionId} could be found.
580 "CannotDeleteCachedViewingSession" The viewing session you attempted to delete was not created with serverCaching set to "none".