OneSpan Sign How To: Setting Up Reminders
By setting a reminder schedule, a sender can choose when and how often to notify the signer(s) about a pending signature; in addition to the initial notification sent the moment the package is sent for signing. In other words, assuming the package is not yet completed, a customizable number of notifications can be sent with a specified interval between each to remind your signer(s) of a pending signature.
Reminder schedules can only be created before a package is sent for signing. After a package is sent for signing, the reminder schedule can be retrieved, updated, or deleted. It is important to note that setting reminder schedules can only be done through the API/SDKs. If you are looking to this through the Web UI, the standard schedule of reminders of an expiring package is followed.
In this blog, I’ll show you how to setup reminder schedules with the OneSpan Sign Java SDK, .NET SDK, and REST API.
The Code
Now that we know our objective, let’s get started with the code. I will cover the exact same information for each method. Feel free to skip to the section which applies to you. Full code for this blog can be found in the Developer Community Code Share: Java, .NET, and REST.
Java SDK
I’ll start with the Java SDK. Below is a sample code on how you would create your ReminderSchedule
object. You will need to pass your packageId
object as a parameter to the ReminderScheduleBuilder
, along with the settings that suits your requirement. Since you need a packageId
to set your reminder schedule, you will need to do this AFTER you have created the package, but BEFORE you send it, so if you’re using the createAndSendPackage()
method to send your packages, you’ll need to split it up.
The withDaysUntilFirstReminder()
method allows you to wait a certain amount of days before sending the first reminder. This will not affect the initial notification sent the moment your document package is sent for signing. The withDaysBetweenReminders()
method sets the frequency of your reminders. The withNumberOfRepetitions()
method sets the number of reminders OneSpan Sign will send to your signer(s), with a maximum of 5 reminders. Once you’ve built your ReminderSchedule
object, you call on your OneSpan SignReminderService
to create your reminder schedule.
ReminderSchedule reminderScheduleToCreate = ReminderScheduleBuilder.forPackageWithId(packageId) .withDaysUntilFirstReminder(1) .withDaysBetweenReminders(1) .withNumberOfRepetitions(5) .build(); eslClient.getReminderService().createReminderScheduleForPackage(reminderScheduleToCreate);
Similarly, once you’ve sent your document package for signing, you can update your reminder schedule by creating a new ReminderSchedule
object with different parameters and calling on your OneSpan Sign ReminderService
.
eslClient.getReminderService().updateReminderScheduleForPackage(reminderScheduleToUpdate);
You can also retrieve your ReminderSchedule
object by calling on your OneSpan Sign ReminderService
. By doing so, you will also get all the reminders that have been sent to your signer(s). Reminders are returned as a list. In the example code below, I chose to print the sent date of each reminder.
ReminderSchedule reminderSchedule = client.getReminderService().getReminderScheduleForPackage(packageId); List<Reminder> reminders = reminderSchedule.getReminders(); for (Reminder reminder : reminders) { System.out.println(reminder.getSentDate()); }
To delete your reminder schedule, you likewise call on your OneSpan Sign ReminderService
.
eslClient.getReminderService().clearReminderScheduleForPackage(packageId);
.NET SDK
Next, I will cover the .NET SDK. Below is a sample code on how you would create your ReminderSchedule
object. You will need to pass your packageId
object as a parameter to the ReminderScheduleBuilder
, along with the settings that suits your requirement. Since you need a packageId
to set your reminder schedule, you will need to do this AFTER you have created the package, but BEFORE you send it, so if you’re using the CreateAndSendPackage()
method to send your packages, you’ll need to split it up.
The WithDaysUntilFirstReminder()
method allows you to wait a certain amount of days before sending the first reminder. This will not affect the initial notification sent the moment your document package is sent for signing. The WithDaysBetweenReminders()
method sets the frequency of your reminders. The WithNumberOfRepetitions()
method sets the number of reminders OneSpan Sign will send to your signer(s), with a maximum of 5 reminders. Once you’ve built your ReminderSchedule
object, you call on your OneSpan Sign ReminderService
to create your reminder schedule.
ReminderSchedule reminderScheduleToCreate = ReminderScheduleBuilder.ForPackageWithId(packageId) .WithDaysUntilFirstReminder(1) .WithDaysBetweenReminders(1) .WithNumberOfRepetitions(5) .Build(); eslClient.ReminderService.CreateReminderScheduleForPackage(reminderScheduleToCreate);
Similarly, once you’ve sent your document package for signing, you can update your reminder schedule by creating a new ReminderSchedule
object with different parameters and calling on your OneSpan Sign ReminderService
.
eslClient.ReminderService.UpdateReminderScheduleForPackage(reminderScheduleToUpdate);
You can also retrieve your ReminderSchedule
object by calling on your OneSpan Sign ReminderService
. By doing so, you will also get all the reminders that have been sent to your signer(s). Reminders are returned as a list. In the example code below, I chose to print the sent date of each reminder.
ReminderSchedule createdReminderSchedule = eslClient.ReminderService.GetReminderScheduleForPackage(packageId); List<Reminder> reminders = createdReminderSchedule.Reminders; foreach (Reminder reminder in reminders) { Debug.WriteLine(reminder.SentDate); }
To delete your reminder schedule, you likewise call on your OneSpan Sign ReminderService
.
eslClient.ReminderService.ClearReminderScheduleForPackage(packageId);
REST API
Finally, I will cover the REST API. In this section, all the requests are made to the following base URL: https://sandbox.esignlive.com/api/packages/{packageId}/reminders. You can create a reminder schedule by making a POST
request to the base URL with the following example JSON:
{ "startInDaysDelay": 1, "repetitionsCount": 5, "intervalInDays": 1, "packageId": "{packageId}" }
You will need to pass your packageId
as a parameter along with the settings that suits your requirement. The startInDaysDelay
parameter allows you to wait a certain amount of days before sending the first reminder. This will not affect the initial notification sent the moment you sent your document package for signing. The intervalInDays
parameter sets the frequency of your reminders. The repetitionsCount
parameter sets the number of reminders OneSpan Sign will send to your signer(s), with a maximum of 5 reminders.
Similarly, once you’ve sent your document package for signing, you can update your reminder schedule by making a PUT
request to the base URL with different parameters.
{ "startInDaysDelay": 2, "repetitionsCount": 5, "intervalInDays": 3, "packageId": "{packageId}" }
You can retrieve your reminder schedule by making a GET
request to the base URL. By doing so, you will also get all the reminders that have been sent to your signer(s). Below is an example JSON returned by OneSpan Sign.
{ "packageId": "ebfcf18f-7bbc-4ff6-a5db-6352dbbfa9f6", "startInDaysDelay": 2, "repetitionsCount": 5, "intervalInDays": 2, "reminders": [ { "sentDate": "2016-02-26T00:30:02Z", "date": "2016-02-25T16:53:13Z" }, { "sentDate": "2016-02-27T00:30:03Z", "date": "2016-02-26T16:53:13Z" }, { "sentDate": "2016-02-28T00:30:01Z", "date": "2016-02-27T16:53:13Z" }, { "sentDate": "2016-02-29T00:30:02Z", "date": "2016-02-28T16:53:13Z" }, { "sentDate": null, "date": "2016-02-29T16:53:13Z" }, { "sentDate": null, "date": "2016-03-01T16:53:13Z" } ] }
To delete your reminder schedule, you make a DELETE
request to base URL.
Running Your Code
You can now go ahead and run your code. In my example, I’ve chosen to send a reminder to my signer once a day. Below is a screenshot of the notification emails received by my signer for a pending signature.
For the Java and .NET SDKs, I’ve included the code that prints out the sent date of each reminder to the console. Below is a screenshot of what such an output would look like.
There you go. You have successfully set up reminders for a document package. If you have questions regarding this blog or anything else concerning integrating OneSPan Sign into your application, visit the developer community forums: https://developer.esignlive.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.
Haris Haidary
Junior Technical Evangelist