Data Binding and Synchronization
In integration scenarios, tasks are often initiated or managed through triggers from third-party services. For example, using Pipedrive as an illustrative CRM system, the following scenarios could occur:
- When a new Pipedrive deal is added, a task related to the transaction contract needs to be sent to the trader for signature.
- When a Pipedrive deal is deleted, the corresponding task created in DottedSign should also be deleted.
Furthermore, changes in DottedSign tasks may require corresponding updates in the third-party service:
- When all signers have completed signing, the Pipedrive deal should be updated to "Closed-Won".
- When all signers have completed signing, the signed contract should be downloaded for archiving and attached to the Pipedrive deal.
Thus, it is crucial for third-party services to have bidirectional binding with DottedSign tasks, allowing applications to identify which deal corresponds to which DottedSign task.
Binding Strategies
Recording Task ID
Once a task is created, the DottedSign API returns a task_id
. The application can then associate this task_id
with third-party data (e.g. deal_id
from Pipedrive) and record it in its database.
Using Metadata
Developers can also directly record third-party data on the task using metadata
during creation, with both the Quick Create a Task and Create a Task APIs. This method eliminates the need for users to manually maintain this binding relationship.
{
"file_name": "My Task",
"template_id": 1,
"stages": [
{
"email": "[email protected]",
"name": "John",
...
}
],
"metadata": {
"pipedrive_deal_id": 999
},
...
}
Synchronization Strategies
Proactive Trigger
Once data in the third-party service is updated, the application might synchronize with the DottedSign task. If using the Recording Task ID binding strategy, operations on the DottedSign API can be carried out based on the mapped task_id
, such as using the Void a task or the [Discard a Task] API.
If only the Using Metadata binding strategy is utilized, users must search for tasks containing specific metadata (e.g. pipedrive_deal_id=999
) via the Get task list API and then carry out the appropriate actions using the DottedSign API.
Passive Updates by Polling
Developers can periodically retrieve tasks of interest using the Get task list API or the Get a Task API to obtain the latest status. By monitoring changes in parameters, corresponding actions can be taken, such as updating the Pipedrive deal when a task status changes to declined
.
Be Aware of Rate Limits
Be mindful of the Rate Limit set by the DottedSign API to avoid reaching the usage cap, which could impact your application functionalities.
Passive Updates by Webhook
If developers have configured a webhook, they can receive events whenever there is activity in a task. These events include the action_name
, the corresponding task_id
, and the related metadata
. Actions can be performed based on this data, such as triggering the Download the task API to archive the completed document after receiving a completed
event.
{
"resource_id": 999,
"resource_type": "SignTask",
"action_name": "completed",
"event_datetime": "1704067200",
"event_email": "[email protected]",
"ip_address": "192.168.1.1",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36",
"task": {
"task_id": 999,
"metadata": {
"pipedrive_deal_id": 999
},
...
}
}
Updated 6 months ago