5.4 Set Process Information
5.4.1 Description
This webservice method updates the persons involved in the process (stakeholders) and assigns them steps which need to be taken.
Important: an API v3.1 version of this call is also available. See section 5.5 for more information. Any new Set Process Information features that are added to the API in the future will be introduced on that API v3.1 call while the call in this section will not change.
Note: all stakeholders must be specified each time this call is made, otherwise they will get deleted.
5.4.2 URL
https://[servername]:[port]/webportalapi/v3/packages/{id}/process
5.4.3 HTTP Method
PUT
5.4.4 Template parameters
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
id | Required | Unique id for the signing package | String |
5.4.5 Request parameters
The root level has currently only one parameter: 'Stakeholders'.
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
Stakeholders | Required (1-n) | Information about the people who are involved in the process. | Array of objects |
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
Stakeholder (array of objects) | Required (1-n) | Information about the people who are involved in the process. | Array of objects |
Actors | Required (1-n) | Array with more information about what the stakeholder must do. | Array of objects |
EmailAddress | Required | Email address | String |
FirstName | Required | First name | String |
Language | Required | UI language of this stakeholder. Currently supported: en, nl, de, fr, es. |
String |
LastName | Required | Last name | String |
BirthDate | Conditional | Date of birth in format: YYYY-MM-DD Note: activating mandated signer validation in the API or configuration might make this required. See section 5.4.12 below. |
String |
ExternalStakeholderReference | Optional | Reference given by the calling application. This parameter will not be used by the eSignatures Portal. | String |
5.4.5.1 Actor
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
Stakeholders --> Actors (array of objects) | Required (1-n) | This object gives information about what the stakeholder must do. | Array of objects |
Type | Required | Signer Receiver Note: actor of type Signer will become a receiver as well |
String |
OrderIndex | Required for Signer | This number specifies in which order actors need to execute their action. If this number is the same for all actors, then the order in which they sign doesn’t matter; they sign in parallel. Incrementing numbers indicate a sequential signing flow: the actor with the lowest OrderIndex value must sign first, the one with the second lowest must sign second and so on. You can also design a complex signing flow: assign the same OrderIndex value to multiple actors who may sign in parallel and assign a different OrderIndex value to actors who must sign before or after the parallel signing. |
Int |
LocationIds | Required for Signer | The location ids where a signature must be placed by this person. | Array of strings |
SigningTypes | Required for Signer | One or more signing type info objects. See section 8. | Array of objects |
Phonenumber | Optional Only Signer |
Phone number to receive an SMS OTP. Note: always add the country code in front of the phone number. E.g. +32xxxxxxxxx. It is recommended to use the plus sign as international dialing prefix instead of using "00". Important: never use spaces in the phone number format. |
String |
RedirectURL | Optional Only Signer Required if IsBackButtonEnabled is set to false in the Configuration Index. |
Url to which the end user is redirected after signing, or rejecting. This field must be a valid absolute url. See section 5.4.14 Redirect Details below. |
String |
RedirectType | Conditional Only signer Forbidden if no RedirectUrl has been set. |
This parameter defines when exactly actors are redirected when using an asynchronous signing method and when a RedirectUrl has been defined. Possible values: AfterSession (default), AfterCompletion, AfterDelay, Immediately. By default, actors are redirected AfterSession. This means they cannot close the signing session and have to wait for all documents to be signed before being redirected. For actors to be redirected immediately, enter Immediately as value. For actors to be redirected after 5 seconds, enter AfterDelay as value. To make sure the final actor is only redirected after the entire package is completed, enter AfterCompletion as value. Note: when AfterCompletion is set for multiple actors, it will only be applied to the final actor. For the other actors, the default AfterSession will be used. Note that this parameter does not apply to F2FRedirectUrl. |
String |
SendNotifications | Optional Only Signer |
eSignatures can send e-mails to the actors whose action is required, such as signing. Such notifications can be enabled or suppressed by setting this parameter as ‘true’ or ‘false’ (the default is ‘false’). This parameter is set per actor. |
Boolean |
UserRoles | Conditional Only Signer Forbidden for XML signing |
Information about the signer’s function. This field must match the language used in the documents to be legally valid. Can currently only be passed when signature policy is used, as seen in section 5.4.13 below. | Array of strings |
LegalNoticeCode | Optional Only Signer Forbidden for XML signing |
LEGALNOTICE1 LEGALNOTICE2 LEGALNOTICE3 The 3 values will point to the 3 legal notices built into the application. These can be altered in the Configuration Index. The language in which the legal notice is displayed, depends on the DocumentLanguage. |
String |
LegalNoticeText | Optional Only Signer Forbidden for XML signing. |
Custom legal notice text in case none of the three predefined legal notices apply. The text should be written in the same language as the one used in the documents of the package. | String |
5.4.5.2 Signing Type Specific Information
The following object defines what kinds of signing types are allowed and it can define extra validation steps for that signing type.
Note: when any of the optional parameters are specified, all signing type objects need to contain the same values for those parameters. This is especially important for MandatedSignerValidation. When you are using choice of signing (i.e. when the signer may choose from different signing types), and you set the MandatedSignerValidation parameter to MatchId or NameAndBirthDate for one signing type, you must also set that parameter to the same value for all the other signing types for that actor, even though those signing types may not support MandatedSignerValidation.
This restriction will be solved in a future version of eSignatures, making all kinds of combinations possible.
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
Stakeholders --> Actors --> SigningTypes (array of objects) |
Required (1-n) | This object specifies the signing type and its related properties. | Array of objects |
SigningType | Required | The signing type. See section 9. |
String |
CommitmentTypes | Conditional Forbidden for XML signing |
One or more OIDs of commitment types. Can only be passed when signature policy is used. See section 5.4.13 below. | String |
MandatedSignerValidation | Optional | Type of validation to execute during eID or other smart card signing session. See section 5.4.12 below. Values: Disabled NameAndBirthDate MatchId |
String |
MandatedSignerIds | Conditional | Defines which eID or other smart cards are allowed to sign during this session. See section 5.4.12. Required when MandatedSignerValidation is of type MatchId. | Array of strings |
MatchLevel | Conditional | Can only be passed when NameAndBirthDate is used as MandatedSignerValidation. This parameter determines how accurately the actor’s FirstName and LastName must match the data retrieved from the signing certificate or signing service. Important: do not add the percentage sign to the value. A value between 90 and 95 usually produces good results. See section 5.4.12 Mandated Signer Validation for more information. |
Integer between 50 and 100 |
SignaturePolicyId | Optional | This parameter should only be used if you want a different signature policy than the default one set by set by Connective in the Configuration Index. If clients want to use a custom Signature Policy, they need to log a service request at Connective. See section 5.4.13. for more information. Important: if you want to combine legal notices and signature policies, the setting CombineLegalNoticeAndSigningPolicy must be enabled in the Configuration Index. |
String |
5.4.6 Example request 1
In this example request, one actor named John Doe will sign one document inside a package, choosing BeId or BeLawyer as signing type.
{
"Stakeholders": [
{
"FirstName": "John",
"LastName": "Doe",
"EmailAddress": "john.doe@example.org",
"Language": "en",
"BirthDate": "1972-09-24",
"ExternalStakeholderReference": "C0004105",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 1,
"LocationIds": [
"68f35693-5530-4770-b8d8-76284719e524", "c2e325a4-7b1d-42a6-8179-5377707d007c"
],
"SigningTypes": [
{
"SigningType": "BeId",
"MandatedSignerValidation": "MatchId",
"MandatedSignerIds": [
"72092400465", "72092630155"
]
},
{
"SigningType": "BeLawyer",
"MandatedSignerValidation": "MatchId",
"MandatedSignerIds": [
"83fc726f-9e4a-486f-9d99-87c6604bde7d","7ab8594b-4cd0-4c7e-862e-3cc226622149"
]
}
],
"PhoneNumber": "+32477123456",
"UserRoles": [
"Lawyer"
],
"SendNotifications": true,
"RedirectUrl": "https://www.mycompany.com"
}
]
}
]
}
5.4.7 Example request 2
This example request displays a complex signing use case: John Doe will use BeId to sign his recruitment contract at MyCompany. Once he has signed, Jane Jefferson (the CEO of MyCompany) and Bob Smith (the HR Officer of MyCompany) must countersign the contract. The OrderIndex value determines John Doe must sign first; he has the lowest OrderIndex value. Then, the two other actors must sign. The order in which they do has no importance – since the OrderIndex value is the same for both, but higher than the one for John Doe.
{
"Stakeholders": [
{
"FirstName": "John",
"LastName": "Doe",
"EmailAddress": "john.doe@example.org",
"Language": "en",
"ExternalStakeholderReference": "Employee",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 1,
"LocationIds": [
"68f35693-5530-4770-b8d8-76284719e524"
],
"SigningTypes": [
{
"SigningType": "BeId",
"MandatedSignerValidation": "Disabled"
}
],
"SendNotifications": true
}
]
},
{
"FirstName": "Jane",
"LastName": "Jefferson",
"EmailAddress": "jane.jefferson@mycompany.org",
"Language": "en",
"ExternalStakeholderReference": "CEO",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 2,
"LocationIds": [
"76284719e524-5530-4770-b8d8-68f35693"
],
"SigningTypes": [
{
"SigningType": "BeId",
"MandatedSignerValidation": "Disabled"
}
],
"SendNotifications": true
}
]
},
{
"FirstName": "Bob",
"LastName": "Smith",
"EmailAddress": "bob.smith@mycompany.org",
"Language": "en",
"ExternalStakeholderReference": "HR Officer",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 2,
"LocationIds": [
"55304486e524-5530-4770-b8d8-68f35748"
],
"SigningTypes": [
{
"SigningType": "BeId",
"MandatedSignerValidation": "Disabled"
}
],
"SendNotifications": true
}
]
}
]
}
5.4.8 Response parameters
Parameter | Content / Description | Type |
---|---|---|
None | Empty object |
5.4.9 Example response
{ }
5.4.10 Response codes
Response status code | Description |
---|---|
200 OK | The process information has successfully been added to the package. |
400 Bad Request | There are invalid parameters in the request. |
404 Not Found | When an unknown package id is passed. |
409 Conflict | Some parameters conflict with the data found in the database or configuration. |
5.4.11 Error codes
HHTP Code | Code |
---|---|
400 | Request.RequiredFieldIsMissing |
400 | Stakeholder.BirthDayInFuture |
400 | Stakeholder.UnsupportedLanguage |
400 | SigningField.InvalidPage |
400 | SigningType.Invalid |
400 | Stakeholder.EmailAddressInvalid |
400 | SignaturePolicy.MissingUserRole |
400 | SignaturePolicy.MissingCommitmentType |
400 | Signer.ParameterCannotBeUsedWithoutSignaturePolicy |
400 | Actor.TypeInvalid |
400 | Actor.MissingPhoneNumber |
409 | MandatedSigner.BirthDateMissing |
409 | MandatedSigner.MandatedSignerIdMissing |
409 | SignaturePolicy.NotFound |
409 | CommitmentType.NotAllowed |
409 | PhoneNumber.Invalid |
409 | Location.NotFound |
409 | SignaturePolicy.ShouldBeSameForActor |
409 | CommitmentType.ShouldBeSameForActor |
409 | SigningType.Disabled |
5.4.12 Mandated signer validation
eSignatures can do an extra identity check to verify if an end user is mandated to sign during a particular signing session. This check is called Mandated Signer Validation.
How does mandated signer validation work?
Some signing methods use a signing certificate (BeID, BeLawyer and Itsme) or signing service (iDIN) that contains data directly tied to the end user. This data may be their first and last name, but also their national security number or laywerID.
To validate if an end user is mandated to sign during a particular session, eSignatures compares the data the API user enters in the Set Process Information call to the data stored in the signing certificate, or to the data returned by the signing service (in case of iDIN). If the data matches, the end user is mandated to sign. If it doesn’t, the end user receives a message they are not mandated.
Types of mandated signer validation
The validation can be done in two ways: based on a unique identifier (MatchId) linked to a smart card or based on the end user’s name and birthdate data stored in the signing certificate (NameAndBirthDate).
MatchId
The following signing methods support mandated signing based on MatchId:
- BeID
- BeLawyer
In case of BeID the national security number is used as unique ID. For BeLawyer, the LawyerID is used.
NameAndBirthDate
The following signing methods support mandated signing based on NameAndBirthDate:
- BeID
- Itsme
- iDIN
How to use manded signer validation in the API?
MatchId
Add “MatchId” as value of the MandatedSignerValidation parameter.
Then add the required unique identifiers as value of the MandatedSignerIds parameter. Only the certificates that contain one of the allowed ids will be mandated to sign.
Tip:
The system admin can also choose to set MatchId as default validation type in the Configuration Index. This way, the API user doesn’t need to enter the MandatedSignerValidation parameter, but only the MandatedSignerIds parameter.
When MatchId is set as default in the Config Index, note that it can still be disabled for a single API request by passing “Disabled” as value of the MandatedSignerValidation parameter.
NameAndBirthDate
Add “NameAndBirthDate” as value of the MandatedSignerValidation parameter. Important: make sure the name and birth date exactly match the data on the signing certificate. How to do so is explained in Which data must match? below.
The MandatedSignerIds parameter is not used in this case.
Note: the API also accepts numeric values (“0” = Disabled, “1” = NamedAndBirthDate, “2” = MatchId) but this is deprecated and will be removed in API v4 / eSignatures 6. It is recommended to use text ids.
Which data must match?
In this section we provide an overview of the eSignatures data that is compared to the signing certificate data.
Important: since Connective does not issue the signing certificates used in the respective signing methods, we have zero control over the information they contain. In order to know which data to enter in the API request, the API user must check the data on the signing certificate to make sure the data matches.
For BeID signing based on MatchId:
- The id entered as MandatedSignerIds must match the national security number stored in the signing certificate of the eID card.
For BeLawyer signing based on MatchId:
- The id entered as MandatedSignerIds must match the LawyerID stored in the signing certificate of the BeLawyer card.
For BeID signing based on NameAndBirthDate:
- The FirstName value entered on Stakeholder level must match the “G=” value (Given Name) on the eID card.
- The LastName value must match the “SN=” value (SurName).
- The BirthDate must match the Date of birth value.
To check which data is stored on an eID card use the eID Viewer application.
For Itsme signing based on NameAndBirthDate:
- The FirstName value entered on Stakeholder level must match the First name(s) value in their Itsme app.
- The LastName value must match the Surname value.
- The BirthDate value must match the Date of Birth value.
To check which data is stored in an end user’s itsme app, they must consult My ID data in their app.
For iDIN signing based on NameAndBirthDate:
- The FirstName value is not checked, since iDIN doest not store this info.
- The LastName value must match the consumer.legallastname value.
- The BirthDate value must match the consumer.dateofbirth value.
Attention: specific LastName naming conventions apply with iDIN.
- It must be the legal last name of the iDIN consumer, without prefixes.
- It may contain a maximum number of 200 characters without numbers.
- It must not include the prefix of the first last name. Prefixes of later sections of the last name must be included.
- If the last name consists of multiple sections that are separated by a -, the – must not be led and followed by a space.
- Leading and trailing spaces are not allowed.
Examples
- For the name “Luana van Oranje-Nassau van Amsberg” the value should be “Oranje-Nassau van Amsberg”.
- For the name “Jacques d’Ancona” the value should be “d’Ancona”.
- For the name “Jacques d’ Ancona” the value should be “Ancona”
Choice of signing with Mandated Signer Validation
When you want to offer choice of signing combined with mandated signer validation, you need to make sure that all the signing methods you add on Actor level support the same Mandated Signer Validation type. For instance, if you want the end user to be able to choose between Itsme and BeID, you need to enter “NameAndBirthDate” as MandatedSignerValidation value, since that’s the only type both signing methods support.
This restriction will be solved in a future version of eSignatures, making all kinds of combinations possible.
What to do in case the data doesn't match?
For choice of signing with mandated signing to work, the data stored on the different signing certificates must be identical. Practice has shown that this is often not the case. Even when using a single signing method such as BeID, it may occur that the data stored in the signing certificate doesn't match the visual representation on the physical eID card, and therefore the wrong data is entered in the API call. This especially applies to names with special characters, or additional first names, etc.
In previous versions of eSignatures, the slightest mismatch in data would render the signer "not mandated to sign".
Since eSignatures 5.4 however, the system admin can configure a MatchLevel value in the Config Index when using NameAndBirthDate as MandatedSignerValidation. The MatchLevel parameter determines how accurately the FirstName and LastName entered in the Set Process Information or Instant Package Creation call must match the data retrieved from the signing certificate or signing service. The default value is set to 100%, which means the data must be completely identical. When you notice a signer constantly receives error messages stating they are not mandated to sign, you can lower the MatchLevel to for instance 90 or 95 in the Configuration Index. Or you can override the Config Index value by passing the MatchLevel parameter in the API call, in case you don’t want to lower the accuracy on environment level.
This way you can configure the right balance so that only the required party is able to sign, while the identity check is flexible enough to go past minor inconsistencies.
Note: The Jaro-Winkler algorithm is used to calculate the accuracy. So, the accuracy is not based on the exact number of characters that match.
5.4.13 Signature Policies and Commitment Types
Digital signatures can reference a signing policy which details the terms and conditions of how a valid signature should be created and validated.
Since such a policy needs to be drafted before it can be used, these policies are specified using a single Id which needs to be configured in the eSignatures database. Please ask the Connective customer services team for more information when a policy is required.
Commitment types are limited to the following set of 6 types defined in the ETSI CAdES standards:
Type OID | Description |
---|---|
1.2.840.113549.1.9.16.6.1 | Proof of origin |
1.2.840.113549.1.9.16.6.2 | Proof of receipt |
1.2.840.113549.1.9.16.6.3 | Proof of delivery |
1.2.840.113549.1.9.16.6.4 | Proof of sender |
1.2.840.113549.1.9.16.6.5 | Proof of approval |
1.2.840.113549.1.9.16.6.6 | Proof of creation |
5.4.14 Redirect URL Details
The redirect url is used to redirect the end user to the originating web application pointed to by that URL. The redirect occurs immediately after the user has signed or rejected.
If there is no URL, the end user will have to close the current tab by clicking the Close Tab button of the browser.
The base URL (without any parameters) must be given in the Set Process Information call and is appended with the following query parameters:
- SessionID (unique identifier of the package signing session)
- ExternalReference (as found in the Stakeholder object of the Set Process information call)
- Status (SIGNED, REJECTED or INVALIDTOKEN)
- PackageExternalReference (as found in the ExternalPackageReference parameter of the Create Package call/Create Instant Package call)
The RedirectUrl parameter must contain a valid, absolute URL with no existing query parameters.
For example, if the RedirectUrl parameter contains the following redirect url:
https://myserver.example.org/rental/services/testredirect
then the effective redirect URL will be:
https://myserver.example.org/rental/services/testredirect?SessionID=5a2aff04-3cfa-4278-9480-64ac39f74734&ExternalReference=user1@example.org&**Status**=REJECTED&**PackageExternalReference**=dossier-3592
Note: the end user can counterfeit the redirect URL because the redirection happens client-side! Either establish a second secure channel by means of the Callback URL, or verify through session state that the end user returned from the correct session id. Afterwards a call to Get Package Status (see section 5.8) must be done to verify that the document was actually signed or rejected.
Note: during asynchronous signing, the signer has the possibility to close the signing session - by means of a Close button - while the signing continues in the background. The purpose of a RedirectUrl however is to redirect the signer to a new URL after the signing has finished. By default, the signer has to wait until all documents are signed before being redirected. Since eSignatures 5.4, it is possible to configure when the redirect happens: 1) immediately as soon as the signing starts, 2) after a delay of 5 seconds, or 3) after completion of all documents.