PrizmDoc v13.2 - Updated
Viewing Sessions
API Reference > PrizmDoc Application Services (PAS) RESTful API > Viewing Sessions

Viewing Session

POST /ViewingSession

Routes key: PostViewingSession

Request

PrizmApplicationServices will handle properties in the source object and any additional ViewingSession properties defined outside of the source object will be forwarded to the PrizmDoc Server when creating the Viewing Session. Please use the below watermarks example as a reference.

The set of fields supported in the request body depends on where the documents come from, such as local documents, documents specified via url, etc. This is specified by the type property. See the fields supported for each type below.

When using a local document

When using a URL

When uploading the document

When using a viewing package

When comparing two documents

The set of fields supported by both the original and revised objects depends on where the documents come from, specified by the type property of those objects. Original and revised documents don't have to use the same type. See the fields supported for each type below:

When original or revised is a local document:

When original or revised is a URL:

When original or revised will be uploaded:

Note: Use PUT /ViewingSession/u{viewingSessionId}/SourceFile/Original and/or PUT /ViewingSession/u{viewingSessionId}/SourceFile/Revised to upload the original and/or revised document in a subsequent request.

Response

Successful Response

JSON body.

Error Responses

Status Code JSON errorCode Description
403 "InvalidSecret" The secret key, provided in the Accusoft-Secret header is invalid.
404 "DocumentNotFound" The specified document could not be found.
480 "InvalidInput" Input is invalid. See errorDetails in the response body.
480 "CannotChangeDocument" The viewing session already has an original source document.
480 "IncorrectUsage" The viewing session is already used for viewing of a single source document.
480 "FeatureNotLicensed" MSO enabled license is not installed.
480 "FeatureDisabled" Microsoft Office renderer is not configured.
480 "InputNotSupportedWithDocumentId" Input is not supported when creating a viewing session with caching. See errorDetails in the response body.
480 "InputConflictsWithViewingPackage" Input conflicts with viewing package. See errorDetails in the response body.

Examples

Create a session using a local document

Use Storage Provider to find the correct document and uses it to create a viewing session.

POST pas_base_url/ViewingSession
Content-Type: application/json
{
    "source": {
        "type": "document",
        "fileName": "sample.doc"
    }
}
Successful Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "viewingSessionId": "XYZ..."
}
Error Response
HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "errorCode": "DocumentNotFound"
}

Create a session using a local document with caching enabled

Use Storage Provider to find the correct document and use it to create a viewing session. Asynchronously, a viewing package creator process will begin creating a viewing package for the same document which, once complete, can be used by viewing sessions created from an identical request or by viewing sessions created with source.type="viewingPackage".

Note: When caching is enabled, watermarks cannot be used and will return an error.

POST pas_base_url/ViewingSession
Content-Type: application/json

{
    "source": {
        "type": "document",
        "fileName": "sample.doc"
        "documentId": "doc_9495837910qc"
    }
}
Successful Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "viewingSessionId": "{viewingSessionId}"
}
Error Responses

Watermarks Input:

The watermarks property cannot be used when creating a viewing session with caching.

HTTP/1.1 480
Content-Type: application/json

{
    "errorCode": "InputNotSupportedWithDocumentId",
    "in": "body",
    "at": "watermarks"
}

render.html5.alwaysUseRaster Input:

The render.html5.alwaysUseRaster property cannot be used when creating a viewing session with caching.

HTTP/1.1 480
Content-Type: application/json

{
    "errorCode": "InputNotSupportedWithDocumentId",
    "in": "body",
    "at": "render.html5.alwaysUseRaster"
}

Conflicting Input:

When creating a viewing session from a completed viewing package, the source and render properties must match those from the package. When attempting to create a viewing session from a package with different render or source properties, PAS will return an error similar to this one:

HTTP/1.1 480
Content-Type: application/json

{
    "errorCode": "InputConflictsWithViewingPackage",
    "in": "body",
    "at": "source.fileName"
}

Create a session using a url

POST pas_base_url/ViewingSession
Content-Type: application/json

{
    "source": {
        "type": "url",
        "url": "http://google.com/",
        "headers": {
            "user-agent": "PrizmShare"
        },
        "acceptBadSslCertificate": true
    }
}
Successful Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "viewingSessionId": "XYZ..."
}

Create a session using a viewing package

Use a complete viewing package to start a viewing session. All viewable content for the session is immediately available by the viewing package. See the PrizmDoc Application Services RESTful Viewing Package Creators API for more details about creating viewing packages and the PrizmDoc Application Services RESTful Viewing Packages API for more details about managing viewing packages.

POST pas_base_url/ViewingSession
Content-Type: application/json
{
    "source": {
        "type": "viewingPackage",
        "documentId": "doc_9495837910qc"
    }
}
Successful Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "viewingSessionId": "{viewingSessionId}"
}
Error Response
HTTP/1.1 480 InvalidInput
Content-Type: application/json

{
    "errorCode": "InvalidInput",
    "in": "body",
    "at": "source.documentId",
    "expected": {
        "type": "string"
    }
}

Passing Additional parameters to the back end

POST pas_base_url/ViewingSession
Content-Type: application/json

{
    "source": {
        "type": "document",
        "fileName": "sample.doc"
    },
    "watermarks": [
        {
            "type": "text",
            "opacity": 0.6,
            "text": "jdoe\n67.79.169.114\n11/13/2014 2:24 PM\nNOT FOR DISTRIBUTION",
            "color": "red",
            "fontFamily": "Consolas",
            "fontSize": "16pt",
            "fontWeight": "bold",
            "verticalAlign": "bottom",
            "horizontalAlign": "right"
        }
    ]
}
Successful Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "viewingSessionId": "XYZ..."
}

Create a session by uploading a document

Creates a new blank session

POST pas_base_url/ViewingSession
Content-Type: application/json

{
    "source": {
        "type": "upload",
        "displayName": "sample_2015-10-31T19:15:32Z.doc"
    }
}

While the above is the minimum required data, when uploading a file, it is also a good idea to add the markupId property in source, as such:

{
    "source": {
        "type": "upload",
        "displayName": "sample_2015-10-31T19:15:32Z.doc",
        "markupId": "YSB1bmlxdWUgdmFsdWU="
    }
}

When this value is provided, PAS will use it when saving and reading markup files for this document. This ID needs to be unique for the binary document being used. Note that if your system contains mutable documents -- one that the user can edit and the system will still see it as a separate document -- this ID needs to take into account the revision of the document, as an edited version of the same document is considered a new, unique document by PrizmDoc. If this ID is not provided, PAS will hash the displayName value, which would in turn have the same uniqueness requirements.

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

{
    "viewingSessionId": "XYZ..."
}

Create a session for comparison of a local document and a document specified by url

POST pas_base_url/ViewingSession
Content-Type: application/json

{
    "source": {
        "type": "comparison",
        "original": {
            "type": "document",
            "fileName": "original.docx"
        },
        "revised": {
            "type": "url",
            "url": "http://mysite.com/documents/revised.docx"
        }
    }
}
Successful Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "viewingSessionId": "XYZ..."
}
Error Responses
Response when source.type of "comparison" is requested and MSO renderer is not licensed

Document comparison feature requires MSO enabled license to be active. If you attempt to set source.type to "comparison" when the license is not active, you will receive an HTTP 480 error response with an errorCode of "FeatureNotLicensed":

HTTP/1.1 480 FeatureNotLicensed
Content-Type: application/json

{
     "errorCode": "FeatureNotLicensed",
     "errorDetails": {
          "in": "body",
          "at": "source.type"
     }
}
Response when source.type of "comparison" is requested and MSO renderer is not enabled

Document comparison feature requires Microsoft Office renderer to be configured, see "fidelity.msOfficeDocumentsRenderer" parameter in the central configuration file. If you attempt to set source.type to "comparison", when the renderer is not configured, you will receive an HTTP 480 error response with an errorCode of "FeatureDisabled":

HTTP/1.1 480 FeatureDisabled
Content-Type: application/json

{
     "errorCode": "FeatureDisabled",
     "errorDetails": {
          "in": "body",
          "at": "source.type"
     }
}
Response when attempting to use documentId when source.type is set to "comparison"

Use of documentId and source.type` of "comparison"` is not be supported

HTTP/1.1 480 InputNotSupportedWithDocumentId
Content-Type: application/json

{
     "errorCode": "InputNotSupportedWithDocumentId",
     "errorDetails": {
          "in": "body",
          "at": "source.type"
     }
}

PUT /ViewingSession/u{viewingSessionId}/SourceFile

Routes key: PutViewingSessionSourceFile

Uploads a document to the session.

Request

Request Header

Name Description
Accusoft-Secret A secret key

Request Body

A document to be uploaded.

Response

Successful Response

HTTP/1.1 200 OK

Error Responses

Status Code JSON errorCode Description
403 "InvalidSecret" The secret key, provided in the Accusoft-Secret header is invalid.

Examples

PUT pas_base_url/ViewingSession/u{viewingSessionId}/SourceFile
Accusoft-Secret: mysecretkey

<<file bytes>>

Successful Response

HTTP/1.1 200 OK

Error Response

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "errorCode": "InvalidSecret"
}

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

Routes key: PutViewingSessionOriginalSourceFile

Uploads original document to the comparison viewing session.

Request

Request Header

Name Description
Accusoft-Secret A secret key

Request Body

A document to be uploaded.

Response

Successful Response

HTTP/1.1 200 OK

Error Responses

Status Code JSON errorCode Description
403 "InvalidSecret" The secret key, provided in the Accusoft-Secret header is invalid.
480 "CannotChangeDocument" The viewing session already has an original source document.
480 "UnsupportedFormatForComparison" An original document file format is not one of 'doc' or 'docx'. See errorDetails in the response body.
480 "IncorrectUsage" The viewing session is already used for viewing of a single source document.
480 "FeatureNotLicensed" MSO enabled license is not installed.
480 "FeatureDisabled" Microsoft Office renderer is not configured.

Examples

PUT pas_base_url/v2/viewingSessions/{ViewingSessionID}/sourceFile/original
Accusoft-Secret: mysecretkey

<<file bytes>>

Successful Response

HTTP/1.1 200 OK

Error Responses

Response when invalid secret key has been provided
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "errorCode": "InvalidSecret"
}
Response when attempting to change a source document that has already been assigned

Once a viewing session is given a source document, that document cannot be changed. If a viewing session already has a source document and you attempt to assign a document by reference, you will receive an HTTP 480 error response with an errorCode of "CannotChangeDocument":

HTTP/1.1 480 CannotChangeDocument
Content-Type: application/json

{
     "errorCode": "CannotChangeDocument"
}
Response when source document file format is not supported for comparison

Document comparison feature supports only "doc" and "docx" source document formats. If you attempt to assign any other format for comparison, you will receive an HTTP 480 error response with an errorCode of "UnsupportedFormatForComparison":

HTTP/1.1 480 UnsupportedFormatForComparison
Content-Type: application/json

{
    "errorCode": "UnsupportedFormatForComparison",
    "errorDetails": {
        "in": "body"
    }
}
Response when a single source document is assigned to the viewing session already

The viewing session type depends on the documents that have been assigned to it, and can not be changed. If a single source document has been assigned, regular viewing session is created. If original and/or revised documents have been assigned, comparison viewing session is created.

If you assign a single source document to a viewing session, and then attempt to assign original document, you will receive an HTTP 480 error response with an errorCode of "IncorrectUsage".

HTTP/1.1 480 IncorrectUsage
Content-Type: application/json

{
     "errorCode": "IncorrectUsage"
}
Response when MSO renderer is not licensed

Document comparison feature requires MSO enabled license to be active. If you attempt to provide an original document, when the license is not active, you will receive an HTTP 480 error response with an errorCode of "FeatureNotLicensed":

HTTP/1.1 480 FeatureNotLicensed
Content-Type: application/json

{
     "errorCode": "FeatureNotLicensed"
}
Response when MSO renderer is not enabled

Document comparison feature requires Microsoft Office renderer to be configured, see "fidelity.msOfficeDocumentsRenderer" parameter in the central configuration file. If you attempt to provide an original document, when the renderer is not configured, you will receive an HTTP 480 error response with an errorCode of "FeatureDisabled":

HTTP/1.1 480 FeatureDisabled
Content-Type: application/json

{
     "errorCode": "FeatureDisabled"
}

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

Routes key: PutViewingSessionRevisedSourceFile

Uploads revised document to the comparison viewing session.

Request

Request Header

Name Description
Accusoft-Secret A secret key

Request Body

A document to be uploaded.

Response

Successful Response

HTTP/1.1 200 OK

Error Responses

Status Code JSON errorCode Description
403 "InvalidSecret" The secret key, provided in the Accusoft-Secret header is invalid.
480 "CannotChangeDocument" The viewing session already has a revised source document.
480 "UnsupportedFormatForComparison" A revised document file format is not one of 'doc' or 'docx'. See errorDetails in the response body.
480 "IncorrectUsage" The viewing session is already used for viewing of a single source document.
480 "FeatureNotLicensed" MSO enabled license is not installed.
480 "FeatureDisabled" Microsoft Office renderer is not configured.

Examples

PUT pas_base_url/v2/viewingSessions/{ViewingSessionID}/sourceFile/revised
Accusoft-Secret: mysecretkey

<<file bytes>>

Successful Response

HTTP/1.1 200 OK

Error Responses

Response when invalid secret key has been provided
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "errorCode": "InvalidSecret"
}
Response when attempting to change a source document that has already been assigned

Once a viewing session is given a source document, that document cannot be changed. If a viewing session already has a source document and you attempt to assign a document by reference, you will receive an HTTP 480 error response with an errorCode of "CannotChangeDocument":

HTTP/1.1 480 CannotChangeDocument
Content-Type: application/json

{
     "errorCode": "CannotChangeDocument"
}
Response when source document file format is not supported for comparison

Document comparison feature supports only "doc" and "docx" source document formats. If you attempt to assign any other format for comparison, you will receive an HTTP 480 error response with an errorCode of "UnsupportedFormatForComparison":

HTTP/1.1 480 UnsupportedFormatForComparison
Content-Type: application/json

{
    "errorCode": "UnsupportedFormatForComparison",
    "errorDetails": {
        "in": "body"
    }
}
Response when a single source document is assigned to the viewing session already

The viewing session type depends on the documents that have been assigned to it, and can not be changed. If a single source document has been assigned, regular viewing session is created. If original and/or revised documents have been assigned, comparison viewing session is created.

If you assign a single source document to a viewing session, and then attempt to assign revised document, you will receive an HTTP 480 error response with an errorCode of "IncorrectUsage".

HTTP/1.1 480 IncorrectUsage
Content-Type: application/json

{
     "errorCode": "IncorrectUsage"
}
Response when MSO renderer is not licensed

Document comparison feature requires MSO enabled license to be active. If you attempt to provide a revised document, when the license is not active, you will receive an HTTP 480 error response with an errorCode of "FeatureNotLicensed":

HTTP/1.1 480 FeatureNotLicensed
Content-Type: application/json

{
     "errorCode": "FeatureNotLicensed"
}
Response when MSO renderer is not enabled

Document comparison feature requires Microsoft Office renderer to be configured, see "fidelity.msOfficeDocumentsRenderer" parameter in the central configuration file. If you attempt to provide a revised document, when the renderer is not configured, you will receive an HTTP 480 error response with an errorCode of "FeatureDisabled":

HTTP/1.1 480 FeatureDisabled
Content-Type: application/json

{
     "errorCode": "FeatureDisabled"
}

 

 

©2018. Accusoft Corporation. All Rights Reserved.

Send Feedback