Sign Attachments on Approval¶
Goal¶
Require the approver to sign the attached PDF documents with an electronic signature when approving a request, and verify the signatures on the server before the workflow continues.
What You Will Learn¶
- start electronic signing from an action's user select script
- cancel the action when the user does not complete the signature
- write signer information into the form data
- verify the signed documents in the postwork script
Difficulty and Estimated Time¶
- Difficulty: Intermediate
- Estimated time: 20 minutes
Assumed Knowledge¶
You should be familiar with pools, user tasks, actions, roles, forms, and the script execution order.
Required Reading¶
Prerequisites¶
- permission to create or import a process definition
- a test user or group that can be assigned to the
Approverrole - for the approver: an electronic signature certificate and the Kolay İmza signing application installed
- one or more test PDF documents without personal data
The example uses the BES signature level, which does not require a time stamping server.
Example Overview¶
The example contains two tasks:
1 2 3 | |
The requester attaches PDF documents. The approver either rejects them with a comment or approves and signs them. The signatures are embedded in the PDF files and checked on the server before the instance completes.
Steps¶
Create the Process Flow¶
- Create a pool named
Signed Approvalwith the root elementContract. - Add the initiating task
Submit Contractwith aSubmitaction whose validation group isSubmit. - Route
Submitto a second user task namedApprove Contract. - Add the actions
Approve(captionApprove and Sign) andRejectto the approval task. Set the comment policy ofRejecttoRequired. - Leave Allow Bulk Selection disabled for
Approve. Bulk and email selection do not run the user select script.
Neither approval action has a route, so the instance completes after either action.
Configure the Approver Role¶
- Create a role named
Approver. - Assign a test user or group with a signature certificate.
- Assign the role to
Approve Contract.
Build the Form¶
Create a form with two sections:
Documents: a FileList widget bound toDocuments, accepting.pdffiles and required by theSubmitvalidation group.Signer: two text boxes bound toSigner/NameandSigner/SerialNumber.
Assign the form to both tasks. On Submit Contract, set Documents to the default state and hide Signer. On Approve Contract, set both sections to Disabled, so the approver cannot change the documents or the signer fields.
Add the User Select Script¶
Open the Approve action's User Select Script and add:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | |
Add the Postwork Check¶
Open the Approve Contract task's postwork script and add:
1 2 3 4 5 6 7 8 9 | |
How It Works¶
The user select script runs in the approver's browser after the approver selects Approve and Sign and confirms it. AltiKare.Signature.signFiles opens the signing dialog and starts the signing application. The script returns true only after a successful signature, so the action is submitted together with the signed documents and the signer fields.
When the action is submitted, the signed content becomes the current revision of each file. The postwork script then runs on the server and verifies every document with $Crypto.VerifyFile. Because the browser result is user input, the server check is the one that guarantees a signed document. If a document is not validly signed, the error rejects the completion and the task stays open. Keep Execute Delay disabled on the approval task so that this check runs while the approver submits the action.
Reject has no user select script, so the approver can reject without a certificate.
Verify the Result¶
- Configure the
Approverrole for a test identity with a signature certificate. - Start the process, attach a test PDF, and select
Submit. - Open
Approve Contractas the approver and selectApprove and Sign. - Complete the signature in the signing application.
- Confirm that the instance completes and the signer fields contain the certificate name and serial number.
- Download the PDF and confirm in a PDF viewer that it carries the signature.
Failure and Edge Cases¶
- Close the signing dialog without signing. The action must be cancelled and the task must stay open.
- Try
Submitwithout a document. The form should fail theSubmitvalidation group. - Select
Rejectwithout a comment. The comment is required. - Sign with a certificate that does not belong to the approver's national identity number, when one is defined for the user. The signing application must not offer that certificate.
- Complete the approval through a REST call or another path that skips the user select script. The postwork check must stop the completion because the document is not signed.
Security and Portability Notes¶
- The example contains no user, group, tenant, email, certificate, or domain identifier.
- Configure
Approverindependently in each target domain. - The browser script improves the user experience; the postwork check enforces the rule.
- Use test documents and test certificates while trying the example.
Download and Try It Yourself¶
Download the signed-approval process definition.
Configure the Approver role after import.
Troubleshooting¶
- The signing dialog keeps waiting: Confirm that the signing application is installed and allowed to start from the browser.
- No certificate is offered: Confirm that the certificate's identity number matches the approver's identity properties, and that the signature device is connected.
- The postwork check reports an invalid signature: Confirm that the documents are PDF files. For other file types, use
Cadesas the verification format. - The action completes without a signature: Confirm that the user select script is on the
Approveaction and that Allow Bulk Selection is disabled.
What to Learn Next¶
- Electronic Signatures for detached signatures, text signing, and server signing
- Create a Correction and Resubmission Loop