Integration Methodologies
with external Applications

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.

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

*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.

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.

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.

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.

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.

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:

The trustLevelCode can be chosen from the following values:

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..

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).

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

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.

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).

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

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

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);

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);

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.

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.

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.

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.

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.

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:

The tasks object, in turn, is composed of:

The documents object, in turn, is composed of:

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

The item  actionDef, in turn, is composed as follows

The newUsers object, in turn, is composed of:

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

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:

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

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:

The object actionsResume has the following structure:

The object process has the following structure:

The object detail is composed as follows:

The message object is composed as follows:

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"
}

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

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",
}
}
}

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
}
}

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"
}
}
}

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.

POST /services /ws/

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

Object Format InsertEnvelopeRequest to be included in the request body:

The AddUsersInCC object, in turn, is composed of:

The envelope object, in turn, is composed of:

The docClass object, in turn, is composed of:

The tasks object, in turn, is composed of:

The documents object, in turn, is composed of:

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

The item actionDefs, in turn, is composed as follows

The newUsers object, in turn, is composed of:

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.

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>

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());

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

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:

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:

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.

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:

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

The compilation and evaluation rules are as follows:

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

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.

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.

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.

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

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"
}

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.

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

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

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

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”

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"
}
}

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).

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"
}

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

The necessary parameters are the following:

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"
}

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

Below is an example of GetEnvelopeStatus Response:

OK

The possible values returned by the service are:

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

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.

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:

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"

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:

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

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:

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"


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:

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"


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