Introduction

NOTE: Use of a Central Database for PrizmDoc will be required in a future release in order to move towards eliminating server affinity.

The PrizmDoc Application Services (PAS) use a central configuration file to determine, among other things, where to find documents, where to store logs, and how to connect to a database.

NOTE: PrizmDoc Cloud uses a specific default value that differs from the self-hosted default value: defaults.viewingSessionTimeout is 5h. This is the only value that differs between PrizmDoc Cloud and self-hosted for PAS configuration.

Configuration File Location

• On Windows, assuming a default installation, the configuration file is located at C:\Prizm\pas\pcc.win.yml.

• For Docker, the configuration file pcc.nix.yml is located in the folder that you mapped as /config when creating the container. See Installing / Using Docker for more details.

• In Kubernetes, configuration parameters are provided via a ConfigMap resource. See Deployment to Kubernetes Guidance for more details.

Default Configuration

Among other things, the config file includes the port, logs.path, defaults.viewingSessionTimeout, defaults.viewingPackageLifetime, and viewing.validateTlsCertificates properties.

• port defines the port that PAS will use to listen to its HTTP connection.

  NOTE: When using PrizmDoc Docker containers, we recommend that you keep this property unchanged.

• logs.path determines the location on the local filesystem where the logs for PAS will be stored.

  NOTE: When using PrizmDoc Docker containers, we recommend that you keep this property unchanged.

• defaults.viewingSessionTimeout is the length of time that a viewing session remains usable. The value must be an integer, followed by "s", "m", "h", or "d". The suffixes stand for second, minute, hour, or day, respectively. There should not be any space characters between the number and suffix. For example, "20m" indicates viewing sessions will timeout after 20 minutes.

  NOTE: This setting is respected only when the source of the viewing session is viewingPackage.

  NOTE: For PrizmDoc Cloud, the default value is 5h.

• defaults.viewingPackageLifetime is the minimum time for the created viewing package content to remain available. The value must be an integer, followed by "s", "m", "h", or "d". The suffixes stand for second, minute, hour, or day, respectively. There should not be any space characters between the number and suffix. For example, "20m" indicates viewing packages will timeout after 20 minutes. If missing, the value is considered to be 24 hours. If set to 0, viewing package content will remain available perpetually. This value could be overridden by the input.viewingPackageLifetime property in individual viewingPackageCreators requests when starting a new viewing package creator process. This is a beta feature that is not officially supported by Accusoft and its behavior can be changed at any time in a future version of the product.

• viewing.validateTlsCertificates indicates whether the TLS certificate for a remote server will be validated when a document is requested for the creation of a viewing session or viewing package. The default value is true indicating that requests for a document via a remote url will require strict TLS certificate validation. Some administrators may find it necessary to allow the request of documents from servers where the TLS certificate is not valid. In this case, the viewing.validateTlsCertificates property may be set to false which will bypass TLS certificate validation when downloading documents. You should understand that setting this property to false weakens the security of your server.

Configuring the PrizmDoc Server Connection

The connection to your desired PrizmDoc Server, whether Self-Hosted or Cloud, can be configured through the pccServer object, which has the following properties:

• pccServer.hostName - the hostname to use to connect to PrizmDoc Server.
• pccServer.port - the port on the above hostname to connect to.
• pccServer.scheme - the scheme to use to communicate with PrizmDoc Server. This can be set to http or https.
• pccServer.apiKey - the API Key that PAS should use if you are using the PrizmDoc Cloud Server. This value will be ignored for a PrizmDoc Self-Hosted Server.

Configuring Storage for Your Needs

There are various data entities stored or accessed by PAS, as noted by comments in the config file. All of these can be configured separately.

Each storage entity will have a name, such as documents or markupLayerRecords, and each named entity will have a .storage property, such as documents.storage. This property defines the kind of storage that will be used. The supported values are as follows:

• "filesystem" - Store on the local filesystem or network attached storage that has been mapped to a local drive or folder. For any data entity configured to be stored on the filesystem, the following additional properties are required:
  • .path - Folder location where the data should be stored. On Windows, this can also include environment variables. If these paths are changed from the default values, PrizmDoc must be granted write permissions for them to function.
    NOTE: When using PrizmDoc Docker containers, we recommend that you keep this property unchanged.
• "database" - Store inside the configured database. See Configuring the database below for more details.
• "s3" - Store files in S3 Buckets. For any data entity configured to be stored in S3 Buckets, the following additional properties are required:
  • .s3BucketName - Name of the bucket that you would like to store the specified data entity type. This bucket must be unique across all of Amazon S3 services and must be created in your S3 dashboard.
  • .path - Base “key” the data should be organized into. S3 uses keys as its directory structure. This must have no starting / and no trailing /.
• "azureBlobStorage" - This is a beta feature that stores files in Microsoft Azure Blob Storage. For any data entity configured to be stored in Azure blob storage, the following additional properties are required:
  • .azureBlobStorageConnectionString - Connection string to the Microsoft Azure Blob Storage.
  • .azureBlobStorageContainerName - Name of the container in the Microsoft Azure Blob Storage that you would like to store the specified data entity type.
  • .path - Sub-key of the .azureBlobStorageContainerName where the data should be stored.

Storage Entities & Storage Providers

The following table shows the storage entities and supported storage providers:

NOTE: Not all storage entities are compatible with all storage providers. Checking for these values is done on start up and an informative error will be logged to the PAS log, {installDir}/logs/pas, in the case of a mismatch.

Additional S3 Notes

You must handle Amazon Web Services credentials in one of the available ways that are provided on the following pages:

Loading credentials in Node.js from IAM Roles for EC2:

• http://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-iam.html

Loading credentials from a shared credentials file:

• http://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html

Loading credentials from environment variables:

• http://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html

Examples

documents.storage: "filesystem"
documents.path: "/data/documents"

documents.storage: "filesystem"
documents.path: "C:\\Docs\\Docs"

documents.storage: "filesystem"
documents.path: "\\\\servername\\sharename\\docs\\docs"

markupLayerRecords.storage: "filesystem"
markupLayerRecords.path: "%ALLUSERSPROFILE%\\Accusoft\\Prizm\\MarkupLayerRecords"

viewingPackagesData.storage: "database"

documents.storage: "s3"
documents.s3BucketName: "myS3Bucket"
documents.path: "Samples/Documents"

documents.storage: "azureBlobStorage"
documents.azureBlobStorageConnectionString: "AccountName=..."
documents.azureBlobStorageContainerName: "pas"
documents.path: "Documents"

NOTE: some data entities have limitations on the kind of storage that they can be stored in. If PAS is misconfigured, it will not start correctly. It's best to keep a copy of the defaults so that you can revert them if you need to.

Legacy Mode

DEPRECATION NOTICE: The Legacy Mode has been deprecated and will be removed in a future release.

Legacy Mode refers to being able to open markup files that were created using one of the Web Tier Samples available before the release of PAS. To work correctly, it needs to be enabled on documents, markupXml, and markupLayerRecords, as such:

documents.legacyMode: true
markupXml.legacyMode: true
markupLayerRecords.legacyMode: true

If you do not need this feature (for example, if PAS is the first time you are using markup files) you can turn this off by setting all values to false, which will provide a small performance gain when working with the markup APIs. Note that all markup files created by PAS itself, regardless of whether legacyMode was on or off, will be compatible with PAS when legacyMode is off.

Feature Toggles

Some features in PAS are behind feature flags, and they can be turned on or off. This is done through the feature.* options in the config file. The values can be set to:

• enabled - turns the feature on
• disabled - turns the feature off

You can also remove the specific feature configuration value altogether in order to observe the default behavior for that feature. The list of features is:

• viewingPackages - default: disabled - Enables Pre-Conversion Services and APIs, which allow you to pre-convert documents and cache on-demand document views in PAS, improving the speed at which documents can be viewed, as well as reducing the processing time in PrizmDoc Server for repeat document views.

Example

feature.viewingPackages: enabled

Configuring the Database

IMPORTANT: A database is required in order to use Viewing Packages. This feature is disabled by default and will need to be turned on. Without turning Viewing Packages on, PAS will not use a database, or even check for its existence in the configuration.

PAS requires configuration to a database, allowing it to store some of its data there. It will not start without having a correctly configured and accessible database. The following config properties are available in PAS to support that:

• database.adapter - the type of database being used. The following values are supported:
  • sqlserver - Microsoft SQL Server. The following versions are currently supported:
    • Microsoft SQL Server 2014
    • Microsoft SQL Server 2017
  • mysql - MySQL. MySql 5.7 & 8.0 are currently supported.
• database.connectionString - the connection string to the database.
  • For Microsoft SQL Server, you can use either a classic connection string or a URI-based connection string.
  • For MySQL, you must use a URI-based connection string.

Microsoft SQL Server Examples

database.adapter: sqlserver
database.connectionString: "Server=tcp:prizm-server.database.host,1433;Database=prizmdb;User ID=prizm-user;Password=password;Encrypt=True"

database.adapter: sqlserver
database.connectionString: "mssql://prizm-user:password@prizm-server.database.host:1433/prizmdb?encrypt=true"

MySQL Example

database.adapter: mysql
database.connectionString: "mysql://prizm-user:password@prizm-server.database.host:3306/prizmdb"

Alternately, instead of specifying a database.connectionString, you can use the following older options to connect to the database:

• database.host - the hostname to use to communicate with the database.
• database.port - the port to use to communicate with the database.
• database.user - the user to use when connecting to the database.
• database.password - the password for the specified user.

• database.database - the database name to use on the database server.

  NOTE: We strongly recommend you use database.connectionString instead as it is more flexible.

Configuring Cross-Origin Resource Sharing

While you can set up CORS quite easily through your web server, PAS also supports settings CORS headers directly. It is exposed through the cors config object, as such:

• cors.enabled - whether to set CORS headers. Supported values are true or false.
• cors.allowedOrigins - an array of the exact origin values to support. Not including this value will cause all CORS requests to be denied. This array will be used to determine the Access-Control-Allow-Origin header.
• cors.exposedHeaders (optional) - an array of headers keys to allow the browser to read. This value is configured to include headers returned by PAS by default.

Example

cors.enabled: true
cors.allowedOrigins: [ "http://example.com", "https://example.com" ]