CertSign Integration for electronic signature

Certsign is a digital certification for digital signatures. It will provide the user with the capability to use the Esign processor in the Studio and Portal. This makes possible to sign contracts and other documents by a client. The existing integration provides two types of signature:

  • Remote signature (with authorization code sent through sms)
  • Automatic signature (with an existing certificate)
  • Automatic signature with qualified electronic sign.

After the installation of the ESign provider package, you should add the following configuration in FTOS Portal web.config, section appSettings or JobServer serviceSettings.config:

Copy 
<add key="FTOSServicesESignProvider2Endpoint" value="https://aztestapi01.azure-api.net/certSign"/> <!-- This is the test env url -->
<add key="FTOSServicesESignProvider2AppId" value=""/><!-- the subscription key -->
<add key="ESignProvider2CertName" value="certSignTest"/> <!-- the mapping for the certificate provided by FTOS-->

If you have to configure also, the automatic signature, please add the following keys:

Copy 
<add key="ESign2AutomaticNumber_{ProfileName}" value=""/> <!--this will contain the serial number provided for the specific profile-->
<add key="ESign2AutomaticName_{ProfileName}" value="cn=certSIGN CA Class 2 G2,ou=certSIGN CA Class 2 G2,o=certSIGN,c=RO"/> <!--this will contain the issuer information for the profile-->
IMPORTANT!  
The token {ProfileName} must be replaced with a profile name that will be used when requesting the signature process.

Set up for the automatic signature with qualified electronic sign

After the installation of the ESign provider package, you should add the following configuration in JobServer serviceSettings.config:

Copy 
<add key="FTOSServicesESignProvider2Endpoint" value="https://aztestapi01.azure-api.net/certSign"/> <!-- This is the test env url -->
    <add key="FTOSServicesESignProvider2AppId" value=""/><!-- the subscription key -->
    <add key="ESignProvider2AutomaticQESCertName" value="certSignTestAutomatic"/> <!-- the mapping for the certificate provided by FTOS for the Automatic QES signature-->

Insert a record in the business entity FTOS_DDM_ESignQueue, this record will contain the configurations that will be used for automatic qualified electronic sign.

ProfileName, choose a name for this automatic profile, make sure it is unique if you have multiple configurations:

  • ExternalId, this value should be provided CertSign, it will be the externalId of the user that is enrolled to sign with automatic QES
  • Seed, this value will be read by the agent from his CertSign acount (he will receive an email with steps to follow)
  • WorkstepsBulkNo, this represents the number of worksteps that will be sent in the request to be signed with automatic QES.

Calling the automatic signature with qualified electronic sign

The request for automatic QES will be sent together with the rest of the worksteps. The signing processes will be made in the order provided in the request. It is recommended that this signature to stay at the end because it will be processed async by Job Server.

The workstep with automatic QES should be like:

Copy 
{
      "signatureTag": "#tagAgentQES#",
      "signatureType": FTOSServices.DDM.signatureType.AutomaticQES,
      "automaticProfile": "ProfileNameDefinedInQueue", //defined in FTOS_DDM_ESignQueue
      "signatureStamp": { //this is for the signature stamp 
        "SignerName":"Sign name",
        "Reason": "Credit loan", //this will appear in signature details
        "Subject": "Bank signature",
        "ShowTimeStamp": true, //show date in signature stamp
        "FontSize": "12"
      }
    }

 

Copy 
var signRequest = {
  "workstepConfigs": [
    {
      "signatureTag": "#tagClient#",
      "signatureType":FTOSServices.DDM.signatureType.QualifiedElectronicSign,
      "recipient": {
        "Country": "RO",
        "Email": "@fintechos.com",
        "ExternalId": "", //an unique id representing the customer (ex: Accoountid)
        "FirstName": "M",
        "LastName": "C",
        "PhoneMobile": "+407",
        "SocialSecurityNumber": "", //PIN
        "IdPhoto": "", // ftos file attribute value representing the id picture
        
      },
      "signatureStamp":{
        "Reason": "Client reason",
        "Subject": "Credit loan",
        "SignerName":  "TestFirstName TestLastName",
        "FontSize": "12"
      }
    },
    {
      "signatureTag": "#tagAgentQES#",
      "signatureType": FTOSServices.DDM.signatureType.AutomaticQES,
      "automaticProfile": "ProfileNameDefinedInQueue",
      "signatureStamp": { //this is for the signature stamp 
        "SignerName":"Sign name",
        "Reason": "Credit loan", //this will appear in signature details
        "Subject": "Bank signature",
        "ShowTimeStamp": true, //show date in signature stamp
        "FontSize": "12"
      }
    }
  ],
  "signedDocumentName": "test.pdf",
  "files": [
    {
      "ftosFile": "" //ftos file attribute value representing the pdf that needs to be signed
    }
  ]
}

 

NOTE  
The automatic QES signing has to be processed by Job Server, so you must configure a schedule trigger with a server side script. Please make sure that you won't use the same ExternalId on multiple instances of FintechOS. Also, the scheduled trigger should be configured to run with a frequency of at least 30 seconds. The recommended cron expression should be to start at second 0 or at second 30 and to run from 30s in 30s (or a multiple of 30s = 1min, 2min, etc).

In the server side script you have to call the following method with the parameter ProfileName that you've defined in FTOS_DDM_ESignQueue:

Copy 
//This method returns the list with processed eSignId and the workstepId that has been finished
//As input you shoul pass the Name that you've configured in  FTOS_DDM_ESignQueue
var result = FTOSServices.DDM.ESign2.processPendingAutomaticQESSign("ProfileNameDefinedInQueue");


// if success the result will look like:
/*
{
  "isSuccess": true,
  "isFinished": true,
  "eSignProcesses": [
    {
      "eSignId": "e2f2bc20-de1f-41f1-851b-5c0279cc4cb7",
      "eSignWorkstepId": "13b2ea4e-f5cb-491a-a32a-268741e7da2a"
    },
    {
      "eSignId": "ac42d532-88a3-4db6-932c-9d0888e2fd0e",
      "eSignWorkstepId": "6830d22a-9309-4a11-9e9a-05ab7ac8807b"
    }
  ]
}
*/

FTOS ESign Services API

In order to sign a document you must call the following methods:

  1. RequestSign (for the configuration of the automatic signature)

    For client signature with remote method with authorization code sent through sms:

  2. AcceptTermsAndConditions
  3. Authorize signature
  4. Resend code

RequestSign

Firstly, add a reference to the library FTOSServices. To request with qualified electronic signature and automatic, use the following example:

Copy 
var signRequest = {
    "workstepConfigs": [{
        "signatureTag": "#tagClient#",
        "signatureType": FTOSServices.DDM.signatureType.QualifiedElectronicSign,
        "recipient": {
            "Country": "RO",
            "Email": "@fintechos.com",
            "ExternalId": "", //an unique id representing the customer (ex: Accoountid)
            "FirstName": "M",
            "LastName": "C",
            "PhoneMobile": "+407",
            "SocialSecurityNumber": "", //PIN
            "IdPhoto": "", // ftos file attribute value representing the id picture
        },
        "signatureStamp": {
            "Reason": "Client reason",
            "Subject": "Credit loan",
            "SignerName": "TestFirstName TestLastName"
        }
    }, {
        "signatureTag": "#tagBank#",
        "signatureType": FTOSServices.DDM.signatureType.AutomaticSign,
        "automaticProfile": "Profile1",
        "signatureStamp": { //this is for the signature stamp
            "Reason": "Credit loan", //this will appear in signature details
            "Subject": "Bank signature",
            "ShowTimeStamp": true //show date in signature stamp
        }
    }],
    "signedDocumentName": "test.pdf",
    "files": [{
        "ftosFile": "" //ftos file attribute value representing the pdf that needs to be signed
    }]
}
Optionally, you can add to the recipient property the following information.It will appear in terms and conditions file......
"workstepConfigs": [{
        "signatureTag": "#tagClient#",
        "signatureType": FTOSServices.DDM.signatureType.QualifiedElectronicSign,
        "recipient": {......
            "DocumentIssuedBy": "splcid", "DocumentIssuedOn": "2020-01-20", "DocumentExpiryDate": "2050-01-25", "DocumentNumber": "123456", "DocumentSeries": "xa", "County": "Braila", "City": "Braila", "Street": "asd", "StreetNo": "12", "Block": "asd", "Entrance": "q", "ApartmentNo": "123", "ZipCode": "123453",
        }
HINT  
If you have a request with multiple signatures, please keep in mind that the signing processes is sequentially and the client signature must have manual input (accept terms and conditions and authorize signing using the code received via sms).

You should save the eSignId in order to track the status of the eSign process using the method GetESignStatus.

Add a reference to the client script library FTOS_DDM_ESignProvider2.

Copy 
/**
* Accepts terms and conditions for emtitting the certificate
* @param termsId is the id returned by requestSign method (entityId property)
* @param accepted should be set on true, if the user accepts the terms and conditions
* @return documentId that will be used for authorize signing
*/
acceptTermsAndConditions(termsId: string, accepted: boolean): Promise<any>

Example:

Copy 
var ddmESign = ebs.importClientScript("FTOS_DDM_ESignProvider2");
ddmESign.acceptTermsAndConditions(termsId, true).then(function(result) {
    console.log(result);
    //output should be{isSuccess: true, entityId: "12437-34873"}
}, function(error) {
    console.log(error); 
});

Add a reference to the client script library FTOS_DDM_ESignProvider2.

Copy 
// @param documentId is the id returned by acceptTermsAndConditions method (entityId property)
// @param code should be the code sent via sms for the signing process

authorizeSign(documentId: string, code: string): Promise < any > ;

// Example:

var ddmESign = ebs.importClientScript("FTOS_DDM_ESignProvider2");
ddmESign.authorizeSign(documentId, code).then(function(result) {
    console.log(result);
    //output should be {isSuccess: true}
}, function(error) {
    console.log(error); 
});

Example:

Copy 
var ddmESign = ebs.importClientScript("FTOS_DDM_ESignProvider2");
ddmESign.authorizeSign(documentId, code).then(function(result) {
    console.log(result);
    //output should be {isSuccess: true}
}, function(error) {
    console.log(error); 
});

As before, add a reference to the client script library FTOS_DDM_ESignProvider2.

Copy 
/**
* @param documentId is the id returned by acceptTermsAndConditions method (entityId property)
*/
resendCode(documentId: string): Promise<any>

Example:

Copy 
var ddmESign = ebs.importClientScript("FTOS_DDM_ESignProvider2");
ddmESign.resendCode(ebs.getCurrentEntityId()).then(function(result) {
    console.log(result);
    //output should be {isSuccess: true}
}, function(error) {
    console.log(error);
});

Async methods, can be used with JobServer:

This method should be called using Job Server scheduler. It will update the status of the in progress eSign processes.

FTOSServices.DDM.ESign2.updateStatusESignProcess();

This method should be called using Job Server scheduler. It gets the in progress esign processes that must be signed with automatic signatures.

FTOSServices.DDM.ESign2.processPendingAutomaticSign();

This method returns the status of the eSign process. If the status is Finished, then you can get the signed document name to use it in your digital journey.

Copy 
/**
 * @param eSignId is the id returned by requestSign
 */
FTOSServices.DDM.ESign2.getESignStatus(eSignId): any
Example: var eSignStatus = FTOSServices.DDM.ESign2.getESignStatus(eSignId);
log(toJson(eSignStatus));
/*should print:
{
"isSuccess": true,
"status": "Finished",
"documents": "[\r\n  {\r\n    \"Name\": \"contract1.pdf\",\r\n    \"RealName\": \"contract1_42dfa5ba-c1f4-4328-b095-b6075d0c12ee.pdf\",\r\n    \"IsSuccess\": true,\r\n    \"Message\": null,\r\n    \"ClientScript\": null,\r\n    \"Serialized\": null,\r\n    \"ErrorCode\": 0,\r\n    \"UIResult\": null\r\n  }\r\n]"
}
/*

Example:

Copy 
var eSignStatus = FTOSServices.DDM.ESign2.getESignStatus(eSignId);
log(toJson(eSignStatus));
/*should print:
{
"isSuccess": true,
"status": "Finished",
"documents": "[\r\n  {\r\n    \"Name\": \"contract1.pdf\",\r\n    \"RealName\": \"contract1_42dfa5ba-c1f4-4328-b095-b6075d0c12ee.pdf\",\r\n    \"IsSuccess\": true,\r\n    \"Message\": null,\r\n    \"ClientScript\": null,\r\n    \"Serialized\": null,\r\n    \"ErrorCode\": 0,\r\n    \"UIResult\": null\r\n  }\r\n]"
}
/*