1. Creating and Sending a Package

This guide shows you how to create and send your first document package.

This guide will walk you through the steps necessary to create and send a document package (transaction in the new UI) with the OneSpan Sign Java SDK, including, downloading the Java SDK, downloading the Eclipse Java IDE, and creating/configuring a Java project.

Requirements

Below are a few requirements for following along with this guide.

Downloading the Java SDK

Before you can use the Java SDK, you will need to download it. You can find the download by visiting the following link.

Download the Java SDK

Downloading a Java IDE

This guide uses the Eclipse IDE. You can use another, but everything in this guide will be described using Eclipse. Below is a link to download Eclipse. You can use any of the download packages that is for Java development.

Download Eclipse

Go ahead and install Eclipse by unzipping the zip file to your preferred location. For example, “C:/Eclipse/”.

Create and Send a Package

Now that you have all of the essentials for completing the guide, you can go ahead and get started.

Create and Configure a Java Project

Open Eclipse by running eclipse.exe from the root “eclipse” folder. Once it has started up: if it is not already open, open the Java perspective. You can do this by going to Window -> Open Perspective -> Other… -> Java.

Capture

Once you have the Java perspective open, you should see a View called the “Package Explorer” on the left side of the screen. Right-click inside this window and go to New -> Java Project. That will open a window like the one below:

Capture

Name your project whatever you would like. For example, “CreateAndSendPackage”. Then, hit next.

Choose the Libraries tab, click the “Add External JARs…” button, navigate to the location that you saved your SDK to, and select the “sdk–jar-with-dependencies” jar. After you select “Open”, you will see that the SDK jar has been added to your build path.

Capture

Select Finish.

Your new project has now been added to your Package Explorer view.

Capture

Expand the package by clicking on the arrow to the left, right click on the “src” folder and go to New -> Package. Enter what you want for the package name. For example, “com.esignlive.example”. Select Finish.

Capture

Right-click on your new package in the Package Explorer and go to New -> File to create a new java file. Enter a name for the file. For example, “SimpleCreateAndSendPackage.java”. Select Finish.

Finally, add a sample PDF file that you want to have signed to your project with a simple copy and paste from your file system into your project in the package explorer.

This completes the setup and configuration. Your project should now look like this:

Capture

You are now ready to write the code in your Java class.

The Code

In this section, the code will be broken down section by section. You can download the full sample code from the Developer Community Code Share, here.

The first few lines define your connection information for OneSpan Sign.

public static final String API_KEY = "";
public static final String API_URL = "https://sandbox.esignlive.com/api";
// USE https://apps.esignlive.com/api FOR PRODUCTION

To retrieve your API key, log in to your OneSpan Sign account and click on “ACCOUNT” from the top menu. Your API key is listed there. By default, the value is hidden. Select “Unlock” to show the value. Now, replace with your API key value.

Next is the API_URL. If you’re using the Sandbox, the correct URL is already in place. If in production, you should use the commented out URL.

EslClient eslClient = new EslClient( API_KEY, API_URL );

The above line of code creates our OneSpan Sign Client using your OneSpan Sign account’s API Key and the appropriate API URL that you defined above.

The next block of code is where you actually create the document package. Within this block, you give your package a name.

DocumentPackage documentPackage = newPackageNamed( "Test Package Java SDK" )

Next, two signers are added to the package. One being yourself and the other being the person you will send the package to for signature. In this block, you will replace the email addresses and names with your test info.

.withSigner( newSignerWithEmail( "signers.email@example.com" )
        .withCustomId( "Signer" )
        .withFirstName( "SignerFirstName" )
        .withLastName( "SignerLastName" ) )
.withSigner( newSignerWithEmail( "your.email@example.com" )
        .withFirstName( "YourFirstName" )
        .withLastName( "YourLastName" ) )

Now, you add your document to be signed and also place the signature blocks for your signers. Again, remember to replace the sample values in this block with your test info.

.withDocument( newDocumentWithName( "sampleAgreement" )
        .fromFile( "your file path" )
        .withSignature( signatureFor( "signers.email@example.com" )
                .onPage( 0 )
     	        .atPosition( 175, 165 ) )
        .withSignature( signatureFor( "your.email@example.com")
                .onPage( 0 )
                .atPosition( 550, 165 )))

Finally, you build your package.

.build();

Now that the document package object is ready, you access your OneSpan Sign Client, create your package, and send it to the signers.

// Issue the request to the OneSpan Sign server to create the DocumentPackage
PackageId packageId = eslClient.createPackageOneStep( documentPackage );
 
// Send the package to be signed by the participants
eslClient.sendPackage( packageId );

Running the Code

With your Java class completed, you can go ahead and execute your simple application. There are a few ways you can do this from Eclipse. In the toolbar, you can select the run button, you can select Run -> Run from the menu bar, or you can right click on your Java class in the Package Explorer and choose Run As -> Java Application.

If you check your OneSpan Sign Sandbox account inbox, you will see that the package has been created and waiting for signature. Here is an example of what you might expect:

Capture

Get the Code