⚠ This article is new and still under construction so content can be changed at any time!
This article is written for administrators that want to support the users of the yuuvis® RAD client to sign their PDF documents via Docusign.
Prerequisites
Signing-Service
Beginning with yuuvis® RAD 9.4 the new Signing-Service will be part of the Service Infrastructure. This service can be requested for signing the PDF-formated file of a given document via the DocuSign platform.
This service is designed to add connectors for other signing platforms like Adobe Sign.
Update step
After the update of your system, you have to add the Signing-Service to the service infrastructure by adding this code to the 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
These are the parameters to control the behavior of the Signing-Service in the signing-prod.yml file:
signingplatform: docusign
docusign-config:
apiBasicAuth: ZjBkZDk3NTgtZTZjNS00NGUzLThmMDAtZjJhODczY2Q1MzBlOjNjM2JiZmQyLWEyOGYtNDg3ZC1iNzQ2LWE3NDllYTZhZDdiNQ==
apiUsername: 611c7fa3-eda4-4173-8af5-2bde0bccb54f
pathToPrivateKey: /home/kolja/Projects/DocuSign/Grizzly/keys/private.key
usetemplates: false / tbd
templateid : "a572b25d-b4c4-4545-a5b3-9d4fd17d1cca" / tbd
templates:
- documenttype: "contract"
templateid: "a572b25d-b4c4-4545-a5b3-9d4fd17d1cca"
- documenttype: "workinstruction"
templateid: "a572b25d-b4c4-4545-a5b3-9d4fd17d1cca"
Parameter | possible values | Description |
|---|---|---|
signingplatform | docusign | This parameter controls which platform to use. Currently, only ‘docusign’ for the use of the DocuSign platform can be configured. In the future others will follow. |
docusign-config | Section for the parameters that need to be configured or that can be configured for the DocuSign platform | |
apiBasicAuth | <string> | Generated using the apiUsername and a secret key generated within your DocuSign account. |
apiUsername | <string> | To be taken from your DocuSign account. |
pathToPrivateKey | <path> | The path to your private key that is needed for a secure communication with the DocuSign platform. |
templates | Section for templateIds that should be used for documents that are based on specific object types. | |
documenttype | <technical name of a document type> | The Signing-Service uses this templateId that is configure for this document type when requesting signatures for a document that is based |
templateid | <string with a templateId> | The templateId that is configured on the DocuSign platform in your account. |
If no templateId is configured the DocuSign envelop will be created without a templateId.
Enabled Signing Capability
The Signing Capability has to be activated using the management studio.
Derive relevant object types from the signing abstract object type
Beginning with yuuvis® RAD 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:
The technical name of the abstract object type is 'yuvsigning'
Technical field name | Neutral label | Description |
|---|---|---|
yuvsigsubject | Subject | The reason why the signing was requested . This subject is part of the email sent to a signer. |
yuvsigtype | Signature type | 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. |
yuvsigrequester | Signing requester | The ID of the requesting user |
yuvsigreqdate | Date of request | The Date and time the request was activated |
yuvsigdate | Date | The date the signing process wass finished |
yuvsigstatus | Status | Status of the signing process. The shown values are those of the catalog ‘yuvsigstatus’ described below. |
yuvsigerror | Error message | Error message writte by the client or the Signing-Service in case of an error. |
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. In the beginning only ‘docusign’ will be reported here. |
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 |
yuvsigneremail | Email address | Email address of a signer that is used by Docusign for sending the email. |
yuvsignerphone | Phone number | This number can be used for two-factor authentication |
yuvsignextern | external | 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. |
yuvsigcomment | Comment | This field is used to show the comment that the signers has given on the signing platform |
Warning: 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:
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 |
cancelled | cancelled | Set when a users had cancelled 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 | inprocess | Set by the Signing-Service if the transfer to the signing platform was positiv. |
Warning: don’t change the technical value names. They are used by the client to show different colors for each label.
The catalog ‘yuvsigtype’ offers the list of signature types. The values are:
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 |
Warning: don’t change the technical value names. They are used by the Signing-Service to request the configured signing platform correctly.
The use case
A user is offered the object action ‘Request signature’ ('Signatur anfordern') if
the signing capability is activated
the relevant object type is derived from the signing abstract object type
they own the edit permission for the relevant document
the document is editable (e.g. not finalized, no signing was requested before)
Activating this action the user is asked to enter the names of one or more signers as well as its email addresses and a subject that describes the reason for signing.
After finishing the signing request the Signing-Service is fetching the document file and transfers it to the Docusign platform. The status information is written back to the object as new attributes. An audit entry is written to the object history. A symbol in the object headers is indicating this status.
The signing progress
Once the signing process was started by the Signing-Service the service is polling the Docusign platform every 15 minutes or more as configured. Docusign is sending an email to the next signer. After a signing the status information of the object is updated. After the last signer has finished the process is closed and a symbol in the object details header is indicating this status.
Canceling the request
During this process, users with edit permission can cancel the process.
Signing information
As long as the client does not support the planned new object details aspect ‘Signing’ for documents of an object type that is derived from the abstract object type ‘yuvsigning’ administrators can configure the form for that object type that includes the properties of the abstract object type as shown below:
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.
