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.
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.
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.
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.
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:
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.
Your new project has now been added to your Package Explorer view.
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.
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:
You are now ready to write the code in your Java class.
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 = "your_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 and optionally company and title with your test info. And setting Custom Id in SDK could better identify your signer.
.withSigner(newSignerWithEmail("email@example.com") .withCustomId("Signer") //optional .withFirstName("SignerFirstName") .withLastName("SignerLastName") .withCompany("ABC Company") //optional .withTitle("Applicant")) //optional .withSigner(newSignerWithEmail("firstname.lastname@example.org") .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. Optionally, setting Document and Signature Ids would help you better locate your signature.
.withDocument(newDocumentWithName("sampleAgreement") .withId("document1") //optional .fromFile("your_file_path") .withSignature(signatureFor("email@example.com") .withId(new SignatureId("signature1")) //optional .onPage(0) .atPosition(175, 165)) .withSignature(signatureFor("firstname.lastname@example.org") .onPage(0) .atPosition(550, 165)))
Finally, you build your package.
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: