Introduction

The PrizmDoc Server viewing sessions REST API is used by PAS and is maintained for backwards compatibility. It should not be used for new application development. Please use the newer PAS viewing sessions REST API instead.

Available URLs

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

Request Body

• minSecondsAvailable (Integer) Minimum number of seconds the viewing session will exist or 0 to use the default value specified by product configuration. This property is only really useful if you explicitly set serverCaching to "none". When serverCaching is "full", the only allowed value for this property is 0. Default is 0.
• documentSource (String) Specifies how the source document will be provided. Default is "api". Possible values:
  • "api" - The source document will be provided by the calling application in a subsequent API request.
  • "http" - PrizmDoc Server will download the source document from a URL specified by externalId.
  • "file" - PrizmDoc Server will use a local file as the source document using the file path specified by externalId.

    NOTE: By default, "file" is not enabled as a valid documentSource. Enable "file" by adding it to the viewing.sessionConstraints.documentSource.allowedValues array in Central Configuration.

• externalId (String) Required when documentSource is "http" or "file". Indicates where the source document should be acquired from:
  • When documentSource is "http": A URL where the source document will be downloaded from.
  • When documentSource is "file": A path to a file on the server which will be used as the source document.
• documentExtension (String) - File extension of the source document (like "docx", "html", or "csv") used to indicate the source document file format. Often unnecessary. Only required when 1) the documentSource is "http" or "file" but the externalId containing the URL or file path did not end with a recognizable file extension and 2) the source document file format could not be automatically detected (this most-commonly occurs for text-based file formats, such as txt, csv, and html).

  NOTE: If Format Detection is disabled, then the source document format will never be automatically detected.

• password (String) Password to use when opening a password-protected source document.
• tenantId (String) Custom, arbitrary tenant id to be associated with the viewing session. PrizmDoc Server has no concept of tenants; if provided, this metadata is only for use by the calling application.
• origin (Object) Custom, arbitrary set of key/value string pairs to be associated with the viewing session. Intended for associating end user origin data (like IP address or hostname), but you can use any set of key/value strings you want.

• render (Object) Options which control how browser content is rendered:

  • html5 (Object) Options when the output format is HTML:

    • alwaysUseRaster (Boolean) Required. Determines whether only raster data, instead of SVG, should be created for the viewing session. With modern browsers, it is rare to only want raster. This is typically set to false. See the CAD Files topic for a use case when this option might be useful.
    • svgMaxImageSize (Number) The maximum edge length, in pixels, that is allowable for any image when creating SVG. For example, a value of 8000 would ensure that any images in a PDF whose width or height were greater than 8000 pixels would be down-sampled before the image was added to the final SVG. Default is configurable, but is typically 8000. To disable this optimization, use a value of 0.

      NOTE: When embedded images are very large and the optimization is disabled, browsers may display a placeholder icon instead of an image. If you want to keep high resolution images, consider setting this parameter to a large value, such as 30000, instead of setting it to 0.

    • timeZone (String) Specifies the time zone for the rendering of documents. Currently, this only affects date and time in email headers. If not specified, date and time in email headers will be displayed according to the fileTypes.email.timeZone Central Configuration parameter.
      Supported Values: See Supported Time Zones.
      See Configure Date and Time Headers in Email Documents for more details.
      

      IMPORTANT: This experimental parameter is a work-in-progress that is not officially supported by Accusoft. Its behavior may change at any time in a future release of the product.

      NOTE: Markup burning for a viewing session currently ignores this parameter. Result of markup burning uses the time zone defined in the server configuration.

      NOTE: This parameter will be ignored if the __experimental.fileTypes.email.renderMeetingInfo Central Configuration parameter is set to true.

    • vectorTolerance (Number) For CAD documents, the amount of path simplification that is allowable when creating the SVG. Path simplification will merge points which are "close together" to create optimized SVG. You can think of this value as defining what "close together" means. Higher values introduce more simplification but also more distortion. Default is configurable, but is typically 0.3. Cannot be greater than 10.0. To disable this optimization, use a value of 0.

    • rasterResolution (Integer) Deprecated. Providing this value no longer has any effect.
  • flash (Object) Deprecated. We no longer produce Flash content. Providing these options no longer has any effect.
    • optimizationLevel (Integer) Deprecated. Providing this value no longer has any effect.
• watermarks (Array of Objects) Objects describing watermarks which should be applied to page content. Each item must be an object which conforms to the following:
  • text watermark:
    • type: "text" (String) Required. Must be set to "text" to indicate the object represents a text watermark.
    • text (String) Actual text of the watermark. Within the string, you can use the following special tokens to insert dynamic values:
      • {{pageNumber}} - Will be replaced with the current page number.
      • {{pageCount}} - Will be replaced with the total number of pages.
    • opacity (Number) Opacity of the watermark. 1.0 is completely opaque, 0.0 is completely transparent. Default is 1.0.
    • color (String) Text color. Can be any valid CSS color name (like "red") or hex value (like "#FF0000"). Default is "black".
    • fontFamily (String) Font family for the text. Default for SVG output is to use the browser's default font. Default for raster output is unspecified.
    • fontSize (String) Font size specified in points (like "12pt"). Default for SVG output is to use the browser's default font size. Default for raster output is unspecified.
    • fontWeight (String) Determines the font weight. Possible values:
      • "normal" (default)
      • "bold"
    • fontStyle (String) Determines the font style. Possible values:
      • "normal" (default)
      • "italic"
    • textDecoration (String) Possible values:
      • "none" (default)
      • "underlined"
    • horizontalAlign (String) Determines the horizontal position of the watermark. Default is "center". Possible values:
      • "left" - Text will be horizontally anchored to the left side of the page and text will be left aligned.
      • "center" Text will be horizontally anchored to the center of the page and text will be centered. (default)
      • "right" - Text will be horizontally anchored to the right side of the page and text will be right aligned.
    • verticalAlign (String) Determines the vertical position of the watermark. Default is "middle". Possible values:
      • "top" - Text will be vertically anchored to the top of the page.
      • "middle" Text will be vertically anchored to the middle of the page. (default)
      • "bottom" - Text will be vertically anchored to the bottom of the page.
  • diagonal text watermark:
    • type: "diagonalText" (String) Required. Must be set to "diagonalText" to indicate the object represents a diagonal text watermark.
    • text (String) Actual text of the watermark. Within the string, you can use the following special tokens to insert dynamic values:
      • {{pageNumber}} - Will be replaced with the current page number.
      • {{pageCount}} - Will be replaced with the total number of pages.
    • opacity (Number) Opacity of the watermark. 1.0 is completely opaque, 0.0 is completely transparent. Default is 1.0.
    • color (String) Text color. Can be any valid CSS color name (like "red") or hex value (like "#FF0000"). Default is "black".
    • fontFamily (String) Font family for the text. Default for SVG output is to use the browser's default font. Default for raster output is unspecified.
    • fontSize (String) Font size specified in points (like "12pt"). Default for SVG output is to use the browser's default font size. Default for raster output is unspecified.
    • fontWeight (String) Determines the font weight. Possible values:
      • "normal" (default)
      • "bold"
    • fontStyle (String) Determines the font style. Possible values:
      • "normal" (default)
      • "italic"
    • textDecoration (String) Possible values:
      • "none" (default)
      • "underlined"
    • slope (String) Controls the text angle. Default is "up". Possible values:
      • "up" - Text will start in the lower-left corner of the page and extend upwards to the upper-right corner of the page. (default)
      • "down" - Text will start in the upper-left corner of the page and extend downwards to the lower-right corner of the page.
  • image watermark:
    • type: "image" (String) Required. Must be set to "image" to indicate the object represents an image watermark.
    • opacity (Number) Opacity of the watermark. 1.0 is completely opaque, 0.0 is completely transparent. Default is 1.0.
    • src (String) Required. URL or work file id of a PNG image to use for this watermark. When using a URL, the URL must be accessible from the server where PrizmDoc Server is running.

      NOTE: The src MUST be a PNG. If you use a different image format, invalid watermarks will be created.

    • horizontalAlign (String) Determines the horizontal position of the watermark. Default is "center". Possible values:
      • "left" - Image will be horizontally anchored near the left side of the page.
      • "center" Image will be horizontally anchored to the center of the page. (default)
      • "right" - Image will be horizontally anchored near the right side of the page.
    • verticalAlign (String) Determines the vertical position of the watermark. Default is "middle". Possible values:
      • "top" - Image will be vertically anchored near the top of the page.
      • "middle" Image will be vertically anchored to the middle of the page. (default)
      • "bottom" - Image will be vertically anchored near the bottom of the page.
    • scale (Number) - Determines the relative size of the image as compared to the size of the page. Value must be between 0.0 and 1.0. A value of 1.0 indicates the image will be scaled to the size of the page while 0.0 indicates the image will be scaled infinitesimally small and will not be rendered. Default is 0.25.
    • autoSize (String) When set, the image will be automatically sized to fill the page (any value provided for scale, horizontalAlign, and verticalAlign will be ignored). Possible values:
      • "fit" - Image will be scaled to be as large as possible while still completely fitting within the page. The aspect ratio of the image is maintained.
      • "fill" - Image will be scaled to be large enough that the entire page is covered by the image. Some of the image may fall off the edge of the page, but the entire page is guaranteed to be covered by some part of the image. The aspect ratio of the image is maintained.
      • "stretch" - Image width and height will be independently resized so that the image width and height are the same as the page. The aspect ratio of the image is ignored.
• watermarkText (String) Deprecated. Providing this value no longer has any effect. Use watermarks instead.
• pageContentEncryption (String) - Controls whether or not page content will be encrypted for the viewing session. See the Enabling Content Encryption topic for more information about this feature. Possible values:
  • "default" - Product configuration will be used to determine whether or not page content will be encrypted (see viewing.contentEncryption.enabled in the Central Configuration file).
  • "enabled" - Page content will be encrypted for the viewing session.
  • "disabled" - Page content will not be encrypted for the viewing session.
• countOfInitialPages (Integer) Number of pages which should be immediately pre-converted, or 0 if all pages should be immediately pre-converted. Default is 0.
• startConverting (String) When the documentSource is "http" or "file", controls whether initial pages should be converted as soon as the document has been acquired. Default is "none". Possible values:
  • "none" - Conversion will begin only after the session is explicitly started or page content or attributes are requested. (default)
  • "initialPages" - Conversion will begin as soon as the source document has been acquired, unless the document format is one of the file formats provided in the allowedClientFileFormats property.
• allowedClientFileFormats (Array of Strings) - This property defines the file formats that will be used for the client-side viewing. When defined, a viewing session's source document will not trigger processing of the document. Consequently, the HTML5 Viewing and Search Tasks APIs will be disabled for that viewing session. Additionally, when this property is defined, the GET /v2/viewingSessions/{viewingSessionId}/clientFile route will return the document in one of the specified allowed formats. Currently, the only allowed client file format is "pdf".
• contentType (String) - Determines what kind of browser content will be immediately pre-generated (other kinds of content may still be generated if explicitly requested). Possible values:
  • "svgb" - Pre-generate fully-optimized SVG (uses a unicode inline font to store glyph definitions). Smallest possible SVG, but may not be compatible with some browsers. Recommended whenever possible.
  • "svga" - Pre-generate partially-optimized SVG (uses a non-unicode inline font to store only the most frequently-occurring glyph definitions). May not be compatible with some browsers. Use only if "svgb" content is not compatible with the target browser.
  • "svg" - Pre-generate unoptimized SVG (no font is used; glyph definitions are expressed as SVG path operations). Broadest compatibility with browsers but typically much larger, so it renders and scrolls much slower than "svgb" and "svga". Not recommended. Use only as a fallback if both svgb and svga are not compatible with the target browser, or the use of webfonts is disabled in the target browser.
  • "png" - Pre-generate raster content.
• serverCaching (String) Controls whether output is kept for potential reuse by other viewing sessions. Default is "full". Possible values:
  • "full" - Output will be written to disk on the server and retained for reuse by other viewing sessions created for the same source document. Output will not be deleted until the configured viewing cache lifetime is reached (which is a full day with an out-of-box configuration; see viewing.cacheLifetime in Central Configuration). Saves processing time if a source document is viewed repeatedly before the cached data is deleted, but does consume more disk space. (default)
  • "none" - Output will be written to disk on the server but only retained for the duration of the viewing session and never shared with other viewing sessions. Once the viewing session expires, the output will be deleted from the disk. Saves disk space if you know that it is unlikely a source document will ever be viewed more than once, but can result in redundant processing if the same source document is viewed repeatedly.
• serverSideSearch (String) Determines whether the server-side search feature will be available for the viewing session. Default is "enabled". Possible values:
  • "enabled" - Server-side search will be available for the viewing session. (default)
  • "disabled" - Server-side search will not be available for the viewing session.
• attachmentIndex (Integer) - Intended for use only by PrizmDoc Server when it automatically creates viewing sessions for attachments. This is not a property your application should use. If the source document is an attachment that belongs to another document (such as an email or PDF Portfolio), the 1-based index of this attachment in the list of all attachments (e.g. 1 means it was the first attachment, 2 means it was the second, etc.) or 0 to indicate that the source document is not an attachment. Default is 0.
• attachmentDisplayName (String) - Intended for use only by PrizmDoc Server when it automatically creates viewing sessions for attachments. This is not a property your application should use. If the source document is an attachment that belongs to another document (such as an email or PDF Portfolio), the filename of the attachment or null. Default is null.

Successful Response

Response Body

JSON with metadata about the created viewing session.

• viewingSessionId (String) Unique id for this viewing session.
• affinityToken (String) Affinity token for this viewing session. Present when clustering is enabled.

Error Responses

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

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\nNOT FOR DISTRIBUTION",
            "color": "red",
            "fontFamily": "Consolas",
            "fontSize": "16pt",
            "fontWeight": "bold",
            "verticalAlign": "bottom",
            "horizontalAlign": "right"
        }
    ]
}

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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

Successful Response

JSON metadata about the viewing session:

• creationTime (String) A UTC-formatted time string representing the moment the viewing session was created.
• minSecondsAvailable (Integer) Minimum number of seconds the viewing session will exist.
• documentSource (String) Will be one of the following:
  • null - No value was specified in the initial POST to create the viewing session. Same as "api".
  • "api" - The source document will be provided by the calling application via an API request.
  • "http" - PrizmDoc Server will download the source document from the URL specified by externalId.
  • "file" - PrizmDoc Server will use a local file as the source document using the file path specified by externalId.
• externalId (String) Indicates where the source document was acquired from when the documentSource is "http" or "file":
  • When documentSource is "http": The URL where the source document was acquired from
  • When documentSource is "file": The path to the file on the server which was used as the source document
• documentExtension (String) - File extension of the source document provided in the original POST to create the viewing session or null if no value was provided.
• password (String) Password provided to open the source document.
• tenantId (String) Custom tenant id assigned to the viewing session in the original POST.
• origin (Object) Custom origin data included in the original POST to create the viewing session.
• render (Object) Rendering options in use for the viewing session:
  • html5 (Object) HTML5 output options in use for the viewing session:
    • alwaysUseRaster (Boolean) Indicates whether or not only raster data, instead of SVG, will be created for the viewing session.
    • svgMaxImageSize (Number) The maximum edge length, in pixels, that is allowable for any image when creating the SVG. See POST /ViewingSession for more info.
    • vectorTolerance (Number) For CAD documents, the amount of path simplification that is allowable when creating the SVG. See POST /ViewingSession for more info.
    • rasterResolution (Integer) Deprecated and unused. Provided only for backwards compatibility.
  • flash (Object) Deprecated and unused. Provided only for backwards compatibility.
    • optimizationLevel (Integer) Deprecated and unused. Provided only for backwards compatibility.
• watermarks (Array of Objects) Objects describing watermarks which should be applied to page content. See POST /ViewingSession for more info.
• watermarkText (String) Deprecated and unused. Provided only for backwards compatibility.
• pageContentEncryption (String) - Will be one of the following:
  • null - No value was specified in the initial POST to create the viewing session. Same as "default".
  • "default" - Product configuration will be used to determine whether or not page content will be encrypted (see viewing.contentEncryption.enabled in the Central Configuration file).
  • "enabled" - Page content will be encrypted for the viewing session.
  • "disabled" - Page content will not be encrypted for the viewing session.
• countOfInitialPages (Integer) Number of pages which will be eagerly converted, or 0 if all pages should be eagerly converted. Default is 0.
• startConverting (String) When the documentSource is "http" or "file", indicates whether initial pages will be converted as soon as the document has been acquired. Default is "none". Possible values:
  • null - No value was specified in the initial POST to create the viewing session. Same as "none".
  • "none" - Conversion will begin only after the session is explicitly started or page content or attributes are requested. (default)
  • "initialPages" - Conversion will begin as soon as the source document has been acquired.
• contentType (String) - Indicates what kind of browser content will be eagerly pre-generated (other kinds of content may still be generated if explicitly requested). Will be one of the following:
  • null - No value was specified in the initial POST to create the viewing session.
  • "svgb" - Pre-generate fully-optimized SVG (uses a unicode inline font to store glyph definitions). Smallest possible SVG, but may not be compatible with some browsers. Recommended whenever possible.
  • "svga" - Pre-generate partially-optimized SVG (uses a non-unicode inline font to store only the most frequently-occurring glyph definitions). May not be compatible with some browsers. Use only if "svgb" content is not compatible with the target browser.
  • "svg" - Pre-generate unoptimized SVG (no font is used; glyph definitions are expressed as SVG path operations). Broadest compatibility with browsers but typically much larger, so it renders and scrolls much slower than "svgb" and "svga". Not recommended. Use only as a fallback if both svgb and svga are not compatible with the target browser, or the use of webfonts is disabled in the target browser.
  • "png" - Pre-generate raster content.
• serverCaching (String) Indicates whether output is kept for potential reuse by other viewing sessions. Will be one of the following:
  • "full" - Output will be written to disk on the server and retained for reuse by other viewing sessions created for the same source document. Output will not be deleted until the configured viewing cache lifetime is reached (which is a full day with an out-of-box configuration; see viewing.cacheLifetime in Central Configuration). Saves processing time if a source document is viewed repeatedly before the cached data is deleted, but does consume more disk space. (default)
  • "none" - Output will be written to disk on the server but only retained for the duration of the viewing session and never shared with other viewing sessions. Once the viewing session expires, the output will be deleted from the disk. Saves disk space if you know that it is unlikely a source document will ever be viewed more than once, but can result in redundant processing if the same source document is viewed repeatedly.
• attachmentIndex (Integer) - If the viewing session was created for an attachment on a parent source document (such as an email), the 1-based index of this attachment in the list of all attachments (e.g. 1 means it was the first attachment, 2 means it was the second, etc.). 0 otherwise.
• attachmentDisplayName (String) - If the viewing session was created for an attachment on a parent source document (such as an email), the filename of the attachment this viewing session was created for. null otherwise.
• serverSideSearch (String) Indicates whether or not the server-side search feature will be available for the viewing session. Will be one of the following:
  • "enabled" - Server-side search is available for the viewing session. (default)
  • "disabled" - Server-side search is not available for the viewing session.

Error Responses

Example

Request

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

Response

HTTP/1.1 200 OK
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

NOTE: If Format Detection is disabled, then FileExtension is always required. When provided, FileExtension may only include alpha-numeric characters. If Format Detection is enabled (the default), the use of FileExtension is as follows:

• If we can auto-detect the file format, we ignore FileExtension.
• If we cannot auto-detect the file format, we require a FileExtension be specified, otherwise we return HTTP 580 with an errorCode of "UnrecognizedFileFormat". This most-commonly occurs with text-based source documents (such as txt, csv, or html).

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:

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

Example

Request

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

<<file bytes>>

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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

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

Example

Request

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

<<file bytes>>

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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

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

Example

Request

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

<<file bytes>>

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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

URL Parameters

Request Body when assigning reference for a single document

• refType (string) Required. Must be set to "workFile".
• fileId (string) Required. The id of the work file to use as the source document.

Request Body when comparing two documents

• refType (string) Required. Must be set to "comparison".
• original
  • refType (string) Required. Must be set to "workFile".
  • fileId (string) Required. The id of the work file to use as the original document.
• revised
  • refType (string) Required. Must be set to "workFile".
  • fileId (string) Required. The id of the work file to use as the revised document.

Successful Response

A simple HTTP 200 status code.

Error Responses

Examples

Assigning a single source document

PUT prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../SourceRef
Content-Type: application/json

{
   "refType": "workFile",
   "fileId": "CVBuD7DbQYNoJDqByGierQ",
}

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

HTTP/1.1 200 OK

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

Gets the source document in use for a viewing session.

Request

URL Parameters

Response Headers

Response Body

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

Example

Request

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

Response

200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=MonthlySalesReport.docx; filename*=UTF-8''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.

Request

URL Parameters

Response Headers

Response Body

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

Error Responses

Example

Request

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

Response

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

<<file bytes>>

NOTE: See GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceFile for an example when filename includes non-ASCII characters.

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

Response Headers

Response Body

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

Error Responses

Example

Request

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

Response

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

<<file bytes>>

NOTE: See GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceFile for an example when filename includes non-ASCII characters.

GET /v2/viewingSessions/{viewingSessionId}/restrictions

Returns information about any restrictions enforced by the server for the current viewing session.

Request

URL Parameters

Successful Response

JSON with information about any restrictions currently in place for the viewing session:

• delayEnabled (Boolean) - Indicates whether the server has enforced an artificial delay before the document conversion results are allowed to be delivered to the viewer.
• delaySecondsRemaining (Integer) - The number of seconds remaining in the artificially-imposed delay before the document conversion results are allowed to be delivered to the viewer. Only present when delayEnabled is true.
• downloadDisabled (Boolean) - Indicates whether downloading of the source document has been disabled for this viewing session.
• markupBurnersDisabled (Boolean) Indicates whether the markup burner feature has been disabled for this viewing session.
• formInfoDisabled (Boolean) Indicates whether the form detection feature has been disabled for this viewing session.

Example Responses

When the product is licensed, valid allowedClientFileFormats is provided, and the form detection feature is available

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

{
  "delayEnabled": false,
  "downloadDisabled": false,
  "markupBurnersDisabled": false,
  "formInfoDisabled": false,
  "clientFileRetrievalDisabled": false
}

When the product is licensed, valid allowedClientFileFormats is not supplied, and the form detection feature is available

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

{
  "delayEnabled": false,
  "downloadDisabled": false,
  "markupBurnersDisabled": false,
  "formInfoDisabled": false,
  "clientFileRetrievalDisabled": true
}

When the product is unlicensed (evaluation mode), valid allowedClientFileFormats is provided, and 9 seconds of initial delay are remaining:

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

{
  "delayEnabled": true,
  "delaySecondsRemaining": 9,
  "downloadDisabled": true,
  "markupBurnersDisabled": true,
  "formInfoDisabled": true,
  "clientFileRetrievalDisabled": false
}

When the product is unlicensed (evaluation mode), valid allowedClientFileFormats is not supplied, and 9 seconds of initial delay are remaining:

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

{
  "delayEnabled": true,
  "delaySecondsRemaining": 9,
  "downloadDisabled": true,
  "markupBurnersDisabled": true,
  "formInfoDisabled": true,
  "clientFileRetrievalDisabled": true
}

GET /v2/viewingSessions/{viewingSessionId}/clientFile

Gets the source document of the viewing session for client-side viewing. See the allowedClientFileFormats property of the POST /PCCIS/V1/ViewingSession route.

Request

URL Parameters

Response Headers

Response Body

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

Examples

Request

GET prizmdoc_server_base_url/v2/viewingSessions/XYZ.../clientFile?accept=pdf

NOTE: See the Base URL for PrizmDoc Server topic for more information.

Successful Response

200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=MonthlySalesReport.pdf; filename*=UTF-8''MonthlySalesReport.pdf

<<file bytes>>

Error response when the feature is not licensed

480 FeatureNotLicensed
Content-Type: application/json

{
  "errorCode": "FeatureNotLicensed"
}

Error response when the feature is not turned on

480 DocumentFormatNotAllowed
Content-Type: application/json

{
  "errorCode": "DocumentFormatNotAllowed"
}

Error response when the accept query parameter is not in the array of allowedClientFileFormats (i.e. a docx client file is requested but allowedClientFormats = ["pdf"]).

480 DocumentUnavailable
Content-Type: application/json

{
  "errorCode": "DocumentUnavailable"
}

Error response when the "accept" parameter is missing

480 MissingInput
Content-Type: application/json

{
  "errorCode": "MissingInput",
  "errorDetails": {
    "in": "query",
    "at": "accept",
    "expected": {
      "flags": ["pdf"]
    }
  }
}

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 Server 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

Successful Response

JSON with the work file id.

• fileId (String) - Work file id for the source document of the viewing session.
• affinityToken (String) Work file affinity token. Present when clustering is enabled.

Error Responses

Example

Request

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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 Server 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

Request Headers

Request Body

• viewer (String) - Type of viewer being used. Default is "HTML5". Possible values:
  • "HTML5"

Successful Response

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

Error Responses

Example

Request

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

{
}

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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

Request Headers

Request Body

• httpStatus (Integer) - HTTP status code to respond with for any future requests to this viewing session. Default is 580.
• endUserMessage (String) - Error message to use for both the HTTP reason phrase and Accusoft-Status-Message response header for any future requests to this viewing session. Default is "Session is stopped".
• accusoftErrorNumber (Integer) - Value for the Accusoft-Status-Number response header for any future requests to this viewing session. Default is 580 or httpStatus if it is provided.
• serverLogMessage (String) - Message that should be emitted to the PrizmDoc Server log file when the session is stopped. Default is "The viewing session is stopped on request from the client.".

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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: 418

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

Mark a viewing session as errored so that it can no longer be used but it is still possible to request the source file. (See GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceFile)

Erroring a viewing session can be useful when:

1. It is necessary to stop its usage but keep a source document available to download.
2. The password is invalid for a password-protected source document so the viewing session can be replaced using POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/Replacement API.

When you mark a viewing session as errored, 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 errored viewing session.

Request

URL Parameters

Request Headers

Request Body

• httpStatus (Integer) - HTTP status code to respond with for any future requests to this viewing session. Default is 580.
• endUserMessage (String) - Error message to use for both the HTTP reason phrase and Accusoft-Status-Message response header for any future requests to this viewing session. Default is "Session is errored".
• accusoftErrorNumber (Integer) - Value for the Accusoft-Status-Number response header for any future requests to this viewing session. Default is 580 or httpStatus if it is provided.
• serverLogMessage (String) - Message that should be emitted to the PrizmDoc Server log file when the session is stopped. Default is "The viewing session is errored on request from the client.".

Successful Response

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

Example

Request

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

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

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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: 418

POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/Replacement

Replace the existing viewing session with a new one that has a new password parameter value. The other original viewing session parameters are preserved. If a source document is uploaded it is attached to the newly created viewing session with a new password. The old viewing session is stopped.

The replacement API is useful when a session is errored because of either an invalid or missing password, and you want to replace it with a new session with the same parameters against the same document but with a modified password.

Request

Request Headers

Request Body

• password (String) Password to use when opening a password-protected source document. If the parameter is not provided a new viewing session is created with a default null password parameter value.

URL Parameters

Successful Response

Response Body

JSON with metadata about the created viewing session.

• viewingSessionId (String) Unique id for this viewing session.

Error Responses

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

Example

Request

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

{
    "password":"123"
}

NOTE: See the Base URL for PrizmDoc Server topic for more information.

Response

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

{
    "viewingSessionId": "THMMytF4ACHrxmN2bXj4vahx4Gnwly_kEeFt20XtRau-z43pPHIjUy5JXJ05Wj1MaqvdfsXp98JxIk7ALWkukg"
}

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

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

Request

URL Parameters

Successful Response

HTTP 204 indicating the session was deleted.

Error Responses