Skip to content

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 Approver role
  • 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
Submit Contract ──Submit──> Approve Contract ──Approve and Sign──> (end)
                                    │
                                    └──Reject──> (end)

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

  1. Create a pool named Signed Approval with the root element Contract.
  2. Add the initiating task Submit Contract with a Submit action whose validation group is Submit.
  3. Route Submit to a second user task named Approve Contract.
  4. Add the actions Approve (caption Approve and Sign) and Reject to the approval task. Set the comment policy of Reject to Required.
  5. 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

  1. Create a role named Approver.
  2. Assign a test user or group with a signature certificate.
  3. Assign the role to Approve Contract.

Build the Form

Create a form with two sections:

  • Documents: a FileList widget bound to Documents, accepting .pdf files and required by the Submit validation group.
  • Signer: two text boxes bound to Signer/Name and Signer/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
const files = $Xml.SelectAll('Documents/File');

if (files.length === 0) {
    alert('There is no document to sign.');
    return false;
}

try {
    const result = await AltiKare.Signature.signFiles(files, 'BES', '');

    if (!result) {
        // the user closed the signing dialog
        return false;
    }

    $Xml.SetValue('Signer/Name', result.certificateName);
    $Xml.SetValue('Signer/SerialNumber', result.certificateSerialNumber);

    return true;
} catch (err) {
    alert('Signing failed: ' + err.message);
    return false;
}

Add the Postwork Check

Open the Approve Contract task's postwork script and add:

1
2
3
4
5
6
7
8
9
if ($WorkItem.SelectedAction == 'Approve') {
    $Xml.SelectAll('Documents/File', function (file) {
        var result = $Crypto.VerifyFile(file.Evaluate(), 'Pades');

        if (!result.AllValid) {
            throw new Error('The document ' + file.GetAttribute('Caption') + ' does not have a valid signature.');
        }
    });
}

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

  1. Configure the Approver role for a test identity with a signature certificate.
  2. Start the process, attach a test PDF, and select Submit.
  3. Open Approve Contract as the approver and select Approve and Sign.
  4. Complete the signature in the signing application.
  5. Confirm that the instance completes and the signer fields contain the certificate name and serial number.
  6. 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 Submit without a document. The form should fail the Submit validation group.
  • Select Reject without 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 Approver independently 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 Cades as the verification format.
  • The action completes without a signature: Confirm that the user select script is on the Approve action and that Allow Bulk Selection is disabled.

What to Learn Next