Integration Considerations for a Software Vendor

Overview
A lot of business applications today are starting to use commercial web services.  The ubiquity of connectivity allows us to move mission critical business processes outside of our internal firewalls to cut down on maintenance, increase reliability, create more feature rich applications and get instant updates.

Whether or not your application is installed or delivered as a service, integration with web services such as the ones delivered by DocuSign requires a shift in user interface, support and architecture.

The cost of adopting the new paradigms are often less then the benefits you receive by utilizing the services oriented architecture (SOA). In this post we will examine the benefits, architecture considerations, implementation guidelines and support for an application integrated with DocuSign web services.

The target audience of this post are enterprise software architects and technical project managers that are designing an integration with DocuSign web services.

Benefits
ISO 9126 is an international standard for evaluating software quality.   There are six main characteristics and utilizing DocuSign web services directly contributes to all of them.
1. Functionality
As you are considering executing contracts electronically or just gathering electronic signature you should keep in mind that stated requirements are most of the time are missing the full scope.

In addition to end user stated functionality electronic signatures have a number of applicable laws. Utilizing a commercial web service eases the burden of figuring out the details.  The service providing the full range of options can have immediate return on your investment or most likely will have a return in the near future.

Before you decide to build your own or buy a limited service it's generally a good exercise to ask your users if any of the additional features could be applicable to their contract execution.  These are the types of questions that can help you figure out the evolution of requirements: “Dear Project Stakeholder, I know you are saying that right now all you need is a signature on the last page, but do you foresee us executing contracts that might require signatures on multiple pages?  Could initials come in handy?  Do we need to collect any data with this contract or just get the signatures?”
2. Reliability
Enterprise ready commercial web service providers such as DocuSign host their solution in a secure and reliable data center.  There are personnel controls, audit logs and secure storage utilized to make sure that the solution and the data are well maintained.  In case of a forensics exercise or data loss by your application the secure audit log at DocuSign will still maintain that your documents were signed.

In addition to the operational reliability the software releases by an enterprise ready web service provider go through test passes and beta testing by other users of the web service.]
3. Usability
Commercial web services can leverage economies of scale and invest more in user interface and application interface.  DocuSign continuously invests into ease of use both by end signers, senders and developers.

The usability improvements are then vetted and confirmed by thousands of signers that interact with the service every single day.
4. Efficiency
One of the biggest wins when utilizing SOA is that the resource cost of executing the transactions is equal to the cost of making a call to the web service.  That's a miniscule impact in comparison to what the web service provider needs to invest in to support presentation, conversion, cataloging and archiving of the electronic contracts.
5. Maintainability
Web service provider maintains the solution and fixes any issues.  In addition to your staff not having to fix issues, the issues found by other users by the web service are also fixed and immediately delivered to you.
6. Portability
Utilizing a standards based web service rather then an installed behind the firewall system allows you for maximum portability of your application.

First the application physical location is flexible.  You can access the commercial web service from any location with connectivity to the Internet.

Second the standards based SOAP API allows you to utilize any operating system or technology that supports that interface.  Most of the application stacks in use today support SOAP and XML.

Billing Information
Commercial web services need to support a billing configuration.  When architecting an application you need to consider the following billing relationships:
1)    You are going to purchase a subscription to the web service and deliver the application pre-configured and ready to go.
2)    You are going to ask your clients to purchase a subscription to the commercial web service.

The first configuration is probably easiest for deployment because the billing information is static.  When a new client starts using your application they don't have to purchase a subscription to DocuSign services.  The burden of billing and possibly pre-paying for the subscription is something your system has to manage.

The second configuration will leverage DocuSign billing infrastructure but will have an up front cost of setting up a DocuSign corporate account and plugging that information in.

From a software architecture perspective the credentials that identify an account on DocuSign system are going to be global or stored in a customer record.

Application Configuration
Most user friendly applications have a configuration page that allow the administrators to make changes without having to recompile or re-deploy the application.

Depending on the choices you made for the billing configuration between your application and your clients the configuration page is going to be global or on a per user basis.

It's important to make sure that the configuration is limited and secured to the users that know how to properly configure connection to DocuSign web services.

There are also web service methods that can be used to make configuration easier.  Login method allows your application to get the web service credentials by supplying an e-mail and a password in a human readable form.  DocuSign also supports a Ping method which doesn't validate credentials but returns True if you are successfully connecting to the web service end point.

DocuSign has several server farms:
a.    Production (www.docusign.net) - this is where legally binding contracts are processed.
b.    Demo (demo.docusign.net) - used for development and is free for customers to test against.  The code mirrors production exactly, the data is separate.
c.    Preview (preview.docusign.net) - used to give customers early access to the upcoming versions of the web service.

A full DocuSign configuration screen should contain the following elements:
1)    E-mail
2)    Password
3)    Billing Account selection (one e-mail and password could belong to several accounts)
4)    Web Service URL selection (demo/production/preview)

If you opt out of using the Login method and would like to obtain web service credentials directly your screen should at least contain these elements:
1)    Web Service User ID
2)    Account ID
3)    Password
4)    Web Service URL selection (demo/production/preview)

We also suggest that you add a “Test” button that uses Ping and Login method for basic checking.  It will save you time on generating a real transaction in order to just test whether the configuration is correct.
Support Considerations
Your application is likely to have it's own screens, processes and data flow.  When an administrator or an end user is looking for help you need to provide functionality that will enable them to get help from DocuSign.

DocuSign deals with millions of different contracts and hundreds of integrated applications.  In order to help DocuSign developer support troubleshoot the errors we suggest you build in logging that shows what the requests and responses were at the web service level.

Different technology stacks support various methods for enabling tracing of web service calls.  When you escalate a support request to DocuSign you should have these key pieces of information - XML output of the web service call that is failing, XML response from DocuSign web service, Envelope IDs that are exhibiting problems, web service URL that you are interfacing with.

We suggest devising a configuration screen or a report that will allow an IT Operation person to generate the above-mentioned output.  Having that information handy is going to enable us to service you a lot quicker.

Meta Data Linking
Most integrating applications extend their workflow and replace what used to be a faxing or printing functionality with DocuSign electronic contract execution.  From a system level you will be using an external data source for some of your data.  The data needs to be correlated between the two data sources to provide a coherent view to the end user.

DocuSign transaction containers are called Envelopes and every single envelope has an envelope ID.  An appliction that creates or references those envelopes should at the very minimum store the envelope ID in one of its tables.

Envelopes also have Custom Fields.  Those are places where arbitrary data can be placed.  If you are looking for a bi-directional data linking you can use these fields.  Commonly applications store things like account ID or transaction ID in the envelope custom fields.

Given the envelope ID you can control the envelope and maybe most importantly gather the data from a completed envelope to update your application state.

For example when envelope completes you might want to change the customer record in your application and move forward in the business process.
Multi Tenant Support
Often applications will support having several companies in one data store.  For example SalesForce.com supports thousands of tenants that all have their own configuration and are expecting SalesForce.com to keep their records private and secured from each other.

When integrating with DocuSign web services you need to keep in mind that every tenant in your application might want to plug in their own web service credentials in case they have a DocuSign subscription already.

The configuration screens, data tables and onboarding procedures need to take this into account.  Consequently any support escalating from one of the tenants of the application might be due to the fact that the settings in that tenant's DocuSign account are incorrect.

A common scenario is a changed password.  A new password would invalidate existing web service credentials for one of the tenants and the web service calls are going to generate “Invalid User Name or Password” credentials.

X509 Certificates
A few of DocuSign's web service calls are secured with an additional level of security.  The security based on WS-Security standard is utilizing a binary security token generated with an X509 Certificate.

These certificates need to be issues by a well known certificate authority such as Thawte or VeriSign.  The certificates also tend to have an expiration date.

If your application is using the methods that require a functioning certificate you need to make sure that the certificate doesn't expire.  If you are not careful then one day with no code changes and no data changes the web service calls might start failing.
Other Considerations
Some businesses have additional requirements:
1)    What kind of identity verification is necessary for the signers?  DocuSign supports scalable security around signing from a unique activation link sent to the e-mail to RSA integrated ID Check system.  Increased levels of security generally make getting to signing harder and have different costs associated with them.
2)    Has your development team implemented Web Service connectivity before?  If not we strongly advise you to get help from a knowledgeable integrator or from DocuSign Professional Services.
References:
http://en.wikipedia.org/wiki/ISO_9126