This article is written for administrators who want to support the users of the yuuvis® RAD client to sign their PDF documents via DocuSign or Adobe Sign. It describes how to set up the service as well as the schema so that the users can request others to sign a specific document file.

1 Signing-Service as part of the service infrastructure
2 Signing progress
3 Searching for signed documents
4 UML Diagrams for signing
- 4.1 Request for signatures
- 4.2 Check of signing status

Signing-Service as part of the service infrastructure

In yuuvis® RAD 9.16 LTS the new Signing-Service is part of the Service Infrastructure. This service is intended to support the signing of a document file via the DocuSign eSignature platform or the Adobe Sign platform.
The document file must be in Microsoft Office or PDF format.
The following signature types are supported:

simple signature (only email address needed)
advanced signature (e-mail address and telephone number (SMS) needed)
qualified signature (e-mail address and Identity Provider with 2FA and previous registration needed) - only available with DocuSign at the moment (in Germany the Identity Provider is SignMe).

The Signing-Service is planned to add further custom connectors for other signing platforms. This feature is not yet implemented.

Installation and Update

After the installation, the Signing-Service is part of the infrastructure so the following configuration is in place.

Configuration of the Service-Watcher

After the update of your system, you have to add the Signing-Service to the service infrastructure by adding this code to the <service-manager>\config\servicewatcher-sw.yml file:

- name: signingservice
  type: microservice
  profiles: prod,cloud,red
  instances: 1
  memory: 256M
  port: 7381
  path: ${appBase}/signingservice/signingservice-app.jar

Configuration of the Gateway-Service

These are the routing parameters to be added to the <service-manager>\config\gateway-prod.yml file:

  - name: 'signing'
    url: 'http://signing/signing'

Service-Admin

If the Service-Wachter and Gateway are well configured the Signing-Service is part of the services list in the Service-Admin:

Signing-Service Endpoints in the Swagger-Interface

The Signing-Service offers the following five endpoints that can be seen but not directly used in the Swagger-UI that is available via the Service-Admin.
You need a REST-WS client like postman or cURL to try the endpoints with the user access data configured in yuuvis RAD.
Configure the REST-WS client to authenticate according to the chosen gateway instance. For example for a basic auth gateway configure basic authentication and enter your yuuvis® RAD user credentials (admin rights needed).

Endpoints of the signing-controller.

POST http://<gateway>/signing/signing/request/{documentId}

This endpoint is used by the client when the user executes the action ‘Request signatures’. The Signing-Service reads the given signing properties from the object with documentId (Item-ID, Object-ID), fetches the document file, creates the DocuSign envelope, and requests DocuSign. The responded envelopeId is written to the object field ‘yuvsigplatformid’ as well as ‘docusign’ to ‘yuvsigplatform’ to indicate the used signing platform (see the description of all signing properties below).

The payload for the request with two signers can look like this:

{
   "signatureType": "advanced",
   "signers":[
      {
         "signerName":"Anton",
         "signerPhone":"+49123456789",
         "signerEmail":"anton@mysystem.com",
         "signerOrder":1
      },
      {
         "signerName":"Berta",
         "signerPhone":"+49123456787",
         "signerEmail":"berta@mysystem.com",
         "signerOrder":2
      }
   ]
}

^{Legend: Example payload for a signing request. The "signatureType": "advanced" is set. In this case, the phone number of the signers has to be included.}

GET http://<gateway>/signing/signing/poll

This endpoint forces the service to poll Docusign regarding the requested envelope IDs. Generally the service polls every 30 minutes if documents with the 'yuvsigstatus' equal to ‘inprocess’ are existing.

If a status has been changed the service is updating the document. And if the signing is completed the signed document file is fetched from Docusign and added as a new version to the document.

For each specific update of the document, a corresponding custom comment is written into the audit (history).

PUT http://<gateway>/signing/signing/cancel/{documentId}

This endpoint is used by the client to cancel the DocuSign signing process. Besides the documentId there is one required parameter: 'reason'.

The Signing-Service reads the envelope ID from the given document with documentId (Item-ID, Object-ID), requests the cancel on DocuSign including the reason, and updates the document with the changed value of the property ‘yuvsigstatus’ to ‘canceled’.

GET http://<gateway>/signing/signing/info/

This endpoint lists the important configurations done in the file signing-prod.yml (see next topic). It is used by the client to read the available signature types simple, advanced, and qualified, as well as the default email subject and body that should be offered in the ‘Request signature’ dialog. A response of the endpoint looks like this:

^{Legend: Example response of the ../signing/info endpoint}
The list of signatureTypesEnabled depends on the configuration of ‘signatureTypes’ in the <service-manager>\config\signing-prod.yml file. This list can be empty, so all elements are optional.

GET http://<gateway>/signing/signing/status/

This endpoint checks the connection status to the set signing platform and informs about the important configurations done in the file <service-manager>\config\signing-prod.yml (see next topic) as well as of those configurations of the used signing platform that are needed for configurations in the <service-manager>\config\signing-prod.yml file. The “name” of the available providers for the signature types simple, advanced, and qualified has to be set in the <service-manager>\config\signing-prod.yml as described in the next topic.

The section availableProviders is exactly from the response of this DocuSign endpoint:
https://developers.docusign.com/docs/esign-rest-api/reference/accounts/accountsignatureproviders/list/

^{Legend: Example response of the ../signing/status endpoint for a connected DocuSign eSignature account with a simple ("name": "universalsignaturepen_imageonly") and an advanced signature type ("name": "universalsignaturepen_opentrust_hash_tsp") configured.}

The section "signatureTypes" is only available for DocuSign.

If the signing platform is DocuSign eSignature and the connection is not possible, the response looks like this:

Configuration of the Signing-Service

These are the parameters to control the behavior of the Signing-Service in the <service-manager>\config\signing-prod.yml file:

With a service-manager update there might be new parameters for the signing-service that are not automatically added to the <service-manager>\config\signing-prod.yml. You will need to add those manually afterwards as described in the https://yuuvisdevelop.atlassian.net/wiki/spaces/YMY/pages/320047787

To encrypt the keys from the signing platform, use the batch-tool <service-manager>\tools\encode.bat:

Legend:

Parameter	possible values	Description

Parameter	possible values	Description
signingplatform	docusign adobesign	This parameter controls which platform to use. Currently, only ‘docusign’ for the use of the DocuSign or Adobe Sign platform can be configured. In the future other platforms will follow.
max-signers	<integer>	The maximum number of signers that can handed over to the signing platform. If more signers are handed over the endpoint is responding with an error.
docusign-config		Section for the parameters that need to be configured or that can be configured for the DocuSign platform
secretKey	<string>	This key has to be taken from your DociSign eSginature account.
integrationKey	<string>	This key has to be taken from your DociSign eSginature account.
apiUsername	<string>	Thits name has to be taken from your DocuSign eSignature account.
pathToPrivateKey	<path>	The file path to your private key that is needed for a secure communication with the DocuSign eSignature account. This key hast to be generated in your DocuSign sSignature account and save in to the file private.key
requestsize	<integer>	Default 50. This is the number of DocuSign envelopes that are part of one requested.
signatureTypes		Beginning with yuuvis® RAD version 9.16 and using the DocuSign eSignature platform, users which are requesting signatures can select between these types of signatures. This parameter contains the followig sub-parameters which are optionally part of the signing/request call and are the same that a user can pick from a list when requesting signatures. The value of these parameters must be one of the DocuSign `availableProviders` represented by its `name` .
simple	DocuSign: `universalsignaturepen_imageonly` Adobe Sign: `true`	To be used for simple signatures. For DocuSign: If the client requests signing without a specific signature type the default `universalsignaturepen_imageonly` will be used.
advanced	DocuSign: `universalsignaturepen_opentrust_hash_tsp` Adobe Sign: `true`	The value of this parameter must be one of the DocuSign `availableProviders` represented by its `name` and to be used for advanced signatures. The default is `universalsignaturepen_opentrust_hash_tsp` In this case the “sms” option is requested as well and the phone number of the signers had to be entered by the user who requested the signatures. For Adobe Sign: use the value `true`
qualified		The value of this parameter must be one of the DocuSign `availableProviders` represented by its `name` and to be used for qualified signatures. No default is given because DocuSign offers differend 3rd party Providers.
fixedRate	<seconds>	Time between between the polls of the Signing-Service requesting the signing platform for the status of the files in process. The default is 30 Minutes. Before polling the Signing-Service checks whether the abstract object type ‘yuvsigning’ is part of the schema. If not an error is logged and the search for objects and the following polling is skipt.
email		Section for email properties
subject	<string>	If the signing request from the client does not includge the emailSubject this string will be used for the sent email to the signers.
body	<string>	If the signing request from the client does not includge the emailBody this string will be used for the sent email to the signers.

Preparation of the DocuSign eSignature account to work with the yuuvis® RAD Signing-Service

To let the yuuvis RAD ® Signing-Service work with your DocuSign eSignature production account you need to go through the following steps:

Step 1: Create an app for the yuuvis® RAD Signing-Service and get the authentication information

First, an app in your DocuSign eSignature developer account for the yuuvis® RAD Signing-Service has to be added. Follow these steps:

Login with an administrative account to the DocuSign Developer portal at https://account-d.docusign.com/
Go to the menu entry "Apps and Secrets"
Click on create a new App
Give the app a name like 'yuuvis RAD Signing-Service' and copy the integration key shown
Click on “generate secret key” and copy the shown secret key for later configurations
Click on “generate RSA key pair” and save the shown public- and private-key
Enter a redirect URL of your choice - this can also be just http://localhost if you don't know of any
Save the app

Step 2: Granting Consent

The Signing-Service needs a dedicated DocuSign eSignature user account to request signatures. This user account needs full API control of the created app. Therefore, the app (identified by its integration key) must be connected with the user ID of the dedicated account.

The steps for granting this consent are explained in this DocuSign eSignature article (we use “Granting consent individually”)

https://www.docusign.com/blog/developers/oauth-jwt-granting-consent (Further informatin is also available here )

Here is a short summary:

Log in as the administrator of the dedicated DocuSign eSignature account and navigate to

In the above-mentioned DocuSign documentation consent pattern 2 (“Granting consent individually”) is relevant:
A URL in the following format must be created:

SERVER/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
- SERVER is https://account.docusign.com (production) or https://account-d.docusign.com (developer demo).
- CLIENT_ID is the app’s integration key.
- The REDIRECT_URI is a URI. It must exactly match one of the redirect URIs you defined for the app’s integration key in the DocuSign eSignature Administration tool. The URI must be URL encoded.
This URL must be used to log in to the dedicated account. This user will also be announced as the sender of the emails to the signers.

On the page that opens the button “allow” must be clicked. If the browser shows an error after clicking the “allow” button, this is expected and ok. If a new page comes up stating that the URI is not known, then check the URI again, make sure it is URL-encoded and try again.

Step 3: Test the app to get it ready for productive use on the DocuSign eSignature platform

After you have configured the authentication parameters in the <service-manager>\config\signing-prod.yml you have to start the yuuvis® RAD Signing-Service and let it be tested for production use following these actions:

In the yuuvis® RAD client request signing for 20 documents
Sign all 20 documents by opening the link sent in the e-mail of docusign.
On the DocuSign Developer portal, click on "Apps and Keys"
Click on the "actions" drop-down menu of your app and choose "Start production verification"
Wait until DocuSign verified the app (this can take up to 20 minutes)
Once verfication succeeded, click on the button to elevate the to the production environment.
Switch to the DocuSign Production portal with your administrative account
Open the app that now appears in the app list
Choose the action "edit" in the drop-down menu
Create a new secret key and a new RSA key pair
Create a new user in the production environment (or choose an existing one) and copy its ID
Update the signing-prod.yml and private.key file with the new values.
Restart the signing-service

Step 4: Production is now live

Preparation of the Adobe Sign account to work with the yuuvis® RAD Signing-Service

To let the yuuvis® RAD Signing-Service connect to your Adobe Sign account you only need to fetch your integrationKey and set it encrypted as described above into the file <service-manager>\config\signing-prod.yml.

When the Integration Key is created, it must be granted the following permissions:
user_read, agreement_read, agreement_write, agreement_send

If you want to use the advanced signature this needs an enabled authentication via code that is sent via SMS. For this, you need to activate the Phone authentication in the Send Settings of your Adobe Sign account.

Remark: See the configuration of the signature types in the signing-prod.yml above

The following shows a part of this configuration for Adobe Sign:

^{Legend: This is a part of the <service-manager>\config\signing-prod.yml configuration file where the advanced signature for the platform Adobe Sign is enabled.}

Schema definition

This section describes how to set up the schema to enable the signing capabilities in the client.

Derive relevant object types from the signing abstract object type

Beginning with yuuvis® RAD version 9.0 it is possible to derive an object type from more than one abstract object type. Following this concept, we are offering a specific abstract object type that can be added to existing object types so that specific new signing features can be used:

For version 9.16 and later with the additional support of the signature types ‘advanced’, and ‘qualified’.
Last changes: Comment fields are extended to 500 characters.

The technical name of the abstract object type is 'yuvsigning'

Technical field name	English label	Description	Default size

Technical field name	English label	Description	Default size
yuvsigemailsubject	Email subject	Used as the subject of the email which is sent to a signer. A default is configured in the configuration signing-prod.yml	100
yuvsigemailbody	Email message	Used as an additional part of the email message which is sent to a signer. A default is configured in the configuration signing-prod.yml	2000
yuvsigtype	Signature type	Prepared for a later version: This is a catalog field with the values ‘simple’, ‘advanced’, and ‘qualified’. The values control which type of signature will be used on the signing platform. A default is configured in the configuration signing-prod.yml
yuvsigrequester	Requested by	The ID of the requesting user.
yuvsigreqdate	Requested on	The Date and time the signatures were requested.
yuvsigdate	Changed on	The date the status value was changed.
yuvsigstatus	Status	Status of the signing process. The shown values are those of the catalog ‘yuvsigstatus’ described below.
yuvsigerror	Notice	Error message written by the Signing-Service in case of an error. This information is in the apsect ‘Signatures’ only shown to an administrator (role: System-Admin-Role).	500
yuvsigcanceledby	Canceled by	The field gets the userid of the one who had canceled the signing process. The client show the user name if given.
yuvsigreason	Reason	This fields get a reason that a user was requested to give, for e.g. if he canceles the signing process.	500
yuvsigplatform	Signing platform	The technical name of the signing platform that is configured in the signing-prod.yml file and that was used for the signing process. Currently, only ‘docusign’ is supported.
yuvsigplatformid	ID of the signing platform	The ID of the signing process on the external signing platform. In case of the signing platform ‘docusign’ this will be the envelopId. It is used by the Signing-Service to ask the signing platform for its status.
yuvsigners	Signers	The table listing the signers data.
yuvsignerorder	Signing order	Signer 2 gets an email after signer 1 has signed and so forth.
yuvsignername	Name	The name of the signer as offered on the Docusign platform.	100
yuvsigneremail	Email address	Email address of a signer that is used by Docusign for sending the email.	100
yuvsignerphone	Phone number	Prepared for a later version: This number can be used for two-factor authentication.	100
yuvsignextern	external	Prepared for a later version: The boolean shows whether the signer is not a user of the yuuvis® RAD based system.
yuvsignerdate	Date	The date and time the signer has signed or revised.
yuvsignerstatus	Status	The status of the single signing step. This status is set by the Signing-Service. The status ‘inprocess’ is the indicator for the signing service to ask the signing platfrom for the status. The shown values are those of the catalog ‘yuvsigstatus’ described below.
yuvsigcomment	Comment	This field is used to show the comment that the signers has given on the signing platform	500

The catalog ‘yuvsigstatus’ offers the processing status values:

Technical value name	Neutral label	Description

Technical value name	Neutral label	Description
signed	signed	Set by the Signing-Service after successful transfer to the external signing platform An audit entry is written to the object history.
revised	revised	Set by the Signing-Service if one of the signers has revised the signing on the external signing plaform An audit entry is written to the object history.
expired	expired	Set by the Signing-Service if the signing process was timed out on the external signing platform. An audit entry is written to the object history.
canceled	canceled	Set by the Signing-Service when a user had cancelled the signing process or an DocuSign administrator has das voided the signing process An audit entry is written to the object history.
error	Error	Set by the Signing-Service in any case of error. An audit entry is written to the object history.
inprocess	in process	Set by the Signing-Service if the transfer to the signing platform was positiv. An audit entry is written to the object history.

The catalog ‘yuvsigtype’ offers the list of signature types. The values are:

Technical value name	Neutral label	Description

Technical value name	Neutral label	Description
simple	simple	This signature is not based on a certificate.
advanced	advanced	This signature is based on a selfsigned certificate.
qualified	qualified	This signature is based on a certified certificate.

Changing the labels in the object details aspect ‘Signatures’

All labels which are shown in the client can be changed in the language files. These are those used in the aspect ‘Signatures’ (file en.json):

Signing progress

Once the signing process was started by the Signing-Service the service is polling the Docusign platform every 30 minutes. Docusign is sending an email to the next signer. After a changed status is detected on the docusign platform the status information of the object is updated. After the last signer has finished or the process was canceled, the process is closed and a symbol in the object details header is indicating this status.

Supported mime types

Users can request signatures also for Microsoft Office files. In the case of using DocuSign eSignature the file is rendered by this platform to PDF. After completion, the Signing-Service is saving the PDF file to the yuuvis RAD object of the original document as a new version. The filename is the same but added with ‘.pdf’.

This is the list of mime-types for which the action ‘Request signatures’ is offered:

mime type	Application

mime type	Application
application/pdf	Adobe Acrobat
application/msword	Microsoft Word with extension doc
application/vnd.openxmlformats-officedocument.wordprocessingml.document	Microsoft Word with extension docx
application/vnd.ms-excel	Microsoft Excel with extension xls
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Microsoft Excel with extension xlsx
application/vnd.ms-powerpoint	Microsoft Powerpoint with extension ppt
application/vnd.openxmlformats-officedocument.presentationml.presentation	Microsoft Powerpoint with extension pptx

Support of DocuSign’s anchors: Position of date, signature, and name

The DocuSign eSignature platform offers the possibility to position the signature, the date of signing, and the name of each signer. They are offering anchors that can be named and placed by using text fields in Word like this:

You have to format the anchor text and text-field box background with white color to make it invisible in the Word document. The text-field box size must stay big enough so that the entire text is visible.
Only for the sign-anchor: The signing graphic will be inserted so that the top frame line is the horizontal middle of the graphic. So account for enough space above the text field.

The Signing-Services is always handing over these anchors to the DocuSign eSignature platform when requesting signatures:

Anchor name	Description

Anchor name

Description

#anchor_sign1#

If the first signer starts signing on the DocuSign platform the sign control is placed on the position of this anchor.

If the anchor is not used the signer will be able to place the sign individually.

#anchor_date1#

If this anchor is used the date and time when starting the signing is placed on the given position.

#anchor_name1#

If this anchor is used the name of the signer that is entered during the request dialog in the client is placed on the given position.

For the second signer change the number ‘1' to '2’ etc.

The result on the document looks like this for the name ‘Martin Bartonitz’:

Support of Adobe Sign text tags: Position of date, signature, and name

The Adobe Sign platform offers the possibility to position the signature, the date of signing, and the name of each signer, and much more as documented here:

Text tags are formatted with {{specific text tag}} and can be placed anywhere in your Microsoft office document or your PDF formatted file. In the following example the date format for the first signer (on the right side) is a German one and looks like 22.08.2023. The date for the second signer (on the left side) will look like Aug 22, 2023.

If the signers are clicking on the requested link in their email they will be guided to sign at the given place.

If the signer is registered on the Adobe Sign platform his fullname will be placed as well.

Canceling the request

During this process, users with edit permission can cancel the process. The client is requesting the cancel endpoint of the Signing-Service which is requesting the signing platform to remove the case. The Signature-Service is writing the ID of the requesting user to the document property ‘yuvsigrequester’ and his given reason in ‘yuvsigreason’.

Localized audit entries

The Signing-Service is updating metadata and content (document file) using the parameter ‘intent’. This intent is written to the audit trail/history. The client is localizing the intent so that the user can read this in his language. These are the intent keys that are written by the Signing-Service:

Intent code	Localization key and its labels in the client (en.json; de.json)

Intent code	Localization key and its labels in the client (en.json; de.json)
YUVSIG_REQUESTED	eo.object.history.entry.type.YUVSIG_REQUESTED.description EN: 'Signatures were requested.' DE: 'Signature wurden angefordert.'
YUVSIG_COMPLETED	eo.object.history.entry.type.YUVSIG_COMPLETED.description EN: 'The document file has been signed by everyone.' DE: 'Dokument wurde vollständig signiert.'
YUVSIG_CANCELED	eo.object.history.entry.type.YUVSIG_CANCELED.description EN: 'The signing process was canceled.' DE: 'Der Signierprozess wurde abgebrochen.'
YUVSIG_REVISED	eo.object.history.entry.type.YUVSIG_REVISED.description EN: 'One signature was rejected.' DE: 'Eine Signatur wurde abgewiesen.'
YUVSIG_EXPIRED	eo.object.history.entry.type.YUVSIG_EXPIRED.description EN: 'The signing period has expired.' DE: 'Die Signaturfrist ist abgelaufen.'
YUVSIG_ERROR	eo.object.history.entry.type.YUVSIG_ERROR.description EN: ‘The signature process was canceled due to an error.’ DE: 'Der Signaturprozess wurde aufgrund eines Fehlers abgebrochen.'
YUVSIG_UPDATE	eo.object.history.entry.type.YUVSIG_UPDATE.description EN: 'One signature has been completed.' DE: 'Eine Signature wurde abgeschlossen.'
YUVSIG_CONTENT_ADDED	eo.object.history.entry.type.YUVSIG_CONTENT_ADDED.description EN: 'The signed document file was added.' DE: 'Die signierte Dokumentdatei wurde hinzugefügt.'

Searching for signed documents

The abstract object type ‘yuvsigning’ with the neutral label 'Signing’ is configured with a form as shown below. Users can search for documents that are signed or in the signing process by setting the specific values to find the expected documents.

UML Diagrams for signing

Request for signatures

The following diagram shows the sequence of actions after requesting for signatures of a PDF or Office file.

Check of signing status

The signing-service checks by default every 30 minutes the status of each document that was handed over to the signing platform. The following diagram shows the sequence of actions for this check.