Vault External Document Viewer

You can embed the external document viewer into a website or use it as a standalone viewer for documents in your vault. Vault ensures that only the latest steady state version of the document will be accessible through the viewer at all times.

Note: The external document viewer is only available in PromoMats and MedComms vaults with the Public Distribution and View-Based User license type features enabled. Learn more in Vault Help.

The External Viewer has the following unique properties:

  • Allows anonymous access to documents stored in Vault.
  • Can be embedded in an iFrame within a website using the JavaScript code below.
  • Supports use as a standalone browser page.

The Token API generates document access tokens needed by the external viewer:

  • A valid Vault session is required to ensure the non-vault user has access to the document.
  • Only users with a view-based license can access the endpoint to request an anonymous viewing token.
  • In order to generate the token, a valid session ID is required.

Setting up the External Viewer

You can include the following snippet of JavaScript code into your website to display a specific Vault document.

<!DOCTYPE html>
<html>
 <body>
   <!-- 1. The <iframe> (and vault viewer) will replace this <div> tag. -->
   <div id="viewer"></div>

   <script>
     // 2. This code loads the IFrame Viewer API code asynchronously.
     var tag = document.createElement('script');

     tag.src = "https:​//js.veevavault.com/vault.js";
     var firstScriptTag = document.getElementsByTagName('script')[0];
     firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

     // 3. This function creates an <iframe> (and vault viewer) after the API code downloads.
     var viewer;
     function onVeevaVaultIframeAPIReady() {
       viewer = new VV.Viewer('viewer', {
         height: '600',
         width: '600',
      error: 'We\'re sorry. The document you are trying to view is not available.'
       });
     }
   </script>
 </body>
</html>

Once the viewer is embedded, a Vault Document Token generated for the desired document needs to be provided in the URL parameters, as well as a DNS parameter to pass the source Vault's DNS.

Generating Tokens for Vault Documents

Send POST to /api/{VERSION}/objects/documents/tokens

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Document IDs

Required - Include the docIds request parameter with a comma-separated string of document id values. This will generate tokens for each document. For example: docIds=101,102,103,104

Token Expiration Date

Optional - Include the expiryDateOffset request parameter set to the number of days after which the tokens will expire and the documents will no longer be available in the viewer. If not specified, the tokens will expire after 10 years by default.

Download Option

Optional - Include the downloadOption request parameter set to PDF, source, both, or none. These allow users viewing the document to be able to download a PDF version or source version (Word, PPT, etc.) of the document. If not specified, the download options default to those set on each document.

Distribution Channel

Optional - Include the channel request parameter set to the website object record id value that corresponds to the distribution channel where the document is being made available.

Token Groups

Optional - Include the tokenGroup request parameter. This only required if you want to group together generated tokens for multiple documents in order to display the documents being referenced in the same viewer. This value accepts strings of alphanumeric characters (a-z, A-Z, 0-9, and single consecutive underscores) up to 255 characters in length.

The token that is passed as a URL parameter to the External Viewer is the primary token and the document it references will be displayed normally. However, any additional documents that have tokens generated with the same case-sensitive tokenGroup string will be displayed in a sidebar of the viewer.

The order of documents in the sidebar depends on the order in which the tokens are generated. If multiple tokens are generated with one request, the documents will be ordered top-to-bottom based on the order they are passed to the docIds parameter.

For example: If passing the parameters docIds=101,102,103,104 and tokenGroup=group_1 with the request, the top-to-bottom order in the sidebar will be documents 101, 102, 103, 104. If a new request is then made with the parameters docIds=105 and tokenGroup=group_1, document 105 will be added below document 104 in the previous list.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=101,102,103,104" \
-d "expiryDateOffset=90" \
-d "downloadOption=PDF" \
-d "channel=00W000000000301" \
https://myvault.veevavault.com/api/v12.0/objects/documents/tokens

Response

{
    "responseStatus": "SUCCESS",
    "tokens": [
        {
            "document_id__v": 101,
            "token__v": "3003-cb6e5c3b-4df9-411c-abc2-6e7ae120ede7"
        }
        {
            "document_id__v": 102,
            "token__v": "3003-1174154c-ac8e-4eb9-b453-2855de273bec"
        },
        {
            "document_id__v": 103,
            "token__v": "3003-51ca652c-36d9-425f-894f-fc2f42601fa9"
        },        
        {
            "document_id__v": 104,
            "errorType": "OPERATION_NOT_ALLOWED",
            "errors": [
                {
                    "type": "INVALID_DOCUMENT",
                    "message": "Document not found [104]."
                }
            ]
        }
    ]
}

Details

In the example above, tokens are generated for the first three documents. The fourth document could not be found. This indicates either an incorrect document id or that the specified document is a binder.

Errors

Error Type Error Message Comments
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. The logged-in API user does not have permission to complete the request.
OPERATION_NOT_ALLOWED Cannot create resource: [Approved Email] is not enabled. This error indicates that your vault has not been configured for use with the integration feature: "Approved Email" or "Public Distribution". Learn more in Vault Help.
INVALID_DOCUMENT Document not found [{ID}] The document id specified in the request cannot be found in your vault. This error is also returned if the specified document is a binder (binder__v=true).
INVALID_DATA Invalid value [{VALUE}] specified for parameter [downloadOpt] specified: one of [None, PDF, Source, Both] is expected. If using the downloadOption request parameter to set the document download options, valid values are None, PDF, Source, or Both.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [tokenGroup]: string exceeds max length [255]. The tokenGroup value cannot exceed 255 characters.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [tokenGroup]: value can only contain [a-z, A-Z, 0-9, single consecutive '_']. The tokenGroup value has invalid character values.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [channel]: valid [channel] is expected. If using the channel request parameter to associate the documents with a particular distribution channel, you must enter a valid website__v object record ID.

How to Create the URL

When sharing your documents in an embedded viewer, users must navigate to a URL that includes both the anonymous viewing token and your vault's DNS:

https://{PAGE_WITH_EMBED_SCRIPT}?token={VIEWING_TOKEN}&dns={CUSTOMER}.veevavault.com`

For example, a URL for information for the CholeCap product might be:

https://cholecap.com/about.html?token=3003-cb6e5c3b-4df9-411c-abc2-6e7ae120ede7&dns=myvault.veevavault.com

If you want to display multiple documents in the viewer, use the tokenGroup parameter when requesting tokens and use any of the tokens from the response within the URL. Vault will determine whether a token belongs to a group and will automatically show all documents within the group. The token in the URL corresponds to the document that displays when the viewer loads.