This walkthrough covers the RequestStatus family of methods. These methods are used to get the status of existing DocuSign Envelopes for electronic signature and are probably the most frequently used methods.

Of course, you should already be comfortable with working with webservices to follow along here. There will be code samples displayed in both C# (using .NET 3.5) and PHP, but you should already know how to get your local proxy class setup and your credentials entered.

Getting Status

So, let’s say that you’ve gone through the electronic signature code walkthrough on using the CreateAndSendEnvelope method and sent your first envelope. After sending the envelope, you should receive the return value of the method, an EnvelopeStatus object containing a property called EnvelopeID, which is the DocuSign unique identifier for an envelope. You should always save this value somewhere in your application, because it is the primary means used to identify an envelope. If you want to get the status of an envelope, you need the EnvelopeID. If you want to download an envelope, you need the EnvelopeID. If you want to void an envelope, you need the EnvelopeID. You always want to keep the EnvelopeID.

Here’s the RequestStatus method call:

//.NET
	string EnvelopeID = "Your EnvelopeID";
	EnvelopeStatus envStatus = apiService.RequestStatus(EnvelopeID);

//PHP
	$RequestStatusParams = new RequestStatus();
	$RequestStatusParams->EnvelopeID = "Your EnvelopeID";
	$result = $api->RequestStatus($RequestStatusParams);
	$envStatus = $result->RequestStatusResult;

Pretty simple; you send in the EnvelopeID, and you get back an EnvelopeStatus object. The EnvelopeStatus object has a lot of information in it, so let’s take a look at it. The top level of the EnvelopeStatus object contains information about the Envelope itself – for example, the EnvelopeID, the Subject of the Envelope, the Username and Email of the Envelope Sender, timestamps for key events in the Envelope’s lifetime, etc. You will probably be most interested in the Status property. This is a string value that indicates where the Envelope is in the signing process. The values for Status are:

The Status value also has a timestamp value associated with it – for example, for a Created Status value there is an associated date-time value that indicates when the Status changed to Created, and the date-time associated with the Sent status tells you when an Envelope was sent.

Along with the Envelope level information, there are collections (or arrays) that provide status information on Recipients and CustomFields. A RecipientStatus object will let you see when the recipient received and signed the envelope, any extra authentication information that was used, and the status of the tabs assigned to the recipient.

Using the CustomFields status you can retrieve the value of any CustomFields that were specified when the envelope was sent. A CustomField is a collection of name-value pairs that are set by the sender and not visible to the recipients and they can be used to add information to an envelope that is useful to your application.

Of course, there are more status fields than the ones we’ve covered here – you can see the full list in the API documentation in the “EnvelopeStatus” section.

Now, let’s cover the rest of the RequestStatus family. There are actually four methods that differ based on the number of envelopes we are asking the status of and how much information we want to get back.

The Ex Methods

The Ex suffix on an API method indicates that there will be additional elements returned in the status and that these elements might change. The current version of the API documentation indicates which additional elements are currently being returned. There might be additional elements added in subsequent releases, so you should be sure that your code can accept the surprise appearance of new status properties. The Ex method’s input parameters are identical to the standard version – so the RequestStatusEx method takes a single EnvelopeID, just like the RequestStatus method.

The Es Methods

The ‘Es’ methods indicate that the method operates on multiple envelopes at a time. Because of this, they take different input parameters than the single envelope versions and they return a different object. Although they still use the same EnvelopeStatus object described above, it’s just placed in an array in a wrapper object.

The input parameter to these methods is an EnvelopeStatusFilter. This object is used to specify search parameters to identify the set of envelopes that are reported on. You can specify the Sender’s Username and Email, a span of Dates for an envelope event (for example, all envelopes where the Signed date is between the start and end dates), the current status of the envelope, or even a list of specific EnvelopeIDs. The AccountID is a required parameter and is used to indicate which account is the target of the search. So your code should prepare an EnvelopeStatusFilter representing the search you want to perform, pass that in to the method, and in return you get a FilteredEnvelopeStatuses object.

The FilteredEnvelopeStatuses object has a property called ResultSetSize that tells you how many envelopes matched your criteria. It also contains the EnvelopeStatusFilter used to make the request and an array of up to 200 EnvelopeStatus objects.

The methods are limited to returning up to 200 status objects per call, so if you have a large resultset you will have to make multiple calls. You can do this by passing in the number that you want to start at each time as the StartAtIndex of the EnvelopeStatusFilter. If your initial response indicated that there were 300 envelopes that matched your criteria, you would have received the first 200 status objects in the response, and then you would call the method again, this time setting the StartAtIndex property of the EnvelopeStatusFilter to 200, and you would receive the last 100 status objects in the response.

Here is an example of a request to retrieve all envelopes that are in a Complete status and were sent in the last 24 hours.

//.NET
	int StatusesReceived = 0;
	bool moreStatusesAvailable = true;
	FilteredEnvelopeStatuses statuses ;

	EnvelopeStatusFilter filter = new EnvelopeStatusFilter();
	filter.AccountId = "Your AccountID Here";
	filter.Statuses = new EnvelopeStatusCode[1];
	filter.Statuses[0] = EnvelopeStatusCode.Completed;
	filter.BeginDateTime = new EnvelopeStatusFilterBeginDateTime();
	filter.BeginDateTime.statusQualifier = "Sent";
	filter.BeginDateTime.Value = DateTime.Now.AddDays(-1);
	while (moreStatusesAvailable==true)
	{
		// apiService is an already configured api proxy
		statuses = apiService.RequestStatuses(filter);

		// do something with statuses here

		StatusesReceived += statuses.EnvelopeStatuses.Length;

		if (statuses.ResultSetSize == StatusesReceived)
		{
			moreStatusesAvailable = false;
		}
		else
		{
			filter.StartAtIndex = StatusesReceived.ToString();
		}
	}

//PHP
	$StatusesReceived = 0;
	$moreStatusesAvailable = true;

	$oneDay = 60 * 60 * 24;
	$BeginDateVal = date("c",time() - $oneDay);

	$filter = new EnvelopeStatusFilter();
	$filter->AccountId = "Your AccountID Here";
	$filter->Statuses[0] = "Completed";
	$filter->BeginDateTime->statusQualifier = "Sent";
	$filter->BeginDateTime->_ = $BeginDateVal;
	$RequestStatusesParam = new RequestStatuses();
	$RequestStatusesParam ->EnvelopeStatusFilter = $filter;

	while($moreStatusesAvailable === true){
		$result = $api->RequestStatuses($RequestStatusesParam);
		$statuses = $result->RequestStatusesResult;
		// do something with statuses

		// this check is because php won't create an empty status array if there are no results,
		if($statuses->ResultSetSize > 0){
			$StatusesReceived += count($statuses->EnvelopeStatuses->EnvelopeStatus);
		}

		if ($statuses->ResultSetSize === $StatusesReceived)
		{
			$moreStatusesAvailable = false;
		}
		else
		{
			$filter->StartAtIndex = $StatusesReceived;
		}
	}

Both examples assume that you are doing something with the status results, like updating a local database, or preparing a list of documents to retrieve, etc.

So that’s the RequestStatus family. Be sure to check the API docs for full details on the methods and parameters, especially for the Ex methods. And as always, if you have any questions, please use the DocuSign DevCenter forums for assistance.

In this walkthrough, we’ll cover the sending of an electronic signature Envelope using the CreateAndSendEnvelope method. This is the most common method of sending a DocuSign Envelope as it does not require too much preparatory work. It requires a PDF document that you wish to get signed, some knowledge of where the signatures should go, and the name and email address of the person who should sign it. A common business scenario for this is getting an application signed – in fact, there are two sample projects in the SDK that use this scenario: LoanCo and InsuranceCo. Both of these sample apps show an end user filling out an application which is then sent to DocuSign and prepared for signature.

You should already be comfortable with working with webservices to follow along here. There will be code samples displayed in both C# (using .net 3.5) and PHP, but you should already know how to get your local proxy class setup and your credentials entered.

If you have looked over the API Documentation, you might have seen the CreateAndSendEnvelope method call, and the parameters that you can pass in. There are a lot. We are going to ignore most of them, as they deal with advanced functionality, and just concentrate on the basics: Recipients, Documents, and Tabs.

The Envelope Object

First, let’s create the objects for our method call. In the PHP Code, using the proxy classes from the SDK, it looks like this:

$CreateAndSendEnvelopeParam = new CreateAndSendEnvelope();

Here’s the .NET version:

Envelope envelope = new Envelope();

Notice that the PHP class is one level higher in the hierarchy so we will end up using

$CreateAndSendEnvelopeParam->Envelope->property

whereas in .NET we will use

envelope.property

Other than that, the code samples will look very similar.

Now let’s populate these objects.

Recipients

A Recipient is someone who will participate in the Envelope Signing in some way – they may sign the documents, they may help prepare the documents, or they may be sent a copy of the documents. The most common type of Recipient is a signer.
Here’s a basic signer constructed in .NET:

	Recipient recipient = new Recipient();
	recipient.ID = "1";
	recipient.Email = "someemail@somewhere.com";
	recipient.UserName = "Some Person";
	recipient.Type = RecipientTypeCode.Signer;
	recipient.RequireIDLookup = false;

And in PHP:

	$Recipient = new Recipient();
	$Recipient->ID = "1";
	$Recipient->Email = "someemail@somewhere.com";
	$Recipient->UserName = "Some Person";
	$Recipient->Type = "Signer";
	$Recipient->RequireIDLookup = false;

Since there can be multiple recipients on an Envelope, the DocuSign API expects an array of Recipients, so we’ll put them in one:

	//.NET
	envelope.Recipients = new Recipient[1];
	envelope.Recipients[0] = recipient;

	//PHP
	$CreateAndSendEnvelopeParam->Envelope->Recipients->Recipient[] = $Recipient;

(Note the PHP hierarchy has an extra level in it – instead of using Recipients[] as you might expect, it uses Recipients->Recipient[]. This is due to the code that generated the PHP proxy objects (wsdl2php ver 0.2). If you happen to use some other code to generate your proxy objects you might see a slightly different class hierarchy. All of these code samples are using the proxy objects included in the php sample code in the SDK.)

Documents

We need a document. For this case, let’s assume that we have a PDF document available to our code, so we can read it in as a byte array;

	//.NET
	envelope.Documents = new Document[1];
	Document doc = new Document();
	doc.ID = "1";
	doc.Name = "Our Document";
	doc.PDFBytes = System.IO.File.ReadAllBytes(Server.MapPath("resources/Loan.pdf"));
	envelope.Documents[0] = doc;

	//PHP
	$CreateAndSendEnvelopeParam->Envelope->Documents->Document[0]->ID = "1";
	$CreateAndSendEnvelopeParam->Envelope->Documents->Document[0]->Name = "Document";
	$CreateAndSendEnvelopeParam->Envelope->Documents->Document[0]->PDFBytes = file_get_contents("resources/Loan.pdf");

Tabs

Now that we have a Recipient, and a Document, we need some way to express that the Recipient is supposed to sign the Document in a certain place. We do this using a Signature Tab. The tab will reference a Recipient and a Document, and provide the location of the signature.

	//.NET
	Tab tab = new Tab();
	tab.DocumentID = "1";
	tab.RecipientID = "1";
	tab.Type = TabTypeCode.SignHere;
	tab.PageNumber = "1";
	tab.XPosition = "100";
	tab.YPosition = "100";
	envelope.Tabs = new Tab[1];
	envelope.Tabs[0] = tab;

	//PHP
	$tab = new Tab();
	$tab->Type = "SignHere";
	$tab->DocumentID = "1";
	$tab->RecipientID = "1";
	$tab->PageNumber =  "1";
	$tab->XPosition = "100";
	$tab->YPosition = "100";
	$CreateAndSendEnvelopeParam->Envelope->Tabs->Tab[] = $tab;

Note that while we are using a single signature tab for this example, there are several different types of tabs available for use. As well as indicating signature locations, they can be used to indicate locations of a Recipient’s Initials, Form Field locations where Recipients can enter data, System Information, etc. You can also set Tab locations by specifying a bit of text that appears in your document, and having DocuSign place a tab at every location that text appears in your document. This technology is called “Anchor Tabs”, and will be discussed in more detail in another article.

Ready to Send?

Not quite. We have to set a couple of pieces of information on the Envelope object itself. We are going to give our Envelope a subject, so when the Recipient sees it in their inbox they will know what it is for, and we are going to provide an bit of text that will be included in the email that is sent to the Recipient – this will allow us to personalize it a bit. And finally, we will set the AccountID that the Envelope will be sent from. Since DocuSign allows users to be in multiple accounts, the AccountID is necessary to indicate which account the Envelope should be sent from.

	//.NET
	envelope.AccountId = "Your AccountID Here";
	envelope.Subject = "Sample Application";
	envelope.EmailBlurb = "You can add a personal message here.";

	//PHP
	$CreateAndSendEnvelopeParam->Envelope->AccountId = "Your AccountID Here";
	$CreateAndSendEnvelopeParam->Envelope->Subject = "Sample Application";
	$CreateAndSendEnvelopeParam->Envelope->EmailBlurb = "You can add a personal message here.";

At this point we are ready to send the envelope. When we send an envelope we get a status object (of type EnvelopeStatus) in return.
We will use our API Proxy to call the CreateAndSendEnvelope Method:

	//.NET
	APIServiceSoapClient apiService = new APIServiceSoapClient();
	apiService.ClientCredentials.UserName.UserName = "Your DocuSign UserName here";
	apiService.ClientCredentials.UserName.Password = "Your DocuSign Password here";
	EnvelopeStatus envStatus = apiService.CreateAndSendEnvelope(envelope);
	string envelopeId = envStatus.EnvelopeID;

For the php code, we are assuming that we have the wsdl file cached locally in the indicated location.

	//PHP
	$api_endpoint= "https://demo.docusign.net/api/3.0/api.asmx";
	$api_wsdl = "api/APIService.wsdl";
	$api_options =  array('location'=>$api_endpoint,'trace'=>true,'features' => SOAP_SINGLE_ELEMENT_ARRAYS);
	$api = new APIService($api_wsdl, $api_options);
	$api->setCredentials("Your DocuSign UserName here", "Your DocuSign Password here");

	$result = $api->CreateAndSendEnvelope($CreateAndSendEnvelopeParam);
	$envStatus = $result->CreateAndSendEnvelopeResult;
	$envelopeID = $envStatus->EnvelopeID;

The response from the CreateAndSendEnvelope method is an EnvelopeStatus object, which contains detailed status about the process of the envelope signing. In this example, we are grabbing the EnvelopeID property from this object so that we can store it somewhere in our own system. The EnvelopeID is the unique Identifier for this envelope in DocuSign, and there are several other API methods that will use it as a parameter – methods for requesting status, retrieving documents, voiding the envelope, etc.

At this point the envelope has been sent, and the Recipient should have gotten an email from DocuSign. This email will contain a link that will take the Recipient to the DocuSign site, and guide them through the process of signing the Document.

To get DocuSign tools and a free developer account please visit DocuSign DevCenter. To see what other developers have created on DocuSign’s electronic signature platform, take a look at DocuSign’s github e-siganture code repository.

My job? To show you the automation and extension features built into the Spring ‘10 release!

We’ve:

• extended the workflow for new types of recipients in the transaction
• added a way for recipients to collaborate on documents via markup
• added a way for you to build conditional logic for SecureFields™
• created a new way for you to launch a DocuSign envelope
• included many more features

Today I’d like to drill into the new way to launch DocuSign envelopes – the feature we call PowerForms 2.0. PowerForms have existed in DocuSign for a long time and were originally designed to enable sending a PDF form that could be filled in, eSigned, and tracked with DocuSign. With the Spring ’10 release, DocuSign PowerForms 2.0 extends this feature to allow direct launch without the PDF form in the middle of the process and before you know it, we’ve got a whole new protocol!

Previously, if you wanted to create a DocuSign envelope in response to a click on your website you had to write some server side code. While this wasn’t a big issue for a lot of people who already had some back-end systems, those with a Google Site or a pure HTML site had to extend their infrastructure. Now with PowerForms 2.0 to launch a DocuSign transaction all you need to do is create a PowerForm and copy the link to it.

You can send that link via e-mail or add it to your website. In addition to the link, you can add data or recipient information from your site to the URL and that information is inserted into the appropriate fields in the envelope. The data can be passed in the URL or in a form post.

As a proof of concept, we created a small form on a Google site that takes a few form fields and posts the data and the recipient information to a PowerForm. As a result, without any code (JavaScript or back-end code like C#, Java or PHP), a new envelope is created and we have an integrated solution.

Here is the form (you will need to map it to your own PowerForm link of course).

Which looks like:

Google Sites Screenshot

For more on the PowerForm data syntax see the PowerForms User Guide

Want to inject DocuSign’s electronic signature capabilities into your existing technology? Take a look at the DocuSign eSignature Developer Center and register here for a DocuSign Developer account for free access to the leading eSignature API and SDK!

The summer’s heating up for DocuSign’s developers, working with our API to inject eSignature capabilities into other technologies. We’ve seen some amazing integrations recently, highlighted in our Featured eSign Applications. These electronic signature applications were all built using our Free eSign Development Account – you can register to get free access to the DocuSign API and SDK! Take a look at the DocuSign DevCenter – did you know that one of our talented DocuSign DevCenter developers has created and released eSignControl, a new mobile app for DocuSign? Available as an iPhone app and iPad app, eSignControl enables users to track and report results as well as send and sign documents.

With eSignControl, available for iPhone and iPad, you can:

• See current status and history
• Review contracts
• Correct envelopes

• Send from Google Docs, DocuSign templates (using your local address book) and your local drafts folder
• Drag / drop tags onto documents with Mobile Tagger

• Create groups of users to track
• Filter envelopes based on envelope or data fields
• Generate performance reports with totals
• Email reports

Want to learn more about DocuSign’s API and eSign developer community? Join Mike Borozdin for our weekly Developer Webinars on Thursdays – click to register!

Generally what we go through in the webinar is a quick overview of the DocuSign system and then we get into the things that developers care about: our system architecture, API functions, getting web service credentials and setting up samples. We have tried to keep these webinars small and use a townhall format – people raise their virtual hand and we clarify points right on the spot. Today, we covered sending DocuSign envelopes, retrieving the latest documents, getting status and embedding DocuSign UI in an IFRAME.

Folks asked some really good questions: using a template versus anchoring signatures to a text, using our publisher technology, how to back port our samples to Visual Studio.NET 2005 and a few more.

I just wish we could make that hour last a little longer. Message to our developers: at our next DevCenter Jumpstart webinar, go ahead and send in your questions ahead of time and we’ll try to incorporate them into the slide deck. Click to register for any of our DevCenter Jumpstart Webinar.

Thank you very much for attending!!!

– Mike Borozdin, Manager of Professional Services

What did attendees think? Matt Frizzell, from adBlocks shares:

Thanks so much. That was a great presentation and your knowledge of your product is superb. It is amazing how many times I have heard, “I’ll need to ask someone about that” in demos but you were able to answer everything thrown in your direction.

The Wall St Journal recently ran an article about freelancers, consultants, contractors and other independent workers and the challenges they face collecting payment for their services. The industry leading eSignature provider, DocuSign, provides an electronic signature solution for individual professionals that can help them close deals with clients more quickly as well as accelerate the time to revenue.

From the Wall Street Journal:

For New York business consultant Christopher Santini, the pursuit for payment from one client has practically become a second job. Last May, a small business he consulted for went through a merger, and the new company fell behind on payments to him. Now, Mr. Santini, who’s been a freelance consultant since 2008, says he is owed about $35,000, which would have accounted for almost 40% of his annual income last year.

“I started to get the standard run around,” says Mr. Santini. “The secretary would tell me the person I needed to speak to was out. Finally [they] started to ignore me and not return emails or calls.”

Mr. Santini says he has spent 80 hours calling and emailing company officials.

If Mr. Santini were to use DocuSign to manage his client contracts and invoices, he could have asked his clients for the names and emails for whom to send paperwork to and send them the paperwork directly.

DocuSign for Individual Professionals can help them close deals faster and accelerate time to revenue.

With DocuSign’s electronic signature services, you’ll have the ability:

• To see when your invoices were opened with the audit trail
• To ask for a signature to acknowledge receipt and
• To set up your invoices to automatically forward to payroll or finance once your engagement sponsor has signed off the invoice

DocuSign also has a function that enables you to set auto-reminders so that you’ll spend less time following up as a bill collector and more time concentrating on providing your clients with service or building your business. With DocuSign’s API, you also have the option to integrate DocuSign into your existing CRM system.

DocuSign’s electronic signature services can save you time – as a freelancer, independent consultant, contractor or otherwise independent worker, you know your time is valuable. Don’t spend it trying to get paid for your work. Use DocuSign to close more deals and speed your time to revenue! Click here to try DocuSign Electronic Signature for Individual Professionals, free for 30 days!

At DocuSign, we think electronic signature and paperless processes add convenience and eliminate the need to fax, copy and file paper. From our customers, we’ve heard accounts of their clients appreciating the convenience DocuSign’s eSignature services provides. From Mike Borozdin, manager of professional services here at DocuSign, we have a story of how going paperless has changed his life:

In less than a month it’s going to be a year since I stopped storing paper. Last spring before my move from Madrona to Capitol Hill I did a bit of spring-cleaning. As I was cleaning out my closets and the attic I realized how much old and useless stuff I had. Some of my old tech toys ended up with my friends. Most of my old clothes ended up at Good Will. And then I started cleaning out my files. For a guy who has been on the bleeding edge of tech for a bit I had a surprising amount of old statements and receipts. Consolidated it was three full boxes.

During my childhood my parents told me not to lose paper. I remember carefully storing and filing my bank statements “just in case something happened.” My car was hit in the late nineties and sure enough I had a full folder of papers for a car that was totaled a decade ago. I was torn: I had an emotional attachment to my old dusty paper, yet I was too lazy to move these boxes with me. I decided that I am going to go paperless.

I decided to scan some of the most important documents from my past and have them backed up online. I promised to myself that going forward I would not store any more paper. It seemed like in the age of Internet it should be pretty easy. After all Chase already offered paperless statements and Fidelity did too. My Comcast bill could be viewed and paid online and so was AT&T’s. Those were the first steps and they took care of a lot of my paper.

This seemed like a piece of cake and I lasted without accumulating any more paper for about a month. Then I had a dentist appointment. My dentist is great when it comes to my teeth, but his assistant still writes the bills by hand and stuffs them in little blue envelopes that cost 40 cents to deliver less than a mile. My accountant insisted on sending me things via mail and the worst was healthcare. Between the Polyclinic on Broadway and Regence I must have 5 letters for every visit to the doctor.

I had to counteract this somehow. I employed two services: for anything where people wanted me to sign anything I used DocuSign and for all the paper that people wanted to send me still I created an Earth Class Mail account.

It took a little getting used to. Not for me, but for all the people that all of a sudden were shocked that I resisted their attempts to send me pages of stuff in the mail. My accountant was probably the most shocked. I kept telling her that I really don’t want my tax return sent to me. I kept reminding to send me things in a PDF file via some secure delivery service such as our own DocuSign, but she kept on trying to give me paper. Thankfully EarthClassMail would scan it in and then, if there were signatures required, I would DocuSign it and send it back to her via e-mail.

So after 5-6 months of constantly attempting to fend off the influx of paper at my door I finally ended up getting most of my important mail electronically. My life has altered a bit. I stopped going to my mailbox to see if there is anything new. The only new things were junk mail from Pizza Hut and Office Max. I tried taking that stuff out and putting it into the recycling bin but then I got lazy about that too. I stopped going to the mailbox altogether. On the eleventh month I went to clean my mailbox one more time and to my surprise it was completely clean with just a yellow note from my local post office. It read: “Your address has been marked as vacant.” According to the old paper world I might no longer exist.

Mike can track all of his necessary documents through various online services and uses DocuSign for his electronic signature needs. Congratulations to Mike for being paperless personally AND professionally!

Interested in taking a look at the DocuSign API and downloading the DocuSign SDK to integrate DocuSign into your existing technology? Take a look at the DocuSign dev center, which Mike manages, to get your FREE development account today!

Did you know that Dow AgroSciences LLC uses DocuSign to securely transact grower contracts online? Using DocuSign’s Application Programming Interface (API), DocuSign seamlessly integrates with Dow AgroSciences’ Trait Stewardship Web portal. Growers can now quickly and conveniently complete and sign the Trait Stewardship Grower Agreement digitally using DocuSign e-signature technology. Dow AgroSciences has successfully reduced the average turnaround of grower contracts from days to minutes by employing DocuSign. Aimee Zahora, U.S. seeds & traits business manager for Dow AgroSciences, shares her thoughts:

It is clear that DocuSign positively impacts our Grower Agreement compliance activities and will also provide value in other departments—legal, marketing programs and customer service. We are excited about DocuSign’s ease of use and the efficiencies gained through e-signing. DocuSign is the right solution at the right time for the long-term at Dow AgroSciences.

While launching the high-yielding and award-winning SmartStax^TM corn hybrids, Dow AgroSciences investigated eSignature technology to enhance contract compliance. After viewing a demonstration, Dow AgroSciences was convinced that DocuSign was the right choice:

DocuSign has saved Dow AgroSciences considerable administrative time, energy and resources. Our seed retailers no longer have to wait on a cumbersome paper process to obtain a license number for their growers and invoice the seed and traits. And, our growers can execute their agreements quickly and securely. -Doug Hoberty, OneSource Manager for Dow AgroSciences.

Working with DocuSign Professional Services, Dow AgroSciences used DocuSign’s Connect API to quickly integrate DocuSign electronic signature technology within the Trait Stewardship portal and Dow AgroSciences’ grower database, managed by a third-party vendor. The portal is dedicated to promoting awareness of and training on stewardship requirements for seed containing Herculex® Insect Protection, SmartStax^TM technology and Wide Strike® Insect Protection. Growers are required to sign a formal agreement to ensure regulatory requirements are met during the purchasing, planting, and exporting of crops grown with one of Dow AgroSciences’ traits.

The Grower Agreement is available through Dow AgroSciences’ Traits Stewardship portal where the grower completes a simple registration and adopts an e-signature. The grower is then guided through the e-signing process by DocuSign’s familiar Sign Here tabs, ensuring all form fields are completed. The agreement is completed in minutes online, and growers no longer have to hassle with paperwork, and mailing or faxing back forms. Because DocuSign is integrated with Dow AgroSciences’ database, all data obtained during the DocuSign process is automatically updated, saving time and eliminating rekeying and data entry errors. In addition, the entire transaction is safe and secure, backed with a comprehensive audit trail.

We’re excited that Dow AgroSciences chose DocuSign as its eSignature provider. Steve King, president and CEO of DocuSign, shares his thoughts:

Dow AgroSciences provides cutting-edge technology to increase crop yields for safe, affordable food. With DocuSign, Dow AgroSciences can further extend their leadership with fast, safe and affordable e-signing of Grower Agreements. We are pleased to be working with this leader in agriculture sciences to streamline workflows, increase efficiencies and enhance grower satisfaction while optimizing regulatory compliance.

For more information about the DocuSign API, visit the DocuSign Developer Center, where you can sign up to download the software developer kit (SDK), access the API, and participate in the DocuSign eSign forums!

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.

Demonstrate Use Cases
To schedule a Certification, your application needs to be close to complete. We understand that you will keep innovating in your space and continue converting more document execution to DocuSign. For us to get the proper context, we need to see at least a Beta.
Most of the applications we certify have multiple use cases. If only select use cases deal with electronic contract execution or electronic signatures, we recommend isolating your DocuSign use cases and preparing data, if possible, to provide the most benefit.
For example: What if your user needs to establish an account, input 3 screens of data and then sign the appropriate application? You can pre-create a user with all the data entered prior to Certification.
Commonly missed edge use cases:
1.    Users can decline to sign: DocuSign interface supports that.
2.    Users can take several sessions to sign: DocuSign allows someone to review the document, leave the signing experience and come back later to re-start signing.
3.    Network connectivity issues: Network code needs to account for circumstance. You can simulate that by plugging in the wrong web service URL.
4.    Mistyped username or password: While it’s unlikely that your API enabled user account will mistype passwords, you do want to be ready when someone resets the password through DocuSign account management console.

Timing
You might get some actionable feedback during the Certification process. That means your code, your workflow and maybe your configuration may need to change. If your company has actively engaged DocuSign Professional Services, then most likely you will have no surprises waiting for you. However, if you were coding on your own, it’s probably best to structure additional review time in your schedule to ensure sufficient time in your application release cycle.
Keep in mind that DocuSign Professional Services are booked out about 2-3 weeks in advance. The earlier you can let your account manager know that you have a new application getting ready to certify, the better.

Participants
During the Certification, your sustained engineering staff and the implementation team will be introduced to DocuSign developer support, operations and escalations personnel.
One of the goals of certification is to ensure that, in case of an emergency, precious time is not wasted determining who needs to be contacted and who can fix the business critical systems.
Re-certification: “When Do I Need to Re-certify?”
Given the fee associated with the Certification, it’s natural to try to minimize the number of Certifications. That’s a fine strategy as long as the supportability of your application doesn’t suffer.
In a case where you are adding more signatures or documents to the same process, it’s probably not going to change the calls or architecture of the application. You can continue innovation on that scale without looping DocuSign in. However, if you introduce a brand new module, change frameworks, or change programming languages then you might end up in a situation where the DocuSign documentation on your solution is out of date. Contact your Account Manager!

Summary
Please let us know if you need additional clarity into the certification process and our expectations. As mentioned above, the latest checklist can be obtained from your DocuSign Account Manager. While the contents of the Certification Checklist are constantly refined and improved, the spirit of ensuring quality, supportable integrations with DocuSign service remains the same.