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

• source (object) Properties relevant to PrizmApplicationServices will reside in this object. Note: This object will be removed before sending the rest of the body to PCCIS.
  • type (string) Required. Set to document.
  • fileName (string) Required. Filename that the Storage Provider API can use.
  • markupId (string) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given.
  • downloadName (string) Name to use for the filename attribute in the Content-Disposition response header, when downloading the original document. We will use the fileName if this option is not provided.
  • fileExtension (string) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. We will get the extension from fileName if this option is not provided.
  • documentId (string) A customer supplied identifier which is used to uniquely identify a viewing package. The documentId is required to have a non-zero length less than 256 characters and must consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. If the value refers to a complete viewing package it will be used for the viewing session. If a viewing package does not exist for the given documentId, the current request will be forwarded to PCCIS and a new viewing package creator process will be started which, once complete, can be used by viewing sessions using the same documentId value. If the value refers to a viewing package in error, the request will be forwarded to PCCIS and the viewing package must expire or be deleted before another can be created.

When using a URL

• source (object) Properties relevant to PrizmApplicationServices will reside in this object. Note: This object will be removed before sending the rest of the body to PCCIS.
  • type (string) Required. Set to url.
  • url (string) Required. URL to create a viewing session from.
  • headers (object) Request headers to send from PrizmApplicationServices when retrieving the URL.
  • acceptBadSslCertificate (boolean) If true, requires SSL certificates be valid. Default is false. Note: to use your own certificate authority, you need to specify an agent that was created with that CA as an option.
  • markupId (string) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given.
  • downloadName (string) Name to use for the filename attribute in the Content-Disposition response header, when downloading the original document.
  • fileExtension (string) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded.
  • documentId (string) A customer supplied identifier which is used to uniquely identify a viewing package. The documentId is required to have a non-zero length less than 256 characters and must consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. If the value refers to a complete viewing package it will be used for the viewing session. If a viewing package does not exist for the given documentId, the current request will be forwarded to PCCIS and a new viewing package creator process will be started which, once complete, can be used by viewing sessions using the same documentId value. If the value refers to a viewing package in error, the request will be forwarded to PCCIS and the viewing package must expire or be deleted before another can be created.

When uploading the document

• source (object) Properties relevant to PrizmApplicationServices will reside in this object. Note: This object will be removed before sending the rest of the body to PCCIS.
  • type (string) Required. Set to upload.
  • displayName (string) Required. The display name of the document that's being uploaded. E.g. "sample.doc"
  • markupId (string) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given.
  • downloadName (string) Name to use for the filename attribute in the Content-Disposition response header, when downloading the original document. We will use the displayName if this option is not provided.
  • fileExtension (string) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. We will get the extension from displayName if this option is not provided.
  • documentId (string) A customer supplied identifier which is used to uniquely identify a viewing package. The documentId is required to have a non-zero length less than 256 characters and must consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. If the value refers to a complete viewing package it will be used for the viewing session. If a viewing package does not exist for the given documentId, the current request will be forwarded to PCCIS and a new viewing package creator process will be started which, once complete, can be used by viewing sessions using the same documentId value. If the value refers to a viewing package in error, the request will be forwarded to PCCIS and the viewing package must expire or be deleted before another can be created.

When using a viewing package

• source (object) Properties relevant to PrizmApplicationServices will reside in this object. Note: This object will be removed before sending the rest of the body to PCCIS.
  • type (string) Required. Set to viewingPackage.
  • documentId (string) Required. A customer supplied identifier which is used to uniquely identify a viewing package. The documentId is required to have a non-zero length less than 256 characters and must consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. This value must refer to a complete viewing package, otherwise the viewing session will not be created and an error will be returned.
  • markupId (string) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given.
  • downloadName (string) Name to use for the filename attribute in the Content-Disposition response header, when downloading the original document.

When comparing two documents

• source (object) Properties relevant to PrizmApplicationServices will reside in this object. Note: This object will be removed before sending the rest of the body to PCCIS.
  • type (string) Required. Set to comparison.
  • original (object) Required. Original document to compare.
    • Additional properties will depend on where the document comes from. See below.
  • revised (object) Required. Revised document to compare.
    • Additional properties will depend on where the document comes from. See below.
  • markupId (string) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given.
  • downloadName (string) Name to use for the filename attribute in the Content-Disposition response header, when downloading the comparison result. We will use "comparison.docx" if this option is not provided.

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:

• type (string) Required. Set to document.
• fileName (string) Required. Filename that the Storage Provider API can use.
• downloadName (string) Name to use for the filename attribute in the Content-Disposition response header, when downloading the original document. We will use the fileName if this option is not provided.
• fileExtension (string) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. We will get the extension from fileName if this option is not provided.

When original or revised is a URL:

• type (string) Required. Set to url.
• url (string) Required. URL to create a viewing session from.
• headers (object) Request headers to send from PrizmApplicationServices when retrieving the URL.
• acceptBadSslCertificate (boolean) If true, requires SSL certificates be valid. Default is false. Note: to use your own certificate authority, you need to specify an agent that was created with that CA as an option.
• downloadName (string) Name to use for the filename attribute in the Content-Disposition response header, when downloading the original document.
• fileExtension (string) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded.

When original or revised will be uploaded:

• type (string) Required. Set to upload.
• displayName (string) Required. The display name of the document that's being uploaded. E.g. "sample.doc"
• downloadName (string) Name to use for the filename attribute in the Content-Disposition response header, when downloading the original document. We will use the displayName if this option is not provided.
• fileExtension (string) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. We will get the extension from displayName if this option is not provided.

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.

• viewingSessionId (string) The ID for this new viewing session.

Error Responses

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 Headers

Request Body

A document to be uploaded.

Response

Successful Response

HTTP/1.1 200 OK

Error Responses

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 Headers

Request Body

A document to be uploaded.

Response

Successful Response

HTTP/1.1 200 OK

Error Responses

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 Headers

Request Body

A document to be uploaded.

Response

Successful Response

HTTP/1.1 200 OK

Error Responses

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