PrizmDoc Viewer v13.18 Release - Updated
API Reference / PrizmDoc Server REST API / Viewer Support / Viewing Sessions
In This Topic
    Viewing Sessions
    In This Topic

    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

    URL Description
    POST /PCCIS/V1/ViewingSession Creates a new viewing session.
    GET /PCCIS/V1/ViewingSession/u{viewingSessionId} Gets information about a viewing session.
    PUT /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceFile Uploads the source document to be used for a viewing session.
    PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/original When viewing a comparison of two source documents, uploads the first of the two source documents.
    PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/revised When viewing a comparison of two source documents, uploads the second of the two source documents.
    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.
    GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/SourceFile Downloads the source document in use for a viewing session.
    GET /v2/viewingSessions/{viewingSessionId}/sourceFile/original When viewing a comparison of two documents, downloads the first of the two source documents.
    GET /v2/viewingSessions/{viewingSessionId}/sourceFile/revised When viewing a comparison of two documents, downloads the second of the two source documents.
    GET /v2/viewingSessions/{viewingSessionId}/restrictions Returns information about any restrictions enforced by the server for the current viewing session.
    GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/FileId Gets the work file id for the source document in use for a viewing session.
    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.
    POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/Notification/SessionStopped Invalidates a viewing session so that it can no longer be used.
    POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/Notification/SessionErrored Marks a viewing session as errored so that it can no longer be used.
    POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/Replacement Replaces a viewing session with new parameters.
    DELETE /PCCIS/V1/ViewingSession/u{viewingSessionId} Deletes a viewing session.

    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

    Name Description
    Content-Type Should be application/json
    Accusoft-Affinity-Hint Some sort of string value which uniquely identifies the source document you intend to use for the viewing session. Used to ensure that two viewing sessions created with the same Accusoft-Affinity-Hint are very likely to be handled by the same server, increasing the chances that cached output is reused for viewing sessions of the same source document. See Optimizing Cache Performance for Cluster Mode.
    Accusoft-Affinity-Token When you intend to use an existing work file as the source document via a subsequent call to PUT /SourceRef, the affinityToken of the existing work file. Required only when you intend to use an existing work file as the source document.

    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.
        • 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.
        • 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 eagerly converted, or 0 if all pages should be eagerly 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.
    • contentType (String) - Determines what kind of browser content will be eagerly 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), 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), 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:

    Status Code JSON errorCode Description
    480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
    480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
    480 "InputNotSupportedWithServerCachineEnabled" Can occur when minSecondsAvailable is specified when serverCaching is not set to "none". See errorDetails in the response body.

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

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    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

    Status Code Reason Phrase Description
    403 The session is invalid or has expired You requested a valid {viewingSessionId} but it is no longer available.
    500 Internal Server Error Can occur if you forget to prefix the {viewingSessionId} portion of the URL with u, or if you simply request an invalid {viewingSessionId}.

    Example

    Request

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

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.
    {FileExtension} Required for text-based formats (such as txt, csv, html). File extension of the document being uploaded. This parameter may or may not be required depending on the file type and whether Format Detection is enabled. Note that the extension must not include the leading period (for example, csv is accepted but .csv will return an error). Extensions are not case sensitive. > 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:

    Status Code JSON errorCode Description
    480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because one or more files (original and/or revised) have already been provided for comparison.

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

    Status Code Accusoft-Status-Message Header Description
    580 "Unrecognized File Format" Occurs when the file format cannot be automatically detected. To avoid this, provide an explicit FileExtension query string parameter for this kind of file. This most-commonly occurs with text-based source documents where we require an explicit FileExtension to know the file format (such as txt, csv, or html). You may need to create a new viewing session for the PUT to succeed.
    580 "Watermark image download failed" Occurs when image watermark defined in the Viewing Session cannot be downloaded.

    Example

    Request

    PUT prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../SourceFile?FileExtension=doc
    
    <<file bytes>>
    

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    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

    Status Code JSON errorCode Description
    404 - No viewing session with the provided viewingSessionId could be found.
    480 "CannotChangeDocument" The viewing session already has an original document assigned.
    480 "UnsupportedFormatForComparison" The uploaded file was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files).
    480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document has already been provided.
    480 "FeatureNotLicensed" The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
    480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

    Example

    Request

    PUT prizmdoc_server_base_url/v2/viewingSessions/XYZ.../sourceFile/original
    
    <<file bytes>>
    

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    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

    Status Code JSON errorCode Description
    404 - No viewing session with the provided viewingSessionId could be found.
    480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
    480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
    480 "CannotChangeDocument" The viewing session already has a revised source document assigned.
    480 "UnsupportedFormatForComparison" The uploaded file was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files).
    480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document has already been provided.
    480 "FeatureNotLicensed" The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
    480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

    Example

    Request

    PUT prizmdoc_server_base_url/v2/viewingSessions/XYZ.../sourceFile/revised
    
    <<file bytes>>
    

    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

    Name Description
    Content-Type Must be application/json

    URL Parameters

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    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

    Status Code JSON errorCode Description
    480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
    480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
    480 "NotFound" The given work file has expired or does not exist. See errorDetails in the response body.
    480 "CannotChangeDocument" The viewing session already has a source document assigned. See errorDetails in the response body.
    480 "UnsupportedFormatForComparison" One of the files provided for comparison was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files). See errorDetails in the response body.
    480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you have already provided a source document and then attempt to provide an original and revised document pair, or vice versa, you will receive this error.
    480 "FeatureNotLicensed" The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
    480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

    Examples

    Assigning a single source document
    PUT prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../SourceRef
    Content-Type: application/json
    
    {
       "refType": "workFile",
       "fileId": "CVBuD7DbQYNoJDqByGierQ",
    }
    
    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",
        }
    }
    
    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.
    {ContentDispositionFilename} The filename as a URL-encoded string, without extension, to be used in the Content-Disposition response header (appropriate file extension such as doc or docx will automatically be added). By default, the value will be SourceFile.<ext>.

    Response Headers

    Name Description
    Content-Disposition Indicates to a browser that the response body should be treated as a file download and specifies the filename the browser should use.
    Content-Type The most-specific MIME type for the returned document or application/octet-stream otherwise.

    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
    

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.
    {contentDispositionFilename} The filename as a URL-encoded string, without extension, to be used in the Content-Disposition response header (appropriate file extension such as doc or docx will automatically be added). By default, the value will be OriginalSourceFile.<ext>.

    Response Headers

    Name Description
    Content-Disposition Indicates to a browser that the response body should be treated as a file download and specifies the filename the browser should use.
    Content-Type The most-specific MIME type for the returned document or application/octet-stream otherwise.

    Response Body

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

    Error Responses

    Status Code JSON errorCode Description
    404 - No viewing session with the provided viewingSessionId could be found.
    480 "DocumentNotProvidedYet" An original document has not been provided to the viewing session yet.
    480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document was provided for viewing, so there will never be an original comparison document to get.

    Example

    Request

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

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.
    {contentDispositionFilename} The filename as a URL-encoded string, without extension, to be used in the Content-Disposition response header (appropriate file extension such as doc or docx will automatically be added). By default, the value will be RevisedSourceFile.<ext>.

    Response Headers

    Name Description
    Content-Disposition Indicates to a browser that the response body should be treated as a file download and specifies the filename the browser should use.
    Content-Type The most-specific MIME type for the returned document or application/octet-stream otherwise.

    Response Body

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

    Error Responses

    Status Code JSON errorCode Description
    404 - No viewing session with the provided viewingSessionId could be found.
    480 "DocumentNotProvidedYet" A "revised" document has not been associated with the viewing session yet.
    480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document was provided for viewing, so there will never be a revised comparison document to get.

    Example

    Request

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

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    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 and the form detection feature is available

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "delayEnabled": false,
      "downloadDisabled": false,
      "markupBurnersDisabled": false,
      "formInfoDisabled": false
    }
    
    

    When the product is unlicensed (evaluation mode), 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
    }
    
    

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    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

    Status Code JSON errorCode Description
    480 "DocumentNotProvidedYet" Occurs when you create a viewing session with a documentSource of "api" but have not yet made the API call(s) necessary to provide the source document.
    480 "LicenseCouldNotBeVerified" The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits (such as, for a Cloud License, the total number of logical CPU cores in use).

    Example

    Request

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

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    Request Headers

    Name Description
    Content-Type Should be application/json.
    User-Agent Browser user agent string which PrizmDoc Server uses to generate the most-appropriate content for the viewer.

    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

    Status Code Description
    500 Can occur if your request body is not JSON. Make sure your JSON contains at least an empty object ({}).

    Example

    Request

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

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    Request Headers

    Name Description
    Content-Type Should be application/json.

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

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    Request Headers

    Name Description
    Content-Type Should be application/json.

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

    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

    Name Description
    Content-Type Should be application/json

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    Successful Response

    Response Body

    JSON with metadata about the created viewing session.

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

    Error Responses

    Status Code Reason Phrase Description
    403 The session is invalid or has expired You requested a valid {viewingSessionId} but it is no longer available.
    500 Internal Server Error Can occur if you forget to prefix the {viewingSessionId} portion of the URL with u, or if you simply request an invalid {viewingSessionId}.

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

    Status Code JSON errorCode Description
    480 "PropertyNotReplaceable" Unsupported property to replace was used. See errorDetails in the response body.

    Example

    Request

    POST prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uXYZ.../Replacement
    Content-Type: application/json
    
    {
        "password":"123"
    }
    
    

    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

    Parameter Description
    {viewingSessionId} The viewingSessionId which identifies the viewing session.

    Successful Response

    HTTP 204 indicating the session was deleted.

    Error Responses

    Status Code JSON errorCode Description
    404 - No viewing session with the provided {viewingSessionId} could be found.
    580 "CannotDeleteCachedViewingSession" The viewing session you attempted to delete was not created with serverCaching set to "none".