Built-in workflows

RSS

Contract's data

Contract's data

{
  "workflowId" : "rss", <1>
  "type": "PDF", <2>
  "metaData" : {
    "remoteSigningService" : "ses-pdf" <3>
  },
}

1. The identifier of the workflow (required)
2. Type of the payload (required)
3. The name of a valid signing service (required)

Synchronous RSS

Contract's data

Contract's data

{
  "workflowId" : "synchronousRss", <1>
  "type" : "DIGEST", <2>
  "metaData" : {
    "remoteSigningService" : "ses-pdf", <3>
    "pdfDocMDP" : "1" <4>
  },
  "payload" : "ewogICJhbGdvcml0aG1PaWQiOiAiMi4xNi44NDAuMS4xMDEuMy40LjIuMSIsCiAgInZhbHVlIjogIm40YlFnWWhNZldXYUwrcWd4VnJRRmFPL1R4c3JDNElzMFYxc0ZiRHdDZ2c9Igp9" <5>
}

1. The identifier of the workflow (required)
2. The type of the contract (PDF, DIGEST) (required)
3. The name of a valid signing service. The service must be synchronous (no explicit user authentication required) (required)
4. The type of protection of the certification (1 : No changes allowed, 2 : Only form fill-in, signing and page adding actions are allowed, 3 : Only commenting, form fill-in, signing and page adding actions are allowed). Default: 1
5. The payload of the contract, the format varies depending the type selected. PDF : Base64-encoded PDF file, DIGEST : Base64-encoded JSON object containing algorithmOid and value fields, as described below

Digest payload format

{
  "algorithmOid": "2.16.840.1.101.3.4.2.1", <1>
  "value": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=" <2>
}

1. OID of the digest algorithm
2. Digest value Base64-encoded

RSS With SMS Authentication

Activation

This workflow requires the deployment of a dedicated authentication module provided by SwissSign.

It requires as well the following configuration in configuration file application-workflow.yml to be activated.

application-workflow.yml

workflow:
  sms-auth:
    auth:
      url: http://localhost:8080/authentication <1>
      username: admin <2>
      password: changeit <3>
      timeout: 5m <4>

1. URL of the authentication module (required)
2. Username for basic authentication (required)
3. Password for basic authentication (required)
4. Timeout duration of the authentication request (optional). Default: 5m

Contract's data

Contract's data

{
  "workflowId" : "rssWithSmsAuth", <1>
  "type": "PDF", <2>
  "metaData" : {
    "remoteSigningService" : "ses-pdf" <3>
  },
}

1. The identifier of the workflow (required)
2. Type of the payload (required)
3. The name of a valid signing service. The service must be synchronous (no explicit user authentication required) (required)

Standard validation workflow

Contract's data

Contract's data

{
  "workflowId" : "standard", <1>
  "type" : "PDF" <2>
}

1. The identifier of the workflow (required)
2. Type of the payload (required)

Multi signatures workflows

Serial Signatures

Attaching user sequentially

The initial contract submitted to the workflow engine does not contain any information about the signatories (username, meta data) but only the contract's configuration.

Contract's data

{
  "workflowId" : "rss", <1>
  "multiSignaturesWorkflowId" : "serialSignatures", <2>
  "type": "PDF", <3>
  "usernames":[], <4>
  "metaData" : {
    "remoteSigningService" : "ses-pdf", <5>
  },
}

1. The name of a valid single signature workflow (required)
2. The identifier of the workflow handling multi signatures (required)
3. Type of the payload (required)
4. An empty array, signatories are defined afterwards
5. The name of a valid signing service. The service must be synchronous (no explicit user authentication required) (required)

Attaching user

When contract is submitted, and after each intermediate callback received, it's possible to attach the next signatory to the contract.

The Event REST API must used for the given contract id with event name ATTACH_USER.

The event cannot be sent if the previous signatory has not signed the contract yet.

POST /api/admin/event/ <1>
{
  "contractId":"7b76a94f-1fae-4e27-b7ae-06bd9f49eb57", <2>
  "name": "ATTACH_USER", <3>
  "data": "ewogICJ1c2VybmFtZSI6ICJ1c2VybmFtZTEiLAogICJtZXRhRGF0YSIgOiB7CiAgICAiZmlyc3RuYW1lIiA6ICJKb2huIiwKICAgICJsYXN0bmFtZSIgOiAiRG9lIgogIH0sCn0=" <4>
}

1. The REST API endpoint
2. The contract identifier (required)
3. The name of the event (required)
4. Base64-encoded JSON object containing username and metaData fields, as described below

Attach user event's data

{
  "username": "username1", <1>
  "metaData" : { <2>
		"firstname" : "John",
		"lastname" : "Doe"
  },
}

1. Username of the next signatory
2. List of metadata dedicated to the signatory

Finalize contract

Once all signatories have signed the contract, it's necessary to notify the workflow that all responses have been received, especially if the workflow has post-signature action (e.g electronic seal, archiving, etc.). The workflow will the send a final callback and mark the contract as processed (incl. clearing business data).

The Event REST API must used for the given contract id with event name ALL_RESPONSES_RECEIVED.

POST /api/admin/event/ <1>
{
  "contractId":"7b76a94f-1fae-4e27-b7ae-06bd9f49eb57", <2>
  "name": "ALL_RESPONSES_RECEIVED" <3>
}

1. The REST API endpoint
2. The contract identifier (required)
3. The name of the event (required)

Attaching all users at once

It's possible to submit a contract by specifying directly all signatories involved in the process.

It provides the possibility to get rid of managing intermediate callbacks but requires to know in advance the order of the signatories and provide all dedicated meta data with specific prefixes.

Contract's data

{
  "workflowId" : "rss", <1>
  "multiSignaturesWorkflowId" : "serialSignatures", <2>
  "type": "PDF", <3>
  "usernames":[  <4>
  "username1", "username2"
  ],
  "metaData" : {
    "remoteSigningService" : "ses-pdf", <5>
    "skipIntermediateCallback" : "false", <6>
    "users[username1].index" : "0", <7>
		"users[username1].firstname" : "John", <8>
		"users[username2].index" : "1",
		"users[username2].firstname" : "James"
  }
}

1. The name of a valid single signature workflow (required)
2. The identifier of the workflow handling multi signatures (required)
3. Type of the payload (required)
4. An array of signatories (1 or more). The order of the signature is not necessarily defined by the order of the array. To explicitly define signatories order, use metadata index attribute
5. The name of a valid signing service. The service must be synchronous (no explicit user authentication required) (required)
6. Boolean indicating whether the workflow should not send a callback after each signatory. Default : false
7. Index of signatory username1, used to define signatories order. Integer value
8. Custom meta data dedicated to username1

Serial Signatures with Electronic Seal

Contract's data

Please refer to the serialSignatures workflow for the usage and contract's data.

The difference with the previous workflow are listed below.

Contract's data

{
  "multiSignaturesWorkflowId" : "serialSignaturesWithElectronicSeal", <1>
  "metaData" : {
    "remoteSigningService" : "ses-pdf", <2>
    "electronicSealSigningService" : "sample-sas" <3>
  }
}

1. The identifier of the workflow handling multi signatures (required)
2. The name of a valid signing service that will be used by signatories to sign the document. The service must be synchronous (no explicit user authentication required) (required)
3. The name of a valid signing service that will be used to seal the document. The service must be synchronous (no explicit user authentication required) (required)

Envelopes

We provide the possibility to send a single contract containing multiple documents to be signed at the same time.

Contract's data

Contract's data

{
  "workflowId" : "rss", <1>
  "multiSignaturesWorkflowId" : "serialSignatures", <2>
  "type": "ENVELOPE", <3>
  "usernames": [ "username1" ], <4>
  "metaData" : {
    "remoteSigningService" : "ses-pdf" <5>
  },
  "payload" : "ev..." <6>
}

1. The name of a valid single signature workflow (required)
2. The identifier of the workflow handling multi signatures (required, even for single signatory contract)
3. Type of the payload (required)
4. An array of signatories (1 or more). The order of the signature is not necessarily defined by the order of the array. To explicitly define signatories order, use metadata index attribute
5. The name of a valid signing service. The service must be synchronous (no explicit user authentication required) (required)
6. Base64-encoded JSON object containing the list of documents and meta data as described below

Envelope's payload

[ <1>
   {
      "id":"yourDocumentId", <2>
      "type":"PDF",<3>
      "metaData":{ <4>
         "title":"Document's title",
         "description":"Document's description"
      },
      "payload":"base64-encoded PDF" <5>
   },
   {
      "id":"yourDocumentId2",
      "type":"PDF",
      "metaData":{
         "title":"Document's title2",
         "description":"Document's description2"
      },
      "payload":"base64-encoded PDF"
   }
]

1. An array of documents (min. 2)
2. Custom identifier of the document, that will be used to identify documents in callbacks (required)
3. Type of the payload (required)
4. Meta data dedicated to each document (optional)
5. Base64-encoded PDF file (required)

Callback's format

The callback's format consists of a standard callback object as described in REST APIs. The difference with envelopes resides in the response's data format, which consists of a base-64 encoded JSON object representing a list of ContractResponse (one per document)

Contract's response data for envelopes

[
   {
      "id":"yourDocumentId", <1>
      "contractId":"48155539-1d5c-4829-895b-d6145c046751", <2>
      "username":"username1",
      "response":"accepted",
      "context":{
         "Operating system":"Android",
         "Device model":"HUAWEI P10 lite"
      },
      "signature":"UEtDUyM3IERFUg==",
      "data":"base64-encoded signed PDF", <3>
      "date":1481040008086
   },
   {
      "id":"yourDocumentId2",
      "contractId":"d25fb4bd-7479-42fb-a648-7143ef142e73",
      "username":"username1",
      "response":"accepted",
      "context":{
         "Operating system":"Android",
         "Device model":"HUAWEI P10 lite"
      },
      "signature":"UEtDUyM3IERFUg==",
      "data":"base64-encoded signed PDF",
      "date":1481040008095
   }
]

1. The custom identifier of the document, provided in original contract's payload
2. The contract's ID of the document, which differ with the submitted contract. This identifier may be useful to retrieve easily signature details for a given document in audit trail.
3. Signed data

Auto Prepared PDF

The autoPreparedPdf workflow prepares a PDF document on the server side by embedding visual signature graphics based on the received metadata (including a signature image, custom text, font size, page index, coordinates, dimensions...).

Then it calculates the document SHA-256 digest, requests a digital signature from a remote signing service, and assembles the final signed PDF document.

Configuration

When using an asynchronous signing service, the polling interval used to check the status of the contract on the remote signing service can be configured in application-workflow.yml as following:

application-workflow.yml

auto-prepared-pdf:
  statusPollingPeriod: 10s <1>

1. Duration of the polling interval when checking asynchronous signature status (optional). Default: 10s

Contract's data

Contract's data

{
  "workflowId" : "autoPreparedPdf", <1>
  "type": "PDF", <2>
  "usernames": [ "john.doe" ], <3>
  "payload": "JVBERi0xLj...=", <4>
  "metaData" : {
    "remoteSigningService" : "ses-pdf", <5>
    "signatureImage" : "iVBORw0KGgoAAAANSUhEUgAA...", <6>
    "signatureText" : "Signed by John Doe\n2026-08-01 12:00:00", <7>
    "signatureTextFontSize" : "10", <8>
    "signaturePage" : "1", <9>
    "signatureX" : "100", <10>
    "signatureY" : "150", <11>
    "signatureWidth" : "500", <12>
    "signatureHeight" : "150", <13>
    "signatureName" : "John Doe", <14>
    "signatureReason" : "accepted", <15>
    "signatureLocation" : "Lausanne", <16>
  }
}

1. The identifier of the workflow: autoPreparedPdf (required)
2. Type of the payload: PDF (required)
3. Array containing the signatory username (required)
4. Base64-encoded PDF document content (required)
5. The identifier of a valid signing service (e.g. ses-pdf, letssign-rss, letssign-rss-eu) (required)
6. Base64-encoded signature image file (e.g. PNG or JPEG) attached to the visual signature (optional)
7. Text content rendered inside the visual signature box, multi-line separated by \n (optional)
8. Font size in points for signature text (optional). Default: 10
9. 0-based page index where the visual signature is rendered (optional). If null or out of range, defaults to the last page of the PDF document
10. X coordinate in points for visual signature position (optional). Default: 0
11. Y coordinate in points for visual signature position (optional). Default: 0
12. Width in points of the visual signature bounding box (optional). Visual signature rendering is active when signatureWidth and signatureHeight are both greater than 0. Default: 0
13. Height in points of the visual signature bounding box (optional). Default: 0
14. Name field stored in PDF digital signature dictionary (optional)
15. Reason field stored in PDF digital signature dictionary (optional)
16. Location field stored in PDF digital signature dictionary (optional)

Note: If the metadata for the visual signature are not provided, an invisible signature is used.

Common configuration

Push notification

By default, built-in workflows will try to send a push notification to all mobile devices registered for the user. If mobile applications are not configured in the mobile gateway, or if user has no registered device the action will do nothing and workflow will continue as usual.

It's possible to configure or disable the push notification by adding the following meta data in the contract.

Contract's metadata

{
  "metaData" : {
    "skipNotification" : "false", <1>
    "backgroundNotification" : "false", <2>
    "notificationTitle" : "New document available", <3>
    "notificationBody" : "Signature request expires in 2 days" <4>
  }
}

1. Boolean indicating that no push notification must be sent for the contract. Default: false
2. Boolean indicating wether the notification should be flagged as background. For iOS, a background notification will set the contentAvailable to 1. For Android, notification will handle have data attributes (data-only notification). Default: false
3. String indicating the title of the notification. The title is also provided as notification extra data with key user-title. Default: null
4. String indicating the body of the notification. The body is also provided as notification extra data Default: New data available in your inbox

Data persistence

By default, built-in workflows will clear all business data (payload, responses, meta data) after callback is sent to keep only the primary contract information (id, workflowId, type, usernames, state). In case callbacks cannot be implemented by our own, it's possible to indicate to the workflow that business data must not be cleared using the meta data described below.

After retrieving the data using our REST API, it's possible to remove it by sending a CLEAR_DATA event to the contract

Contract's metadata

{
  "metaData" : {
    "keepContractData" : "true" <1>
  }
}

1. Boolean indicating if the data attached in the contract must be kept when contract is processed (optional). Default: false

Common events

Clear data explicitly

In case business data is not cleared automatically by the workflow engine, it's possible to send an event to the workflow to force data removal.

The Event REST API must used for the given contract id with event name CLEAR_DATA.

POST /api/admin/event/ <1>
{
  "contractId":"7b76a94f-1fae-4e27-b7ae-06bd9f49eb57", <2>
  "name": "CLEAR_DATA" <3>
}

1. The REST API endpoint
2. The contract identifier (required)
3. The name of the event (required)