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 Signature statistics
5 Post-processing
6 Error notification via email
7 UML Diagrams for signing
- 7.1 Request for signatures
- 7.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-Manager

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 exist. Only users with the privilege Manage system settings can request this endpoint.

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:

{
    "platform": "docusign",
    "supportedPlatforms": [
        "docusign",
        "adobesign"
    ],
    "maxSigners": 6,
    "defaultEmailSubject": "Please sign.",
    "defaultEmailBody": "Please sign the document.",
    "signatureTypesEnabled": [
       "simple",
       "advanced",
       "qualified"
    ]
}

^{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.

Only users with the privilege Manage system settings can request this endpoint.

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

{
    "accountInfo": {
        "name": "My Company Inc",
        "connected": true,
        "errorMessage": "<message from the signing platform if a connection was not possible>"
    },
    "platform": "docusign",
    "supportedPlatforms": [
        "docusign",
        "adobesign"
    ],
    "maxSigners": 6,
    "defaultEmailSubject": "Please sign.",
    "defaultEmailBody": "Please sign the document.",
    "signatureTypesEnabled": [
       "simple",
       "advanced",
       "qualified"
    ]
    "availableProviders": [
        {
            "name": "universalsignaturepen_imageonly",
            "label": "DS Electronic",
            "definition": {
                "isRequired": "false",
                "priority": "0",
                "signatureProviderDisplayName": "DS Electronic",
                "signatureProviderId": "0",
                "signatureProviderName": "universalsignaturepen_imageonly",
                "signatureProviderOptionsMetadata": null,
                "signatureProviderRequiredOptions": null
            }
        },
        {
            "name": "universalsignaturepen_opentrust_hash_tsp",
            "label": "DS EU Advanced",
            "definition": {
                "isRequired": "false",
                "priority": "1",
                "signatureProviderDisplayName": "DS EU Advanced",
                "signatureProviderId": "5",
                "signatureProviderName": "universalsignaturepen_opentrust_hash_tsp",
                "signatureProviderOptionsMetadata": [
                    {
                        "signatureProviderOptionDisplayName": "One Time Password",
                        "signatureProviderOptionId": "0",
                        "signatureProviderOptionName": "onetimepassword"
                    },
                    {
                        "signatureProviderOptionDisplayName": "SMS Authentication",
                        "signatureProviderOptionId": "1",
                        "signatureProviderOptionName": "sms"
                    }
                ],
                "signatureProviderRequiredOptions": [
                    {
                        "requiredSignatureProviderOptionIds": [
                            "0",
                            "1"
                        ],
                        "signerType": "signer"
                    }
                ]
            }
        }
    ]
}

^{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:

{
    "accountInfo": {
        "name": null,
        "connected": false,
        "errorMessage": "400 Bad Request: \"{\"error\":\"invalid_grant\",\"error_description\":\"issuer_not_found\"}\""
    },
    "platform": "docusign",
    "supportedPlatforms": [
        "docusign",
        "adobesign"
    ],
    "maxSigners": 6,
    "defaultEmailSubject": "Please sign.",
    "defaultEmailBody": "Please sign the document.",
    "signatureTypes": {
        "simple": {
            "name": "universalsignaturepen_imageonly",
            "label": "none",
            "enabled": false
        },
        "advanced": {
            "name": "universalsignaturepen_opentrust_hash_tsp",
            "label": "none",
            "enabled": false
        },
        "qualified": {
            "name": "",
            "label": "none",
            "enabled": false
        }
    },
    "availableProviders": []
}

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

This endpoint reports the number of signings and affected documents for the following optional parameters:

Parameter	Description

Parameter	Description
`documentTypes`	A value list with the technical name of object types. The default is none for all object types that are derived from the abstract object type `yuvsigning`
`status`	A value list of the catalog `yuvsigstatus`, default is `signed`, see others in the description of the signing project.
`signatureTypes`	A value list of the catalog `yuvsigtype` with `simple`, `advanced`, `qualified`, default is all of them
`from` and `to`	A time range, default is the first and last day of the year. Only dates in the format yyyy-mm-dd are allowed.
`aggregationField`	The Elasticsearch-specific name related to a qualified technical name of an object property or its context (parent) See the document of the similar expert search in the client: https://help.optimal-systems.com/yuuvisRAD/v100/user/client/en/02-Suchen-und-finden/cln_tsk_suche-experten-modus.htm

Precondition: The signing-service must be configured to use the profile es in the file <service-manager>\config\servicewatcher-sw.yml.

- name: signingservice
  ...
  profiles: prod,red,es
  ...

This endpoint can only be requested by users with the role Use signature statistics.

Example request with a list of documentTypes:

http://mydomain.com/signing/statistics?documentTypes=contracts&documentTypes=hrdocuments&aggregationField=key_contract_type&from=2023-01-01

Remark: In the URL the parameters can only take one value. Repeat the list parameter with all values needed.

Response example:

{
  "status": [
    "signed"
  ],
  "countSignatures": 15,
  "countObjects": 10,
  "signatureTypes": [
    "Not specified. Possible Values: simple, advanced, qualified"
  ],
  "documentTypes": [
    "contracts",
    "hrdocuments"
  ],
  "aggregations": {
    "employment contract": 2,
    "Amendment agreement": 2,
    "Decision": 3,
    "Power of attorney": 4,
    "medical certificate": 2,
    "Driver's license": 2
  },
  "period": {
    "from": "2023-01-01T00:00:00",
    "to": null
  }
}

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:

signingplatform: "docusign"
#signingplatform: "adobesign"
fetch-error-tolerance-hours: 24
max-signers: 6

# configuration for accessing Docusign
docusign-config:
  pathToPrivateKey: 'C:\yuuvis\service-manager\certificates\private.key'
  # see documentation
  secretkey: ENC(xxxxxxxx)
  integrationKey: ENC(xxxxxxxx)
  oAuthBasePath: account-d.docusign.com
  apiUsername: ????????-????-????-????-????????????
  requestsize: 50
  combine-certificate-in-service: false
  signatureTypes:
    simple: universalsignaturepen_imageonly
    advanced: universalsignaturepen_opentrust_hash_tsp
    #qualified:

# configuration for accessing Adobe Sign
adobesign-config:
  #The integration key must be created for the permissions "user_read", "agreement_read", "agreement_write", "agreement_send"
  #integrationKey: ENC(xxxxxxxx)
  #signatureTypes:
    #simple: true
    #advanced: false
    #qualified: false

## default values for e-mails
email:
  subject: Please sign.
  body: Please sign the document.
  
## Scheduler
## Minimum of fixedRate is 1200000 (20 mins)
fixedRate: 1800000

# configuration for the start of a BPM process for additional actions like finalization of the object or sending info tasks to the requester
# path is case-sensitive
#process-after-completion: "Signing-finalization"

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.
fetch-error-tolerance-hours	<integer>	Since yuuvis RAD 10.16 LTS: If the status of an envelope can not be checked, the corresponding object is set to “error” after the given hours.
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.
combine-certificate-in-service	true/false (default)	If set to true the signed document and certificate are downloaded and merged by the service (what under certain conditions could cause problems). Otherwise the document and certificate are merged by Docusign if the setting “Attach certificate of completion to envelope“ is set for this account in “Signing Settings → Envelope Delivery”. Initially it is probaly deactivated. The service parameter “combine-certificate-in-service” can be used to force the service to merge the documents after download. Default value is false and it is recommend to use the Docusign feature.
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.
process-after-completion	<string>	The value for this parameter must be the project name where the process model is located (see management-studio/processes/process models). The given process model will be started after the signing process is completed with the `yuvisgstatus` = `signed`, `experid`, `revised`, and `error`. A standard process model `"Signing-finalization"` is provided which finalizes the object if the status is signed, and for each status an info task is sent to the requester. For more information see this documentation: https://yuuvisdevelop.atlassian.net/wiki/spaces/onpremise/pages/edit-v2/447184897#Post-processing

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 https://developers.docusign.com/platform/auth/authcode/authcode-get-token/ )

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: Further Settings of the Docusign account

Activate the feature for combining document and certificate by Docusign: In “Signing Settings” → “Envelope Delivery” check the box “Attach certificate of completion to envelope“

Step 4: 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 5: Production is now live

Each signing will now be charged by Docusign.

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.

Screenshot from the 'Send Settings' section of an 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:

signingplatform: "adobesign"

# configuration for accessing Adobe Sign
adobesign-config:
  #The integration key must be created for the permissions "user_read", "agreement_read", "agreement_write", "agreement_send"
  integrationKey: ENC(xxxxxxxx==)
  signatureTypes:
    simple: true
    advanced: true
    qualified: false

^{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.

Beginning with yuuvis® RAD version 10.10 the template project is extended with a process model that can be used for post-processing purposes. For more information see this part of the documentation:
https://yuuvisdevelop.atlassian.net/wiki/spaces/onpremise/pages/edit-v2/447184897#Post-processing

Description of the schema:

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

Don’t change the technical field names. They are used by the client to handle the signing features correctly.

The catalog ‘yuvsigstatus’ offers the processing status values:

General Configurations for Signing