Integration Methodologies
with external Applications

Revision History

Revision Data Summary of Changes
01 05/11/2020 First document release
02 13/11/2020
  • Chapter 12 added
  • Added “Gosign – AzureActiveDirectory” attachment
03 24/11/2020
  • Chapter 11 update with more information
  • Deleted “Gosign – AzureActiveDirectory” attachment
04 17/12/2020
  • Added the point “the workNotificationServices and getExternalStatus services are exposed on the same host” at the end of 7-8 chapters
  • Added that the fied loadedByExtId in OAuth2 autentications is optional (chap.9/12)
05 12/01/2021 Added exemple of new user with already exist e-mail address in GoSign System. (par 6.2)
06 04/02/2021
  • Added Soap insertEnvelope Schema (chap. 5)
  • Added Soap insertEnvelope request and response
  • Added Rest OAuth2 insertEnvelope Schema (chap. 9)
  • Added chapter 10 with an example of differences between the calls of the main web service
  • Added attachment about soap worknotification services
  • Insights into the signature policy with examples (par 6.5)
07 28/05/2021 Added the “signatureType” field. (par 9.2.1)
08 09/06/2021 Added detail about signatureType= Fea_otp (par 9.2/9.2.1)
09 12/10/2021
  • Removed chapter 9.2.1
  • Added chapter 9.7/9.7.1

1 - Introduction

GoSign provides various possibilities for integration with external systems. Depending on the use case and application context, one or more methods can be used depending on the convenience.

  • SOAP Web Services
  • REST Web Services
  • LegalBus whit REST Proxy
  • LegalBus whit asincrone queues

These methods have different capabilities and ways of applications; understanding its characteristics and possible use cases is essential to choosing the most correct method.

For instance, here are described different scenarios of integration:

Case 1: Generation of GoSign files and their following management and archiving in an external DMS.

In this case we want to Generate and manage an authorization processe in GoSign and then archiving of the documents produced in an external DMS.

The procedure can consist of one or more documents on which one or more signatures can be collected. The procedure is created in GoSign and at the end of the process it is sent to the DMS, which can store it and use the signed documents in a specific workflow or with other applications directly implemented in the DMS.

Case 2: Generation of an envelope in the external system and use of GoSign as authorization Front End.

In this case we have  an activation by an authorization process involving one or more actors on an external system and GoSign is used as authorization Front End for these actors.

The authorization process is managed in GoSign and once complete (or rather once it has completed its signature process) it become available to the external system.

Case 3: Mixed scenario.

It is also possible to manage mixed situations in which those who have to sign a document can use both GoSign and the external system, depending on the situation and ease of use.

In case of conflict (document already worked on the external system) various control and resolution policies can be implemented. For instance, ask to the external system for the status of the procedure before signing on GoSign, or establish that the signed document on the external system is the right one (in this case the docuement is removed from GoSign).

There are also specific Add-ins for GoSign integration with specific systems: SharePoint 2013 on Premise, Sharepoint Online O365, SalesForce and OpenText.

The cases covered by the Add-ins are described below.

Activate Authorization Process

Activation by an external system user (Sharepoint, Salesforce, OpenText) of an authorization process involving one or more actors and use of GoSign as authorization Front End for these actors. In this case the GoSign dossier is activated by the Front End of the external system with appropriate visual components. The authorization process is managed in GoSign and the complete file, once its process is completed, is made available to the requesting system.

Sign

Activation by a user of the external system (Sharepoint, Salesforce, OpenText) of the digital signature functionality to sign himself the documents he is working on. In this case, through appropriate visual components, the GoSign authorization front end for the user is activated by the GUI of the external system, who signs the documents and finds them immediately available on the calling system.

1.1 - Available methodologies

In the following table are summarized the various approaches and main characteristics that they will be examined in the next paragraphs.

Technology Used with SDK Mode Call-back method
SOAP Web Services Http SOAP No Synchronous Polling or SOAP call-back
REST Web Services Http REST Yes* Synchronous Polling or Rest call-back
LegalBus with asin-crone queues JMS Yes Synchronous
Asynchronous
Asynchronous Events
LegalBus with REST Proxy Http REST Yes Asynchronous Asynchronous Events

*OAuth2 is not integrated

Here are the authentication methods managed today for the services listed above:

  • For SOAP/REST Services, API KEY/TOKEN (Customer Code).
  • For Rest services, OAuth2 authentication
  • For Legalbus services through JMS, SSL Client Authentication.

Please refer to the specific documentation for the description of the Add-ins.

1.1.1 - SOAP Web Services

GoSign has a layer of SOAP services that allow you to perform only the basic integration operations:

  • Inserting documents
  • Querying the approval status of documents
  • Recovery of signed documents

This type of service is synchronous and blocking: the caller is waiting for GoSign to finish the requested operation. The result of the operation (OK or KO) is immediately returned to the caller.

The typical use case is:

  • The external system uploads one or more documents to GoSign with the SOAP document insertion method
  • The external system can request GoSign on-demand for the processing status of documents with the SOAP method of recovering the approval status

At the end of the document process, the external system recovers the signed documents. It’s possible to understand when a process is concluded in two ways:

  1. The external system can poll individual documents uploaded to GoSign by calling the approval status SOAP service at regular intervals. This method can be used only for few documents.
  2. For higher loads, GoSign calls the external system by sending “push” notifications of processing status when these occur (in particular the conclusion of the approval process), effectively eliminating the need for polling. In this case, the external system must implement a SOAP service that receives the processing notifications from Go-Sign. GoSign also implements a notification retry policy in the event of communication errors with the external system.

1.1.2 - REST/JSON Web Services

In addition to the basic SOAP services, GoSign provides a layer of REST / JSON services that implement more generic and extended use cases.

For example, administration services are available to manage users, search for documents with filters, etc. Apart from the different technology, the REST services have the same way of using the SOAP services. The same behaviours are also applies to “push” processing notifications.

REST services are also a synchronous communication and the availability of systems can be a critical point. GoSign’s REST services can be used directly by HTTP requests with a proper JSON body.

The JSON data model can be complex due to the multiple use cases and number od properties. For this reason can be useful the SDK or the YAML files attached.

1.1.3 - LegalBus with asynchronous queues

To make the integration more robust in case of temporary unavailability of the systems (both GoSign and the external system) it is possible to use an integration method through asynchronous decoupling queues. In this scenario there is a communication middleware, LegalBus, which manages the communication between external systems and GoSign. For LegalBus description refer to the specific product documentation.

The use of queues allows you to have a “cache” of requests to and from GoSign which are kept active even when the systems are not online (for maintenance or for any infrastructure problems).

This model is therefore characterized by the use of asynchronous communications unlike the Rest and Soap services that work synchronously.

The most common use scenario is the following:

  • The external system requires to LegalBus to insert one or more documents into GoSign
  • LegalBus immediately sends the request to GoSign and responds to the calling system with a “take in charge” message of the request not yet been processed by GoSign. The external system does not know at this time when this request will be completed; it only knows that his request has been forwarded to GoSign. The external system can immediately start to doing something else; it knows that the result of this request will be communicated to him later.
  • GoSign receives the insertion request and begins its processing. At the end (positive or negative) GoSign sends a message to LegalBus containing the result of the processing; LegalBus forwards it to the external system that originally requested the processing.
  • The external system finally receives the end of processing notification with which it can decide how to proceed based on its use case.

It is important to emphasize that in this asynchronous model it’s the external system that must “synchronize” its requests. For example, before requesting the deletion of a document previously uploaded in GoSign, the external system must be sure that the insertion operation has actually been completed. In other words, before doing any operation on a loaded document, it must first have received the asynchronous message of “insertion completed”. This is valid for all asynchronous operations available in GoSign.

Also in this asynchronous model synchronous services can be implemented. Typically they are those in which the user is interested in immediately receiving a response from the system on the basis of which to perform different operations later. Consider, for example, checking the status of a document on GoSign before signing it on an external system, which allows you to avoid working the same document twice and avoid possible conflicts. Therefore, synchronous functions are available on an asynchronous model also in the case of LegalBus with asynchronous queues.

An additional advantage of an asynchronous environment is that it simplify to exchange information when unpredictable events occur without the need for polling. Typical events are, for example, the conclusion of an approval process or the change of status of a document.

The use of LegalBus and asynchronous queues is available only through the use of the integration SDK. This is needed to hide the complexity of sending and receiving messages from the caller and to use an easy-to-understand data model.

1.1.4 - LegalBus with Proxy REST

The use of LegalBus and queues is the most flexible and robust methodology available for integrating GoSign with external systems but for its adoption the SDK must be used.

If this is not feasible, it is possible to use a “hybrid” integration mode in which LegalBus takes care of making REST calls from the external system asynchronous. GoSign’s REST application interface is then replicated on LegalBus with an implementation that allows requests to be sent to GoSign through asynchronous queues. In this case LegalBus acts like a sort of REST proxy.

The use case of inserting a document becomes the following:

  • The external system calls LegalBus with a REST call, the same call it would if it were directly connected to GoSign.
  • LegalBus translates the REST request and forwards it on the asynchronous queues; it also immediately responds to the calling system with a “take in charge” message of the request which has not yet been carried out by GoSign at this time. As with the case of asynchronous queues, the external system does not know when this request will be completed; it only knows that his request has been forwarded to GoSign. The external system can immediately start to doing something else; it knows that the result of this operation will be communicated to him at a later time.
  • GoSign receives the insertion request and begins its processing. At the end (positive or negative) GoSign sends a message to LegalBus containing the result of the processing;
  • LegalBus receives the end of processing message and translates it into a SOAP call to a “Operation completed” service that the external system implements. This call replaces the asynchronous message sent in the LegalBus approach with asynchronous queues.
  • The external system that received the SOAP call “Operation completed” can decide how to proceed based on its use case.

Even with this hybrid approach it is important to underline that in this asynchronous model it is the external system that must “synchronize” its requests. For example, before requesting the deletion of a document previously uploaded to GoSign, the external system must be sure that the insertion operation has been completed. Before performing any operation on a loaded document, it must have received the asynchronous message of “insertion completed”. This is valid for all asynchronous operations available in GoSign.

LegalBus also takes care of carrying out the same “push” processing notifications of the SOAP Services approach (which are in SOAP standard).

The use of LegalBus in this hybrid mode is available by HTTP requests with a proper JSON body.

Not all features are available with this integration method.

2 - Data Model

The most important entity for GoSign is the “envelope”. This entity is used to describe a set of documents (one or more) that follow the same working process. Each document in an envelope can contain multiple signatures of one or several users. In GoSign no documents can exist without an envelope; in the case of processes that work on a single document, it is necessary to create an envelope with a single document.

An Envelope has the following main properties:

Field Description
externalId Id of the envelope as defined in the external system. It must be unique
in GoSign and is case sensitive.
Subject Object of the envelope (free text)
Starred True if the envelope is urgent
sysGenerator Code of the external system that loaded the envelope. It is provided
dur-ing the configuration phase.
trustLevelCode Trust level code to be used for the envelope
sendingMode Sending method to users:
IMD: immediate when the package is loaded
DRF: loading of the envelope with “draft” status
corporateUseType Type of use in the company.
P: public
C: corporate
A: reserved
X: restricted

The trustLevelCode can be chosen from the following values:

Value Description
INTERNAL_PDF The recipients make simple electronic signatures without legal validity
FEA A single “closing” digital signature made directly by GoSign
DIGITAL_PDF Recipients make eIDAS signatures with PaDES signatures or signatures through . p12 files.
DIGITAL_P7M Recipients sign eIDAS with CaDES signatures
GRAPHO_FEA Recipients can sign using a graphics tablet or the mobile app Gosign Graph

An Envelope has relationships with other entities:

Document

It’s the document’s model and contains properties like title, mime-type, original file name, file bytes. An Envelope must have at least one Document.

DocumentClass

They allow you to configure the metadata structure that can be associated with an envelope.

With these two entities it is possible to express the two basic concepts of cataloging the documents of a DMS. It is possible to define a document category (for example “ORDER”) and associate the metadata that describes this type of object (for example “DATE”, “AMOUNT”, “SUPPLIER”, etc.).

The DocumentClass has a name and a series of DocumentFields, each of which has a name, type (text, date, number), value (based on type), format etc.

An Envelope can have only one DocumentClass, which is optional. Generic Envelopes may exist and could be not associated with any DocumentClass.

Message

Each envelope is connected to different email messages. In particular, there is a message common to all users of the envelope. It is also possible to manage specific messages for individual users.

“Message” is therefore a message that is sent to a recipient via email. It has the typical attributes of an email (an object, a text, the user to send it to, etc.). An Envelope is associated with a common Message to all users and it is possible to configure a list of specific Messages for individual user.

ProcessDef

GoSign allows you to configure articulated signature processes (in series, in parallel and a mix of these two basic types).

The ProcessDef entity is the definition of the process that the package will have to follow passing between the various users. It has a code, a revision and at least one ProcessTaskDef. An Envelope has a ProcessDef.

ProcessTaskDef

It is the single process step of an envelope. Based on the value of its properties (in particular “order” and “actorExpression”) it is possible to express series, parallel or mixed processes. It has a series of DocumentActionDef which qualify what the actors of this task must do on documents.

DocumentActionDef

It is the single action that a user must perform on a document. Based on the “type” field it can be signature, approval, check, etc. It also has a visual representation identified by a DocumentActionAppearance.

DocumentActionAppearance

Describes how the processing tag is placed on the PDF (be it a signature, approval or other). It can be an absolute coordinate, based on the cardinal points or other algorithm.

Process

They are the runtime information of a ProcessDef: start date, end date, status, a series of ProcessStep, etc..

ProcessStep

Like the Process, it is the runtime information of a ProcessTaskDef: start date, end date, status, etc..

ProcessStepEvent

It is a summary information on a past event, present event or event that could happen in the future of a Process / ProcessDef. It is used to describe the past, present and future of the processing of an envelope. For this reason it includes data about the ProcessTaskDef, ProcessStep, and process users.

DocumentAction

They are the runtime information of a DocumentActionDef, typically its working status (new, confirmed or worked).

EnvelopeDetails

Indicates whether an Envelope is visible to a user and how. It is an important entity because it models the processing status of an Envelope for a specific User.

User

He is a GoSign user: username, password, authorizations, email, phone, etc..

3 - SDK GoSign --DEPRECATED--

The GoSign integration SDK is a set of APIs that allow a full integration with external applications. The APIs are available in Java and in .NET / C # and allow developers to integrate GoSign by working only at the process level. The GoSign integration via SDK allows the external system to use an API key-based authentication. Is not possible to use the SDK to perform an Oauth2 integration.

This section describes the Java version of the SDK. The .NET version is very similar: basic concepts, application interfaces and communication mechanisms are almost identical but it only manages the queue mode, and not the RESTful one.

The typical integration scenario involves one or more Customer systems (completely “external” to GoSign) that can, through the integration API, perform the typical operations of GoSign users (create and send a package to one or more managers, check the status of the packages sent, create new users, etc.).

In this scenario, the authorization processes are always triggered by the external system, which calls and activates GoSign for specific operations. To manage this type of use case, the GoSign integration SDK provides a set of methods to allow the external system to use GoSign functions exactly as if it is a manager, a secretariat or a service administrator.

There is also a second type of use cases triggered by actions on GoSign and which by their nature are events, for example the signature of a document or the end of the processing of an envelope. In these cases, it is GoSign that reports the occurrence of events on communication channels in which the external system is “listening”. In this way, the external system can react to these events. The SDK provides a listening interface and a series of call-back methods that allow external applications to listen to these events and to execute custom management code (§ 3.4.1).

Finally, other integration cases involve the execution of operations that “start” from GoSign and the external system is the target. A tipical example is the insertion of the processed documents and the verification of the status of a document on the external system. For these cases, the SDK includes an application interface that the external system must implement to answer these types of calls (§ 3.4.2).

3.1 - Prerequisites

The JDK is compiled with Java SE 1.6 and is compatible with later versions of the JDK.

3.2 - SDK composition

The SDK consists of a series of interfaces and model classes that allow you to use GoSign at an adequate level of abstraction.

The basic package is eu.ecomind.sdk which contains the main interface of the eu.ecomind.sdk SDign.SignatureBook plus a series of support classes

The eu.ecomind.sdk.listener package contains interface and classes for listening to events and defining the related call-backs

The eu.ecomind.sdk.extworker package contains interface and classes for the functionality required of the external system

The other packages contain classes and implementations supporting previous packages.

The documentation of all the classes and interfaces in the SDK is available to the developer in JavaDoc format. The documentation is completed by a series of JUnit 4.x tests of the main use cases. These tests can be taken as an example of the possible uses of the SDK.

3.3 - Direct implementation and messaging

In the SDK, two implementations of the eu.ecomind.sdk.SignatureBook interface are available.

The first one, eu.ecomind.sdk.impl.SignatureBookDirectImpl, represents a tool to directly re-quest the execution of the operations available by invoking RESTful services . The request / re-sponse mechanism is direct since there are no intermediate applications or middleware layers that mediate the communication between GoSign and the external system.

The .NET SDK does not provide for this implementation but only the eu.ecomind.sdk.impl.SignatureBookMessageImpl

The second one, eu.ecomind.sdk.impl.SignatureBookMessageImpl, represents an implementation based on message communication. Communication between GoSign and the external system takes place through the exchange of JMS messages; in particular, there is a queue for each communication lines, for which a generic request is created by the external system (SDK performs its encapsulation in a completely transparent way to the external system) in a JMS message which is forwarded on the request queue. After performing the necessary operations, GoSign appends the results of processing on the response queue. In this technological scenario it is also possible to take advantage of an additional JMS destination (queue or topic) for the management of the events that occur in GoSign and to support asynchronous communication mechanisms (§ 3.4.2).

3.4 - Basic Concept

The main access point of the SDK is the eu.ecomind.sdk.SignatureBook interface. These interface methods can be divided into various sections according to their use:

  • Secretarial methods
  • Manager methods
  • Administration methods

Among the secretarial methods there are those for managing the package (insertion, modification, etc.), among those for the manager there are the processing methods for the package, while those for administration are the methods for adding / changing users, roles , etc.

All methods have in common the customerCode parameter, which is of fundamental importance for GoSign.

The customerCode parameter has the shared-secret role with which you can access Go-Sign services from the SDK.

This code is provided during the installation of GoSign and is to be considered as a KEY API to be kept confidential.

The SDK, like all other integration methods, uses the data model described in paragraph 2. To sim-plify the use of SignaureBook methods, specific Envelope classes are used in the SDK according to the use case.

For example, in the method of inserting a new envelope (insertEnvelope), the entity used is called InsertEnvelope and contains sufficient fields for insertion, while in the recovery of a package the entity used in response to the findEnvelope is called FindEnvelope. The latter class has the cre-atedAt field which indicates the date of creation of the envelope which by its nature is enhanced by the GoSign server and therefore is not present in the InsertEnvelope class.
The same approach was also followed for the other SDK entities

In case of errors or malfunctions, all methods raise an exception of type eu.ecomind.signbook.sdk.SignatureBookException of Runtime type (i.e. not checked). In the returnStatus field of the exception, the detail of what happened as code and text description is indicated. Examples of error codes are as follows

Code Description
ACCESS_DENIED Access denied to the resource or operation
ILLEGAL_ARGUMENT Invalid or missing parameter
USER_NOT_FOUND User not found
ENVELOPE_NOT_FOUND Envelope not found
BAD_DOC_FORMAT Bad document format

For the complete list, consult the documentation (javadoc) of the class eu.ecomind.signbook.sdk.Constants

3.4.1 - EnvelopeEventListener Interface

The interface eu.ecomind.singbook.sdk.EnvelopeEventListener allows the external system to listen to the envelope events launched by GoSign. It is a typical event handler interface and in fact it extends java.util.EventListener. The EnvelopeEvent and subclasses classes instead extend java.util.EventObject.

The methods of this interface are used to implement the management call-backs for the package events. Those provided are the following:

void envelopeSent(EnvelopeEvent e);

Call-back call when for any reason a envelope is sent to users, for example when an answering machine presses the “Enter” key on a package that has finished composing. In the EnvelopeEvent event the id of the envelope being sent is indicated.

void envelopeStepClosed(EnvelopeStepClosedEvent e);

Call-back called when a process step is closed, for example when all the users of a step have processed the envelope. The EnvelopeStepClosedEvent event indicates the id of the envelope subject to the closure of the step. This event is useful if you want to keep track of the progress of a envelope process.

void envelopeStatusChanged(EnvelopeStatusChangedEvent e);

Call-back called when for any reason an envelope changes state, for example from “In progress” to “Worked”. The EnvelopeStatusChangedEvent event shows the id of the envelope being sent, the previous and the current status. This event is useful for example when you need to take special actions at the end of the processing of a package. Call-back call when for any reason an envelope changes state, for example from “In progress” to “Worked”. In the EnvelopeStatusChangedEvent event, the id of the envelope being sent, the previous and current status is indicated. This event is useful for example when particular actions need to be taken at the end of the processing of an envelope

void operationDoneReceived(OperationDoneEvent e);

Call-back called when an asynchronous operation request, forwarded by the external system, is processed by GoSign. The OperationDoneEvent event indicates the id of the envelope object of the request, the id and the type of the operation performed. This event is useful for the external system to be able to evaluate the processing status of an asynchronous request: for example, it may consider a request to have expired if the event has not been received within a certain time

A test implementation could be the following:

public class EmptyEnvelopeEventListener implements EnvelopeEventListener {
@Override
public void envelopeSent(EnvelopeEvent e) {
System.out.println("Envelope sent:" + e.getEnveExtId());
}
@Override
public void envelopeStepClosed(EnvelopeStepClosedEvent e) {
System.out.println("Envelope step closed:" + e.getEnveExtId());
}
@Override
public void envelopeStatusChanged(EnvelopeStatusChangedEvent e) {
System.out.println("Envelope status changed. Enve:" + e.getEnveExtId() +
" old:" + e.getOldStatus() + " current:" + e.getNewStatus());
}
@Override
public void operationDoneReceived(OperationDoneEvent e) {
System.out.println("Operation done received:" + e);
}
}

Which is set up in the SDK like this:

SignatureBook signatureBook = […];
EnvelopeEventListener listener = new EmptyEnvelopeEventListener();
signatureBook.addEnvelopeEventListener(listener);

3.4.2 - ExternalWorker Interface

The interface eu.ecomind.singbook.sdk.ExternalWorker describes the operations the external system must provide in response to GoSign requests. In other words, they are the minimum requirements that the external system must satisfy in order to be integrated with GoSign.

Not all methods must be implemented by the external system but those not put in action can inhibit some use cases and / or GoSign features.

The method:

String getRuntimeStatus();

is used to know the functioning status of the integration interface. The returned string is coded in the eu.ecomind.signbook.sdk.Constants class

The method:

String getEnvelopeStatus(GetEnvelopeListStatusParam param);

returns the processing status of the package (coded in eu.ecomind.signbook.sdk.Constants) to the external system. In the argument parameter are stored the envelope identifier and the identifier of user that is in charge. This method is useful if  an envelope can be processed simultaneously by both GoSign and the external system.

The method:

Map<String, String> getEnvelopeListStatus(List<GetEnvelopeListStatusParam> param);

Similar to the previous one, but it requires the processing status of a list of envelopes. The returned object is a map in which the key identifies the document and the value the processing status (coded in eu.ecomind.signbook.sdk.Constants). During the processing of an envelope GoSign queries the external system with this method: if the answer is “already worked” GoSign discards the envelope and / or warns the user.

The method:

String insertEnvelope(InsertEnvelope envelope);

is used to insert a new envelope into the external system. The returned value is the id on the external system of the envelope just stored..

The method:

void updateEnvelope(UpdateEnvelope envelope);

update the envelope on the external system.

The method:

List<UserWorklist> findUserWorklist(String userId);

returns the list of envelopes being processed for the user indicated in the external system; it is useful to fix any misalignments that may occur between GoSign and the external system.

The method:

List<InsertEnvelope> newEnvelopes(List<String> extIds);

returns the information of the envelopes, indicated in the input parameter, present on the external system. It is used during the envelope alignment algorithm between GoSign and the external system.

To set up a specific implementation of this interface in the SDK, you have to:

SignatureBook signatureBook = […];
ExternalWorker acmeWorker = new ACMEExternalWorker();
signatureBook.setExternalWorker(acmeWorker);

3.5 - Main use cases

Some usage scenarios are described below, with reference to the test cases defined in the eu.ecomind.signbook.sdk.test.SignatureBookTests class.

The main operations made available by the interface are shown in two scenarios.

  1. The first one, synchronous, expects that the external system requests the execution of a particular operation from GoSign and remains awaiting a response.
  2. The second one, based on an asynchronous communication, expects that the external system sends a request to GoSign, this responds immediately by communicating the operation’s code identification; the processing, which can take place in another moment, ends with the creation of an OperationDoneEvent event with which GoSign communicates the outcome of the operation to the external system.

In the following subsections are described, for each case, the actions to be taken to properly use the methods exposed in the SDK  and the results presented as output.

3.5.1 Inserting an envelope

The eu.ecomind.signbook.sdk.SignatureBook#insertEnvelope method allows you to insert a new envelope. The minimum set of preliminary operations needed to the method excetution are used to create the hierarchy of objects related to the envelope and can be enumerated as follows:

 

  1. Association one or more documents to the envelope: the PDF documents to be included in the envelope are read directly from the classpath of the application and each PDF file must be associated with an identifier that will allow it to be uniquely identified.
  2. Creation of the envelope’s information: definition of the generic data of the envelope such as the identifier of the envelope, the identifier of the user requesting insertion, object of the envelope, management method (envelope in draft after loading, immediate dispatch, etc.)
  3. Definition of document classes: the association of document classes to the envelope is optional and, if the user decides to specify the information, it is necessary to define the exhaustive list of fields relating to the individual document class.
  4. Setting the common message, that is, the body of the email that the recipient user will receive.
  5. Definition of the signature process associated with the envelope: this series of operations defines the structure of the signature process and, in particular, it defines the task specifying the involved actors, the cardinality of minimum signatures and the order in which the signatures must be affixed; then, the actions related to the task and the details that characterize each of these are defined, such as the type (Signature, Approval, Visa or Initials), the document with which the action is associated and the type of positioning of the signature frames.

 

The choice of the type of positioning of the signature frames can be described in three different specific use cases related to the generic envelope insertion operation:

 

  1. Positioning by cardinal points (eecomind.signbook.test.sdk.SignatureBookTests #insertEnvelopeWithCompassPositioning method): the single signature tag is positioned in one of the 9 imaginary quadrants into which the document page is divided. The positioning zones are defined in eu.ecomind.signbook.sdk.model.docaction.CompassAppearance. It is also necessary to indicate the progressive number of the page on which to place the signature tag.
  2. Positioning by coordinates (ecomind.signbook.test.sdk.SignatureBookTests# insertEnvelopeWithCoordPositioning method): the signature tag is positioned in a rectangle whose method caller must specify the Cartesian coordinates of the lower corner left and bottom right corner. Note that the reference system for indicating the coordinates originates in the lower left corner of the sheet.
  3. Positioning via tag pattern (eu.ecomind.signbook.test.sdk.SignatureBookTests# insertEnvelopeWithTagPositioning method): a string (tag) , builded following some rules described below, is defined within the text of the PDF document and the signature tags are positioned in correspondence with the identified tag.

The pattern can be represented by a fixed string (e.g. “sign here”, “f_manager1”, “f1_mgr”, etc.) isolated in the text and then separated by spaces. It is possible to indicate in the pattern which detail related to the actor involved in the action must be used to build the string according to the following convention:

%3 : email
%4 : id

For example, given the user Andrea to whom the following details refer [id = 119, email =  andrea@email.it]

indicating a tagPattern “% 3” the string that will be searched in the text is “andrea@email.it”; similarly, if the tagPattern is “% 4” the string that will be searched in the text is “119”.

It is possible to use both notations in a combined way: indicating the tagPattern “firma% 4” the signature tag will be positioned in correspondence with the text “firma34PL”.

In the same pattern, the details of multiple actors can be indicated, in line with the acto-rExpression present in the task definition: the tagPattern “% 3% 4” indicates that the concatenation of the email address of the first actor with the id of the second actor. Also in this case it is possible to manage combined cases (eg “signature% 3_firma_here% 3”).

 

Each customer has the ability to configure a list of custom separators (set of characters) for identifying the tag. Specifically, it can decide whether to use the default configuration (the algorithm identifies the tag consisting of a text and a space in line) or redefine the identification of the tag by specifying a list of separators.

Given, therefore, a list of custom separators, the tag within the PDF document must comply with the following rule: each tag is a unique string consisting of a text with the same separator before and after it.

The configuration of the separators allowed for customer is carried out by the GoSign administrator. Once a separator has been configured, it is mandatory to use it in the tags, the space is no longer valid.

 

Example of use

List of custom separators: “@@”, “##”
Valid tag: “@@testo@@”, “##testo##”
Not valid tag: “@@testo##”, “##testo@@”, “##testo”, “testo##”, “@@testo”, “testo@@”

 

The use of custom separators is not compatible with the% placeholders described above. Space is also not allowed in custom separators.

For other positioning details see paragraph 6.

 

It is possible to define more complex envelopes by associating more documents or more verbose signature processes involving multiple actors with different signature actions. For this purpose, private methods have been implemented in the eu.ecomind.signbook.test.sdk.SignatureBookTests class that allow to compose sequences of multiple atomic operations in order to define properly the eu.ecomind.signbook.sdk.insertenvelope.InsertEnvelope as input of the eu.ecomind.signbook.sdk.SignatureBook#insertEnvelope method

 

Positive use case

The method does not return any parameters and, if the execution ends without errors, the insertion is to be considered successfully completed.

 

Negative use case

If an exception of the eu.ecomind.signbook.sdk.SignatureBookException type will be raised,it means that the insertion was cancelled due to an application error.

3.5.2 Inserting an envelope(asynchronous)

The method eu.ecomind.signbook.sdk.SignatureBook#insertEnvelopeAsynch allows to insert a new envelope, but unlike what is described above (§ 3.4.2.1), the communication mechanism is asynchronous. Therefore, the logic of the insertion algorithm is the same, but the way in which GoSign communicates the insertion outcome to the external system changes.

Positive use case

The method immediately returns the operation identifier. Subsequently, GoSign forwards to the external system a OperationDoneEvent to communicate the successful outcome of the insertion.

Negative use case

If an application error occurred upon insertion (for instance, existing envelope), the OperationDoneEvent event stores details of the failed operation.

3.5.3 Searching for an existing envelope

The method eu.ecomind.signbook.sdk.SignatureBook#findEnvelope allows searching for existing envelopes. Input parameters for the envelope search are the unique identifier, the customer code associated with the client, and a boolean withDocBytes, which indicates whether the byte content of the documents associated with the envelope must be returned; if set to false, the answer will be lightweight, but the response will only shows information related to the envelope and not the content; if set to false, the method response will be complete, including the content of all documents.

Positive use case

The response object of the method is a eu.ecomind.signbook.sdk.findenve.FindEnvelope type and stores the entire envelope with definition of all its details, and the hierarchy of objects related thereto. The input parameter withDocBytes indicates whether the document byte content must be sent.
If no stored envelope matches the input search parameters, the method returns null.

 Negative use case

If an application error occurs or the input parameters are not well defined, an eu.ecomind.signbook.sdk.SignatureBookException exception is raised.

4 - REST services

REST services provide features similar to those that can be used through the SDK. As said before, however, asynchronous methods cannot be implemented with this approach, but only with the SDK.

On the other hands, the OAuth2 can be used only with this approach

JSON RequestBody parameters are case sensitive as well as the value of the externalId field, present in the main entities.

The data model used by REST services is identical to that one used by the SDK, and described in paragraph 2. The JSON shared between clients and GoSign servers is a direct consequence of the data model, regards both the structure and the property names.

In the following sections you can find the REST services exposed by GoSign. This list is provided for direct use of the services.

4.1 - Main services

InsertEnvelope: insert an envelope by indicating the id (as URL parameter) and the full structure (InsertEnvelopeRequest) in the request body. Returns the operation outcome.

the default address is https://webapp.gosign.digital/gosign/services/v1/envelopes/:extId

PUT /services/v1/envelopes/{extId} HTTP/1.1

Object Format InsertEnvelopeRequest to be included in the request body:

Field : Exemple Field Type Mandatory field Description
{
“customerCode”: “***secret***”, String Mandatory Customer Code (API Key)
“externalSystemCode”: “DDC”, String Mandatory DMS Code.
“addUsersInCC”: [], Array Optional CC users, more information below .
“envelope”: {
“subject”: “envelopesubject”, String Mandatory Object of the envelope (can be manipulated later by GoSign in a variety of contexts)
“starred”: false, Boolean Optional Flag “Urgent”, optionally available externally and with a default value of ‘false’
“externalId”: “myenve05”, String Mandatory The external id of the envelope, to be specified by the external system
“sendingMode”: “DRF”, String Optional Type of envelope submission Possible “IMD” values ​​(immediate: the envelope is loaded in “In Progress” state with the signature process already started), “DRF” (draft: the envelope is loaded in Draft state with the signature process not yet started ).
“loadedByExtId”: “userExtId”, String Mandatory External ID of the user loading the envelope
“tag”: “string”, String Optional Can be set up from outside, open value
“expireAt”: 245124521451, Date Optional Expiration date of the envelope, expressed in milliseconds from midnight of January 1, 1970
“note”: “note”, String Optional Notes on the envelope, open field
“corporateUseType”: “P”, String Optional The scope of use of the envelope according to level of confidentiality. Possible values ​​”P” (public), “C” (company).
“expirationFirstReminder”: 6, Integer Optional Number of days after the envelope expiration date for receiving the first notification
“expirationFollowingReminder”: 3, Integer Optional Number of days after the first notification for the receipt of subsequent notifications
trustLevelCode“: null, String Mandatory Envelope trust level code, chosen from “DIGITAL_PDF”, “DIGITAL_P7M”, “INTERNAL_PDF”, “FEA”, “GRAPHO_FEA”; In the event of an incompatible trust level, GoSign will refuse to insert the envelope. In case of trust level = FEA, it is not possible to upload a document already signed
“sysGenerator”: “EXT” String Optional The system that generated the envelope.
“documents”:[{}] Array Mandatory List of documents to be uploaded (at least 1)
“commonMessage”:{ Message to be sent to all users
“subject”:”title”, String Mandatory Message title
“text”:”message text” String Mandatory Message text
},
“docClass”:{ Optional Document class to be assigned to the document
“id”: “01”, String Mandatory docClass Id
“name”: “DC01” String Mandatory Field name
“fields”: [{ Array Validation of the fields for the doc class; at least one of the *value fields must be entered
“name”:”fieldname”, Striga Mandatory Name of the field
“dateValue”:21451245212212, Date Optional Date field value (expressed as the number of milliseconds elapsed from 00:00 January 1, 1970)
“numericValue”:0, Double Optional Value of the numeric field
“textValue”:”string” String Optional String field value
}]
},
“procDef”:{ Definition of the process
“code” : “TPL001”, String Optional Policy code
“revision” : “2”, String Optional Revision, -1 for the last version
“tasks”:[{}] Array List of tasks that make up the process (see task-Def in the following table).
“newUsers”:[{}] Array Optional New User definition
}}}

The tasks object, in turn, is composed of:

Field : Exemple Field Type Mandatory field Description
“task”:[{
“type”: “T”, String Mandatory Type of the taskdef, possible values: “T” Type of task performed by users internal to GoSign (HTASK = Human TASK), “A” type of automatic task (logging or sending mail).
“order”: 1, Integer Mandatory Task order, used to indicate serious and parallel processes through the WS.
“actorExpr”: “id1R|id2U”, String Mandatory List of managers / roles involved, according to the following scheme: xR: role with id = x – yU: manager with id = y – | (pipe) OR logical – Example: id1R | id2U.
“action”: “WRK”, String Mandatory Process action, possible values: “WRK” – Processing of documents, “SDM” – Sending mail, v. next line.
“howMany”: 1, Integer Mandatory Allowed values: 1, 2, 3, 4. Represents how many actors must perform the action to consider the task completed.
“actionDefs”: [{}], Actions that make up this taskDef (see actionDef in the following table).
“confString”: “”, String Optional Configuration JSON string; the signAllVisible key defines the visibility of the “Sign all” button and can be set to “V” – button visible or “N” – button not visible.
“certType”: “I” String Mandatory Contains the type (s) of a user’s signature certificates.

Possible values:

“R” – remote certificate

“I” – internal certificate

“T” – sign with token

“sendMailMessage”: null

 

Email message enhanced in the case of tasks such as sending mail, ie with type = “A” and action = “SDM”; not valued for the processing of documents. For further details see the next line and paragraph 6.3
}]

The documents object, in turn, is composed of:

“documents”:[{
“bytes”:”docbytes”, String Mandatory Document bytes encoded in Base64. It is not possible to upload a document that already has a signature with field trust level = FEA.
“externalId”:”extId”,

 

String Mandatory To be completed by the external system to allow identification of the document regardless of the internal mechanisms of GoSign.
“mimeType”:”string”, String Mandatory Type of document, to be completed by the external system. In addition, GoSign will be able to change the value following format conversions or for certain trust levels.
“title”:”doctitle”, String Mandatory Title of the document, to be completed by the external system.
“originalFname”:”f.pdf”, String Mandatory Name of the original file including extension.
“ooxmlSignStrategy”: null, String Optional to be enhanced only in the case of an Office Open XML document; indicates that the signature must be applied to the document in PAdES format, value “OXP”, or XAdES, value “OXX”. If not specified, the Office document is converted to PDF and signed PAdES.
“uri”: file://nome_file.pdf Path Optional Indicates the URI from which to load the document, when the payload is not defined, or the bytes field, in the request.
“privateDoc”: true Boolean Optional Indicates whether the document is private or not
}],

The item sendMailMessage, in turn, is composed as follows:

“sendMailMessage”:{
“subject”: “Send mail task subject”, String Optional Mail subject.
“bodyMail”: “Body mail”, String Optional Body mail.
“sendMailRecipientList”: { List of direct or CC users
“userExternalId”:”jd”, String Optional Recipient’s external id.
“email”:”john.doe@test.com”, String Optional Recipient email
“typeRecipient”:”TO”, String Mandatory Recipient type – “TO” or “CC” –
}}

The item  actionDef, in turn, is composed as follows

“actionDefs”: [{
“docExternalId”: “ext42”, String Mandatory External id of the document on which this action is placed.
“type”: “S”, String Mandatory Type of action required on the document, possible values:

“S” – signature only, default value

“A” – approval only

“V” – only “seen”

“I” – initials

“G” – graphometric signature

“R” – private doc visibility action

“mandatory”: true, Boolean Mandatory True if this action is mandatory. The only admissible value is true in all cases, except in the case of graphometric action.
“confString”: “{}”, String Optional Action configuration key / value map in JSON; more details below.
“appearance”: { Action positioning algorithm
“blankSignatureFieldName”:        “sign_here”, String Optional Name of the empty signature field in which to sign.
“compassAppearance”: { Only in the case of signature for “compass” dials
“page”: 1, Integer Mandatory Number of the page where to sign, starting from 1, or one of the following special values:

  • -1 (last page)
  • -2 (all pages)
  • -3 (first and last page)
“position”: 0 Integer Optional Position in which to sign, chosen from:

-1 (invisible)

1 (top, left – Top-Left or North-West)

2 (top, center – Top or North)

3 (top, right – Top-Right or North-East)

4 (vertical center, left – Central-Left or West)

5 (vertical and horizontal center – center)

6 (vertical center, right – Central-Right or East)

7 (bottom left – Bottom-Left or South-West)

8 (bottom, center – Bottom or South)

9 (bottom, right – Bottom-Right or South-East)

},
“coordAppearance”: { Only in the case of signature by coordinates
“llx”: 0, Integer Mandatory Horizontal coordinate of the point at the bottom left where to place the signature tag.
“lly”: 0, Integer Mandatory Vertical coordinate of the point at the bottom left where to place the signature tag.
“page”: 1, Integer Mandatory Number of the page on which to sign, starting from 1, or one of the following special values:

  • -1 (last page)
  • -2 (all pages)
  • -3 (first and last page)
“urx”: 0, Integer Mandatory Horizontal coordinate of the point at the top right where to place the signature tag.
“ury”: 0 Integer Mandatory Vertical coordinate of the point at the top right where to place the signature tag.
},
{
“tagAppearance”: { Only in the case of positioning by tag
“cornerType”: “”, String Optional Type of positioning identified:

  • “SBL”: Positioning is done by identifying the lower left corner of the text. (Default)
  • “BLR”: The positioning is done by identifying the rectangle defined by the lower left corner of the text of the first tag and by the upper right corner of the text of the second tag. The signature tag will be placed in the center of the rectangle.
  • “TLR”: Positioning is done by identifying the rectangle defined by the upper left corner of the text of the first tag and by the lower right corner of the text of the second tag. The signature tag will be placed in the center of the rectangle.
“endTagPattern”: “end$$1”, String Optional String to be searched in the document to identify the other end of the rectangle in which to place the tag
“startTagPattern”: “start$$1”, String Mandatory String to be searched in the document to identify the initial end of the rectangle in which to place the tag
“xoffset”: 0, Integer Optional Defines a horizontal offset in points on the PDF with respect to the X coordinate of the identified tag.

Examples of use:

  • a null xOffset or equal to 0, does not alter the positioning of the action
  • an xOffset of 50, translates the positioning of the action by 50 points to the right
  • an xOffset equal to -100, translates the positioning of the action by 100 points to the left
“yoffset”: 0 Integer Optional Defines a vertical offset in points on the PDF with respect to the Y coordinate of the identified tag.

Examples of use:

  • a null yOffset or equal to 0, does not alter the position of the action
  • a yOffset of 50 translates the position of the action upwards by 50 points
  • a yOffset equal to -100, translates the positioning of the action downwards by 100 points
},
“tagPattern”: “marker$$1” String Optional DEPRECATED – Optional string to be found in the document to derive the position in which to sign. This parameter is deprecated in favor of only the startTagPattern in tagAppearance, obtaining the same effect. The two parameters are mutually exclusive.
}]

The newUsers object, in turn, is composed of:

“newUsers”:[{
“username”:”lrossi@mail.it”, String Mandatory Username to access the application
“name”:”Luigi”, String Mandatory Name of the user
“surname”:”Rossi”, String Mandatory User surname
“phoneNumber”:”+390123456789″, String Optional Telephone number
“email”:” lrossi@mail.it “, String Mandatory Email address
“externalId”:”lrossi@mail.it”, String Mandatory External ID of the user
“newUserStrategy”:”ACCEPT_ALWAYS”, String Mandatory Possible values:

ACCEPT_ALWAYS

REJECT_IF_DIFFERENT

REJECT_ALWAYS

EMAIL_BASED

Refer to chapter 6.2 for definitions.

“userAuthorities”:[{}] Array Mandatory
}]

The item userAuthorities, in turn, is composed as follows:

“userAuthorities”:[{      
“username”:”lrossi@mail.it”, String Mandatory Username of the user created
“authority”:”ROLE_STRANGER” String Mandatory Possible roles to be assigned to the user:

ROLE_STRANGER – Stranger

ROLE_ADMIN – Administrator

ROLE_SEGR_ADMIN – Secretariat / Administrator

ROLE_SEGR – Secretariat

ROLE_MGR – Manager

}]      

Description of the confString field in the actionDef object

This field is used to configure the action to which it refers to. It is a JSON map in which the following keys can be used:

  • actionInTCF: if true the action is inserted already approved awaiting confirmation. Pay attention to use this feature because it does not force the user to view the document and therefore it not follow the regulations on digital signature. The client will take responsibility for this decision.
  • visibilityStatus: visibility of the action on the document
    • V = Valid for Signatures, Visas and Approvals: action visible on the PDF
    • H = Only valid for Signatures: the digital signature is applied to the PDF, but it lacks its visible part
    • N = Only valid for Visas and Approvals: the visa / approval is a flag on the DB without consequences for the PDF (the PDF is not changed)
    • Initials are never invisible and it is not possible to change their visibility.
  • customSignatureText: first line of text present in the signature tag.The placeholder # nnss # is replaced with the” Surname Name “of the user who is performing the action.
  • customSignatureTextL1 and customSignatureTextL2: configure the other two lines of text in the signature tag. They can have the following values:
    • TTL Title field in the profile of the user who is working the action
    • ORG Organization field in the profile of the user who is working the action
    • CMP Company field in the profile of the user who is working the action
    • TOC Title or Organization or Company – The first of the three fields found filled in the personal data of the user who is working the action
    • OPD Date on which the user is performing the action.
    • NAN No value, empty line

Similarly to what happens by setting the information via the web during the compilation of a envelope by a secretariat, the keys CustomSignatureTextL1 and customSignatu-reTextL2 can be used limited to the possibilities admitted by the TrustLevel associated with the dossier:

  • With DIGITAL_PDF those can be used only for actions of type Visa and Approvals
  • With INTERNAL_PDF or FEA those can be used for actions such as Signature, Visa and Approach
  • With DIGITAL_P7M you can not use those

Different values or used for invalid TrustLevel values will not be taken into account during the confirmation of the actions. For more information on the type of signature, consult the GoSign user manuals.
The texts of customSignature will always be aligned at the bottom and any empty lines will be eliminated; i.e. no white space will ever be left. For example, the following confStrings will produce similar results if the user didn’t provide information in  the organization and business fields in his profile:

{
"customSignatureText":"#nnss#",
"customSignatureTextL2":"ORG",
"visibilityStatus":"V"
}

{
"customSignatureText":"#nnss#",
"customSignatureTextL1":"CMP",
"visibilityStatus":"V"
}

If the confString field is not evaluated, default values are used for displaying the text in the signature tag. Also the actions are always visible on the document.

As an example, given a user with name and surname “Mario Rossi”, field Title in his profile valued as “Engineer”, TrustLevel INTERNAL_PDF  and the following confString:

{
"customSignatureText":"Signed by #nnss#",
"customSignatureTextL1":"TOC",
"customSignatureTextL2":"OPD",
"visibilityStatus":"V"
}

The result is a Visa action with three lines of text similar to the following:

Signed by Mario Rossi
Engineer
10/09/2010 11:09:23 CET

InsertEnvelope2: Insert an envelope by indicating the id (as parameter in the URL) and the full structure (InsertEnvelopeRequest) in the request body. Unlike InsertEnvelope, this method returns the entire envelope just inserted.

The default address is https://webapp.gosign.digital/gosign/services/v1/envelopes2/:extId

PUT /services/v1/envelopes2/{extId} HTTP/1.1

GetEnvelope: Retrieves an envelope indicating its id (as parameter in the URL) and search parameters (FindEnvelopeRequest) in the request body. Returns the required envelope if retrieved.

The default address is https://webapp.gosign.digital/gosign/services/v1/envelopes/:extId

POST /services/v1/envelopes/{extId} HTTP/1.1

The body has the following format:

{
“customerCode” : “***secret***”, String Mandatory Customer code whereby you intend to search for an envelope
“externalSystemCode” : “ZZZ”, String Mandatory Codice del DMS.
“enveExtId” : “EXTID_00XAB”, String Mandatory External code of the envelope for which you want to search
“withDocBytes” : true Boolean Mandatory True if the returned JSON must also include the contents of the documents
}

The answer will contain an object envelope with the following structure:

{
externalId: “EXTID_00XAB”, String External ID of the envelope (specified by the external system during insertion)
code: “1WFAJ7DE9”, String Unique code of the envelope (generated automatically by GoSign during insertion)
subject: “subj”, String Title of the envelope
status: “DRF”, String Current status of the envelope, possible values: “DRF” (draft), “PGS” (sent, processing), “WKD” (processing completed), “TRJ” (to reject), “REJ” (refused), “EXP” (expired), “DEL” (deleted, temporary status), “STO” (archived), “TOE” (temporary), “TMP” (temporary), “STP”(cancelled)
previousStatus: null, String Previous envelope status (if available)
starred: false, Boolean true if urgent envelope
createdAt: 1493397433000, Integer Creation date of the envelope, expressed as the number of milliseconds passed since 00:00 of January 1, 1970
completedAt: null, Integer Date of completion of the envelope, expressed as the number of milliseconds passed since 00:00 of January 1, 1970
loadedByExtId: “usr1”, String External identifier of the user uploading the envelope
notifiedStatus: “X”, String Notification status of the envelope, possible values: “X” (initial state), “M” (manager signature completed, notification pending), “E” (manager signature completed and notified, vendor signature completed, notification pending), “S” (manager and vendor signature completed, notification to manager pending), “N” (manager signature completed and notified, pending vendor signature), “Y”, (completed process, all required signatures and notifications completed), “R” (rejection of the completed envelope, awaiting notification), “C” (cancelling the completed envelope, awaiting notification), “B”, notification pending)
notifiedAt: null Integer Date of execution of the last notification, expressed as the number of milliseconds elapsed since 00:00 of January 1, 1970
loadingMethod: “W”, String Identifier of the method used for loading the envelope, possible values: “C” (loading from GoSign Web console), “D” (loading from desktop), “W” (loading from webservice), “M” mail), “P” (loading from portal), “T” (loading from tablet), “X” (unknown loading method)
process: null, Process followed by the envelope, described below
type: “STD”, String Type of envelope, possible values: “STD” (standard), “SST” (sign & send), “TPL” (template)
tag: null, String Label on the envelope
nDocs: 5, Integer Number of documents of which the envelope is composed
nPages: 5, Integer Number of pages in the envelope
size: 0, Integer Overall size of the envelope (sum of the size of all documents)
expireAt: null, Integer Expiration date of the envelope, expressed as the number of milliseconds passed since 00:00 of January 1, 1970
expireAtTimezoneID: null, String Reference timezone identifier for the envelope expiration date
note: null, String Note on the envelope
corporateUseType: “P”, String Type of use of the envelope, possible values: “P” (public), “C” (company)
sendingMode: “DRF”, String Send mode, possible values: “DRF” (in draft, do not send), “IMD” (immediate)
documents: [{}] List of documents in the envelope
details: [], List of custom messages for each manager
commonMessage: { Message to be sent to all users
},
messages: [ List of personalized messages for each manager.
],
usersInCC: [], List of users who were cc’ ed in the envelope
expirationFirstReminder: 6, Integer Number of days after which GoSign will send a reminder for envelopes pending processing
expirationFollowingReminder: 3, Integer Number of days after which GoSign will send a second reminder for envelopes pending processing
hoursToExpiration: 0, Number of hours before expiration
sendFirstReminder: false, Boolean true if the first reminder is sent, otherwise false
storedAt: null, Integer Storage sate (if executed), expressed as the number of milliseconds passed from 00:00 on January 1, 1970
deletedAt: null, Integer Deletion date (if executed), expressed as the number of milliseconds elapsed since 00:00 of January 1, 1970
sysGenerator: “EXT”, String System that generated the envelope (“SB3”, which stands for SignBook3, is the default value, whereas “UNK” means unknown system)
delayDays: 0, Integer Days elapsed since the creation date of the envelope
actionsResume: null, (actionResume object) described below
cSostId: null, String Identification of the envelope on the backup storage system. Completed only if the storage is executed.
cSostState: “EXC”, String Backup state of the envelope, possible values:

“STS” (envelope ready to be sent to the external backup storage system indicated in the document class),

“WTN” (envelope was sent to the external backup storage system listed in the document class, albeit has not been yet stored),

“STD” (the envelope has been properly stored on the external backup storage system indicated in the document class),

“EXC” (the envelope is excluded from the backup process on an external system)

lastCSostChange: 1493397433000, Integer Date of the last backup status change (the date is expressed as the number of milliseconds passed since 00:00 of January 1, 1970)
dmsState: “EXC”, String Envelope storage status on external DMS, possible values:

“STS” (the envelope is ready to be sent to the external storage system listed in the document class)

“SNT” (the envelope was sent to the external storage system listed in the document class),

“EXC” (the envelope is excluded from the storage process on an external system)

lastDmsChange: 1493397433000, Integer Date of the last status change concerning DMS storage (the date is expressed as the number of milliseconds passed since 00:00 of January 1, 1970)
tplMinsBeforeExpiration: null, Integer Number of minutes to elapse from envelope insertion to expiration

(GoSign uses this information, if present, to automatically set the expiration date when inserting an envelope based on the template data)

costCenterId: null, Integer ID of the relevant cost centre for this envelope
trustLevelId: 1, Integer ID of the trust level chosen for this envelope (values between 1 and 4)
trustLevelCode: “INTERNAL_PDF”, String Trust level code chosen for this envelope. Possible values:

“DIGITAL_PDF” (Digital signature in PDF – corresponding to trustLevelId 1),

“DIGITAL_P7M” (Digital signature ID in P7M – corresponding to trustLevelId 2),

“INTERNAL_PDF” (Internal PDF signature – corresponding to trustLevelId 3),

“FEA” (Advanced electronic signature in PDF – corresponding to trustLevelId 4)

custEnveId: “2017-492”, String Envelope ID created by the template
notes: [], List of known objects associated with the envelope
evaluateFellowshipBefore: false, Boolean This field is set to true when the envelope cannot be processed by the user regarding a friendship request. That is, if the friend request between the envelope sender and the recipient is CONFIRMED, the recipient’s management of the envelope falls under the standard configuration (false), otherwise it is necessary to manage the friendship request first (true).
hasThirdPartyTasks: false, Boolean true if there are third-party tasks in the envelope, otherwise false or null
template: false, Boolean true if this envelope represents a template
hasProcessInstance: false, Boolean true if this envelope has an instantiated process
excludedForDms: true, Boolean true if this envelope is not affected by DMS storage processes
excludedForCSost: true, Boolean true if this envelope is not affected by document backup storage
waitingForCSost: false, Boolean true if the envelope is awaiting for backup storage
actualEnveId: “2017-492”, String equal to custEnveId if specified, otherwise equal to ID
loadedByUnknown: false, Boolean true if the envelope was loaded by an unknown system
loadedBySignBook3: true, Boolean true if the envelope was loaded by GoSign (“SignBook3”)
hasProcessDef: true, Boolean true if the envelope has a defined process (generally true unless the envelope is in draft status)
sst: false, Boolean true if the envelope is of type “sign & send”
temp: false, Boolean true if the envelope is of “temporary” type
deleted: false, Boolean true if the envelope is deleted
stored: false, Boolean true if the envelope is archived
draft: true, Boolean true if the envelope is in draft state
inProgress: false, Boolean true if the envelope is being processed
cancel: false, Boolean true if the envelope is cancelled
toReject: false, Boolean true if the envelope is in “to reject” status
rejected: false, Boolean true if the envelope was rejected
worked: false, Boolean true if the envelope has been fully processed
expired: false, Boolean true if the envelope has expired
externalNotifInProgress: false, Boolean true if the envelope notification to an external system is in progress
sendingModeImmediate: false, Boolean true if the sending mode is “immediate”
scheduledToSendToDms: false, Boolean true if sending to the DMS is scheduled (but not yet executed)
scheduledToSendToCSost: false, Boolean true if backup storage is scheduled (but not yet executed)
daysToExpiration: 0, Integer number of days left before the envelope expires (calculated as hoursToExpiration/24)
maxSizeEnabled: true, Boolean true if the maximum size of the envelope is active
availableToWork: false, Boolean true if the envelope is available for processing (i.e. it is “in progress” or “to reject” status)
npages: 5, Integer number of total pages in the envelope (excluding signing reports)
ndocs: 5, Integer number of documents in the envelope (excluding signing reports)
sentToDms: false, Boolean true if sending to the DMS was executed
externalNotifDisabled: true, Boolean true if the notification to an external system is disabled beforehand; this happens if the external system is SB3 or unknown, or if there is no externalId
loadedMethonKnown: true, Boolean true if the envelope loading method is different from “unknown”
sendingModeDraft: true, Boolean true if the sending mode is “draft”
storedInCSost: false Boolean true if the back-up was completed
}

The envelope object holds additional objects that inform of the current status: documents, actionsResume, process, message and detail.

The item documents is composed as follows:

{
size: 92609, Integer Document size, expressed in bytes
exported: false, True if the document was exported to external systems
exportedAt: null, Integer export date to external systems (if executed), expressed as the number of milli-seconds passed since 00:00 of January 1, 1970
encrypted: false, Boolean True if the document has been stored in encrypted form
bytes: “…”, String File contents encoded in Base64 for-mat
title: “test”, String Document title
createdAt: 14933974500, Integer Creation date of the document, ex-pressed as the number of milliseconds passed since 00:00 of January 1, 1970
docStatus: “N”, String Document status, possible values: “N” (just entered), “D” (deleted), “T” (tem-porary), “S” (archived), “E” (to be deleted)
nPages: 1, Integer Number of pages in the document
mimeType: “application/pdf”, String MIME type of document (usually “ap-plication / pdf”)
originalFname: “test.pdf”, String Original name of the document when loaded to GoSign
docType: “D”, String Type of document, possible values: “D” (document), “R” (report), “A” (attach-ment)
externalId: “EXTID_4242”, String External document Id, established by the external system when loaded to GoSign
delayDays: 0, Integer Days elapsed since the creation date of the document
loadingMethod: “X”, String Document load method, “X” = unknown loading method
originalMimeType: null, String “W” = Load from webservice
originalDocSize: null, String Original document MIME type (only validated if the document was converted by GoSign when loaded)
converted: false, Boolean Original document size, expressed in bytes (only validated when converted at up-load time)
srvVer: 1, Integer True if the document has been con-verted
tblVer: 1, Integer Version of the GoSign server that uploaded the document
cSostId: null, String Version of the GoSign app that up-loaded the document
docOrder: 1, Integer Identifier of the document on the substitute storage system. Completed only if the storage is executed.
template: false, Boolean Order of the document within the envelope (1 and above)
cloudService: “LOC”, String Source from which the document was loaded:

  • “LOC”: Local computer (default value)
  • “DBX”: DropBox
  • “LVB”: LiveBox
  • “GDR”: Google Drive
  • “ODR”: OneDrive
ooxmlSignStrategy: null String to be enhanced only in the case of an Office Open XML document; indicates that the signature is applied to the document in PAdES (“OXP” value) or XAdES (“OXX” value) format. If not specified, the Office document is converted into PDF and signed PAdES.
}

The object actionsResume has the following structure:

{
actions: 1, Integer Total count of all actions performed
signActions: 1, Integer Count of the NEW signing actions
signedActions: 1, Integer Count of TCF or WKD signature ac-tions
approveActions: 1, Integer Count of NEW approvals
approvedActions: 1, Integer Count of TCF or WKD approval ac-tions
viewActions: 1, Integer Count of NEW visa actions
viewedActions: 1, Integer Count of TCF or WKD visa actions
batchSignedActions: 1, Integer Count of mass-processed actions
initialsActions: 0, Integer Count of NEW initial actions
initialedActions: 0, Integer Count of TCF or WKD initial actions
confirmedActions: 0, Integer Total action count of any type con-firmed by the user (in TCF or WKD)
registerActions: 0, Integer Counting of NEW logging actions
registeredActions: 0, Integer Count of TCF or WKD logging actions
filledFreeTextActions: 0, Integer Count of completed free text ac-tions
freeTextActions: 0, Integer Count of free text actions
graphometricActions: 0, Integer Graphometric actions count
filledGraphometricActions: 0 Integer Count of the completed graphometric actions
}

The object process has the following structure:

{
startedByUserExtId: “usr1”, String User ID of user who ran the job.
status: “O”, String Process status, possible values: “O” (open), “C” (closed), “X” (cancelled)
ended: false, Boolean true if the process is finished
startedAt: 1495806006000, Integer Process launch date, expressed as the number of milliseconds passed since 00:00 of January 1, 1970
finishedAt: null, Integer Process completion date (or null if the process has not yet been completed), expressed as the number of milliseconds passed since 00:00 of January 1, 1970
steps: [{ Process steps
stepNum: 0, Integer Number of process step (0 for the first step)
startedAt: 1495806006000, Integer Process step launch date, expressed as the number of milliseconds passed since 00:00 of January 1, 1970
finishedAt: 1495806006000, Integer Completion date of this process step (or null if the step is not completed), expressed as the number of milliseconds passed from 00:00 on January 1, 1970
status: “D”, String Process step state, possible values: “N” (not started), “W” (working), “D” (completed), “C” (closed by process?), “X” (cancelled)
howMany: 0, Integer Number of managers who processed the document at this step
ended: true, Boolean True if the step is completed
first: false Boolean True if this is the first step in the process
}],
liveStatus: [{ (list of current steps)
mgrExternalId: “usr”, String Manager’s external ID
mgrName: “John”, String Name of the manager responsible for running this step
mgrSurname: “Doe”, String Surname of the manager responsible for running this step
status: “NEW”, String State of this step, possible values:

“NEW” (Ongoing process, visible envelope, unprocessed),

“TCF” (Ongoing process, visible envelope, processed pending confirmation),

“NEW” (Ongoing process, visible envelope, processed),

“NEW” (Ongoing process, hidden envelope,(future step),

“ERJ” (Process cancelled, rejected envelop),

“PCD” (Process cancelled)

startedAt: 1495806006000, Integer Process step launch date, expressed as the number of milliseconds passed since 00:00 of January 1, 1970
endedAt: null, Integer Completion date of this process step (or null if the step is not completed), expressed as the number of milliseconds passed from 00:00 on January 1, 1970
assignedTo: “Doe John”, String Name and last name of the user involved in this step
stepNumber: 1, Integer Step number (0 is the first step)
actionsResume: {}, (object type actionsResume)
mgrAdDomain: “” String ActiveDirectory domain of the manager responsible for this step
}],
open: true, Boolean True if the process is open
closed: false, Boolean True if the process is closed
cancelled: false, Boolean True if the process is cancelled
endedStepsCount: 1, Integer Number of completed steps
timeElapsedInHour: 141.54921 Double Time elapsed since the process started, expressed in hours
}

The object detail is composed as follows:

{
status: “NEW”, String State of this detail

“NEW” (Initial or ongoing processing state: at least one contained action is in the “new” state), “TCF” (Waiting for confirmation: ALL actions contained are ready for processing thus in the “to confirm” state) , “WKD” (Worked: the manager confirmed and processed the actions contained; accordingly, their status was also “worked”)

action: “WRK”, String Type of preparation for this detail, possible values: “WRK” (Processing of documents), “WEX” (Processing of documents for external managers), “PRG” (Logging of documents), “MPR” (Process change) “MEN” (Envelope modification)
workedAt: null, Integer Processing date of this detail, expressed as the number of milliseconds passed since 00:00 of January 1, 1970
synchedAt: null, Integer Synchronisation date (with the app) of this detail, expressed as the number of milliseconds elapsed since 00:00 of January 1, 1970
statusWorked: false, Boolean True if status is “worked”
statusCC: false, Boolean True if status is “CC”
statusToConfirm: false, Boolean True if status is “to confirm”
toWork: true, Boolean True if status is “to work”
statusNew: true, Boolean True if status is “new”
statusDeleted: false Boolean True if status is “deleted”
}

The message object is composed as follows:

{
subject: “Oggetto”, String Subject of the message
text: “testo”, String Message text
allEnveUsers: true, Boolean true for a common message to all users, false in case of a custom message per user
user: { The user for whom the envelope message is intended, “extId” is its external id
“extId”: “usr1” String Subject of the message
},
textCleaned: “testo”, String Message text, free of any control characters
commonMessage: true Boolean true for a common message to all users, false in case of a custom message per user
}

DeleteEnvelope: Delete the envelope specified in the URL. In the request body must be present the secretariat user that requires deletion and the related customerCode. Mail notifications are also sent to users (if enabled). It returns the operation outcome.

The default address is https://webapp.gosign.digital/gosign/services/v1/envelopes/:extId/delete/

POST /services/v1/envelopes/{extId}/delete/ HTTP/1.1

Json RequestBody - delete
{
"customerCode" : "customerCode_example",
"usrExtId": "userExternalId_example"
}

4.2 - Other services

DeleteUser: deletes a user, if the user has not already been involved in signature processes, otherwise the user will be disabled

PUT /services/v1/deleteUsers/ HTTP/1.1 

InsertSecretary: inserts a new user with the only role of a secretary without signing certificates

PUT /services/v1/secretary/ HTTP/1.1

UpdateAuthoritiesByCommand: assigns a role or a signature certificate to an existing user based on the specific command

PUT /services/v1/updateAuthorities/ HTTP/1.1

RemoveAuthoritiesByCommand: removes a role or a signature certificate from an existing user based on the specific command

PUT /services/v1/removeAuthorities/ HTTP/1.1

ModifyUserAttributes: change the value of a particular user property

PUT /services/v1/modifyUserAttributes/ HTTP/1.1

ConvertStrangerToCorporate: converts a Stranger user to a Corporate user based on the specific command

PUT /services/v1/convertStrangerToCorporate/ HTTP/1.1

4.3 - JSON Example

4.3.1 - Example 1

Here we describe an InsertEnvelope request with a minimal subset of values:

  • One document
  • One action
  • One recipient

PUT  https://webapp.gosign.digital/gosign/services/v1/envelopes/EXTID_YYY

HTTP/1.1
Accept: application/json, application/*+json
Content-Type: application/json

{
"customerCode" : "***secret***",
"externalSystemCode" : "ZZZ",
"envelope" : {
"externalId" : "EXTID_YYY",
"trustLevelCode" : "INTERNAL_PDF",
"sysGenerator" : "SAP",
"subject" : "Oggetto:Wed Apr 20 11:30:27 CEST 2016",
"loadedByExtId" : "segr",
"procDef" : {
"tasks" : [ {
"type" : "T",
"order" : 1,
"actorExpr" : "mgrU",
"action" : "WRK",
"howMany" : 1,
"certType" : "I",
"actionDefs" : [ {
"docExternalId" : "extdocid002_002X1461144549074",
"type" : "S",
"mandatory" : true,
"appearance" : {
"compassAppearance" : {
"page" : 1,
"position" : 1
}
},
"confString" : "{"actionInTCF":"true","customSignatureText":"Firmato da Mario"}",
} ]
} ]
},
"corporateUseType" : "P",
"sendingMode" : "IMD",
"documents" : [ {
"externalId" : "extdocid002_002X1461144549074",
"title" : "test",
"mimeType" : "application/pdf",
"originalFname" : "test.pdf",
"bytes": "JVBERi0xLjY…",
} ],
"commonMessage" : {
"subject" : "Oggetto",
"text" : "testo",
}
}
}

4.3.2 - Example 2

Example of JSON insertEnvelope request with a definition of the document class and positioning with absolute coordinates:

PUT  https://webapp.gosign.digital/gosign/services/v1/envelopes/extid_YYY

HTTP/1.1
Accept: application/json, application/*+json
Content-Type: application/json

{
"customerCode" : "***secret***",
"externalSystemCode" : "ZZZ",
"envelope" : {
"externalId" : "extid_YYY",
"trustLevelCode" : "INTERNAL_PDF",
"sysGenerator" : "SAP",
"subject" : "Oggetto del plico",
"starred" : false,
"loadedByExtId" : "segr",
"docClass" : {
"name" : "TESTCLASS",
"fields" : [ {
"name" : "CODICE",
"textValue" : "XYZ123",
},
{
"name" : "IMPORTO",
"numericValue" : 10.0,
},
{
"name" : "DTINVIO",
"dateValue" : 1462372619099,
}
]
},
"procDef" : {
"tasks" : [ {
"type" : "T",
"order" : 1,
"actorExpr" : "mgrU",
"action" : "WRK",
"howMany" : 1,
"certType" : "I",
"actionDefs" : [ {
"docExternalId" : "ABC123",
"type" : "S",
"mandatory" : true,
"appearance" : {
"coordAppearance" : {
"page" : 1,
"llx" : 75.0,
"lly" : 705.0,
"urx" : 205.0,
"ury" : 665.0
},
},
"confString" : "{"actionInTCF":"true",
"customSignatureText":"Firmato da Mario",
"visibilityStatus":"H" }",
} ]
} ]
},
"expireAt" : null,
"corporateUseType" : "P",
"sendingMode" : "IMD",
"documents" : [ {
"externalId" : "XYZ789",
"title" : "test",
"mimeType" : "application/pdf",
"originalFname" : "test.pdf",
"bytes" : "JVBERi0xLjY…"
} ],
"commonMessage" : {
"subject" : "Oggetto",
"text" : "testo",
},
"expirationFirstReminder" : 6,
"expirationFollowingReminder" : 3,
"sendingModeImmediate" : true,
"sendingModeDraft" : false
}
}

4.3.3 - Example 3

Example of InsertEnvelope JSON request with only the fields required for loading. It is possible to upload a document with sendingMode DRF without defining a process. Generating an envelope in this way, the secretariat identified by the loadedByExtId field will be able to see the envelope inside its dossiers in a “draft” state.

PUT https://webapp.gosign.digital/gosign/services/v1/envelopes/extid_YYY

HTTP/1.1
Accept: application/json, application/*+json
Content-Type: application/json

{
"customerCode" : "***secret***",
"externalSystemCode": "SAP",
"envelope": {
"subject": "Oggetto della pratica",
"externalId": "extid_YYY",
"loadedByExtId": "segr_user",
"sendingMode": "DRF",
"trustLevelCode": "DIGITAL_PDF",
"sysGenerator": "SAP",
"documents": [
{
"externalId": "SAP_138536YYYYY",
"title": "2019_000001",
"originalFname": "2019_000001.pdf",
"bytes": "JVBERi0xLjY…",
"mimeType": "application/pdf"
}
],
"commonMessage": {
"subject": "Oggetto della email di notifica",
"text": "Testo della email di notifica"
}
}
}

5 - SOAP Services examples

This section describes some examples of calls using the SOAP layer. The names of the fields to be valued in XML are case sensitive as well as the value of the externalId field, present in the main entities.

The code examples were produced using a client generated with Apache CXF in this way

wsdl2java -all -p it.infocert.gosign.ws -frontend jaxws21:

https://webapp.gosign.digital/gosign/ws/signBookWS.wsdl

https://webappcl.gosign.digital/gosign/ws/signBookWS.wsdl

where the wsdl used is coming from production and integration environment.

During the integration phase the wsdl related to test environment will be provided.

5.1 - InsertEnvelope

 

POST /services /ws/

The default address is https://webapp.gosign.digital/gosign/ws/

Object Format InsertEnvelopeRequest to be included in the request body:

<?xml version=”1.0″ encoding=”UTF-8″?>

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”>

<soapenv:Header/>

<soapenv:Body>

<insertEnvelopeRequest xmlns=”http://www.librofirma.it/schemas/3.0″>

Mandatory service header
<customerCode>******secret***</customerCode> String Mandatory Customer Code (API Key)
<AddUsersInCC>*******</AddUsersInCC>

 

 

 

Array Optional Object to insert a CC users;  Specifies which users should be included in CC for the case just entered. They can be identified through external_id or with Name Surname and email address
<envelope>******</envelope> Object Mandatory
</insertEnvelopeRequest>

</soapenv:Body>

</soapenv:Envelope>

Mandatory service header

The AddUsersInCC object, in turn, is composed of:

<AddUsersInCC> Array Optional Object to insert a CC users;  Specifies which users should be included in CC for the case just entered. They can be identified through external_id or with Name Surname and email address
<email>emailaddress</email> string Optional the e-mail address of the user in cc
<externalId>idUserInCC</externalId> string Optional the external Identifier of the user in cc
<name>nameUserInCC</name > string Optional the name of the user in cc
<surname>surnameUserInCC</surname > string Optional the surname of the user in cc
<addUsersInCCStrategy >EMAIL_ALWAYS</addUsersInCCStrategy> string Optional schemas:addUsersInCCStrategies à  value=”EMAIL_ALWAYS”. For more info, cap 6.4
</AddUsersInCC> Array

The envelope object, in turn, is composed of:

<envelope> Mandatory
<subject>envelopeSubject</subject> String Mandatory Object of the envelope (can be manipulated later by GoSign in a variety of contexts)
<starred>false</starred> Boolean Optional Flag “Urgent”, optionally available externally and with a default value of ‘false’
<externalId>myenve05</externalId> String Mandatory The external id of the envelope, to be specified by the external system
<joinDocuments>myenve05 myenve06</joinDocuments> String Optional Lists the documents’ ExtID to be merged, separated by space
<sendingMode>IMD</sendingMode> String Optional Envelope send mode; if ‘IMD’ the process starts as you insert the envelope if ‘DRF’ the process must be manually started by the same user who create a dossier;it determines the mandatory nature of the procDef field (see below).
<expireAt>245124521451</expireAt> Date Optional Expiration date of the envelope, expressed in milliseconds from midnight of January 1, 1970
<note>Envelope notes</note> String Optional Notes on the envelope, open field
<corporateUseType>C</corporateUseType> String Optional The scope of use of the envelope according to level of confidentiality. Possible values :

  • P: public
  • C: corporate
  • A: reserved
  • X: restricted
<trustLevelCode>INTERNAL_PDF</trustLevelCode> String Mandatory Envelope trust level code, chosen from “DIGITAL_PDF”, “DIGITAL_P7M”, “INTERNAL_PDF”, “FEA”, “GRAPHO_FEA”; In the event of an incompatible trust level, GoSign will refuse to insert the envelope.  In case of trust level = FEA, it is not possible to upload a document already signed
<sysGenerator>AVG</sysGenerator> String Optional The system that generated the envelope.
<commonMessage> Optional Message to be sent to all users
<text>text of message</text> String Mandatory Message text
<subject>title of message</subject> String Mandatory Message title
</commonMessage>
<documents>*****</documents> Array Mandatory List of documents to be uploaded ;further details
<docClass>****</docClass> Optional Document class to be assigned to the document; further details
<processDef> Object Process definition, only required if sendingMode ‘IMD’, optional with sendingMode ‘DRF’.
<code>TPL001</code> String Optional Policy code
<revision>-1</revision> intager Optional Revision, default assigned “-1 “ for the last version
<tasks>*******</tasks> Array Mandatory List of tasks that make up the process (see task-Def in the following table).
<newUsers>*****</newUsers> Array Optional New Users definition; further details
</processDef>
</envelope>

The docClass object, in turn, is composed of:

<docClass> Optional Document class to be assigned to the document
<id>01</id> intager Mandatory docClass Id
<name>DC01</name> String Mandatory docClass name, required if you are using a policy or a docClass.
<fields> Array Envelope document class definition, one of *value field is required.
<documentFiled>
<id>1000<id> Intager Optional Code of the field
<name>fieldname</name> String Mandatory Name of the field
<dateValue>21451245212212</dateValue> Date Optional Date field value (expressed as the number of milliseconds elapsed from 00:00 January 1, 1970)
<numericValue>0</numericValue> Double Optional Value of the numeric field
<textValue>string</textValue> String Optional String field value
<documentFiled>
</fields>
</docClass>

The tasks object, in turn, is composed of:

<tasks> Array Mandatory
<taskDef> Mandatory
<type>H</type> String Mandatory Type of the taskdef, possible values: “T” Type of task performed by users internal to GoSign (HTASK = Human TASK), “A” type of automatic task (logging or sending mail).
<order>1</order> Integer Mandatory Task order, used to indicate serious and parallel processes through the WS.
<actorExpr>id1R|id2U</actorExpr> String Mandatory List of managers / roles involved, according to the following scheme: xR: role with id = x – yU: manager with id = y – | (pipe) OR logical – Example: id1R | id2U.
<action>WRK<action> String Mandatory Process action, possible values:

  • WRK – Processing of documents (default)
  • PRG – Registration of documents
  • SDM – Sending mail
  • SEA – Seal of documents
  • ASI – Automatic signature of documents
<howMany>1</howMany> Integer Mandatory Number of actors needed to close the task, default 1. May be 1, 2, 3, or 4.
<actionDefs>*****</actionDefs> Array Mandatory Signature actions definition. further details
<confString>{ “signAllVisible”:”V”}

</confString>

String Optional Configuration JSON string; the signAllVisible key defines the visibility of the “Sign all” button and can be set to “V” – button visible or “N” – button not visible.
<certType>I</certType> String Mandatory Contains the type (s) of a user’s signature certificates.

Possible values:

  • “R” – remote certificate
  • “I” – internal certificate
  • “T” – sign with token
<sendMailMessage>****<sendMailMessage>

 

Email message enhanced in the case of tasks such as sending mail, ie with type = “A” and action = “SDM”; not valued for the processing of documents. For further details see the next table
</taskDef>
</tasks>

The documents object, in turn, is composed of:

<documents> Array
<document>
<bytes>docbytes</bytes> String Mandatory Document bytes encoded in Base64. It is not possible to upload a document that already has a signature with field trust level = FEA.
<externalId>extId</externalId> String Mandatory To be completed by the external system to allow identification of the document regardless of the internal mechanisms of GoSign.
<mimeType>string</mimeType> String Mandatory Type of document, to be completed by the external system. In addition, GoSign will be able to change the value following format conversions or for certain trust levels.
<title>doctitle</title> String Mandatory Title of the document, to be completed by the external system.
<originalFname>fileName.pdf</originalFname> String Mandatory Name of the original file including extension.
<ooxmlSignStrategy>OXP</ooxmlSignStrategy> String Optional to be enhanced only in the case of an Office Open XML document; indicates that the signature must be applied to the document in PAdES format, value “OXP”, or XAdES, value “OXX”. If not specified, the Office document is converted to PDF and signed PAdES.
<uri>file://nome_file.pdf</uri> Path Optional Indicates the URI from which to load the document, when the payload is not defined, or the bytes field, in the request.
<privateDoc>true</privateDoc> Boolean Optional Indicates whether the document is private or not
<protocols> Array Optional Any protocols generated for this document
<protocol>
<code>protocolCode</code> String Optional Code of protocol
<createdAt>1573837209000</createdAt> Intager Optional Creation date of the protocol, expressed as the number of milliseconds passed since 00:00 of January 1, 1970
<registry> Protocol register definition
<protocolRegistry>
<code></code> String Optional protocol register code
</protocolRegistry>
</registry>
<protocol>
</protocols>
<document/>
<documents>

The item sendMailMessage, in turn, is composed as follows:

<sendMailMessage> Object
<subject>Send mail task subject</subject> String Optional Mail subject.
<bodyMail>Body mail</bodyMail> String Optional Body mail.
<sendMailDocumentList> Array Optional attachments to be included in the email
<sendMailDocument>
<externalDocId>idDoc1</externalDocId> List of external id documents to be attached to the email
</sendMailDocument>
</sendMailDocumentList>
<sendMailRecipientList> Array List of the recipients (to or cc)
<sendMailRecipient>
<userExternalId>jd</userExternalId> String Optional Recipient’s external id.
<email>john.doe@test.com</email> String Optional Recipient email
<typeRecipient>TO</typeRecipient> String Mandatory Recipient type – “TO” or “CC” –
</sendMailRecipient>
</sendMailRecipientList>
</sendMailMessage>

The item actionDefs, in turn, is composed as follows

<actionDef> object
<docExternalId>ext42</docExternalId> String Mandatory External id of the document on which this action is placed.
<type>S</type> String Mandatory Type of action required on the document, possible values:

  • Sà SIGN
  • Aà APPROVE
  • Và VIEW
  • Ià INITIALS
  • Pà PROTOCOL
  • GàGRAPHOMETRIC
<mandatory>true</mandatory> Boolean Mandatory Defines mandatory action; always true except graphometric signature (internal use).
<confString>{..}</confString> String Optional String json containing approved action flags, text and signature visibility configurations.

Example: { “customSignatureText”:”A custom signature text”, “visibilityStatus” : “V”|”H”|”N” }

<appearance> Signature action positioning algorithm, one and only one property between compassAppearance,coordAppearance and tagAppearance is to be compiled and required.
<invisible>false</invisible> boolean Optional Defines if the action is invisible on the document. Default false
<blankSignatureFieldName>sign_here</blankSignatureFieldName> String Optional Name of the empty signature field in which to sign.
<compassPage>1</compassPage> Integer Mandatory Number of the page on which to sign, starting from 1, or one of the following special values:

  • 1 (last page)
  • 2 (all pages)
<compassPosition>1</compassPosition> intager Optional Position in which to sign, chosen from:

-1 à INVISIBLE

1 à TOP_LEFT_NORTH_WEST

2 à TOP_NORTH

3 à TOP_RIGHT_NORTH_EAST

4 à CENTRAL

5 à CENTRAL_LEFT_EAST

6 à CENTRAL_LEFT_WEST

7 à BOTTOM_SOUTH

8 à BOTTOM_LEFT_SOUTH_WEST

9 à BOTTOM_RIGHT_SOUTH_EAST

<llx>50</llx> float Mandatory X coordinate of the lower left corner of the action placeholder
<lly>50</lly> float Mandatory Y coordinate of the lower left corner of the action placeholder.
<urx>100</urx> float Mandatory X coordinate of the lower right corner of the action placeholder.
<ury>100</ury> float Mandatory Y coordinate of the lower right corner of the action placeholder.
<page>1</page> Integer Mandatory Number of the page where to sign, starting from 1, or one of the following special values:

  • 1 (last page)
  • 2 (all pages)
  • 3 (first and last page)
<tagCornerType>SBL</tagCornerType> String Optional Type of positioning identified:

SBLàSINGLE_BOTTOM_LEFT_CORNER_TYPE               BLRàBOTTOM_LEFT_TOP_RIGHT_RECT_TYPE           TLRàTOP_LEFT_BOTTOM_RIGHT_RECT_TYPE

<startTagPattern>start$$1</ startTagPattern> String Optional String to be searched in the document to identify the initial end of the rectangle in which to place the tag
<endTagPattern>end$$1</endTagPattern> String Optional String to be searched in the document to identify the other end of the rectangle in which to place the tag
<tagXOffset>0</tagXOffset> double Optional Defines a horizontal offset in points on the PDF with respect to the X coordinate of the identified tag.

Examples of use:

  • a null xOffset or equal to 0, does not alter the positioning of the action
  • an xOffset of 50, translates the positioning of the action by 50 points to the right
  • an xOffset equal to -100, translates the positioning of the action by 100 points to the left
<tagYOffset>0</tagYOffset> double Optional Defines a vertical offset in points on the PDF with respect to the Y coordinate of the identified tag.

Examples of use:

  • a null yOffset or equal to 0, does not alter the position of the action
  • a yOffset of 50 translates the position of the action upwards by 50 points
  • a yOffset equal to -100, translates the positioning of the action downwards by 100 points
</appearance>
</actionDef>

The newUsers object, in turn, is composed of:

<newUsers> Array List of new users
<insertUser>
<username>lrossi@mail.it</username> String Mandatory Username to access the application
<name>Luigi</name> String Mandatory Name of the user
<surname>Rossi</surname> String Mandatory User surname
<phoneNumber>3901234567</phoneNumber> String Optional Telephone number
<email>lrossi@mail.it</email> String Mandatory Email address
<emailLanguage>string</emailLanguage> String Optional Language to set in Gosign template email
<externalId>lrossi@mail.it</externalId> String Mandatory External ID of the user
<newUserStrategy>ACCEPT_ALWAYS</newUserStrategy> String Mandatory Possible values:

  • ACCEPT_ALWAYS
  • REJECT_IF_DIFFERENT
  • REJECT_ALWAYS
  • EMAIL_BASED
<userAuthorities>ROLE_STRANGER</userAuthorities> String Mandatory Possible values:

  • ROLE_MGR
  • ROLE_SEGR
  • ROLE_STRANGER
<fiscalCode>string</fiscalCode> string Optional New user fiscalcode
</insertUser>
</newUsers>

An example of the envelope insertion call via SOAP may be the following. Here a two-recipient envelope (usr and usr2) is created in series together with a document and an action per recipient.

<insertEnvelopeRequest xmlns="http://www.librofirma.it/schemas/3.0">
<customerCode>***secret***</customerCode>
<envelope>
<externalId>EXTID_0011491322230858</externalId>
<subject>Oggetto del plico</subject>
<starred>false</starred>
<loadedByExtId>segr</loadedByExtId>
<sysGenerator>SAP</sysGenerator>
<corporateUseType>P</corporateUseType>
<sendingMode>IMD</sendingMode>
<trustLevelCode>INTERNAL_PDF</trustLevelCode>
<commonMessage>
<subject>Oggetto del messaggio</subject>
<text>Testo del messaggio</text>
</commonMessage>
<procDef>
<tasks>
<taskDef>
<order>1</order>
<type>T</type>
<actorExpr>usrU</actorExpr>
<action>WRK</action>
<certType>I</certType>
<howMany>1</howMany>
<actionDefs>
<actionDef>
<docExternalId>extdocid11491322230858</docExternalId>
<mandatory>true</mandatory>
<type>S</type>
<appearance>
<page>1</page>
<llx>50.0</llx>
<lly>50.0</lly>
<urx>150.0</urx>
<ury>80.0</ury>
</appearance>
<confString>{ &quot;visibilityStatus&quot; : &quot;N&quot; }</confString>
</actionDef>
</actionDefs>
</taskDef>
<taskDef>
<order>2</order>
<type>T</type>
<actorExpr>usr2U</actorExpr>
<action>WRK</action>
<certType>I</certType>
<howMany>1</howMany>
<actionDefs>
<actionDef>
<docExternalId>extdocid11491322230858</docExternalId>
<mandatory>true</mandatory>
<type>S</type>
<appearance>
<page>1</page>
<llx>300.0</llx>
<lly>50.0</lly>
<urx>400.0</urx>
<ury>80.0</ury>
</appearance>
</actionDef>
</actionDefs>
</taskDef>
</tasks>
</procDef>
<documents>
<document>
<title>titolo doc1</title>
<mimeType>application/pdf</mimeType>
<originalFname>test.pdf</originalFname>
<externalId>extdocid11491322230858</externalId>
<bytes>JVB…</bytes>
</document>
</documents>
</envelope>
</insertEnvelopeRequest>

5.2 - EraseDocuments

This method allows you to permanently delete one or more documents present in an envelope.

The deletion can take place by specifying one or more external id of documents, one or more filename or a mix of both. Furthermore, in a single call it is possible to delete documents belonging to several fields.

The deletion of a document also eliminates the related actions associated with it. So a document can only be deleted if the following conditions are met:

  • The document belongs to the specified dossier
  • The envelope is in draft status (DRF)
  • For “in process” practices (PGS status) it is possible to delete a document only if their elimination does not make the envelope inconsistent. For example:
    • The document was not signed by anyone
    • The document does not have associated actions (of any kind) or if any have it, the deletion of the document and its actions leaves all the tasks of the process with at least one action

If GoSign detects at least one of these inconsistencies, the deletion is blocked and an error is returned to the caller. Partial eliminations are therefore possible as indicated in the final examples of this paragraph.

In the event of a request for deletion by filename, all documents with the original file name equal to the specified filename will be deleted. So if in a package there are multiple documents with the same original file name they all will be deleted.

During the deletion of documents, further changes are blocked so that no one (users or other web service calls) can somehow make the envelope inconsistent or act on incomplete information.
Here is an example of XML request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<eraseDocumentsRequest xmlns="http://www.librofirma.it/schemas/3.0">
<customerCode>******SECRET*******</customerCode>
<documentToErase>
<enveExtId>ABC0001</enveExtId>
<docExtId>ABC0001_01</docExtId>
</documentToErase>
<documentToErase>
<enveExtId>ABC0001</enveExtId>
<docFilename>filename.pdf</docFilename>
</documentToErase>
</eraseDocumentsRequest>
</soap:Body>
</soap:Envelope>

With this request we intend to delete the document with external id ABC0001_01 of the ABC0001 en-velope and all the documents with filename filename.pdf in the same envelope ABC0001.

Example of complete elimination:


<!-- REQUEST -->
<ns:eraseDocumentsRequest>
<ns:customerCode>******SECRET*******</ns:customerCode>
<ns:documentToErase>
<ns:enveExtId>test_ext_id</ns:enveExtId>
<ns:docFilename>test.pdf</ns:docFilename>
</ns:documentToErase>
</ns:eraseDocumentsRequest>

<!-- RESPONSE -->
<eraseDocumentsResponse xmlns="http://www.librofirma.it/schemas/3.0">
<returnStatus>
<code>OK</code>
<message>Successfull - Documents erased: 1</message>
</returnStatus>
</eraseDocumentsResponse>

Partial elimination:

<!-- REQUEST -->
<ns:eraseDocumentsRequest>
<ns:customerCode>******SECRET*******</ns:customerCode>
<ns:documentToErase>
<ns:enveExtId>test_ext_id</ns:enveExtId>
<ns:docFilename>test.pdf</ns:docFilename>
</ns:documentToErase>
<ns:documentToErase>
<ns:enveExtId>test_ext_id2</ns:enveExtId>
<ns:docFilename>test4.pdf</ns:docFilename>
</ns:documentToErase>
</ns:eraseDocumentsRequest>

<!-- RESPONSE: documento non trovato -->
<eraseDocumentsResponse xmlns="http://www.librofirma.it/schemas/3.0">
<returnStatus>
<code>DOCUMENTS_PARTIAL_DELETION</code>
<message>PARTIAL - reason = Document not found by fileName [enveId=3737, enveExtId=test_ext_id2, docExtId=null, docId=0, docFileName=test4.pdf], erased = 1/2</message>
</returnStatus>
</eraseDocumentsResponse>

Wrong parameters:

<!-- REQUEST -->
<ns:eraseDocumentsRequest>
<ns:customerCode>******SECRET*******</ns:customerCode>
<ns:documentToErase>
<ns:enveExtId>test_ext_id</ns:enveExtId>
<ns:docFilename>test.pdf</ns:docFilename>
</ns:documentToErase>
</ns:eraseDocumentsRequest>

<!-- RESPONSE: customer non trovato -->
<eraseDocumentsResponse xmlns="http://www.librofirma.it/schemas/3.0">
<returnStatus>
<code>CUST_NOT_FOUND</code>
<message>Customer not found or access is denied - customerCode = b8cc3d945b4789055c940aa53b2044a9b7</message>
</returnStatus>
</eraseDocumentsResponse>

Completely rejected deletion:

<!-- REQUEST -->
<ns:eraseDocumentsRequest>
<ns:customerCode>******SECRET*******</ns:customerCode>
<ns:documentToErase>
<ns:enveExtId>test_ext_id</ns:enveExtId>
<ns:docFilename>test.pdf</ns:docFilename>
</ns:documentToErase>
</ns:eraseDocumentsRequest>

<!-- RESPONSE: pratica con lock -->
<eraseDocumentsResponse xmlns="http://www.librofirma.it/schemas/3.0">
<returnStatus>
<code>NO_DOCUMENTS_DELETED</code>
<message>No documents deleted - reason = Envelope is locked by a user [en-veId=3737, enveExtId=test_ext_id]</message>
</returnStatus>
</eraseDocumentsResponse>

5.3 - DeleteEnvelope

The following request logically eliminates an envelope from GoSign, i.e. it is only “hidden” in a sort of store. After some days (which depend on how the environment is configured) the envelope is definitively deleted.This is an example of a SOAP envelope eliminating a single envelope knowing its external id with which it was loaded:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<deleteEnvelopesRequest xmlns="http://www.librofirma.it/schemas/3.0">
<customerCode>*****secret******</customerCode>
<envelopesToDelete>
<idPair>
<extId>extid_envelope</extId>
</idPair>
</envelopesToDelete>
</deleteEnvelopesRequest>
</soap:Body>
</soap:Envelope>

The customer code is needed to authorize the access and a list of idPair is used to indicate which packages should be deleted. In iPair tag, the sub-tag (internal GoSign id) or the sub-tag (external id) should be indicated depending on what information is available.

The response is contained in the returnStatus structure with the tag code and message that indicate the result of the operation. If the customer code is correct and the indicated envelopes exist, the deleteEnvelope returns code = OK. Any other code value is to be considered as an error. Different versions of GoSign may return different error codes.

An example of implementation with a java client is the following:

// Disable strict validation of wsdl
Map<String, Object> requestContext = ((javax.xml.ws.BindingProvider) port).getRequestContext();
requestContext.put("set-jaxb-validation-event-handler", "false");
DeleteEnvelopesRequest deleteEnveReq = new DeleteEnvelopesRequest();
deleteEnveReq.setCustomerCode("*****secret******");
DeleteEnvelopesRequest.EnvelopesToDelete envelopesToDel = new DeleteEnve-lopesRequest.EnvelopesToDelete();
// On IdPair object, set the id field xor the extId field
IdPair enveToDel = new IdPair();
enveToDel.setExtId("extid_envelope");
envelopesToDel.getIdPair().add(enveToDel);
deleteEnveReq.setEnvelopesToDelete(envelopesToDel);
DeleteEnvelopesResponse delResp = port.deleteEnvelopes(deleteEnveReq);
ReturnStatus returnStatus = delResp.getReturnStatus();
System.out.println("Delete response:" + returnStatus.getCode() + " message:" + returnStatus.getMessage());

6 - In-depth

In this paragraph some concepts and techniques introduced previously are shown in deep.

6.1 - Tag positioning

In the previous examples, positioning of signature bookmarks is performed via absolute coordinates. An alternative positioning method is the tag-based one, where GoSign searches for text patterns in the PDFs that serve as positioning placeholders. GoSign does not remove placeholders from the text; as a rule, these tags consist of white text on a white background to rend them invisible.

Tags must all be different because GoSign stops at the first occurrence found. For example, if an action must be applied in the same place of each page for a multiple page document, different tags are required for each action.

This type of positioning is done with the following structure (here an xml-based example):


<appearance>
<startTagPattern>@ABC123</startTagPattern>
<tagXOffset>0.0</tagXOffset>
<tagYOffset>0.0</tagYOffset>
<tagCornerType>SBL</tagCornerType>
</appearance>

The meaning of the fields is the following:

startTagPattern: the text to be searched in the PDF

tagXOffset, tagYOffset: Define an horizontal (X) or vertical (Y) offset in inch on the PDF with respect to the X or Y coordinate of the identified text.

tagCornerType: “SBL” means that positioning takes place from the bottom left corner of the text indicated in startTagPattern

Offset examples:

xOffset equal to 0 does not change the position of the action

xOffset equal to 50, shifts the action position 50 points to the right

xOffset equal to -100, shifts the action position 100 points to the left.

You can also specify a endTagPattern, so as to indicate the positioning area:

Positioning with tagCornerType = BLR

Positioing with tagCornerType = TLR

However, is important avoid to make areas too large, too small, or with completely different relative sizes, as these will produce unsatisfactory graphic results.

This positioning type can also be used with REST and SDK calls. See paragraph 3.5.1 for details regarding the building of the tags and their search in the PDF text.

Appearance example in a REST call (JSON example):

"appearance" : {
"tagAppearance" : {
"cornerType" : "SBL",
"startTagPattern": "##FIRMA##",
"yoffset" : 748.3197021484375,
"xoffset" : 110.64254760742188
}
}

The meaning of the fields remains the same, only the name changes, note well that the field names in the JSON xoffset and yoffset are written in lowercase.

6.2 - Adding new users during insertion

You can also add new users during the insertion of a new envelope (par. 4.1, Item procDef ).New users can also be used in the envelope in insertion (using  the actorExpr fields).

The following example shows the insertion of a new stranger:

<procDef>
<tasks>
<!-- Task definition omitted -->
</tasks>
<!—Insert new users -->
<newUsers>
<username>stranger@example.com</username>
<name>Nome Stranger</name>
<surname>Cognome Stranger</surname>
<phoneNumber>+3912345678980<phoneNumber>
<email>stranger@example.com</email>
<externalId>stranger@example.com</externalId>
<newUserStrategy>ACCEPT_ALWAYS</newUserStrategy>
<userAuthorities>
<username>stranger@example.com</username>
<authority>ROLE_STRANGER</authority>
</userAuthorities>
</newUsers>
<newUsers>
<!—Another users -->
</newUsers>
</procDef>

Field names are quite descriptive. An unknown stranger is inserted because the field authority is set to ROLE_STRANGER in section userAuthorities.

You can also create a user manager by specifying ROLE_MGR. In this case, an internal certificate is automatically generated. Therefore, this user just created cannot do digital signatures.

If you try to add an existing STRANGER user, the system behaves differently according to the value indicated in the newUserStrategy tag for that user:

 

newUserStrategy Description
ACCEPT_ALWAYS The user is searched for username (case insensitive). If not found, proceed with the insertion. If found, the name and surname of the existing stranger or corporate user are updated without reporting errors to the caller.
REJECT_IF_DIFFERENT The user is searched for username (case insensitive). If not found, proceed with the insertion. If found, an error is returned to the caller if the existing stranger has a different first and last name than specified in the request. If the user found is a corporate user, an error is returned immediately, regardless of name and surname.
REJECT_ALWAYS The user is searched for username (case insensitive). If not found, proceed with the insertion. If found an error is returned to the caller: the fact that there is a stranger or an already existing corporate user (no matter if with the same or different surname) is considered a problem. This is the default value if the newUserStrategy tag is not specified.
EMAIL_BASED The user is first searched via externalId (case sensitive). If not found, search by username = email (case insensitive). If not found, search by email (case sensitive) within the customer specified in the request. If in this last verification step there are more users (of any type) an error is returned to the caller. Finally, if the user is not found, the new user is entered. If instead a user is found in one of the previous steps, no user update is performed.

It is very important to be careful when you are creating users during the insertion of new envelope, otherwise you can create unespected duplicate users:

Depending on the newUserStrategy used, the application, as specified in the previous table, performs different checks and then will update users already present in the system or will create new users.

In the following example, 2 cases are shown where two different newUser-Strategies are used:

case 1

newUserStrategy = ACCEPT_ALWAYS

"procDef": {
"newUsers": [
{
"username": "test1",
"name": "stranger",
"surname": "test",
"phoneNumber": "3482259422",
"email": "al***********ail.com",
"externalId": "test1",
"newUserStrategy": "ACCEPT_ALWAYS",
"userAuthorities": [
{
"username": "test1",
"authority": "ROLE_STRANGER"
}
]
}
],
"tasks": [
{

In this case, the username check is bypassed and Gosign creates a new Stranger user, with an email address already present in the system:

case 2

newUserStrategy = EMAIL_BASED

"procDef": {
"newUsers": [
{
"username": "test1",
"name": "stranger",
"surname": "test",
"phoneNumber": "3482259422",
"email": "al***********ail.com",
"externalId": "test1",
"newUserStrategy": "EMAIL_BASED",
"userAuthorities": [
{
"username": "test1",
"authority": "ROLE_STRANGER"
}
]
}
],
"tasks": [
{

In this case the corporate user is correctly selected and a new stranger user is not created.

In any case it is not possible to change the type of a user, from stranger to corporate and back.

This feature is also available for REST and SDK calls.

6.3 - Email sending tasks

In the authorization process it is possible to insert a task definition (Par 4.1, Item Tasks) that allows sending by e-mail documents related to a dossier to multiple adressees.
The information needed for this task is as follows:

  • List of email addresses of direct recipients (at least one is mandatory)
  • List of email addresses of recipients in CC (optional)
  • Subject and body of the email (optional, default values are used if empty)

Here an XML example with some comments:

<taskDef>
<order>3</order> <!— the order number must place the task as the last of the process -->
<type>A</type> <!— Indicate A as the type of task (Automatic) -->
<action>SDM</action> <!— Specify SDM as the send mail action -->
<howMany>1</howMany> <!— set to 1 -->
<actionDefs/> <!— not define action -->
<sendMailMessage>
<subject>Send mail task subject</subject>
<bodyMail>Lorem ipsum dolor sit amet, consectetur adipiscing elit</bodyMail>
<!— List of the recipients -->
<sendMailRecipientList>
<sendMailRecipient>
<typeRecipient>TO</typeRecipient> <!— Recipient in TO -->
<userExternalId>psmvdm</userExternalId>
</sendMailRecipient>
<sendMailRecipient>
<typeRecipient>CC</typeRecipient> <!— Recipient in CC -->
<email>luca.bianchi@test.com</email>
</sendMailRecipient>
...
</sendMailRecipientList>
</sendMailMessage>
</taskDef>

The rules for finding the destination email address are as follows:

  • if not empty, the userExternalId field is used to find the corresponding user in the customer and use his email address
  • if the userExternalId is empty, the email field must be filled

Additional constraints for entering a Send Mail task:

  • The customer to whom the envelope is being sent must be enabled to use “Send Mail” actions
  • There must be at least one recipient with the typeRecipient = TO field
  • The Send Mail task must be the last one in the process
  • There may be only one Send Mail task within the process
  • All documents of the package are sent

If the above constraints are not respected, the insertion procedure will be interrupted.

6.4 - Adding users in CC

To add one or more users in cc while creating a new envelope, you can use the addUsersInCC field (par. 4.1, Item addUserInCC).

Using the REST protocol, the JSON to use is the follows:

{
"customerCode": "...",
"addUsersInCC" : [ {
"externalId" : "extId",
"email" : "user@example.com",
"surname" : "User Surname",
"name" : "User Name",
"addUsersInCCStrategy" : "EMAIL_ALWAYS"
}],
"envelope": {
...
}
}

The same fields exist for the SOAP calls but with XML formalism.

addUsersInCC is an array of objects that identify users to add in CC.

The logic for selecting users is the follow:

  1. if externalId is valorized, the systen will searches for externalId among the corporate users of the customer specified in the call and among corporate users “friends” (that is, who have been invited to participate in customer processes). If a user is found, it is configured as a CC user for the envelope. In this way, this user will see the envelope in his “Signature Book” page within the envelopes in “Copying Concourse”. If no user is found or if more than one user is found, the entry is blocked and an error is returned to the caller.
  2. if externalId is not evaluated, the email field is used to search by email address between the corporate users of the customer specified in the call and among corporate users “friends”. If the email field is not evaluated, an error is returned to the caller. If a user is found, it is configured as a CC user for the package. In this way, this user will see the package on his “Signature Book” page within the files in “Knowledge Copy”. If no user is found or if more than one is found, the entry is blocked and an error is returned to the caller.
  3. if no user is found in the previous steps, the surname, name and email fields are used to insert an email with the documents processed at the end of the work process.

Using the optional addUsersInCCStrategy field it is possible to change the management rules of the addUsersInCC field. The only possible value is EMAIL_ALWAYS which tells GoSign to use the previous case c) for all users specified in addUsersInCC, regardless of the presence of externalId or email fields.

6.5 - Use of signing policies

Policies are process templates that allow you to have one or more predefined envelope templates.

The complete description of the policy features is available in the GoSign user manuals.

In short, a policy defines:

  • A document class associated with the policy
  • A set of rules based on the document class fields that allow you to select one or more envelope
  • For each template:
    • The basic data of an envelope (subject, deadline, …)
    • One or more template documents
    • The signing process with document actions.

Policies are defined by the administrator  and can be used by secretarial users based on the visibility of document classes (through the concept of “scope”).

Each policy has an alphanumeric code and a version that allows it to be used also by web services, both SOAP and REST.

The insertEnvelope call indicates a policy in this way:

"docClass" : {
"name" : "FRM_Ord",
"id" : "377",
"fields" : [
{
"name" : "Proj_desc",
"textValue" : "value to insert",
},
{
"name" : "Proj_number",
"numericValue" : "546798",
}
]
},
[…]
"procDef" : {
"code" : "policy_test",
"revision" : "3"
}

The tasks section is no longer necessary and instead the policy code(code filed)mandatory, and possibly a specific revision (in example “revision”:”2”) must be specified. If no revision is specified, version 1 will be taken. In case you want to take the latest revision available, the revision field must be enhanced with the value -1.

Below is a mock up of GoSign:

In any case, it is necessary to specify the documents section in the insertEnvelope call, because these will be replaced with those of the templates preloaded in the policy, keeping the order.

It is also mandatory to specify the docClass field linked to the chosen policy, specifying:

  • name: field that identifies the name of document class created in Gosign (example FRM_Ord);
  • id: numerical value automatically generated in progression by Gosign when creating a new document class; as specified in the service detail table, the value is of type string (example 377).

Below is an image relating to the document class in GoSign:

All fields marked as mandatory in the document class and the fields that are used as policy control fields are also to be specified.

If any of this information is missing, the insertEnvelope is not successful.The documents loaded through insertEnvelope using a policy must be as similar as possible to the template documents used, otherwise the insertion may not be successful and, depending on the version of GoSign, return a different error code.

The subject field of the Envelope object will be used to overwrite the default dossier object in the policy. When defining a policy, it will not be necessary to value the “Tasks” object, because it contains all the characteristics necessary to define the signature actions.

6.6 - Graphometric signature envelope creation

To create a graphometric signature envelope, simply call the insertEnvelope service taking care to insert the necessary variations(par. 4.1, Item trustLevelCode). The changes act on the “GRAPHO_FEA” trustLevelCode and on the array of actionDefs which have signature actions with type “G” (stands for Graph-metric) and a confString to be correctly valued based on the role of the actor, signatory or contractor and the type of data the field will store.

Below is an example of the actionDefs section for a graphometric envelope:

"trustLevelCode" : "GRAPHO_FEA",
"actionDefs" : [ {
"docExternalId" : "GRAPHO_DOC01",
"type" : "G",
"mandatory" : true,
"appearance" : {
"blankSignatureFieldName" : "FEA_FIRMA_F_001_001_001_MARIO_ROSSI_30226320"
},
"confString" : "{"graphFieldName":" FEA_FIRMA_F_001_001_001_MARIO_ROSSI_30226320","graphFieldDesc":"Firmatario","graphSignerRole":"Contraente","graphSignerName":"Mario Ros-si","customSignatureText":"Firmato da Mario Rossi"}"
}, {
"docExternalId" : "GRAPHO_DOC01",
"type" : "G",
"mandatory" : true,
"appearance" : {
"blankSignatureFieldName" : "FEA_FIRMA_F_001_001_PAOLO_ROSSI_30226320"
},
"confString" : "{"graphFieldName":" FEA_FIRMA_F_001_001_PAOLO_ROSSI_30226320","graphFieldDesc":"Firmatario","graphSignerRole":"Firmatario","graphSignerName":\” ","customSignatureText":"Firmato da Paolo Rossi"}"
]

  • Customer Corporate – Grapho Corporate (CC-CC)

The following example illustrates the creation of a graphometric signature envelope from a usrSgrMgrCC user. The user usrSgrMgrCC is both secretary and manager and belongs to the Corporate customer identified by customerCodeCC

{
"insertEnvelopeRequest": {
"customerCode": "customerCodeCC",
"envelope": {
"externalId": "EXTID_0011579014885584",
"subject": "Oggetto:Tue Jan 14 16:14:45 CET2020",
"starred": "false",
"loadedByExtId": "usrSgrMgrCC",
"sysGenerator": "EXT",
"corporateUseType": "P",
"sendingMode": "IMD",
"commonMessage": {
"subject": "Test CC-CC",
"text": "testo"
},
"processDef": {
"tasks": {
"taskDef": {
"order": "1",
"type": "T",
"actorExpr": "usrSgrMgrCCU",
"action": "WRK",
"certType": "I",
"howMany": "1",
"actionDefs": {
"actionDef": {
"docExternalId": "extDocId1579014885584",
"mandatory": "true",
"type": "G",
"appearance": {
"compassPage": "1",
"compassPosition": "1"
},
"confString": {
"visibilityStatus": "V"
}
}
}
}
}
},
"trustLevelCode": "GRAPHO_FEA",
"documents": {
"document": {
"title": "titolo doc1",
"mimeType": "application/pdf",
"originalFname": "test-tag.pdf",
"externalId": "extDocId1579014885584",
"bytes": "JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBl..."
}
}
}
}
}
}

  • Customer Corporate – Grapho Mass Market (CC-MM)

The following example illustrates the creation of a graphometric signature package from a secretary user usrSgrCC. The user usrSgrCC belongs to the Corporate customer identified by customer-CodeCC. The signatory user is of the mass market type and is identified for example by nore-ply+mm@example.com. See how the taskDef section is defined:

{
"insertEnvelopeRequest": {
"customerCode": "customerCodeCC",
"envelope": {
"externalId": "EXTID_0011579014885584",
"subject": "Oggetto:Tue Jan 14 16:15:45 CET2020",
"starred": "false",
"loadedByExtId": "usrSgr",
"sysGenerator": "EXT",
"corporateUseType": "P",
"sendingMode": "IMD",
"commonMessage": {
"subject": "Test CC-MM",
"text": "testo"
},
"processDef": {
"tasks": {
"taskDef": {
"order": "1",
"type": "T",
"actorExpr": "noreply+mm@example.comU",
"action": "WRK",
"certType": "I",
"howMany": "1",
"actionDefs": {
"actionDef": {
"docExternalId": "extDocId1579014885584",
"mandatory": "true",
"type": "G",
"appearance": {
"compassPage": "1",
"compassPosition": "1"
},
"confString": {
"visibilityStatus": "V"
}
}
}
}
}
},
"trustLevelCode": "GRAPHO_FEA",
"documents": {
"document": {
"title": "titolo doc1",
"mimeType": "application/pdf",
"originalFname": "test-tag.pdf",
"externalId": "extDocId1579014885584",
"bytes": "JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBl..."
}
}
}
}
}
}

  • Customer Mass Market – Grapho Mass Market (MM-MM)

The following example illustrates the creation of a graphometric signature envelope from a mass market user noreply+mm@example.com. The user is both secretary and manager and belongs to a Mass Market customer identified by customerCodeMM.

{
"insertEnvelopeRequest": {
"customerCode": "customerCodeMM",
"envelope": {
"externalId": "EXTID_0011579014885584",
"subject": "Oggetto:Tue Jan 14 16:15:45 CET2020",
"starred": "false",
"loadedByExtId": "noreply+mm@example.com",
"sysGenerator": "EXT",
"corporateUseType": "P",
"sendingMode": "IMD",
"commonMessage": {
"subject": "Test MM-MM",
"text": "testo"
},
"processDef": {
"tasks": {
"taskDef": {
"order": "1",
"type": "T",
"actorExpr": "noreply+mm@example.comU",
"action": "WRK",
"certType": "I",
"howMany": "1",
"actionDefs": {
"actionDef": {
"docExternalId": "extDocId1579014885584",
"mandatory": "true",
"type": "G",
"appearance": {
"compassPage": "1",
"compassPosition": "1"
},
"confString": {
"visibilityStatus": "V"
}
}
}
}
}
},
"trustLevelCode": "GRAPHO_FEA",
"documents": {
"document": {
"title": "titolo doc1",
"mimeType": "application/pdf",
"originalFname": "test-tag.pdf",
"externalId": "extDocId1579014885584",
"bytes": "JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBl..."
}
}
}
}
}
}

7 - SOAP notification service to external systems

This section describes the SOAP notifications that GoSign can send to the external system. The prerequisite is that the external system implements a SOAP service described by WorkNotificationsService.wsdl.

7.1 - SOAP processing notification service

To communicate the envelope status changes to the external system in push mode, GoSign calls at a suitable time a SOAP notification service that the external system must implement. The definition of this service is contained in the file WorkNotificationsService.wsdl.

Notifications available are as follows:

Notification Description
SIGN_PROCESS_ENDED end of the signature process (case without stranger users, with at least one signature action)
PROCESS_CANCELLED the envelope was cancelled by the secretary
VA_PROCESS_ENDED end of signature process (case without stranger users, with only or approval or read actions)
STEP_CLOSED completed process step (a recipient has completed its authorization step)
ENVELOPE_REJECTED A manager rejected the envelope

The notification features the following structure:

  • workNotification
    • envelopeExternalId (mandatory, tipo xs:string)
    • notificationType (mandatory, tipo xs:string, ristretto a SIGN_PROCESS_ENDED, PROCESS_CANCELLED, ENVELOPE_REJECTED, STEP_CLOSED, VA_PROCESS_ENDED)
    • note (optional, tipo xs:string)
    • documents (optional)
      • (lista di) document (almeno uno)
        • docExternalId (mandatory, tipo xs:string)
        • content (optional)
          • mime-type (mandatory, tipo xs:string)
          • data (mandatory, tipo xs:base64Binary, codifica Base64)
    • liveStatus (mandatory)
      • (lista di) stepEvent
        • mgrExternalId (optional, tipo xs:string)
        • fromMgrExternalId (optional, tipo xs:string)
        • mgrName (mandatory, tipo xs:string)
        • mgrSurname (mandatory, tipo xs:string)
        • status (mandatory, tipo xs:string)
        • startedAt (mandatory, tipo xs:dateTime)
        • endedAt (optional, tipo xs:dateTime)
        • assignedTo (optional, tipo xs:string)
        • stepNumber (mandatory, tipo xs:int)
        • actionsResume (conteggi delle action lavorate e non)
          • actions (mandatory, tipo xs:int)
          • signActions (mandatory, tipo xs:int)
          • approveActions (mandatory, tipo xs:int)
          • viewActions (mandatory, tipo xs:int)
          • viewedActions (mandatory, tipo xs:int)
          • approvedActions (mandatory, tipo xs:int)
          • initialsActions (mandatory, tipo xs:int)
          • initialedActions (mandatory, tipo xs:int)
          • signedActions (mandatory, tipo xs:int)
          • confirmedActions (mandatory, tipo xs:int)
          • graphometricActions (mandatory, tipo xs:int)
          • filledGraphometricActions (mandatory, tipo xs:int)

The field envelopeExternalId is the id of the envelope used during the load the file in the field ExternalID. NotificationType indicates the type of notification and its value is one of the constants indicated in the table above. The field Note contains the note of rejection in case of notification ENVELOPE_REJECTED.

The list of documents contains the documents in the envelope. The content below contains the bytes of the document encoded in base64, along with the content-type. This list is only available for notification types where the approval process is completed successfully: SIGN_PROCESS_ENDED, SIGN_PROCESS_ENDED_WSUPPL, VA_PROCESS_ENDED.

The liveStatus with stepEvent represents the process status upon notification. They are designed to be directly usable for display to the user. In practice, they transpose the process status table for a specific envelope onto a web interface:

Field names are related to columns in the table. In particular:

  • Step: stepNumber
  • Assigned to: AssignedTo
  • Participants: mgrSurname mgrName
  • State: status
  • Actions: actionsResume
  • Start / end date: startedAt/endedAt

The structure actionsResume contains the action counters. For example, the number of signature actions to be confirmed (signActions) or already confirmed (signedActions), those of approval or visa, the total of those to be confirmed (confirmedActions), and the overall total (actions).

The optional field fromMgrExternalId is valued only when a replacement is active for the specific process step: the field shows the external identifier of the original manager replaced by mgrExternalId which is the current assignee of the process step.

Following the notification, GoSign notes the response of the external system, which must follow the following scheme:

  • workNotificationResponse (mandatory)
    • success (mandatory, type xs: boolean)
    • (list of) errors (optional)
      • code (mandatory, type xs: string)
      • message (mandatory, type xs: string)

Based on the response, GoSign determines the outcome of the notification:

  • if success, is set to true, the notification has been successful and will not be repeated by GoSign
  • if success, is set to false, the notification is marked as failed and the possible content of errors are logged. GoSign will retry the notification at regular intervals.

7.2 - SOAP service for envelope processing verification

It may happen than GoSign fails to process an envelope for a variety of reasons, including:

  • The user lost his or her signature authorisation after the envelope was loaded to GoSign
  • The envelope has already been processed on the external system

GoSign can be configured to make a check on the eligibility of the envelopes for processing on the external system during their signature.

For example, suppose the user ABC123 has signed 10 envelopes, of which 3 are loaded from an external system, while the others are directly created in GoSign by a secretary. When the user confirms their signatures (regardless of whether this was done via web or tablet), GoSign, during the signature transaction, calls a SOAP web service exposed by the external system, which thus influences the signing process.

This SOAP service is the method getEnvelopeExternalStatus defined in the file WorkNotificationsService.wsdl, the implementation of which is up to the external system.

The request follow the structure:

  • userExtId (mandatory, type xs: string)
  • (list of) envelopeExtIdList (optional, type xs: string)

Specifies the user ID whose status is requested and the list of envelopeds to be checked. In the example, GoSign would specify ABC123 as userExtId, and the codes of 4 individual envelopes loaded by the external system, contacted in as many envelopeExtIdList nodes.

An example of a SOAP request follows:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:getEnvelopeExternalStatusRequest xmlns:ns2="http://www.infocert.it/smartsign/schema/wknotif">
<userExtId>userExtID</userExtId>
<envelopeExtIdList>extEnve1</envelopeExtIdList>
<envelopeExtIdList>extEnve2</envelopeExtIdList>
<envelopeExtIdList>extEnve3</envelopeExtIdList>
<envelopeExtId-List fromUserExtId="userExtIDSubstituted">extEnve4</envelopeExtIdList>
</ns2:getEnvelopeExternalStatusRequest>
</soap:Body>
</soap:Envelope>

Note that in the fourth envelope is specified the non-mandatory attribute fromUserExtId which indicates to the external system that for the package with external extEnve4 id is active a substitution where userExtId takes the place of userExtIDSubstituted.

The service response has the following format:

  • envelopeStatuses
    • userExtId (optional, tipo xs:string)
    • userAllowedToWork (optional, tipo xs:boolean)
    • userReason (optional, tipo xs:string)
    • globalEnvelopeAction (optional, tipo xs:string ristretto a NOP e DELETE)
    • (lista di) envelopeStatuses
      • extId (mandatory, tipo xs:string)
      • workable (mandatory, tipo xs:boolean)
      • reason (optional, tipo xs:string)
      • action (optional, tipo xs:string)

The meaning of which is:

Field Description
userExtId The user ID (the same as in the request) may not be specified should this be inconsistent with the particular external system responding to the request.
userAllowedToWork true if all envelopes indicated in the request can be processed by the user, false otherwise
userReason A descriptive text in the event that userAllowedToWork is false; can be shown to the user
globalEnvelopeAction Action to be performed on the envelopes indicated in the request when userAllowedToWork is set to false, or on the individual envelope when its specific action is not specified (see below)

The field envelopeStatuses is the list of processing states for an individual envelope.

Field Description
extId Envelope Id
Workable if the envelope can be processed by the user set a “true”
Reason A descriptive text when workable is setted at “false”; can be displayed to the user
Action Action to be taken on the envelope when “workable “is setted at false

The compilation and evaluation rules are as follows:

userAllowedToWork envelopeStatuses globalEnvelopeAction Description
true Specified Not specified The envelopeStatuses are scrolled through and the specific actions applies to the non-workable envelopes
true Specified Specified The envelopeStatuses are scrolled through and the specific action is applied to non-workable envelopes; if lacking, the globalEnvelopeAction is applied
false Not specified Specified Apply the globalEnvelopeAction to all envelopes the status of which is required

Actions available for both globalEnvelopeAction and for envelope-specific actions are:

Action Description
NOP No operation: the envelope or envelopes are not processed
DELETE No operation: the envelope or envelopes are automatically deleted.

In our example, if:

userAllowedToWork = false
globalEnvelopeAction = NOP

then all the three verified envelopes would remain in the state prior to the signing transaction, while the other seven envelopes would be confirmed and processed in GoSign.

If instead:

userAllowedToWork = false
globalEnvelopeAction = DELETE

then all three verified envelopes would be deleted, while the other seven envelopes would be confirmed and processed in GoSign.

The system do the same when userAllowedToWork is set to true, with the difference that the action performed on the envelopes would be that specified in the sub-element envelopeStatuses, according to the evaluation rules described in the previous table.

An example of SOAP response follows:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:getEnvelopeExternalStatusResponse xmlns:ns2="http://www.infocert.it/smartsign/schema/wknotif">
<envelopeStatuses>
<userExtId>userExtID</userExtId>
<envelopeStatuses>
<extId>extEnve1</extId>
<workable>true</workable>
<action>NOP</action>
</envelopeStatuses>
<envelopeStatuses>
<extId>extEnve2</extId>
<workable>true</workable>
<action>NOP</action>
</envelopeStatuses>
<envelopeStatuses>
<extId>extEnve3</extId>
<workable>true</workable>
<action>NOP</action>
</envelopeStatuses>
</envelopeStatuses>
</ns2:getEnvelopeExternalStatusResponse>
</soap:Body>
</soap:Envelope>

One further SOAP response example, which also shows a non-workable envelope:

<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
<soap-env:Header/>
<soap-env:Body>
<nm:getEnvelopeExternalStatusResponse xmlns:nm="http://www.infocert.it/smartsign/schema/wknotif">
<envelopeStatuses>
<userExtId>DOUGLAS</userExtId> <userAllowedToWork>true</userAllowedToWork>
<userReason>Pratica 4201010142 in sospeso, permesso non accordato</userReason> <globalEnvelopeAction>NOP</globalEnvelopeAction>
<envelopeStatuses>
<extId>4201010142_0</extId>
<workable>true</workable>
</envelopeStatuses>
<envelopeStatuses>
<extId>4201010142_1</extId>
<workable>true</workable>
</envelopeStatuses>
<envelopeStatuses>
<extId>4201010142_2</extId>
<workable>false</workable>
<reason>Pratica 4201010142 in sospeso, permesso non accordato</reason>
<action>NOP</action>
</envelopeStatuses>
</envelopeStatuses>
</nm:getEnvelopeExternalStatusResponse>
</soap-env:Body>
</soap-env:Envelope>

The workNotification and the getExternalStatus services must be exposed on the same host.

8 - REST notification service to external systems

This section describes the REST notifications that GoSign can send to the external system. The prerequisite is that the external system implements a REST service described by GosignWorkNotificationREST.yaml. This file contains the OpenApi specification of notification and process verification services.

8.1 - REST services Authentication

The services can be developed by implementing an authentication logic chosen from the following protocols:

  • Pubblic (not authentication required)
  • Basic
  • Api-key

Public authentication allows you to activate REST notifications to servers that respond to public URLs that do not require credentials for sending and receiving calls.

Basic authentication, on the other hand, requires the implementation of the HTTP Basic Au-thentication protocol. As is known, in this case the external system must provide GoSign with a username and password for access.

The third type of authentication requires GoSign to insert an header (with a configurable name) containing a text (called api-key, configurable) for each REST request. It is useful if the called endpoint provides authentication in which access to the service is guaranteed if the client presents a secret text (a key) known to both partners.

8.2 - REST Service of Ping

To check the availability of the integration system it is necessary that the external system takes care of creating a ping service starting from the URL base, on the

GET /status

method, without any parameters.

The simplest answer in which the external system declares that all services are available and operational is the following:

{
"online": true
}

It is also possible to report the definitive or temporary unavailability of individual services by adding the “services” field and acting on the “online” and “available” parameters:

{
"online": true,
"services": {
"getStatus": {
"online": true
},
"send": {
"online": true,
"available": false
}
}
}

The “services” field is optional, if not present all the services are given as available; if present, the only services available will be those labeled as “online” equal to true and not with “available” equal to false.

8.3 - Service REST of work notification

In order to report changes in dossier status to the external system in a push mode, GoSign calls (at an right time) a REST notification service which the external system must implement.

The service must be exposed starting from the base URL on path:

POST /envelopes/{enveExtId}/notify

There are two types of notification that differ from the JSON content sent to the external system.

8.3.1 - WorkNotification format

This payload is characterized by the notificationType field which directly indicates the type of notification created. It can have the following values:

Notification Type Description
STEP_CLOSED Process task ended (a user has completed its processing)
SIGN_PROCESS_ENDED End of the envelope manufacturing process with at least one signature action
VA_PROCESS_ENDED End of the envelope manufacturing process with all and only approval or checked actions
ENVELOPE_REJECTED A manager refused the envelope
PROCESS_CANCELLED The envelope was canceled by the secretariat

If not all types are useful to the external system, it is possible, during GoSign configuration, to request that one or more of these types of notification be inhibited.

The notification has a JSON body described in the GosignWorkNotificationREST.yaml file;

an example below:

{
"envelopeExternalId": "string",
"notificationType": "SIGN_PROCESS_ENDED",
"note": "string",
"documents": [
{
"docExternalId": "string",
"content": {
"mimeType": "string",
"data": "string"
}
}
],
"liveStatus": [
{
"mgrExternalId": "string",
"fromMgrExternalId": "string",
"mgrName": "string",
"mgrSurname": "string",
"status": "string",
"startedAt": "2019-09-06T11:04:48.141Z",
"endedAt": "2019-09-06T11:04:48.141Z",
"assignedTo": "string",
"stepNumber": 0,
"actionResume": {
"actions": 0,
"signActions": 0,
"approveActions": 0,
"viewActions": 0,
"approvedActions": 0,
"initialsActions": 0,
"initialedActions": 0,
"signedActions": 0,
"confirmedActions": 0,
"graphometricActions": 0,
"filledGraphometricActions": 0
}
}
]
}

There are three mandatory fields:

  • envelopeExternalId
  • notificationType
  • liveStatus (array di stepEvent)

There are two optional fields:

  • documents (array of document, at last one)
  • note

Document contains the following fields:

  • docExternalId
  • content
    • mime type
    • data

stepEvent contains the following fields:

  • mgrExternalId (optional)
  • fromMgrExternalId (optional)
  • mgrName
  • mgrSurname
  • status
  • startedAt
  • endedAt (optional)
  • stepNumber
  • actionResume

actionResume, contained in stepEvent, contains the following fields, all required:

  • actions
  • signActions
  • approveActions
  • viewActions
  • viewedActions
  • approvedActions
  • initialsActions
  • initialedActions
  • signedActions
  • confirmedActions
  • graphometricActions
  • filledGraphometricActions

The envelopeExternalId field is the envelope id used when loading the envelope in the externalId field while notificationType indicates the type of notification and its value is one of the constants indicated in the previous table. The note field contains the rejection note in case of ENVELOPE_REJECTED notification.

The list of documents are the documents present in the envelope. The content contains the base64-encoded bytes of the document together with the content-type. This list is present only for the types of notifications where the approval process is successful, i.e. SIGN_PROCESS_ENDED and VA_PROCESS_ENDED.

The liveStatus with the stepEvent represents the status of the process at the instant of the notification. They are designed to be directly usable for viewing by the user. In practice they are the transposition of the process status table in the detail of an envelope in the web interface:

The names of the fields are related to the columns of the table. In particular::

  • Step: stepNumber
  • Assigned to: assignedTo
  • Actors: mgrSurname mgrName
  • Status: status
  • Action: actionsResume
  • Data start/end: startedAt/endedAt

The actionsResume structure contains the action counts. For example, there are the number of signature actions to be confirmed (signActions) or confirmed (signedActions), those of approval or checked, the total of those to be confirmed (confirmedActions) and the grand total (actions).

The optional field fromMgrExternalId is only enhanced when a replacement for the specific process step is active: the field shows the external identifier of the original manager replaced by mgrExternalId which is the current assignee of the process step.

Following the notification, GoSign observes the response of the external system, which must respect the following JSON scheme:

{
"outcome": "...",
"message": "..."
}

The content of the outcome field and the http response state determine GoSign’s behavior:

Outcome HTTP status Description
succeeded 2xx Successful notification.
failed_please_retry 2xx Notification failed, GoSign will try to send it by re-try.
failed_please_discard 2xx Notification failed, GoSign will not try to send it again as the notification is, for example, misaligned with the systems status.
any expected or unexpected value Any value other than 2xx Notification failed, GoSign will try to send it again indefinitely as the 4xx or 5xx status is considered a server-side error, resulting in a potential untrusted call

The outcome field can have the following values: “succeeded” (notification successful, not to be retried again), “failed_please_retry” (notification failed, could be successful if repeated in the future, not too soon), “failed_please_discard” (notification failed and cannot be completed , for example for reasons of misalignment between systems; GoSign is requested not to retry the notification and to note the “message” received as the cause of the rejection of this notification, for example in “tag”)

For any value of the outcome field the HTTP code must be 2xx, any HTTP status other than 2xx is considered as a “failed_please_retry“. Similarly, a malformed JSON or other communication errors are interpreted by GoSign exactly as a “failed_please_retry“.

The “message” field is always optional, even if it is recommended to use it if “outcome” is “failed_please_retry” or “failed_please_discard“. It should be noted that “failed_please_discard“, for the purpose of the notification workflow, behaves exactly as “succeeded” but, in addition, it allows the external system to note in GoSign the reason (“message“) for which the notification was completed, but without producing results on the system itself.

8.3.2 - Extended Format

If the information provided by the previous payload is not sufficient for the external system, a second notification format is available with many more details on the notified package. Its use can be configured in GoSign on request.

{
"externalId": "ABCDE-123456-DEFR",
"code": "TT0RJ62Y5",
"subject": "Invio sharepoint",
"status": "WKD",
"previousStatus": "PGS",
"starred": false,
"createdAt": 1573837182000,
"completedAt": 1573837225000,
"loadedByExtId": "mrossi",
"loadedByName":
{
"surname": "Rossi",
"name": "Mario",
"email": "mario.rossi@example.com",
"organizationUnit": null,
"title": null,
"timezone": "Europe/Rome",
"company": null,
"externalId": "mrossi"
},
"docClass":
{
"name": "CL02",
"label": "Classe 02",
"fields": [
{
"name": "FLD02_01",
"label": "Campo 02/01",
"type": "T",
"textValue": "cmp02",
"fieldOrder": 1
},
{
"name": "FLD02_02",
"label": "Campo 02/02",
"type": "D",
"dateValue": 1574722800000,
"fieldOrder": 2
},
{
"name": "FLD02_03",
"label": "Campo 02/03",
"type": "N",
"numericValue": 123.28,
"fieldOrder": 3
},
{
"name": "FLD02_04",
"label": "Campo 02/04",
"type": "L",
"textValue": "Opzione 02",
"fieldOrder": 4
},
{
"name": "FLD02_05",
"label": "Campo 02/05",
"type": "L",
"textValue": "Opzione multi 02|Opzione multi 03",
"fieldOrder": 5
}]
},
"process":
{
"status": "C",
"startedAt": 1573837214000,
"finishedAt": 1573837225000,
"liveStatus": [
{
"mgrExternalId": "abianchi",
"fromMgrExternalId": null,
"mgrName": "Anna",
"mgrSurname": "Bianchi",
"status": "WKD",
"startedAt": 1573837214000,
"endedAt": 1573837225000,
"assignedTo": "Bianchi Anna (abianchi)",
"stepNumber": 1,
"actionsResume":
{
"actions": 1,
"signActions": 0,
"signedActions": 0,
"approveActions": 1,
"approvedActions": 1,
"viewActions": 0,
"viewedActions": 0,
"batchSignedActions": 0,
"initialsActions": 0,
"initialedActions": 0,
"confirmedActions": 1,
"registerActions": 0,
"registeredActions": 0,
"filledFreeTextActions": 0,
"freeTextActions": 0,
"graphometricActions": 0,
"filledGraphometricActions": 0
}
}]
},
"type": "STD",
"expiresAt": 1577746800000,
"expiresAtTimezoneID": "Europe/Rome",
"note": null,
"corporateUseType": "C",
"sendingMode": "DRF",
"documents": [
{
"bytes": "JVBERi0xLjMK....TIKJSVFT0YK",
"title": "test3pagine",
"createdAt": 1573837209000,
"mimeType": "application/pdf",
"originalFname": "test3pagine.pdf",
"externalId": "BGTF-9876-KIDHS",
"docType": "D",
"docOrder": 0
}],
"commonMessage":
{
"subject": "Invio sharepoint",
"text": "Anna Bianchi sent you a new dossier"
},
"messages": [
{
"usrExtId": "abianchi",
"text": "Specific message to Anna"
}],
"usersInCC": [
{
"externalId": "lverdi",
"surname": "Verdi",
"name": "Luigi",
"email": "lverdi@example.com"
}],
"sysGenerator": "TST",
"trustLevelId": 3,
"notes": [
{
"text": "Example note",
"createdAt": 1574777671000,
"name": "Anna",
"surname": "Bianchi"
},
{
"text": "Mr. Verdi note",
"createdAt": 1574778076000,
"name": "Luigi",
"surname": "Verdi"
}]
}

As you can see, this json does not have the notificationType field pre-calculated by GoSign so it is the external system that will have to determine what happened to the envelope using, for example, the status and previousStatus fields. Indeed:

State Description
WKD Envelope worked successfully
REJ Dossier rejected by a recipient
STP Plico canceled by a secretariat
STO Archived envelope. To find out what the actual closing status was, check previousStatus which can be WKD, REJ or STP

All other fields of this JSON have already been described in the previous sections of this document. Of course, not all fields will always be present.

For example, if the envelope does not present the documental class, then the relative docClass field will not be present.

The response expected by GoSign from the external system is the same as the previous type of payload.

8.4 - REST processing notification service

Sometimes it can happen that an envelope created by an external system cannot be processed in GoSign for various reasons, including:

  • The user has been removed from signing permission after the envelope has been uploaded to GoSign
  • The envelope has already been processed on the external system

In these cases GoSign can be configured to carry out a check on the workability of the envelopes on the external system during the signature transaction.

For example, suppose that the user ABC123 has 10 envelopes signed, of which 3 uploaded by an external system while the others have been created directly in GoSign by the secretariat. When the user confirms his signatures (indifferently on the web or tablet side), during the signature transaction GoSign calls the REST service to verify workability exposed by the external system N times where N is the number of envelopes loaded by a system external, which thus has a way of influencing the signing process.

This REST service will have to be exposed by the external system, starting from the URL base, in this way:

GET /envelopes/{enveExtId}/managers/{userExtId}/status
GET /envelopes/{enveExtId}/managers/{userExtId}/for/{originalUserExtId}/status

The second form is used when the userExtId replacement is active for the originalUserExtId user.

The method must return to the caller an HTTP 2xx code and a JSON with the result of the workability verification which contains the following fields:

  • workable – boolean indicating workability.
  • reason – String describing the reason for non-workability in case workable is false. It can be viewed by the end user to indicate why the signature was blocked.
  • action – string that describes the action performed on the envelope in case workable is false. The possible values are NOP (no action will be performed on the non-workable envelope) and DELETE (the non-workable envelope will be automatically deleted).

This is an example of a request:

{
"workable": false,
"reason": "User permission expired",
"action": "NOP"
}

In this case, the envelope is not workable by the user (workable = false) for a reason provided by the system (reason: “user permission expired”) and no action will be taken on the non-workable envelope.

In the previous URLs, originalUserExtId is the extId of the user who, before a replacement, had been called to sign, enveExtId is the id of the file, while userExtId is the extId of the user called to work on the file.

During GoSign configuration, it is possible to inhibit calls to the getEnvelopeExternal-Status service if no workability verification policies are necessary in the external system or if there are no workability verification policies.

The workNotification and the getExternalStatus services must be exposed on the same host.

9 REST API Services (OAuth2)

Unlike the previous services, whose authentication is managed through the API KEY / TOKEN (Customer Code) mechanism, for the REST API services, the OAuth2 protocol can be used. Access to the exposed resources takes place after verification of the validity of an AccessToken received from the Get access token call.

Compared to what has been described in the previous sections, these services are based on a simplified data model which maintain the basic concepts of Envelope, Document, etc, but eliminates less important information and limits the domain of the values assumed for some fields; for example the loadedByExtId field , in the insertEnvelope service, is optional because the user who insert the dossier is extrapolate from the bearerToken .

In order to simplify the use, these services meet OpenAPI specifications and are accompanied by YAML file attached GoSignOAuthAPI_V2.yaml.

9.1 - Get access Token

Through this call, a GoSign user is able to retrieve, after a successful validation, an AccessToken OAuth2 that allows to invoke all the REST calls described in this section.

HTTP METHOD POST
HTTP HEADERS https://webapp.gosign.digital/gosign/oauth/token?grant_type=password&username=<username>&password=<password>&client_id=<idClient>&client_secret=<pswClient> 
HOST authorization-server.com

  • grant_type=password
  • &amp;username=user@example.com
  • &amp;password=123456
  • &amp;client_id=xxxxxxxxxx
  • &amp;client_secret=xxxxxxxxxx

The request, as specified by OAuth2 standard, must include the following parameters:

INPUT PARAMETRS TYPE DESCRIPTION
grant_type mandatory  must be set to “password”.
username mandatory  The username of the user.
password mandatory  The user’s password.
scope optional  Specify the purpose of the request (read / write)
client_id mandatory  ID that identifies the client in GoSign.
client_secret mandatory  Secret key to authorize the client to make requests to GoSign.

The client_id and client_secret parameters, although mandatory, can be omitted if the request includes an HTTP Basic auth in the header.

Below is an example of response.

{
"access_token": "cd95zx0b-1g69-4a8e-b5a3-y8ed15a7630h",
"token_type": "bearer",
"expires_in": 1987683,
"scope": "read write"
}

9.2 - InsertEnvelope

Using this call, it is possible to insert an envelope and to obtain, as response to the parameters passed in the request, a ResultCode or the file just inserted.

After obtaining an AccessToken, then, through the call below, it is possible to store a package in GoSign.

HTTP METHOD POST
HTTP HEADERS https://webapp.gosign.digital/gosign/secure/oauth/api/v2/envelopes
AUTHORIZATION Bearer Token : cd95zx0b-1g69-4a8e-b5a3-y8ed15a7630h
CONTENT-TYPE application/json

In addition to the AccessToken, the parameters necessary for entering an envelope are:

INPUT PARAMETRS TYPE DESCRIPTION
responseWithEnvelope optional if true, when the file is correctly entered, GoSign responds with the file; default value: false
usersInCC optional Specifies which users should be included in CC for the case just entered. They can be identified through external_id or with Name Surname and email address.
envelope mandatory It is the simplified representation of the dossier for which insertion is requested. For details relating to all the attributes of the Envelope; refer to the YAML document.

Below is an example of parameters necessary for entering an envelope:

{
"envelope": {...}
},
"usersInCC": null,
"responseWithEnvelope": true
}

Below is an example of a response to an InsertEnvelope with responseWithEnvelope set to false.

{
"code": "OK",
"message": "Successfull"
}

Below an insertEnvelope schema description:

POST /services /secure/oauth/api/v2/envelopes

Object Format InsertEnvelopeRequest to be included in the request body:

{
usersInCC“: [ { Array Optional Object to insert a CC users;  Specifies which users should be included in CC for the case just entered. They can be identified through external_id or with Name Surname and email address
email“: “string”, string Optional the e-mail address of the user in cc
externalId“: “string”, string Optional the externalIdentifier of the user in cc
name“: “string”, string Optional the name of the user in cc
surname“: “string” string Optional the surname of the user in cc
}],
responseWithEnvelope”: true, Boolean Optional if true, when the file is correctly entered, GoSign responds with the file; default value: false
envelope“: {
subject“: “envelopeSubject”, String Mandatory Object of the envelope (can be manipulated later by GoSign in a variety of contexts)
starred“: false, Boolean Optional Flag “Urgent”, optionally available externally and with a default value of ‘false’
externalId“: “myenve05”, String Mandatory The external id of the envelope, to be specified by the external system
sendingMode“: “IMMEDIATE”, String Optional Envelope send mode; if ‘IMMEDIATE’ the process starts as you insert the envelope if ‘DRAFT’ the process must be manually started by the same user who create a dossier;it determines the mandatory nature of the procDef field (see below).
UseType“: “CORPORATE”, String Optional The scope of use of the envelope according to level of confidentiality. Possible values ​​”PUBLIC”, “CORPORATE”.
trustLevel“: “INTERNAL_PDF” , String Mandatory Envelope trust level code, chosen from “DIGITAL_PDF”, “DIGITAL_P7M”, “INTERNAL_PDF”, “FEA”, “GRAPHO_FEA”; In the event of an incompatible trust level, GoSign will refuse to insert the envelope.  In case of trust level = FEA, it is not possible to upload a document already signed

In order to use the FEA signature with OTP or QUICKSTART FEA, this field should be null
sysGenerator“: “EXT”, String Optional The system that generated the envelope.
commonMessage“:{ Optional Message to be sent to all users
text“:”text of message”, String Mandatory Message text
userMessages“: [{ Optional Message to be sent to a specific user
text“: “text of message”, String Optional Message text
userExtId“: “id2” String Optional User ID
}]
},
documents“:[{}] Array Mandatory List of documents to be uploaded (at least 1)
docClass“:{ Optional Document class to be assigned to the document
name“: “DC01” String Mandatory docClass name, required if you are using a policy or a docClass.
fields”: [{ Array Envelope document class definition, one of *value field is required.
name“:”fieldname”, String Mandatory Name of the field
dateValue“:21451245212212, Date Optional Date field value (expressed as the number of milliseconds elapsed from 00:00 January 1, 1970)
numericValue“:0, Double Optional Value of the numeric field
textValue“:”string” String Optional String field value
}]
},
procDef“:{ Process definition, only required if sendingMode ‘IMMEDIATE’, optional with sendingMode ‘DRAFT’.
tasks“:[{}] List of tasks that make up the process (see task-Def in the following table).
newUsers“:[{}] Optional New User definition
}}}

The tasks object consists of:

tasks”:[{
type“: “HUMAN”, String Mandatory Type of the taskdef, possible values: – HUB

– HUMAN

– EXTERNAL

– THIRD_PARTY

– AUTO (logging or sending mail)

– SUBPROCESS

Task type – ‘HUMAN’ is the most common (requires human intervention for a variety of actions, such as sign, initials, approval, read).

order“: 1, Integer Mandatory Task order, used to indicate serious and parallel processes through the WS.
actorExpr“: “id1R|id2U”, String Mandatory List of managers / roles involved, according to the following scheme: xR: role with id = x – yU: manager with id = y – | (pipe) OR logical – Example: id1R | id2U.
action“: “WORK”, String Mandatory Process action, possible values:

– WORK

– WORK_EXT

– REGISTRATION

– GRAPHOMETRIC

– EDIT_ENVELOPE

– MODIFY_PROC

– SEND_MAIL

– SEAL

howMany“: 1, Integer Mandatory Number of actors needed to close the task, default 1. May be 1, 2, 3, or 4.
actionDefs“: [{}], Signature actions definition.
confString“: “{ “signAllVisible”:”V”}”, String Optional Configuration JSON string; the signAllVisible key defines the visibility of the “Sign all” button and can be set to “V” – button visible or “N” – button not visible.
}]

The documents object, in turn, is composed of:

documents“:[{
bytes“:”docbytes”, String Mandatory Document bytes encoded in Base64. It is not possible to upload a document that already has a signature with field trust level = FEA.
externalId“:”extId”,

 

String Mandatory To be completed by the external system to allow identification of the document regardless of the internal mechanisms of GoSign.
mimeType“:”string”, String Mandatory Type of document, to be completed by the external system. In addition, GoSign will be able to change the value following format conversions or for certain trust levels.
title“:”doctitle”, String Mandatory Title of the document, to be completed by the external system.
originalFname“:”f.pdf”, String Mandatory Name of the original file including extension.
uri“: file://nome_file.pdf Path Optional Indicates the URI from which to load the document, when the payload is not defined, or the bytes field, in the request.
}],

The item actionDef, in turn, is composed as follows

actionDefs“: [{
docExternalId“: “ext42”, String Mandatory External id of the document on which this action is placed.
type“: “SIGN”, String Mandatory Type of action required on the document, possible values:

  • SIGN
  • APPROVE
  • VIEW
  • INITIALS
  • PROTOCOL
  • FREE_TEXT
  • APPROVAL_DATE
  • FIRST_NAME
  • LAST_NAME
  • FULL_NAME
  • OTHER_DETAILS
  • GRAPHOMETRIC
  • SEAL
mandatory“: true, Boolean Mandatory Defines mandatory action; always true except graphometric signature (internal use).
confString“: “{}”, String Optional String json containing approved action flags, text and signature visibility configurations.
appearance“: { Signature action positioning algorithm, one and only one property between compassAppearance,coordAppearance and tagAppearance is to be compiled and required.
blankSignatureFieldName“:        “sign_here”, String Optional Name of the empty signature field in which to sign.
compassAppearance“: { Positioning on the page using the dials.
page“: 1, Integer Mandatory Number of the page where to sign, starting from 1, or one of the following special values:

  • -1 (last page)
  • -2 (all pages)
  • -3 (first and last page)
position“: “BOTTOM_RIGHT_SOUTH_EAST” String Optional Position in which to sign, chosen from:

  • INVISIBLE
  • TOP_NORTH
  • TOP_LEFT_NORTH_WEST
  • TOP_RIGHT_NORTH_EAST
  • CENTRAL
  • CENTRAL_LEFT_EAST
  • CENTRAL_LEFT_WEST
  • BOTTOM_SOUTH
  • BOTTOM_LEFT_SOUTH_WEST
  • BOTTOM_RIGHT_SOUTH_EAST
},
coordAppearance“: { Only in the case of signature by coordinates
llx“: 0, number Mandatory X coordinate of the lower left corner of the action placeholder
lly“: 0, number Mandatory Y coordinate of the lower left corner of the action placeholder.
page“: 1, Integer Mandatory Number of the page on which to sign, starting from 1, or one of the following special values:

  • -1 (last page)
  • -2 (all pages)
  • -3 (first and last page)
urx“: 0, number Mandatory X coordinate of the lower right corner of the action placeholder.
ury“: 0 number Mandatory Y coordinate of the lower right corner of the action placeholder.
},
invisible“: false, boolean Optional Defines if the action is invisible on the document. Default false
tagAppearance“: { Only in the case of positioning by tag
cornerType“: “”, String Optional Type of positioning identified:

  • SINGLE_BOTTOM_LEFT_CORNER_TYPE
  • BOTTOM_LEFT_TOP_RIGHT_RECT_TYPE
  • TOP_LEFT_BOTTOM_RIGHT_RECT_TYPE

“Positioning type – ‘SINGLE_BOTTOM_LEFT_CORNER_TYPE’ lower left corner of text first tag, ‘BOTTOM_LEFT_TOP_RIGHT_RECT_TYPE’ both tags top right, ‘TOP_LEFT_BOTTOM_RIGHT_RECT_TYPE’ both tags bottom right.”

endTagPattern“: “end$$1”, String Optional String to be searched in the document to identify the other end of the rectangle in which to place the tag
startTagPattern“: “start$$1”, String Optional String to be searched in the document to identify the initial end of the rectangle in which to place the tag
xoffset“: 0, number Optional Defines a horizontal offset in points on the PDF with respect to the X coordinate of the identified tag.

Examples of use:

  • a null xOffset or equal to 0, does not alter the positioning of the action
  • an xOffset of 50, translates the positioning of the action by 50 points to the right
  • an xOffset equal to -100, translates the positioning of the action by 100 points to the left
yoffset“: 0 number Optional Defines a vertical offset in points on the PDF with respect to the Y coordinate of the identified tag.

Examples of use:

  • a null yOffset or equal to 0, does not alter the position of the action
  • a yOffset of 50 translates the position of the action upwards by 50 points
  • a yOffset equal to -100, translates the positioning of the action downwards by 100 points
}}]

The newUsers object consists of:

newUsers“:[{
username“:”lrossi@mail.it”, String Mandatory Username to access the application
name“:”Luigi”, String Mandatory Name of the user
surname“:”Rossi”, String Mandatory User surname
phoneNumber“:”+3901234567”, String Optional* Telephone number whith country code included. Useful to send stranger OTP;Mandatory for SignatureType= Fea_Otp
email“:” lrossi@mail.it “, String Mandatory Email address
externalId“:”lrossi@mail.it”, String Mandatory External ID of the user
newUserStrategy“:”ACCEPT_ALWAYS”, String Mandatory Possible values:

ACCEPT_ALWAYS

REJECT_IF_DIFFERENT

REJECT_ALWAYS

EMAIL_BASED

Refer to chapter 6.2 for definitions.

roles“:[“STRANGER”

],

Array Mandatory Possible roles to be assigned to the user:

  • MANAGER
  • SECRETARY
  • STRANGER
company“: “string”, string Optional
organizationUnit“:”string”, string Optional
fiscalCode“: “string”, string Optional
title“: “string”, string Optional
enabled“: true, boolean Optional
}]

Using the confString attribute within the field task of the envelope, you can configure the sending of the invitation email to the stranger and the email with the signed documents at the end of the process. The tag is configurable with the following boolean attributes:

INPUT PARAMETRS TYPE DESCRIPTION
receiveInvitationMailToSign optional invitation mail to the stranger
receiveCompletedEnvelopeMail optional mail with documents signed at the end of the process

Example of the confString field with a value:

{
"envelope": {
...
"procDef": {
...
"tasks": [{
...
"confString": "{"receiveInvitationMailToSign":true,"receiveCompletedEnvelopeMail":false}",
...
}]
}
},
}

Example of InsertEnvelope Request:

{
"envelope": {
"useType": "CORPORATE",
"externalId": "TEST08092020",
"subject": "subject of envelope",
"sysGenerator": "EMA",
"sendingMode": "IMMEDIATE",
"trustLevel": "INTERNAL_PDF",
"starred": true,
"confString": null,
"joinDocuments": null,
"documents": [{
"externalId": "document ID",
"title": "Title of document",
"mimeType": "application/pdf",
"originalFname": "Name_Document.pdf",
"uri": null,
"bytes": " to insert PDF in Base64"
}],
"docClass": null,
"commonMessages": {
"text": "insert TEXT viewable at Front End as a message",
"userMessages": null
},
"procDef": {
"tasks": [{
"type": "HUMAN",
"confString": "{"receiveInvitationMailToSign":true,"receiveCompletedEnvelopeMail":true}",
"order": 1,
"actorExpr": "User of the recipient_signer_practice&U",
"action": "WORK",
"howMany": 1,
"actionDefs": [{
"docExternalId": "like as documents external ID",
"type": "SIGN",
"mandatory": true,
"confString": null,
"appearance": {
"invisible": true,
"annotationContent": null,
"coordAppearance": {
"llx": 100,
"lly": 100,
"page": 1,
"urx": 200,
"ury": 200
}
}
}]
}]
}
},
"usersInCC": null,
"responseWithEnvelope": true
}}

Example of InsertEnvelope Response:

OK

{
"type": "TYPE_STANDARD",
"useType": "CORPORATE",
"externalId": "TEST08092020",
"subject": "subject of envelope ",
"sysGenerator": "EMA",
"sendingMode": "IMMEDIATE",
"trustLevel": "INTERNAL_PDF",
"starred": true,
"documents": [
{
"externalId": "document ID",
"title": "Title of document",
"mimeType": "application/pdf",
"originalFname": "Name_Document.pdf",
"bytes": "Base64 PDF"
}
],
"commonMessages": {
"text": "TEXT viewable at Front End as a message"
}
}

KO

Case 1: external ID of the Envelope is not unique

{
"code": "RETURN_STATUS_ENVELOPE_ALREADY_EXISTS",
"message": "Envelope already exists - extEnveId = TEST08092020"
}

KO

Case 2: external ID of the document is not unique

{
"code": "MULTILPLE_DOCS_WITH_SAME_EXT_ID",
"message": "Multiple docs with the same external id - extDocId = exter-nal_id_document"
}

For more response in ko, see the attached YAML

9.3 - GetEnvelope

Through this call, it is possible to retrieve, if present, an envelope identified by the value of the ExternalID. The request requires that the ExternalID of the dossier to be collected is passed as the parameter of the URL. There are two versions of the same request; the one that provides only the basic information and the one that also provides the bytes of the documents. To invoke the version with documents, just add, after the value of the ExternalID, the path / withDocuments.

The two examples show the getEnvelope call, respectively, with and without documents.

GetEnvelope withDocuments

HTTP METHOD GET
HTTP HEADERS https://webapp.gosign.digital/gosign/secure/oauth/api/v2/envelopes/ TEST08092020/withDocuments
AUTHORIZATION Bearer Token : cd95zx0b-1g69-4a8e-b5a3-y8ed15a7630h
CONTENT-TYPE application/json

Example of GetEnvelope Response withDocuments :

{
"type": "TYPE_STANDARD",
"useType": "CORPORATE",
"externalId": "TEST08092020",
"subject": "subject of envelope",
"sysGenerator": "EMA",
"sendingMode": "IMMEDIATE",
"trustLevel": "INTERNAL_PDF",
"starred": true,
"documents": [
{
"externalId": "document ID",
"title": "Title of document",
"mimeType": "application/pdf",
"originalFname": "Name_Document.pdf",
"bytes": "PDF in Base64"
}
],
"commonMessages": {
"text": "insert TEXT viewable at Front End as a message"
}
}

GetEnvelope “simple”

HTTP METHOD GET
HTTP HEADERS https://webapp.gosign.digital/gosign/secure/oauth/api/v2/envelopes/TEST08092020
AUTHORIZATION Bearer Token : cd95zx0b-1g69-4a8e-b5a3-y8ed15a7630h
CONTENT-TYPE application/json

Example of GetEnvelope Response

{
"type": "TYPE_STANDARD",
"useType": "CORPORATE",
"externalId": "TEST08092020",
"subject": "subject of envelope",
"sysGenerator": "EMA",
"sendingMode": "IMMEDIATE",
"trustLevel": "INTERNAL_PDF",
"starred": true,
"documents": [
{
"externalId": "document ID",
"title": "Title of document",
"mimeType": "application/pdf",
"originalFname": "Name_Document.pdf"
}
],
"commonMessages": {
"text": "insert TEXT viewable at Front End as a message"
}
}

9.4 - DeleteEnvelope

Call that allows you to delete, if present, the envelope indicated in the URL and identified by its Ex-ternalID. Notification emails are also sent to users (if enabled).

Returns the outcome of the transaction.

Example of a cancellation request and two possible replies (one positive and one negative).

HTTP METHOD POST
HTTP HEADERS https://webapp.gosign.digital/gosign /secure/oauth/api/v2/envelopes/ TEST08092020/delete/
AUTHORIZATION Bearer Token : cd95zx0b-1g69-4a8e-b5a3-y8ed15a7630h
CONTENT-TYPE application/json

Example of DeleteEnvelope Response:

OK

{
"code": "OK",
"message": "Successfull"
}

KO

{
"code": "ENVELOPE_NOT_FOUND",
"message": "The id requested does not exist or access is denied - extEnveId = TEST08092020"
}

9.5 - GetUrl

The following service, useful to facilitate the operation of a stranger user, is used to retrieve the url to reach the signature page.

HTTP METHOD GET
HTTP HEADERS https://webapp.gosign.digital/gosign/secure/oauth/getUrl?command=sign&envelopeExtId= TEST08092020&extUserId=manager_test%2B25@gmail.com&extRedirect=http%3A%2F%2Fwww.google.com
AUTHORIZATION Bearer Token : cd95zx0b-1g69-4a8e-b5a3-y8ed15a7630h
ACCEPT text/plain

The necessary parameters are the following:

 

INPUT PARAMETRS TYPE of variable TYPE DESCRIPTION
command String Mandatory Insert value=sign for calls to the signature action
envelopeExtId String Mandatory The External ID of required envelope created
extUserId String Mandatory The External ID of the user whose signature is to be collected
extRedirect String optional Url that GS calls at the end of the processing of the envelope by the user, that is at the end of the process. It can be any url, even with a query string. To avoid problems remember to apply an url encoding before inserting it in the parameter
disableNavBar Boolean optional If true it disables (deletes) the GS top bar. Useful if the generated url is used in an Iframe
inIFrame Boolean optional It must be set to true if the generated url is used in an Iframe

Example of GetUrl Response:

OK

https://webappcl.gosign.digital/gosign/mLink?mLinkParam=YjFrMzU3ZjhZTmlvb2Y5bHl0Y3lCT3NwUElPb1pOeHFOc1ctRE0xcmZmelFmZXZGa1Zha0FCRkVXTVVWdmhDaHhJOEpHLWpEa043U1V1YmxrNU91X2l4d1VSWXdVMnotZmdqWTd6YlNPQ1h0aG02dW5VSENVN1hkSFJGdDZ2TzJDQmlSNllnVDVhd0tpRXJZTDIwbDlyY0MyQTlZa1FHMlVjdmxEVU5nR1I2TG5ieDduWmhDMGYxNW9TRWJ0TEhX

KO

{
"error": "invalid_token",
"error_description": "Invalid access token: e2c32a3e-2c43-4708-80a2-3fb282a3990"
}

9.6 - GetEnvelopeStatus

Given the external ID, the following service is used to recover the status of an envelope.

HTTP METHOD GET
HTTP HEADERS https://webapp.gosign.digital/gosign/ secure/oauth/api/v2/envelopes/ TEST08092020/status
AUTHORIZATION Bearer Token : cd95zx0b-1g69-4a8e-b5a3-y8ed15a7630h

Below is an example of GetEnvelopeStatus Response:

OK

“IN_PROGRESS”

The possible values returned by the service are:

  • DRAFT
  • IN_PROGRESS
  • TO_CONFIRM
  • WORKED
  • TO_REJECT
  • REJECTED
  • EXPIRED
  • DELETED
  • STORED
  • TO_ERASE
  • TEMPORARY
  • CANCELLED

9.7 - Using signature types in REST API Services (from software version 5 only)

REST API services have been partially extended in GoSign 5.

Using the address <base_url_gosign>/oauth/api/gs5/v2, it is possible to use the endpoints already available in GoSign 4 with the following differences:

  • Do not specify the TrustLevel (no longer in use in GoSign 5) in the InsertEnvelope request 
  • Specify in the same request, for each single task, a signatureType attribute
  • The signatureType can be set with one of the following values:
    • SIMPLE : Simple signature
    • SIMPLE_PWD : Simple signature with password
    • SIMPLE_PWD_USA : Simple signature with password and process log
    • DIGITAL_PDF : PDF digital signature
    • DIGITAL_P7M : P7M digital signature
    • FILE : Signature with P12 certificate
    • GRAPHOMETRIC : Graphometric signature
    • FEA_OTP : Advanced electronic signature with OTP (more details in next section)
    • QUICKSTART_FEA : Quickstart Advanced electronic signature (more details in QUICKSTART FEA section)

Each customer has a set of available signature types, enabled by the system administrator.

If a not enabled signature type is used, the InsertEnvelope call fails, returning the error code SIGNATURE_NOT_ENABLED_EXCEPTION.

9.7.1 - FEA OTP

To sign whit Fea_otp signature on Gs5, exploiting the backward compatibility of the gs4 API, is mandatory:

  • Use the OAuth2 APIs
  • set the trustLevel field = null
  • insert the signatureType = FEA_OTP attribute within the Object Task

The tasks object, in turn, is composed of:

The tasks object consists of:

tasks”:[{
type“: “HUMAN”, String Mandatory Type of the taskdef, possible values: – HUB

– HUMAN

– EXTERNAL

– THIRD_PARTY

– AUTO (logging or sending mail)

– SUBPROCESS

Task type – ‘HUMAN’ is the most common (requires human intervention for a variety of actions, such as sign, initials, approval, read).

order“: 1, Integer Mandatory Task order, used to indicate serious and parallel processes through the WS.
actorExpr“: “id1R|id2U”, String Mandatory List of managers / roles involved, according to the following scheme: xR: role with id = x – yU: manager with id = y – | (pipe) OR logical – Example: id1R | id2U.
action“: “WORK”, String Mandatory Process action, possible values:

– WORK

– WORK_EXT

– REGISTRATION

– GRAPHOMETRIC

– EDIT_ENVELOPE

– MODIFY_PROC

– SEND_MAIL

– SEAL

howMany“: 1, Integer Mandatory Number of actors needed to close the task, default 1. May be 1, 2, 3, or 4.
actionDefs“: [{}], Signature actions definition.
confString“: “{ “signAllVisible”:”V”}”, String Optional Configuration JSON string; the signAllVisible key defines the visibility of the “Sign all” button and can be set to “V” – button visible or “N” – button not visible.
signatureType“: “FEA_OTP”, String Optional [From software version 5 only]
The “signatureType” field must be filled in only if the “trustLevel” field is null
}]

 

Below is an example:


"tasks": [
{
"action": "WORK",
"actionDefs": [
{
"appearance": {
"blankSignatureFieldName": "string",
"compassAppearance": {
"page": 0,
"position": "INVISIBLE"
},
"coordAppearance": {
"llx": 0,
"lly": 0,
"page": 0,
"urx": 0,
"ury": 0
},
"invisible": true,
"tagAppearance": {
"cornerType": "SINGLE_BOTTOM_LEFT_CORNER_TYPE",
"endTagPattern": "string",
"startTagPattern": "string",
"xoffset": 0,
"yoffset": 0
}
},
"confString": "string",
"docExternalId": "string",
"mandatory": true,
"type": "SIGN"
}
],
"actorExpr": "string",
"howMany": 1,
"order": 1,
"type": "HUB",
"confString": "string",
"signatureType": "FEA_OTP"

9.7.2 - CREATING A STRANGER WITH FEA OTP

Following the requirements described in the previous paragraph, to create a stranger user in case of signature_type = FEA_OTP, the following parameters must be specified in the Object newUsers of the call structure:

  1. “phoneNumber” [including the country code]
  2. “countryCode”
  3. “serialType”
  4. “fiscalCode”

 

The newUsers object consists of:

newUsers“:[{
username“:”lrossi@mail.it”, String Mandatory Username to access the application
name“:”Luigi”, String Mandatory Name of the user
surname“:”Rossi”, String Mandatory User surname
phoneNumber“:”+3901234567”, String Optional* Telephone number whith country code included. Useful to send stranger OTP;Mandatory for SignatureType= Fea_Otp
email“:” lrossi@mail.it “, String Mandatory Email address
**”emailLanguage“: “it”, String Optional language for email communications (it|en|es|pt|fr|de)
**”adDomain“: null, String Optional Active directory domain
**”timezone“: null, String Optional user timezone (Eg. ‘Eu-rope/Rome’|’America/Los_Angeles’)
**”countryCode“:”it”, String Optional* Country code of user in ISO 3166-1 alpha-2 format; maxLength: 2 ; example: “it”. Mandatory for SignatureType= Fea_Otp
**”serialType“:”TIN”, String Optional* Type of serial number (PAS|IDC|PNO|TIN…); maxLength: 4 . Mandatory for SignatureType= Fea_Otp.Supported values:

  • PAS: Passport serial number
  • IDC: National Identity Card serial number
  • TIN: Tax Identification Number according to the European Commission
externalId“:”lrossi@mail.it”, String Mandatory External ID of the user
newUserStrategy“:”ACCEPT_ALWAYS”, String Mandatory Possible values:

ACCEPT_ALWAYS

REJECT_IF_DIFFERENT

REJECT_ALWAYS

EMAIL_BASED

Refer to chapter 6.2 for definitions.

roles“:[“STRANGER”

],

Array Mandatory Possible roles to be assigned to the user:

  • MANAGER
  • SECRETARY
  • STRANGER
company“: “string”, string Optional
organizationUnit“:”string”, string Optional
fiscalCode“: “string”, string Optional
title“: “string”, string Optional
enabled“: true, boolean Optional
}]

** the fields delimited with a double asterisk refer exclusively to version 5 of the software and THEY MUST NOT BE USED for version 4.

9.7.3 - QUICKSTART FEA

To sign with Quickstart Fea signature on Gs5, exploiting the backward compatibility of the gs4 API, is mandatory:

  • Use the OAuth2 APIs
  • set the trustLevel field = null
  • insert the signatureType = QUICKSTART_FEA attribute within the Object Task
  • Insert only one task, parallel tasks are not allowed for Quickstart Fea.

 

The tasks object consists of:

“tasks”:[{
“type“: “HUMAN”, String Mandatory Type of the taskdef, possible values:

  • HUB
  • HUMAN
  • EXTERNAL
  • THIRD_PARTY
  • AUTO (logging or sending mail)
  • SUBPROCESS

Task type ‘HUMAN’ is the most common (requires human intervention for a variety of actions, such as sign, initials, approval, read).

“order“: 1, Integer Mandatory Task order, used to indicate serious and parallel processes through the WS.
“actorExpr“: “id1R|id2U”, String Mandatory List of managers / roles involved, according to the following scheme: xR: role with id = x – yU: manager with id = y – | (pipe) OR logical –

Example: id1R | id2U.

“action“: “WORK”, String Mandatory Process action, possible values:

  • WORK
  • WORK_EXT
  • REGISTRATION
  • GRAPHOMETRIC
  • EDIT_ENVELOPE
  • MODIFY_PROC
  • SEND_MAIL
  • SEAL
“howMany“: 1, Integer Mandatory Number of actors needed to close the task, default 1. May be 1, 2, 3, or 4.
“actionDefs“: [{}], Signature actions definition.
“signatureType“:

“QUICKSTART_FEA”,

String Optional [From software version 5 only]

The “signatureType” field must be filled in only if the “trustLevel” field is null

}]

Below is an example:


"tasks": [
{
"action": "WORK",
"actionDefs": [
{
"appearance": {
"blankSignatureFieldName": "string",
"compassAppearance": {
"page": 0,
"position": "INVISIBLE"
},
"coordAppearance": {
"llx": 0,
"lly": 0,
"page": 0,
"urx": 0,
"ury": 0
},
"invisible": true,
"tagAppearance": {
"cornerType": "SINGLE_BOTTOM_LEFT_CORNER_TYPE",
"endTagPattern": "string",
"startTagPattern": "string",
"xoffset": 0,
"yoffset": 0
}
},
"confString": "string",
"docExternalId": "string",
"mandatory": true,
"type": "SIGN"
}
],
"actorExpr": "string",
"howMany": 1,
"order": 1,
"type": "HUB",
"confString": "string",
"signatureType": "QUICKSTART_FEA"

9.7.4 - DIGITAL PDF WITH IDENTIFICATION

To sign with Quickstart Fea signature on Gs5, exploiting the backward compatibility of the gs4 API, is mandatory: 

  • Use the OAuth2 APIs
  • set the trustLevel field = null
  • insert the signatureType = DIGITAL_PDF attribute within the Object Task
  • add the entry “requiredIdentification”:true to the confString attribute withing the Object Task
  • Insert only one task, parallel tasks are not allowed for Quickstart Fea. 

 

The tasks object consists of:

“tasks”:[{
“type“: “HUMAN”, String Mandatory Type of the taskdef, possible values:

  • HUB
  • HUMAN
  • EXTERNAL
  • THIRD_PARTY
  • AUTO (logging or sending mail)
  • SUBPROCESS

Task type ‘HUMAN’ is the most common (requires human intervention for a variety of actions, such as sign, initials, approval, read).

“order“: 1, Integer Mandatory Task order, used to indicate serious and parallel processes through the WS.
“actorExpr“: “id1R|id2U”, String Mandatory List of managers / roles involved, according to the following scheme: xR: role with id = x – yU: manager with id = y – | (pipe) OR logical –

Example: id1R | id2U.

“action“: “WORK”, String Mandatory Process action, possible values:

  • WORK
  • WORK_EXT
  • REGISTRATION
  • GRAPHOMETRIC
  • EDIT_ENVELOPE
  • MODIFY_PROC
  • SEND_MAIL
  • SEAL
“howMany“: 1, Integer Mandatory Number of actors needed to close the task, default 1. May be 1, 2, 3, or 4.
“actionDefs“: [{}], Signature actions definition.
confString: “{ “requiredIdentification”:true}”,  String Mandatory Configuration JSON string;

the requiredIdentification key defines if the identification is required.

signatureType: “DIGITAL_PDF”,  String Optional [From software version 5 only]

The “signatureType” field must be filled in only if the “trustLevel” field is null

}]

Below is an example:


"tasks": [
{
"action": "WORK",
"actionDefs": [
{
"appearance": {
"blankSignatureFieldName": "string",
"compassAppearance": {
"page": 0,
"position": "INVISIBLE"
},
"coordAppearance": {
"llx": 0,
"lly": 0,
"page": 0,
"urx": 0,
"ury": 0
},
"invisible": true,
"tagAppearance": {
"cornerType": "SINGLE_BOTTOM_LEFT_CORNER_TYPE",
"endTagPattern": "string",
"startTagPattern": "string",
"xoffset": 0,
"yoffset": 0
}
},
"confString": "{"requireIdentification"=true}",
"docExternalId": "string",
"mandatory": true,
"type": "SIGN"
}
],
"actorExpr": "string",
"howMany": 1,
"order": 1,
"type": "HUB",
"confString": "string",
"signatureType": "DIGITAL_PDF"

10 - Example of insertEnvelope in three different ways

Below is an example of a call made with Rest, Rest Oauth2 and soap services:

REST REST Oauth2 SOAP
{
externalSystemCode“: “EMA”,
customerCode“: “14f931920776cd8c2f6b4d25020505a1”,
addUsersInCC“: [{
externalId“: “manager_1”
},
{
externalId“: “manager_2”
}
],
envelope“: {
subject“: “TestEnvelope”,
sysGenerator“: “EMA”,
corporateUseType“: “C”,
trustLevelCode“: “INTERNAL_PDF”,
externalId“: “id_della_pratica1”,
loadedByExtId“: “segr_test”,
sendingMode“: “IMD”,
documents“: [{
externalId“: “id_del_documento1”,
title“: “attestato”,
mimeType“: “application/pdf”,
originalFname“: “attestato.pdf”,
bytes“: “Body64”
}],
docClass“: null,
commonMessages“: {
text“: “Message for envelope”,
userMessages“: null
},
procDef“: {
tasks“: [{
action“: “WRK”,
type“: “T”,
actorExpr“: “managerU”,
order“: 1,
howMany“: 1,
confString“: “{“signAllVisible”:”V”}”,
actionDefs“: [{
docExternalId“: “id_del_documento1“,
type“: “S”,
mandatory“: true,
confString“: “{“actionInTCF”:”true”},
appearance“: {
invisible“: false,
coordAppearance“: {
page“: 1,
llx“: 65,
lly“: 198,
urx“: 164,
ury“: 231
}
}
}],
newUsers“: [{
username“: “stranger_ext”,
name“: “Test”,
surname“: “Stranger”,
phoneNumber“: “3482259422”,
email“: “stranger.test@.it”,
externalId“: “stranger_ext”,
newUserStrategy“: “ACCEPT_ALWAYS”,
userAuthorities“: [{
username“: “stranger_ext”,
authority“: “ROLE_STRANGER”
}]
}]
}]
}
}
}
{
usersInCC“: [{
externalId“: “manager_1”
},
{
externalId“: “manager_2”
}
],
envelope“: {
subject“: “TestEnvelope”,
sysGenerator“: “EMA”,
useType“: “CORPORATE”,
trustLevel“: “INTERNAL_PDF”,
externalId“: “id_della_pratica1”,
sendingMode“: “IMMEDIATE”,
documents“: [{
externalId“: “id_del_documento1”,
title“: “attestato”,
mimeType“: “application/pdf”,
originalFname“: “attestato.pdf”,
bytes“: “Body64”
}],
docClass“: null,
commonMessages“: {
text“: “Message for envelope”,
userMessages“: null
},
procDef“: {
tasks“: [{
action“: “WORK”,
type“: “HUMAN”,
actorExpr“: “managerU”,
order“: 1,
howMany“: 1,
confString“: “{“signAllVisible”:”V””
},
actionDefs“: [{
docExternalId“: “id_del_documento1”,
type“: “SIGN”,
mandatory“: true,
confString“: {
\
“actionInTCF”:”true”},
appearance“: {
invisible“: false,
coordAppearance“: {
page“: 1,
llx“: 65,
lly“: 198,
urx“: 164,
ury“: 231
},
newUsers“: [{
username“: “stranger_ext”,
name“: “Test”,
surname“: “Stranger”,
phoneNumber“: “3482259422”,
email“: “stranger.test@.it”,
externalId“: “stranger_ext”,
newUserStrategy“: “ACCEPT_ALWAYS”,
roles“: [“STRANGER”]
}]
}
}]
}
]
}
}
}
<addUsersInCCRequest>
<externalId>manager_1</externalId>
<externalId>manager_2</externalId>
</addUsersInCCRequest> <customerCode>14f931920776cd8c2f6b4d25020505a1</customerCode>
<envelope>
<subject>TestEnvelope</subject>
<sysGenerator>EMA</sysGenerator>
<corporateUseType>C</corporateUseType>
<trustLevelCode>INTERNAL_PDF</trustLevelCode>
<externalId>id_della_pratica1</externalId>
<loadedByExtId>segr_test</loadedByExtId>
<sendingMode>IMD</sendingMode>
<documents>
<document>
<externalId> id_del_documento1</externalId>
<title> attestato </title>
<mimeType>application/pdf</mimeType>
<originalFname> attestato.pdf </originalFname>
<bytes>Body64</bytes>
</document>
</documents>
<docClass>null</docClass>
<commonMessage>
<subject>test insertenvelope</subject>
<text>Message for envelope</text>
</commonMessage>
<processDef>
<tasks>
<taskDef>
<action>WRK</action>
<type>T</type>
<actorExpr>managerU</actorExpr>
<order>1</order>
<howMany>1</howMany>
<actionDefs>
<actionDef>
<docExternalId> id_del_documento1 </docExternalId>
<type>S</type>
<mandatory>true</mandatory>
<confString>{“actionInTCF”:”true”}</confString>
<appearance>
<llx>65</llx>
<lly>100</lly>
<page>1</page>
<urx>164</urx>
<ury>150</ury>
</appearance>
</actionDef>
</actionDefs>
</taskDef>
</tasks>
<newUsers>
<username>stranger_ext</username>
<name>Test</name>
<surname>Stranger</surname>
<phoneNumber>+3912345678980</phoneNumber>
<email>stranger@example.com</email>
<externalId>stranger_ext</externalId>
<newUserStrategy>ACCEPT_ALWAYS</newUserStrategy>
<userAuthorities>
<username> stranger_ext </username>
<authority>ROLE_STRANGER</authority>
</userAuthorities>
</newUsers>
</processDef>
</envelope>
</insertEnvelopeRequest>
</soapenv:Body>
</soapenv:Envelope>

11 - LegalBus with REST proxy

With this integration methodology, the following services are available:

  • Asynchronous envelope insertion
  • Notification on envelope processing completion
  • Intermediate and end-of-processing notifications

Envelope insertion occurs via the same REST call that can be used with the REST approach.

The differences are as follows:

  • The insertion REST call is asynchronous: the response given by the server is just the acknowledgement of the operation
  • End of insertion notification (OperationDoneEvent) occurs after the initial REST call, and is accomplished by calling a SOAP WebService that the calling system must implement (the WSDL is available)

REST insertion call

The JSON request and response are identical to those of the REST approach. In the response message, the field code contains OK, while the field message holds an ID to allow associating the request with the subsequent end-of-insertion notification.

The HTTP response status code is 200 or 204.

End-of-insertion notification

This notification is sent by GoSign to the service EvelopeEventService, which the external system must implement. The WSDL definition of this service is EvelopeEventService.wsdl.

The operation is called OperationDone and the SOAP request fields are as follows:

  • OperationDoneEvent
    • ID: Allows connecting this event with the original asynchronous request; corresponds to the value of the message field of the initial REST call result
    • command: In general, is the name of the asynchronous operation to which this event is associated; for insertion, is insertEnvelope
    • extId: External system ID specified as parameter in the original asynchronous operation; for insertion, corresponds to the field ExternalID of Envelope in the JSON request
    • details: Any additional details, blank in insertEnvelope
    • returnStatus
      • code: Result code, OK for successful operation
      • message: Extended text message

Possible values ​​of code:

VALUES DESCRIPTION
product_expired Expired subscription
bad_doc_format One or more invalid documents
document_class_error Wrong document class or fields
illegal_argument Parameter error
cust_not_found customerCode not found
user_not_found One or more recipients could not be found
return_status_envelope_already_exists There is already an envelope with the same ExternalID
return_status_process_definition_error Wrong process definition
error Generic error

In general, any code other than OK is to be considered as an error.

Envelope processing notifications

These notifications are divided into:

  • intermediates: are sent when a step of the signature process ends
  • end-of-processing: the envelope closes its approval process

In the final step of the process upon which the envelope closes the approval process, only the of end-of-processing notification is sent (that of the closing step is skipped in this case).

At every notification, GoSign calls a WebService that the external system must implement to receive notifications. It is the same service described in the paragraph 6.1.

12 - Rest API Services (Oauth2 with external Identity Provider)

The GoSign’s  Rest APIs, described in chapter 9, allow use of multiple functions, such as the insertion of a dossier through the InsertEnvelope call service, but for the access an Access Token OAuth2 linked to a system user and produced by GoSign is required. It is important highlight that for the insertEnvelope service with OAuth2 authentication, the user who insert the dossier, is  extrapolate from the bearerToken.

To satisfy the requirement of machine-to-machine access, using an external identity provider (such as Azure Active Directory), it is necessary to modify the mechanism for accessing the Rest APIs using Oauth2 tokens.

This authentication system involves all the calls detailed in chapter 9.

In the next sections we will describe what are the activities in charge of the external system, both towards the external identity provider and towards GoSign (because this type of authentication must be enabled).

12.1 - External system registration

The external system must register itself with the identity provider (I.P.) following the appropriate procedures; those may be different from case to case and all the details and the documentation will be provided during the first phase of integration.

For instance, if you are using Azure AD, the tenant id, the Azure version and all the necessary documents for sign up the application in Azure will be provided.

Then, the external system will have to be registered in GoSign. To complete successfully this step, the registration with the identity provider must to be completed and all the keys used for validating the tokens and recognizing the system must be provided to GoSign.

12.2 - Data flow generated during the call from the external system to GoSign

After the registration phase, we can proceed to describe how the external system can call the GoSign APIs.

It will have to perform the following actions:

  • request a JWT token, using the appropriate identity provider endpoint. The technical documentation of the chosen identity provider will be provided. This step is mandatory if:
    • you don’t have a valid JWT token
    • in case of receipt of an “unauthorized” error 401;
  • execute the Rest Api Gosign call by using the JWT token as the “Authorization” Header   and with the “Bearer” type

12.3 - Data flow generated during notification from GoSign to the external system

GoSign, as well as the external system, will request to the identity provider the JWT token and will use as authentication header for all the calls to the external system. This change will involve the getExternalStatus call and all the notifications described in chapter 8.

So, the external system must implement the token verification logic to be able to validate the requests.

Depending on the I.P., the token validation specification can be different and will be provided to the external system.

12.4 - Example – Azure Active Directory:

As an example, we show the structure of a JWT token used for integration where the Identity Provider is AzureAD.

The typical payload of a JWT token has the following structure:

Where is it:

  • “tid” is the tenant id at Azure
  • “aud” is the audience, i.e. the identifier of the API to access to which the token was issued
  • “iss” is the issuer of the token (contains the Azure tenant id, corresponds to the “issuer” field of the OpenID configuration JSON and the “tid” field in this JSON)
  • “nbf” is the token validity start date, expressed in “epoch” (milliseconds since January 1, 1970)
  • “exp” is the expiry date of the token, expressed in “epoch” and usually equal to “nbf” plus an hour (therefore, nbf + 3600)
  • “azp” is the Azure identifier of the app that perform the request

From “iss” you can get the OpenID autoconfiguration URL by adding the suffix “/.wellknown/openid-configuration”.

This structure, and the fields valued in it, must be validated and verified both from GoSign and the external system.

GoSign will perform the following checks when a token is received:

  • Verify the signature of the JWT token
  • Check that the token has the expected format for the “iss” field
  • Check the validity of the token
  • Check the tenantId, “tid” field of the token
  • Check the “aud” field which represents the GoSign API id in the reference environment

If all the previous checks are successful, the execution of the requested API continues, otherwise an HTTP 401 error is returned with a JSON payload containing the description of the first failed check.

Similar checks must be implemented by the external system that need validate the token received from GoSign in the notifications services.