PrizmDoc v12.4 - Updated
Viewing Session

Viewing Session

POST /ViewingSession

Routes key: PostViewingSession

Body: a JSON object

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.

Property Type Description
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.
source.type {string} Specify where PrizmApplicationServices can find the document. Can be "document", "url", "upload", or "viewingPackage".
source.fileName {string} (Required if source.type="document"). Filename that the Storage Provider API can use.
source.url {string} (Required if source.type="url"). URL to create a viewing session from.
source.headers {object} (optional) (Optionally used if source.type="url"). Request headers to send from PrizmApplicationServices when retrieving the URL.
source.acceptBadSslCertificate {boolean=false} (optional) (Optionally used if source.type="url"). If true, requires SSL certificates be valid. Note: to use your own certificate authority, you need to specify an agent that was created with that CA as an option.
source.displayName {string} (Required if source.type="upload"). The display name of the document that's being uploaded. E.g. "Sample-2015-09-30T19:17:24Z.doc"
source.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.
source.downloadName {string} (optional) The name that will be used when downloading the original document. We will use the "displayName" or "fileName" if this option is not provided.
source.fileExtension {string} (optional) 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" or "fileName" if this option is not provided.
source.documentId {string} (Required if source.type="viewingPackage", otherwise optional). 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 source.type="viewingPackage", this value must refer to a complete viewing package, otherwise the viewing session will not be created and an error will be returned. For all other source types this value can optionally be provided. 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.

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 http://localhost:3000/ViewingSession
Content-Type: application/json
{
    "source": {
        "type": "document",
        "fileName": "sample.doc"
    }
}

Successful Response:

200 OK
Content-Type: application/json
{ "viewingSessionId": "{viewingSessionId}" }

Errored Response:

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 http://localhost:3000/ViewingSession
Content-Type: application/json
{
    "source": {
        "type": "document",
        "fileName": "sample.doc"
        "documentId": "doc_9495837910qc"
    }
}

Successful Response:

200 OK
Content-Type: application/json
{ "viewingSessionId": "{viewingSessionId}" }

Errored Responses:

Watermarks Input:

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

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.

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:

480
Content-Type: application/json
{
    "errorCode": "InputConflictsWithViewingPackage",
    "in": "body",
    "at": "source.fileName"
}

Create a session using a url

POST http://localhost:3000/ViewingSession
Content-Type: application/json
{
    "source": {
        "type": "url",
        "url": "http://google.com/",
        "headers": {
            "user-agent": "PrizmShare"
        },
        "acceptBadSslCertificate": true
    }
}

Successful Response:

200 OK
Content-Type: application/json
{ "viewingSessionId": "{viewingSessionId}" }

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 http://localhost:3000/ViewingSession
Content-Type: application/json
{
    "source": {
        "type": "viewingPackage",
        "documentId": "doc_9495837910qc"
    }
}

Successful Response:

200 OK
Content-Type: application/json
{ "viewingSessionId": "{viewingSessionId}" }

Errored Response:

480 InvalidInput
Content-Type: application/json
{
    "errorCode": "InvalidInput",
    "in": "body",
    "at": "source.documentId",
    "expected": {
        "type": "string"
    }
}   

Passing Additional parameters to the back end

POST http://localhost:3000/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:

200 OK
Content-Type: application/json
{ "viewingSessionId": "{viewingSessionId}" }

Create a session by uploading a document

Creates a new blank session

POST htp://localhost:3000/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:

200 OK
Content-Type: application/json
{ "viewingSessionId": "{viewingSessionId}" }

PUT /ViewingSession/u{viewingSessionId}/SourceFile

Routes key: PutViewingSessionSourceFile

Uploads a document to the session.

Headers:

Body: a document

Examples

PUT http://localhost:3000/ViewingSession/u{viewingSessionId}/SourceFile
Accusoft-Secret: mysecretkey
Body: a document

Successful Response:

200 OK

Errored Response:

403 Forbidden
Content-Type: application/json
{ "errorCode": "InvalidSecret" }