OneSpan Sign Developer: Lifecycle of a Package

Once you create a transaction in OneSpan Sign, your package starts its lifecycle in “DRAFT” status. Recipient behaviors like a signer completing signing or failing to sign before the expiration date can trigger status changes, but you can also manipulate package’s status programmatically as well. In this blog, we’ll first explore the lifecycle of a package from beginning to end and discuss the relationships between package status and signing status in very near future. Package status and signer’s signing status are two key indicators representing an e-signature process.

Below is a state machine diagram that shows you all possible statuses in OneSpan Sign and two actions regarding the package lifecycle management.

To begin, let’s review the different possible statuses:

• DRAFT: The package has not yet been sent.
• SENT: The package has been distributed for signatures but has not yet been completed.
• COMPLETED: The package has been signed by all recipients.
• OPTED_OUT/DECLINED: The package has at least one recipient who has opted out of signing the document(s) electronically or declined to sign the document(s).
• EXPIRED: The package has expired. Its expiry date is in the past.
• ARCHIVED: The package has been archived.

There are also two package lifecycle management actions:

• Trash Action: The Trash action is used to move a selected package to the Trash folder. 
  
• Delete Action: Your package will be permanently deleted and cannot be reinstated.

In the next section, we’ll focus on points 1 through 5 of above diagram. For trash and delete actions, go check the previous blog: Archive, Trash, and Delete.

1. DRAFT <--> SENT

After you have fully baked your package and are ready to send to your signers, you can do so by calling the below function:

Java SDK:

eslClient.sendPackage(packageId);				//draft to sent

.NET SDK:

eslClient.SendPackage(packageId);				//draft to sent

REST API:

HTTP Request
PUT /api/packages/{packageId}
HTTP Headers
Accept: application/json
Content-Type: application/json
Authorization: Basic api_key
Request Payload
{
   "status": "SENT"
}

If you wish to make some edits to “SENT” packages, change the status of your package to draft through:

Java SDK:

eslClient.changePackageStatusToDraft(packageId);		//sent to draft

.NET SDK:

eslClient.ChangePackageStatusToDraft(packageId);		//sent to draft

REST API:

HTTP Request
PUT /api/packages/{packageId}
HTTP Headers
Accept: application/json
Content-Type: application/json
Authorization: Basic api_key
Request Payload
{
   "status": "DRAFT"
}

2. SENT –> COMPLETED

By default, a package signed by all its recipients changes automatically to COMPLETED status. OneSpan Sign also gives you the capability to put a pause on this automatic status change, giving you time to review a package before marking it complete manually. To toggle this option, first create your package as below:

Java SDK:

DocumentPackage pkg1 = PackageBuilder.newPackageNamed("Example Package " + System.currentTimeMillis())
        .autocomplete(false)
        ......
        .build();

.NET SDK:

DocumentPackage pkg1 = PackageBuilder.NewPackageNamed("Example Package " + System.DateTime.Now)
        .WithoutAutomaticCompletion()
        ......
        .Build();

REST API

HTTP Request
POST /api/packages
HTTP Headers
Authorization: Basic api_key
Accept: application/json
Content-Type: multipart/form-data
Request Payload
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="testDocumentExtraction.pdf"
Content-Type: application/pdf

%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
   "roles":[
      ......
   ],
   "documents":[
      ......
   ],
   "name":"Example Package",
   "type":"PACKAGE",
   "language":"en",
   "emailMessage":"",
   "description":"New Package",
   "autocomplete":false,
   "status":"SENT"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--
Response Payload
{
    "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

Once you have received the “Recipient completed signing” callback event, you can use the below function to mark the package complete.

Java SDK:

eslClient.getPackageService().markComplete(packageId); 		//sent to complete

.NET SDK:

eslClient.PackageService.MarkComplete(packageId); 		//archived to completed

REST API

HTTP Request
PUT /api/packages/{packageId}
HTTP Headers
Accept: application/json
Content-Type: application/json
Authorization: Basic api_key
Request Payload
{
   "status": "COMPLETED"
}

4. OPTED_OUT/DECLINED –> SENT

If a signer has opted out of the signing electronically or has declined to sign the document(s), you may want to modify the package according to their reasons and resend it. To resend, simply call the send package function from section 1.

 Also check our Opt-out and Declined Messages guide to learn how to retrieve the opt-out and declined messages.

5. EXPIRED –> DRAFT

Depending on your requirement, if a package was already in “EXPIRED” status, but you still want to extend the expiry date for your signers. Simply update the package with a future expiration date, and the package will automatically be converted to “DRAFT” status:

Java SDK:

DocumentPackage package1 = eslClient.getPackage(packageId);
package1.setExpiryDate(newDate);
eslClient.updatePackage(packageId, package1);

NET SDK:

DocumentPackage package1 = eslClient.GetPackage(packageId);
package1.ExpiryDate = new DateTime(2019, 3, 12, 1, 0, 0);
eslClient.UpdatePackage(packageId, package1);

REST API:

HTTP Request
PUT /api/packages/{packageId}
HTTP Headers
Accept: application/json
Content-Type: application/json
Authorization: Basic api_key
Request Payload
{
   "due": "2019-03-13"
}

Next, you can modify the package, if necessary, and resend it.

Through this blog, we’ve sorted out all the package status about how they can be triggered by signers and by your application. Therefore, you can decide how many package statuses would be involved and expected in your workflow, this becomes more important when you were modeling objects and designing database for your customized application integrated with OneSpan Sign.

If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today