Nearly every company requires documents to be signed in order to facilitate business transactions.
This article was originally posted on our RPG-XML Suite product website.
Some require hundreds or thousands to be processed daily. Gone is the day of the fax machine. Even a document scanner that facilitates the exchange of signed documents via email can be perceived as outdated. Enter Adobe EchoSign.
With RPG-XML Suite, the Adobe EchoSign platform allows IBM i developers to securely send documents for signature, embed the Adobe EchoSign signing experience into their application, track document status in real time and retrieve signed documents including all related data from EchoSign. Developers can also use the EchoSign platform to manage accounts, users and documents.
Let’s take a closer look at page one of the Adobe EchoSign developer documentation:
The Adobe EchoSign eSignature Platform utilizes a Web Services API for communication with external systems. Web Services is a standard based, secure and scalable method of establishing communications between systems over the Web.
The Adobe EchoSign API requires every developer to have a unique API key allowing them to integrate their solution to EchoSign while applying EchoSign’s permission model to the data they can create or access.
The EchoSign APIs are SOAP-based Web Services that allow applications to communicate with the EchoSign service via RPG-XML Suite for building integrations between these external IBM i applications and EchoSign.
Getting Started
Download and install RPG-XML Suite on your IBM i by filling out the form here and following the install instructions http://www.rpg-xml.com/free-trial/.
After RPG-XML Suite has been installed, you can sign up online for a free unlimited Adobe EchoSign Developer account at https://secure.echosign.com/public/upgrade?type=developer. As part of the registration process developers will receive an API key allowing them to use the eSignature Platform along with code samples and other resources. Note the API Key is CASE SENSITIVE and should be used exactly in the form provided by EchoSign within your integration.
Key developer resources:
• EchoSign API WSDL: https://secure.echosign.com/redirect/latestApiWsdl
• EchoSign API Documentation: https://secure.echosign.com/redirect/latestApiMethods
Working with EchoSign APIs
The EchoSign APIs can be used to build a variety of different integrations from external applications residing on IBM i. These integrations can enable users working in an external application to initiate transactions within EchoSign to get documents signed entirely from within the external application. The external application can also receive status updates for initiated transactions and retrieve a copy of the signed agreements for storage in the external system.
Lets look at a couple of integration scenarios between an external system and EchoSign and walk through the details of building the integration through the API.
Sending a document for signature: To send a document out for signature through the EchoSignAPI, call the sendDocument method. The application will specify the recipients, files and other sending options required for the transaction. The application will specify a callback URL that will be used by EchoSign to notify the external application when an event occurs or deliver the signed and completed document to the calling system when the signature process is complete.
EchoSign returns a unique Document Key for each request. This Document Key can be used to retrieve up-to-date status of the agreement either by polling or when EchoSign notifies the calling application of change of status for the document or for retrieving the signed copy of the agreement.
Checking the status of a document: You can get the most current status of a document by using the getDocumentInfo method. This method takes your API Key and Document Key parameters. EchoSign will return the current status of the agreement and a complete history of events that have happened thus far on the particular document.
EchoSign supports two mechanisms for an external application to reflect the most current or up-to-date status for an agreement sent for signature. The simplest mechanism is for your application to provide a callback URL when sending the document for signature, EchoSign will then ping your service whenever the status of the agreement changes. Upon receiving a callback your application can then call EchoSign to get the latest status of the agreement. The callback URL included in the request must be accessible to EchoSign (i.e. must be Internet facing).
By default the callback URL gets called when the signature process completed. Included in the request will be the completed signed PDF. EchoSign uses an HTTP POST request to return the signed PDF – please ensure that your application can correctly handle such request. Your EchoSign account can also be configured such that the service can ping your application for every change in the status of the agreement. The callback will include the Document Key of the agreement whose status has changed and the current status. Your application logic can evaluate the received status and decide whether to perform an action in the calling system.
The second mechanism is for your application to check the status of the agreement by periodically polling the service and checking the status of the agreement. The upside of polling is that it can be used in case your calling application is behind your firewall and not accessible from the Internet for EchoSign to callback. On the flip side, to use polling you have to create a scheduling mechanism within your application to periodically query the status of all documents that were not yet signed, check whether the document’s status has changed and update your system. If you choose to use polling, it’s recommend you have different policies based on document “age” – ie. reducing the frequency of polling if the document was not signed after X days.
Retrieving the signed PDF: Once an agreement is signed, your application can retrieve the signed copy of the PDF and store that within your application. The signed agreement can be retrieved using the getDocuments method in the API. This API method supports several arguments to allow retrieving the signed documents separately or allow retrieving any supporting documents that the signer may have uploaded during signing, etc.
Depending on your application, you can also retrieve the form field data that your signer may have filled in to the document when signing the document using the getFormData method. The data can be used to update your calling application with the information provided by the signer during signing.
Documentation
Full documentation for the EchoSign SOAP API can be found here https://secure.echosign.com/public/docs/EchoSignDocumentService19.
Full documentation for the EchoSign REST API can be found here https://secure.echosign.com/public/docs/restapi/v2.
With RPG-XML Suite as your foundation, any features found within the EchoSign API-set are fair game to implement within your IBM i environment.
Questions?
Lean on the RPG-XML Suite development team for any implementation questions by contacting them directly at isupport@krengeltech.com!