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:
- Accusoft-Secret: mysecretkey
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" }