Our first e-Signature developer workshop was such a success, so we’re offering another ESIGN developer workshop! Join Mike Borozdin, Manager of Professional Services, in a free electronic signature developer workshop.

Are you evaluating the DocuSign API to integrate electronic signature with you existing processes or technologies? Have you’ve heard about the DocuSign API but aren’t sure how to get started?

This free webinar will help you get started! In one hour, you’ll learn how to get set up a DocuSign .NET Sample and connect it to your DocuSign developer account. You’ll also get a brief overview of DocuSign interfaces and object model.

So when is this all happening? Wednesday, February 17th, from 1:00 – 2:00 pm PST.

Please register for the e-Signature developer workshop, get your free DocuSign Developer account and download the DocuSign SDK prior to the workshop.

Step 1 – Procure an X509 Certificate

• To get BinarySecurityToken working with Java, procure an X509 Certificate. While getting an X509 certificate is beyond the scope of this blog post – you might want to try searching for “SSL Certificates”. SSL transport protocol uses X.509 certificates for encryption.
• DocuSign supports certificates issued by certificate authorities included in Windows2003 servers. The most widely used certificate authorities are Thawte and VeriSign. Additionally, our Demo server farm support CACert.org certificate authority, which enables you to get a certificate without having to pay for it.
• Keys are generally distributed in PEM, PFX or CRT files. You will need one of these files prior to proceeding with this walkthrough.

Step 2 – Generate a Java KeyStore

• Java has its own keystore format which requires the use of its own tool – keytool. In my experience, I had started with a PFX file. To convert to the Java Keystore format, I had to go through a number of cumbersome steps. Then, one of our customers, Gloria Zhang, pointed me to a blog post about a very nifty tool: http://erlend.oftedal.no/blog/?blogid=68
• Using the steps in that tutorial, I created an esign.jks file.

Step 3 – Configure Axis2 to generate electronic signatures

• We’ve prepackaged samples to generate the right configuration files when you want to use XML signatures. I suggest that you start with working code from the DocuSign SDK and plug in your keystore file. This minimizes the number of things that can go wrong.
• You will need to plug in some important information about your keystore into the build.properties.x509 file. Once you plug in the (1) keystore path, (2) alias of the certificate and (3) password, you will need to issue “ant war-x509” command to build the web archive for deployment.
• If you were to examine the build configuration, you should see the following things in your axis2.xml config file:
• <items>Signature UsernameToken Timestamp</items>
• Elements such as ≤signatureCrypto> in the OutflowSecurity portion of the configuration.
• A cert.properties file that seemingly has a set of information that is already provided in axis2.xml. This may be there for historical reasons.

Step 4 – Testing

• Once you have established that the application is still functioning and making web service calls, the next thing to examine is the SOAP calls. LoanSample comes pre-packaged with log4j integration that dumps out the HTTP wire calls. You can find the SOAP requests and responses there.
• In my experience, opening the SOAP requests and responses in an external editor and cutting and pasting the appropriate sections makes them easier to read. After all the edits, you should see your requests to DocuSign web services. Those requests will have the UserNameToken and also BinarySecurityToken element in the headers. The BinarySecurityToken will have signature information and signature value.
• The final test is contacting your DocuSign representative and asking them to turn on XML signature validation on your account. This request should be accompanied by a public export of your certificate. Make sure you do not include the private key in your request.

While configuring XML signatures in Java is an advanced topic that requires that you master servlets, axis (or a similar framework), and PKI file manipulation, you can also work with DocuSign to ensure the correct configuration.

After all the settings are correctly configured, DocuSign will know that the web service calls were generated only by an application that had access to the X.509 certificate file. Enterprise IT operations put a lot of emphasis on the security of the certificate files, so you can enjoy the benefits from the internal infrastructure.

With DocuSign’s award-winning electronic signature service, businesses can accelerate their sales cycles and obtain complete visibility into their agreement process. ESIGNControl extends the value of DocuSign to the iPhone, empowering busy professionals to run reports on their DocuSign transactions, view details of documents in process, and even make corrections on the fly right from their iPhone. DocuSign, combined with ESIGNControl, supercharges business development and operational professionals, sales teams, real estate agents and mortgage brokers who rely on the DocuSign e-signature service to close deals online in minutes.

The iPhone is quickly becoming a must-have business productivity tool and ESIGNControl makes it easy for DocuSign electronic signature clients to remain equally productive when away from the office as they are at work. Using DocuSign’s SDK and developer account, we created ESIGNControl control to offer DocuSign’s customers a fast, convenient and mobile method to use DocuSign from any iPhone. – Tony Tonchev, Founder, Smart Mobile Solutions

How ESIGNControl Works
ESIGNControl is a DocuSign transaction remote control that lets users manage documents sent for signature from any iPhone. With ESIGNControl, DocuSign users can quickly and easily:

• See time based reports about documents in process
• Track and access documents in process
• View document signing status
• Download and view sent documents on the iPhone
• Revise and resend documents

ESIGNControl is available now from iTunes for $6.99.

With DocuSign, businesses save time, cut costs and eliminate errors by automating the signing process. ESIGNControl takes electronic signature document management to the next level by letting users quickly and easily access their documents and manage business at a moment’s notice from any location. This new application is a testament to the power of DocuSign’s DevCenter in arming developers with the resources and support to launch new products and services using DocuSign’s APIs. ESIGNControl, combined with DocuSign’s recently released ‘Designed for Mobile’ web signing experience, means iPhone users have 100 percent of what they need to manage their business anywhere, anytime. – Tom Gonser, Founder and Vice President of Product Strategy, DocuSign

The DocuSign DevCenter
The DocuSign Developer Center provides developers access to the most robust and flexible electronic signature and electronic contract execution APIs available today that can be used to reduce costs associated with contract execution processes, while driving untapped business opportunities. DocuSign APIs adhere to the latest version of the WS-Security (Web services security) protocol to ensure the integrity and confidentiality of DocuSign-powered Web services messaging. The cornerstone of the Developer Center is DocuSign Connect, a suite of integration services designed to extend DocuSign service capabilities into existing systems or new applications. DocuSign Connect includes:

• DocuSign Connect API—Enables the exchange of information between the DocuSign platform and enterprise business applications, allowing developers to create custom DocuSign enterprise Web applications.
• DocuSign Connect Service—A standards-based Web service that pushes DocuSign contract transaction data into disparate applications over HTTPS protocol.

For more information visit the DocuSign DevCenter.

General Contract Signing Process
The following stages represent a generalized, high-level cycle for any contract signing process. Without DocuSign, the contract signing process is “print-ship-sign-copy-return-scan”.

Stage 1: Document and Envelope Preparation
During this stage, the sender will provide transaction data and instructions. This information might come in manually or automatically from a variety of the data sources. The sender will add documents, templates, signing locations, initials locations, data fields, recipients, and reminder and expiration information. Without DocuSign, the sender has to print the documents to paper, ensuring sufficient print time and printer ink.
With DocuSign, you can work with the DocuSign team to automate this stage according to your business specifications. The documents and envelope will be ready to be sent at the completion of this stage.

Stage 2: Transaction Execution
Stage 2 begins when the sender sends the envelope of documents. Without DocuSign, this might entail faxing every sheet of paper and confirming receipt. If the documents are overnighted, someone must either drop off the envelope or schedule a pickup. Then the sender must wait for the recipient to receive the documents. If a critical page is missing or illegible, there may be emails, phone calls or other back-and-forth communication. The recipient must also be physically available to wet-sign. Last minute business trips or other delays can add days to this process.

If the sender were to use DocuSign, the DocuSign services execute all of the actions defined in stage 1 once the envelope has been sent. The envelope is routed via email to the proper recipients in the appropriate order. The recipients enter the required data (as applicable) and electronically sign and initial (as applicable) in all the required locations. Senders can control what happens to an envelope after it has been sent. For example, a sender may correct an e-mail address in case it was mistyped, a sender may stop execution and void the entire transaction before completion. However, more major changes are not allowed without first voiding. For example, senders cannot add an addendum after a signer has signed.

Stage 3 – Filing and Storage
After the transaction has been executed, contracts are typically filed and the data is manually entered into business systems. Sometimes other processes are initiated.
With DocuSign implementation, the filing and storage stage can be automated with some amount of investment.
This discussion of a high-level, generalized contract signing cycle provides a process framework for understanding where and how automation using DocuSign electronic signature and online contract execution adds value. The next section describes how to leverage DocuSign technology and service to automate your contract execution process and turn it into electronic contract execution.

Degrees of Automation
DocuSign offers a web interface, desktop software, and an application programming interface (API) called DocuSign Connect. These different options apply to all three stages in the lifecycle of a contract.

Web interface
The DocuSign web interface allows a user to send, sign, add data, initial, download, and get status of documents. The flexible WYSIWYG interface allows users to get started immediately and work from almost anywhere. Anyone who can use e-mail and a web browser should feel comfortable interacting with the system very quickly.

Standard automation solutions
In addition to the web and software solutions, the DocuSign service provides several standard solutions which automate steps in the electronic contract execution process.

These solutions allow you to:
•    Create a DocuSign envelope out of a blank PDF form using DocuSign PowerForms,
•    Automate document and envelope sending with DocuSign desktop software,
•    Automate data entry of status updates and data collected during the electronic contract execution process to SalesForce with DocuSign Connect for SalesForce,
•    Automate document and data retrieval from the DocuSign service to a server behind your firewall with DocuSign Export,
•    Automate the transport of the authoritative copy of documents to another secure location with eOriginal Vaulting.

These solutions require configuration and possibly installation. The target audiences for these solutions are office “power users” and IT administrators.

Application Programming Interface
The DocuSign API, DocuSign Connect, allows other systems to interact with the DocuSign service and automate the processes around sending, correcting, status, and download.

DocuSign Connect is exposed as a standard SOAP XML Web Service, protected by transport level security and message level security based on WS-Security standards.

DocuSign Connect enables greater automation capability. The most common automations are:
•    Automation of sending process: Senders can send documents with one click. This requires additional programming by the DocuSign customers. This programming enables the automatic selection of the document, data collection requirements, and signers. Using this capability, step 1 of the electronic execution process can be almost entirely automated.
•    Store and update documents and data automatically: Using data from DocuSign Connect, update internal systems with documents, data collected, and status information. DocuSign Connect provides all the information about the transaction at any point in its lifecycle. These capabilities can automate most of the processes in step 3 of the electronic contract execution process.
•    Embedded signing experience: You may embed the DocuSign signing and data collection processes in your portal or website using an IFRAME. This capability keeps your brand in front of the signers at all times in the electronic contract execution process.

A shared understanding of the general contract signing process and how DocuSign’s electronic contract execution process differs enables you to think about which steps of the process are repeatable and appropriate for automation. Understanding the various options around creating an automated electronic contract execution process for your organization and how they each fit into the contract lifecycle may help you communicate the value of adopting electronic signature and ECE technologies and processes.

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

API’s Importance
At DocuSign, we recently released our developer center, a resource for our developer community to access our API, use forums to communicate with other developers and share knowledge with DocuSign experts. We realize that the true benefit of ECE is to integrate it into mission critical applications and processes. That takes developers and domain expertise beyond what any one company can do. By allowing others to leverage the power of the DocuSign cloud in their applications these developers can unlock the ability to streamline processes around the globe.

The DocuSign API actually comes in two flavors – the DocuSign Connect Service which enables DocuSign transactions to deliver real-time status and form data directly to 3rd party applications, and the DocuSign Connect API which allows external systems to ‘embed’ the DocuSign signing or sending process directly into other applications. Both of these interfaces are purely ‘cloud based’ so there is nothing to install. Both are based on well understood standards such as SOAP and XML.

A good example of the DocuSign Connect service is the new DocuSign Connect for Salesforce tool – this has enabled customers to deeply integrate transaction events and document/form data directly into their Salesforce instances, automating what usually required manual work by the sales reps. This means reps spend more time selling, and the data is much more accurate so better decisions can be made.

Expanding the Cloud
Of course, providing an API and developer program is only the beginning. This program also must include registration, support, forums, example code segments, and a validation process to qualify applications that are production ready. Put another way, this is not just a web site – this project requires a commitment. Just ask Mike Borozdin, our lead dev center manager – he spends many, many, hours working with developers to be sure they have what they need.

We know a strong developer community is key to large scale success of our platform. We’ll continue to provide blogs, forums and other social media tools, so our developer community can connect with each other, share ideas, and expand the cloud.

DocuSign’s forums provide information such as development features, SDK updates & content, upcoming release instructions, API feature requests, Java and .NET integration and other relevant discussions.

API’s Role in Adoption
API’s help drive technology adoption. For example, Twitter, one of the more popular microblogging applications, has an API that’s given rise to third party applications that’s helped drive adoption of the service. These tools mean Twitter can focus on its core proposition and users who want additional features such as metrics can use the appropriate third party provider. Twitter’s extensibility due to a popular API may be a reason for its popularity.

By opening up DocuSign’s electronic signature and online contract execution technology to developers via our API and developer center, we hope to ‘expand the cloud’ through the innovations that can only come from developers with all sorts of different perspectives.

Image courtesy of flickr user selena marie under creative commons

Free Resources, SDK and Developer Forum Provide Fast Path to Automating Legacy Processes

The DocuSign Developer Center provides software developers, enterprise architects, systems integrators and independent software vendors with free resources to learn about, create and test solutions powered by DocuSign technology. Complete with a SDK, open standards-based application programming interfaces (APIs) and Developer Forum, the DocuSign Developer Center is now available.

Despite the focus on business process automation, organizations mail or express ship millions of documents for signature daily, relying on a slow, expensive and inherently insecure paper-based process. DocuSign’s on-demand electronic contract execution automates this business process and enables companies to eliminate the antiquated “print-ship-sign-copy-return-scan” cycle, dramatically reducing costs and accelerating business. The new Developer Center allows companies to inject DocuSign technology into their unique business processes including existing ERP, CRM and HR systems to eliminate an unnecessary paper processes, go green and reduce costs. Now developers can quickly offer their company and clients the power and productivity of electronic contract execution.

John Musser, founder of ProgammableWeb, stated:

Open APIs like the new DocuSign Connect are becoming the essential glue that makes the best SaaS services a truly integral part of enterprise IT. Enterprise and third party developers can use this new breed of APIs in the cloud to tailor solutions to work with existing corporate systems from CRM to ERP. DocuSign’s just-launched Developer Center has the key elements that we’ve seen make a difference in getting developer’s the resources they need to succeed.

The Dev Center At-a-Glance

The DocuSign Developer Center provides developers access to the most robust and flexible electronic signature and electronic contract execution (ECE) APIs available today that can be used to reduce costs associated with contract execution processes, while driving untapped business opportunities. DocuSign APIs adhere to the latest version of the WS-Security (web services security) protocol to ensure the integrity and confidentiality of DocuSign-powered web services messaging. The cornerstone of the Developer Center is DocuSign Connect, a suite of integration services designed to extend DocuSign service capabilities into existing systems or new applications.

DocuSign Connect includes:

• DocuSign Connect API—Enables the exchange of information between the DocuSign platform and enterprise business applications, allowing developers to create custom DocuSign enterprise Web applications.

• DocuSign Connect Service—Is a standards-based web service that pushes DocuSign contract transaction data into disparate applications over HTTPS protocol.

As a DocuSign Developer Community member, you receive access to all of the tools, tips and resources needed to develop and deliver a DocuSign-powered solution. For more information visit the DocuSign Developer Center. To start using DocuSign Connect, sign up for a free developer account.

In today’s economic climate, corporations are clearly focused on three critical and essential activities: cutting costs, securing revenue and retaining customers. Our customers tell us daily they have slashed operating costs, raised revenues and improved customer retention by closing deals electronically which may not have happened otherwise. We’re excited to provide you with the tools you need to drive the critical benefits of online contract execution into your organizations.

Image courtesy of flickr user preciouskhyatt under Creative Commons