OneSpan Sign Developer: Transaction Export & Download Tool
How you can monitor the signing progress of ongoing transactions and download completed ones in bulk?
This has been a frequently asked question as well as a common requirement when designing e-signature workflows. OneSpan Sign offers powerful and flexible in-app reporting that provides customers structured data of monthly transactions to conduct a value-added analysis or to manage the operations.
On top of the native reporting capability, this blog will introduce a sample integration tool which pulls a list of transactions within a given time range and allows admin users to export the result into a CSV report. Users can also download the completed transactions with minimal effort. Without further delay, let’s get started!
The integration tool is a Java integration based on the OneSpan Sign API service. Make sure you have all the necessary information and proper environment to run the executive Jar file following these steps:
- Install JRE/JDK environment (1.8 or later).
- With your OneSpan Sign account enabled integration feature, find your account’s API key, request the program issue an API token, or alternatively use your account login credentials to run the tool.
- Download the tool from the Developer Community Code Share, here. For users who have not installed JRE, there’s another version with JRE bundled.
Running the Transaction Export & Download Tool
The Transaction Export & Download Tool initiates an intuitive step-by-step wizard. Once launching the executive Jar file, the first step is to select an OneSpan Sign instance and to input your admin user’s API Key or login credentials.
- (1) If you provide the account owner’s API Key, the tool is able to pull transactions of all senders. Using sender’s respective API key will only permit access to their own transactions.
- (2) If your machine is connecting through a gateway, you must also specify the proxy settings. These settings ensure the API calls reach out to the OneSpan Sign server.
- (3) The tool now provides localizations in different languages, like Spanish and Portuguese. You will find all the options from the dropdown on the top right of the window.
Once you confirmed the login information, click the “Test Connection” button and the OneSpan Sign instance selected will be tested with the given credentials.
In the second screen, you will be prompted for some search criteria before querying the OneSpan Sign system.
These options include:
- Start and end dates. Note this date refers to the “latest update date” of a transaction. You can either select them using the date widget or enter the string directly. The maximum interval is 365 days.
- Whether to include those transactions that the sender has received as a signer. If you are only interested in outbound transactions, switch this option off.
- Whether to allow downloading uncompleted transactions. Toggle this option if you also want to download transactions of other statuses.
Tap the “load” button when you are ready. Although the tool has been optimized for a minimal number of outbound API calls, you might still experience some delay if you are loading a large amount of transactions. In which case, I would suggest to set the interval to every 15 days depending on the monthly amount.
All buttons will be disabled during processing, and a brief sender report will be displayed when the tool has completed loading. Note there are two numbers for each transaction status (e.g. 7/7). The total amount is retrieved from the sender usage report API, and the actual amount is counted when querying via transaction retrieval API.
Export the Report
The “Export as CSV” function generates a CSV report of loaded transactions. From the tool panel, you can choose whether to include transactions of all statuses or only the completed transactions.
Because the tool is an integration running on the customer’s side, it has more flexibility to include more columns in the report as long as the bit of data is accessible via API. The screenshot below what the report could look like:
Bulk Download Transactions
The user can select individual or all transactions listed in the panel. While downloading, a tick shows up after each selected transaction in real time, indicating the tool has downloaded and compressed the relevant documents into a zip file and saved it to the file path of user’s choice. These relevant documents could include the attachments uploaded by the signer, evidence summary with signing-related record, and the signed documents. Users have the option to choose whether to include each part.
Logging and Troubleshooting
You may have noticed that in the login phase, you have the option to choose a location where the log file will be stored. The log file will only be generated when you toggle the option and save all the outbound API Calls and their responses, which is useful when troubleshooting issues in the event the error message does not describe the problem well enough.
Because the log file may contain sensitive information, it’s important to delete the log file after you’ve confirmed the issue has been resolved and the transactions have been successfully exported and downloaded.
This walkthrough should provide you enough information to use the tool. If you encountered any issues when using the tool, enable and check the log file first. Then feel free to make a post if you need any further assistance.
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!