Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Using Adobe EchoSign Electronic Signatures in SAP NetWeaver BPM

vasil_tsimashchuk
Explorer
‎12-19-2013 2:40 PM

In many companies, business processes, in which contracts and agreements are created and sent to external parties for filling and signing, are still the norm. Often, this involves sending a physical document back and forth: from the initial issuer to one or several recipients and back again. Taking into account the time spent for manual interactions and costs incurred by this procedure multiplied by a factor to scale, the opportunity to automate such tasks and to accomplish them electronically becomes priceless. This is where Adobe EchoSign comes into play.

Adobe EchoSign is an electronic signature and Web contracting solution. Its major features focus on document signing, tracking, and filing. It supports signing by email (e-signature) or by fax [1].

In this blog, I am going to elaborate on the topic of integrating Adobe EchoSign services into a business process developed with SAP NetWeaver BPM. To illustrate this routine, I have developed a business process, which involves the creation of an agreement with the SAP NetWeaver BPM environment, sending it for signing to an external party via email, and getting back a notification that the document has been signed. Both, the issuer and the signer of the agreement are expected to fill some custom data into the agreement. The process extensively explores the functionality provided by Adobe EchoSign.

To see a demo of the scenario, please watch the following video:

The blog is organized as follows: first, I describe the use case for the process at hand in greater detail and give an overview of its main parts. After that, a detailed description of each part is provided. I close with a conclusion and references to further information on the topic overall. At the very end of this blog post, you can find an appendix with the points that should be taken into account for productive scenarios.

Use Case

The user story for our business process is as follows:

  • The process deals with an agreement template which is stored in the SAP Enterprise Content Management system (SAP ECM) as a text file.
  • The template contains fields that need to be filled by two parties: internal company manager (an SAP NetWeaver BPM user, who actually owns the process and sends the agreement) and a student (an external person who is supposed to sign the agreement).
  • The process would start with the manager entering the agreement details (name of the hired student and the proposed salary). The manager would also specify the email of the student where the agreement would be sent to.
  • Then, the process would send the agreement with the previously entered data to the Adobe EchoSign Web service, which would then process the request and in turn send an e-mail to the student. The mail would contain a link to an online Adobe EchoSign form.
  • Following the link, the student would be able to fill in his address as well as sign the contract.
  • Finally, the process would be notified that the corresponding document has been signed and provide the manager with the overview of the data filled into the corresponding agreement.

Prerequisites

To be able to integrate the functionality of Adobe EchoSign and SAP NetWeaver BPM, some preparatory steps are required:

  • The Adobe EchoSign SSL certificate should be installed and imported into the system where the process will be run
  • The SAP ECM system should be properly configured

Details are provided at the end of this blog post in the Appendix.

Creating Adobe EchoSign Master Account

To access the online signature features, a master account within Adobe EchoSign has to be created and the corresponding tariff plan needs to be chosen (this can be done here). Depending on the tariff plan, the master account allows creating a number of sub-accounts for different users and assigning relevant permissions and rights to them. This functionality makes a lot of sense for companies where multiple users are expected to send and/or process the agreements. The available functionality depends on the tariff plan, but it is possible to set up a free developer account as a starting point.

Demo BPM Process

We have created a demo process which utilizes the functionality of  Adobe EchoSign. The process involves two parties: a manager (the BPM process owner) and a student (an external party who is supposed to sign the agreement).

The process consists of 4 main parts:

  1. The manager provides the data to be merged into the agreement and specifies the email of the student used for further communication.
  2. The second step is an automatic activity, in which the agreement is actually created from the predefined template and sent to the student via the Adobe EchoSign service.
  3. A sub-process is started, which waits for the document to be signed.
  4. Finally, when the document is signed, the manager receives a task, which provides an overview of the agreement.

In the figure below, the process diagram is shown:

Supplying the Data to Customize the Agreement

In the first task, the manager specifies - in a SAPUI5 UI - the name of the student and proposes a salary. This information will be used in the text of the agreement sent to the student. In addition, the manager specifies the student's email, which is used while sending the agreement for signing. Also, at this stage, we save the principal ID of the task processor in the process context. Afterwards, this is used to obtain his email address to identify the Adobe EchoSign sub-account in the name the agreement is sent.

Sending a Document for an Electronic Signature

Preparing Agreement Template and Filling in the Data Fields

In our process, the manager as well as the student needs to specify some information as part of the agreement. Adobe EchoSign provides an opportunity to achieve this by introducing so-called form fields.

You essentially add tags in a text document (e.g., Microsoft Word, PowerPoint, Excel, .txt or .rtf files) typing in a special string of characters. Adobe EchoSign will automatically find those tags and convert them into properly placed signature blocks, initials, check boxes, radio buttons, and form fields. Advanced optional field processing rules are taken into account as well. This conversion happens when the document is sent for signature or uploaded to the Adobe EchoSign Document Library.

The Adobe EchoSign text tags usually appear between {{ and }}.

The example below shows the text of the agreement which is used in our process:



Dear {{!StudentName}},

We are happy to invite you for a student job in our company with a salary of {{!StudentSalary}} EUR per month.

Please, give us your address and sign this contract:

Address: {{* StudentAddress_es_:signer }}

To get more information about the fields available in the Adobe EchoSign documents, please, refer to this document.

Sending an Agreement

It is possible to access the services provided by Adobe EchoSign in two ways:

The latter is of interest in this blog post. As soon as a master account is created within Adobe EchoSign, a constant unique API key is assigned to it. If you already have a master account, you could find your API key here. This key is used as a parameter for almost all Adobe EchoSign Web services in order to identify the master account, on which behalf the services are executed. In the software component provided with this blog post, the API key must be specified in the web.xml as a parameter. The example software component contains a Web project development component, in which we provide a facade to the Adobe EchoSign Web service. In case you need to access functionality of Adobe EchoSign that is not covered by this facade. I would recommend to extend the facade in this case. The description of all the API functions of the Adobe EchoSign is available, here.

The Adobe EchoSign Web service used for sending a document in the example process is

send(API_KEY apiKey, SenderInfo senderInfo, DocumentCreationInfo documentCreationInfo).

  • The API key refers to the unique key assigned to the master account within Adobe EchoSign.
  • In the sender info, the email and sub-account password are specified either directly or by supplying the user key, which uniquely identifies the sub-account owner. It should be mentioned here that the user must be registered with Adobe EchoSign so that his sub-account matches to the API key supplied in the above parameter. In our process, we take the following steps:
    1. We obtain the email of the user by calling the UME API UMFactory.getUserFactory().getUserByLogonID(String logonId) and passing in the user ID stored in the process context
    2. We then query the Adobe EchoSign service to know whether the user with the corresponding email is registered and either owns the master account or a sub-account, which matches to the corresponding master account: verifyUser(String apiKey, String email, String password).
    3. If the previous requirement is not fulfilled, we create a sub-account for this user within the corresponding master account by calling the Adobe EchoSign API function createUser(String apiKey, UserCreationInfo info).
      It should be mentioned that for real production scenarios, this functionality should be modified to fulfill the security and authorization requirements of your scenario. To this end, the facade to the Adobe EchoSign Web Service, namely EchoSignFacade interface and EchoSignFacadeImpl class, needs to be changed. For an overview of the user management functionality, please, refer to this document.
  • In the document creation info, we specify the following parameters:
    • A list of file infos to be sent: a list of one or more files that will be sent out for signing. The document to be sent can be supplied to the function in two ways:
      • By supplying the agreement file directly. This option is used in our process: in our case, the agreement file is retrieved from the SAP ECM system.
      • By a unique key of a document template in the Adobe EchoSign library.
    • Merged field info: default values for fields to be merged into the document. In our scenario, we use the input of the manager from the previous step (the name of the student as well as the salary offer).
    • The recipient list: the parties who are supposed to sign the agreement. In our case, there is only one recipient (the hired student) whose email address was specified by the manager in the previous task.
    • The name of the agreement: this value is used to identify the agreement in the emails and on the Adobe EchoSign Web site. In our process, this parameter is specified as the title parameter of the StudentHiringProcessMessage message event, which starts the process.
    • Message: a message to the recipient(s) describing what is being sent and/or why their signature is required. In our process, this parameter is specified as the message parameter of the StudentHiringProcessMessage message event, which starts the whole process.
    • Callback info: specifies the URL, which is queried when the status of the document is changed in the Adobe EchoSign document life cycle. The callback mechanism is discussed later in this blog post.

For the full list of parameters that can be specified when an agreement is sent, please, see Adobe EchoSign API methods documentation.

As soon as the document is sent, Adobe EchoSign assigns a unique string document key to it (if the agreement for signing is successfully sent, the Adobe EchoSign API send returns this key as its result). The document key is further used for obtaining the status of the document as well as for getting the data filled into the agreement during sending and signing.

Checking the Status of the Agreement

Adobe EchoSign supports two ways of checking the status of a document:

We have created a generic, reusable process DocumentSigningCheckProcess which implements a timeout pattern and supports both strategies for checking the status of the document. One of the branches of the process expects a callback from Adobe EchoSign. The other branch waits for a certain time period and, if no relevant message arrives during this time period, polls the Adobe EchoSign service to obtain the current status of the document. The process runs in a loop as long as the status of the document is not equal to "SIGNED".

Callback

The lightweight form of checking the status of a document is listening to the callback from Adobe EchoSign. As soon as the status of the document changes, Adobe EchoSign queries (HTTP GET or POST) the URL specified at the sending stage and adds the documentKey and status parameters to it. It can be specified that the agreement is also uploaded to this URL through a POST request.

In our process, we use an intermediate message event to listen to callbacks from EchoSign. The message trigger EchoSignCallBackMessage relates to an asynchronous call-back operation of the EchoSignCallBack Web service. The documentKey and status are the parameters of this operation. The documentKey is used in the correlation condition of the intermediate message event:



string-equal(DocumentKey_DO, CallBack/DocumentKey)

This scenario is preferred in terms of system load. However, it does not guarantee the delivery of the awaited messages (best effort delivery only). That is why it is recommended to also support the alternative way of checking the status of the document, which is not so sensitive to system failures.

Polling

A more reliable (but also performance-heavier) way to check the status of the sent document is to poll the Adobe EchoSign service.

The Adobe EchoSign API getDocumentInfo(String documentId) function is called in this case.

A list of all the agreement statuses in the Adobe EchoSign document lifecycle is available here. In our process, however, we just check whether the status of the document is equal to SIGNED>.

It is not recommended to poll the Adobe EchoSign service too often. In our processes, it is possible to configure the TimeInterval parameter to adjust the polling interval according to your needs. However, these adjustments should be done with care and the corresponding value should be adjusted to the amount of documents which you expect to be sent using the Adobe EchoSign service. For more details and suggestions on the polling strategies, please, refer to the following document.

Retrieving the Input of the Agreement Parties

As soon as the process gets the notification that the agreement has been signed, the process flow proceeds to the next task where the manager can view the information entered by the student in a custom SAPUI5 UI.

To retrieve the agreement details, the following Adobe EchoSign API function is called: getFormData(ApiKey, DocumentKey). The API key refers to the unique identifier of the master account within Adobe EchoSign and the document key is the unique identifier of the document of interest.

Conclusions

In this blog, I briefly described the online signature features provided by Adobe EchoSign and how you can integrate them into SAP NetWeaver BPM. We created an example process which explores the Adobe EchoSign API in order to send an agreement for signing, get a notification when the agreement is signed, and obtain an overview of the signed agreements. The process is modeled generically, easy to extend, and can be used as a starting point for further use cases.

References

  1. Adobe® EchoSign® main page
  2. Article about Adobe® EchoSign® in Wikipedia
  3. Adobe EchoSign White Paper
  4. Creating an Account at Adobe EchoSign
  5. Creating Adobe® EchoSign® Forms with Text Tags
  6. WSDL of the EchoSign Web Service
  7. EchoSign API Main Page (for registered users only)
  8. Sending an Agreement via EchoSign Web Interface (for registered users only)
  9. Description of the EchoSign API functions
  10. EchoSign API Guide
  11. EchoSign Account Management
  12. ECM Community

Appendix: Parameters of the Start Message Event for the Process

The trigger of the start message event for our process relates to the StartHiringProcess operation of the StudentHiringProcess Web service. This operation requires the following parameters to be specified:

  • ApiKey: the unique key assigned to the Adobe EchoSign master account.
  • Title: this value is used to identify the agreement in the emails and on the Web site of Adobe EchoSign.
  • Message: a message to the recipient(s) describing what is being sent and/or why their signature is required.
  • TemplateName: the name of the agreement file in SAP ECM.
  • PollingTimeInterval: time interval in milliseconds, which specifies how often the Adobe EchoSign service will be polled by the system to get updates on the status of the agreement.
  • CallBackUrl: the URL to be queried by the Adobe EchoSign service when the agreement status changes.

Appendix: Productive Considerations

Importing the Adobe EchoSign SSL Certificate

We access the functionality of Adobe EchoSign through the Web service via HTTPS. To be able to call the Web service methods from Java code, the SSL certificate of Adobe EchoSign needs to be installed in the system and imported to the key storage of the JRE. To this end, the following steps should be accomplished:

  1. On the system where SAP AS Java is installed, open the browser. Go to https://secure.echosign.com/public/home, click on the lock in front of the URL (Google Chrome specific), and select the Connection tab.
  2. Click the Certificate information link, choose the Details tab, and choose the Copy to File... button.
  3. Choose Next, and in the opened tab, select Base64-encoded X.509.
  4. Choose the file name, then choose Next and Finish.
  5. To install the certificate on the system, double-click on the saved file and choose Install Certificate... in the opened window. Choose Next twice, and then Finish.
  6. Open the command line in the bin sub-folder of the folder where the SAPJVM JRE is located (here, it is <Diskdrive>:\usr\sap\<Instance>\J00\exe\sapjvm_6\jre).
  7. Run the following command: keytool -importcert -file <path_to_the_downloaded_certificate_file> -keystore ..\lib\security\cacerts -storepass changeit
  8. Confirm the command. Now the certificate has been imported to the key store file.
  9. It might be necessary to restart the system to apply the changes.

Configuring SAP ECM

When dealing with any sort of documents within SAP NetWeaver BPM, a good practice is to store the document in SAP ECM. SAP ECM allows controlling the rights of users who try to access its documents. The software component provided here as an example contains a Web Dynpro development component, namely eswd, which provides the interface to upload and access the documents within SAP ECM. The user of SAP NetWeaver BPM is supposed to have the necessary permissions to the folder where the agreement template is stored. Note, this exemplary ECM integration is not intended to be deployed in  a productive scenario since typically stricter authentication handling needs to be performed for users who are to access the documents in ECM.

Security Issues

As the process provided is intended for demo purposes only, there are several points that should be done for a real productive scenario.

  1. Proper user management and authentication routines for Adobe EchoSign should be implemented that fit the security needs and requirements of your company.
  2. A more secure strategy for SAP ECM authentication should be implemented for cases where users access and/or change the agreement templates.

Download

The SCA archive with the demo process can be downloaded here.

6 Comments
Labels in this area
Popular Blog Posts