Configuring native document collaboration

Prerequisites

Before configuring native document collaboration, check that your installation meets the general prerequisites for document collaboration.

The variety of document collaboration used is set in the configuration property com.unblu.documentcobrowsing.technology. Native document collaboration is the default variety.

Native document collaboration requires Apryse licenses for the WebViewer and related features. Normally, these licenses are part of the Unblu Server license. If they aren’t, refer to Apryse licenses.

General configuration options

For information on general configuration options, refer to the section General configuration options of the article Configuring and manipulating collaboration layers.

Apryse licenses

Native document collaboration requires licenses for different features of the Apryse WebViewer. Normally, these licenses are part of the Unblu Server license. If they aren’t present in your license, you can configure the individual Apryse licenses with the following configuration properties:

com.unblu.documentcobrowsing.javascript.apryseLicenseKey: Used to display documents in the browser.
com.unblu.documentcobrowsing.javascript.apryseServerSdkLicenseKey: Used for server-side operations such as document signing.
com.unblu.documentcobrowsing.javascript.apryseMobileSdkLicenseKey: Used to display documents in the Unblu Mobile SDKs.

Configuration properties

The following configuration properties are set in the CONVERSATION_TEMPLATE scope:

com.unblu.conversation.collaboration.document.allowCreatingEditingAnnotations: Specifies which conversation participants can create and edit annotations. Participants who aren’t listed here don’t have the UI elements to annotate a document. It isn’t possible to specify which particular annotation tools participants may or may not use.

com.unblu.conversation.collaboration.document.allowCreatingEditingSignatures: Specifies which conversation participants can create and edit signatures. Participants who aren’t listed here don’t have the UI elements to sign a document.

For information on configuring document signing, refer to Document signing below.
com.unblu.conversation.collaboration.document.allowEditingAnnotationsOfOtherUsers: Specifies which participants may edit annotations created by other participants. Participants who may edit annotations can also edit other participants' comments on annotations.
com.unblu.conversation.collaboration.action.allowRemoteControlInDocumentCobrowsing: Specifies which participant types may use remote control. In the context of native document collaboration, remote control refers to all the controls in the collaboration layer.
com.unblu.conversation.collaboration.approval.approveRemoteControlDocument: Lists the participant types for whom the assigned agent must approve the use of remote control.
com.unblu.conversation.collaboration.document.allowPrintDocument: Specifies which participants may print the document.
com.unblu.conversation.collaboration.document.allowSaveDocument: Specifies which participants may save the document to the conversation.
The following configuration properties define the width and height of the native document collaboration content in the collaboration layer. The values include the toolbar and side panels:

UI theming

You can configure the look and feel of the native document collaboration UI. Refer to Native document collaboration theming.

Document signing

Participants allowed to sign PDF documents can do so during a native document collaboration session. Unblu supports two signing modes:

Cryptographic signing: the server adds a digital signature to the PDF using a PKCS #12 certificate. The document is tamper-proof and locks after signing. Adobe Acrobat and other PDF readers verify the signature and display the configured reason, signer information, location, and date.
Image-only signing: the server adds an image of the signature to the PDF without cryptographic validation. The document isn’t locked or tamper-proof.

Signing mode

By default, image-only signing is enabled. To enable cryptographic signing instead, set com.unblu.documentcobrowsing.server.useCryptographicPdfSignature to true.

Setting up a PKCS #12 certificate

Cryptographic signing requires a PKCS #12 private keyfile containing a private key, public key, and certificate. Configure the keyfile and its password with the following configuration properties:

com.unblu.documentcobrowsing.server.pkcs12Keyfile: The PKCS #12 private keyfile, encoded as base64.
com.unblu.documentcobrowsing.server.pkcs12KeyfilePassword: The password for the PKCS #12 keyfile.

Unlike the other document signing configuration properties, these two are set in the GLOBAL or ACCOUNT scope, not in the CONVERSATION_TEMPLATE scope. The same keyfile is used for all conversation templates in an account or installation.

To generate a self-signed keyfile with openssl for testing, run the following commands in your terminal:

# 1. Create a private key and self-signed certificate
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
  -sha256 -days 365 \
  -subj "/C=CH/ST=Basel/O=Your organisation/CN=signing.example.com" (1)

# 2. Export the key and certificate as a PKCS #12 keyfile
openssl pkcs12 -export -out signing.p12 -inkey key.pem -in cert.pem

1	Adapt this line to your requirements.

The second command prompts for an export password. Use this password as the value of com.unblu.documentcobrowsing.server.pkcs12KeyfilePassword.

To encode the keyfile as base64 for com.unblu.documentcobrowsing.server.pkcs12Keyfile:

# Linux idiom (on macOS, use: base64 -i signing.p12 -o signing.p12.b64)
base64 signing.p12 > signing.p12.b64

Anyone with access to the private key can produce signatures that appear to come from your organisation. For production environments, use a keyfile signed by a trusted certificate authority so that recipients of signed documents don’t see "untrusted signature" warnings in their PDF reader.

For more information on generating custom signing certificates, refer to the Apryse guide on custom digital signature certificates.

Signer input fields

The signing dialog that’s shown to users can include optional fields for location and contact information. Control the visibility and requirement of these fields with the following properties:

com.unblu.conversation.collaboration.document.provideSignatureContactInfo: Specifies whether the contact information field is hidden, optional, or mandatory in the signing dialog.
com.unblu.conversation.collaboration.document.provideSignatureLocation: Specifies whether the location field is hidden, optional, or mandatory in the signing dialog.

Drawn signatures must contain a minimum number of points to be considered valid. Configure this threshold with com.unblu.conversation.collaboration.document.sign.minSignaturePoints.

Signature appearance

The following properties control how the signature appears in the signed PDF:

com.unblu.conversation.collaboration.document.sign.signatureFontFamilyWebfont: The font family used for typed signatures.
com.unblu.conversation.collaboration.document.sign.signatureFontFamilyWebfontCssUrl: The URL of the CSS file that declares the font family for typed signatures.
com.unblu.documentcobrowsing.server.signatureAppearanceTextFontSize: The font size of the appearance text added below the signature image.
com.unblu.documentcobrowsing.server.signatureAppearanceDatePattern: The date pattern used in the signature’s appearance text. The pattern must conform to the Java SimpleDateFormat.

com.unblu.documentcobrowsing.server.signatureAppearanceText: Controls the text rendered directly below the signature image. It supports the following variables:

Variable

Description

${displayName}

The display name of the person signing

${sourceId}

The person’s source ID (e.g., the single sign-on identifier)

${personId}

The internal Unblu person ID

${contactInfo}

Contact info entered by the signer (if enabled)

${location}

Location entered by the signer (if enabled)

${date}

Signing date, formatted per com.unblu.documentcobrowsing.server.signatureAppearanceDatePattern

The default text is:

$\{contactInfo\}
Person source ID: $\{sourceId\}
$\{location\} $\{date\}

Signing reason

com.unblu.documentcobrowsing.server.signatureReason specifies the reason recorded in the signature metadata of the PDF. The reason is visible when the user inspects the signature in a PDF reader. The template supports the variables ${personId} and ${sourceId}.

Signed file naming

When Unblu signs a document, it creates a new file in the conversation with a name derived from the original. The following properties determine the filename:

com.unblu.documentcobrowsing.server.signedFileName: The filename template. Supports the variables ${originalName} and ${dateTime}. The default is ${originalName} ${dateTime}.signed.pdf.
com.unblu.documentcobrowsing.server.signedFileNameDateTimePattern: The date/time pattern used for the ${dateTime} variable in com.unblu.documentcobrowsing.server.signedFileName. The pattern must conform to the Java SimpleDateFormat.

com.unblu.documentcobrowsing.server.dateTimePattern is deprecated and has been replaced by com.unblu.documentcobrowsing.server.signedFileNameDateTimePattern.

Unsupported collaboration tools

Native document collaboration doesn’t support the collaboration tools mark mode and scroll lock. It provides its own equivalent tools.