Using Connect’s Send Individual Messages Feature
The Connect feature is a DocuSign platform web service. It enables your applications’ web server (your “listener”) to receive notifications about DocuSign envelope and envelope recipient events shortly after they occur. E.g., an envelope has been completed or voided; a signing recipient has declined to sign, etc.
A Connect “webhook” is created as a “subscription” or “configuration” at the account-level to receive notifications about the envelopes sent by some or all the account’s users.
Connect subscriptions can also be created at the envelope-level, to monitor just that envelope. These subscriptions are added via the API by using the eventNotification object when calling Envelopes: create.
Send Individual Messages
By default, Connect sends messages using an “Aggregate Messages” algorithm. The new “Send Individual Messages” (SIM) algorithm is deterministic, making it easier for the developer to use and also fixes some important bugs.
If SIM is not activated, then the Aggregate Messages algorithm will continue to be used for the account.
For more details on how SIM differs from the older Aggregate Messages setting, see the “SIM Details” section below.
The Connect team strongly recommends that all customers test and then switch to the SIM algorithm. All new API integration projects should use SIM.
Rollout
Send Individual Messages is available today for test in the developer sandbox system, demo.docusign.net. Today, to enable Send Individual Messages, use the Classic Admin tool:
- If you use the New DocuSign Experience (NDSE), go to the Admin tool, then choose the “Classic Preferences” navigation item in the “Account” group on the left column.
- If you use the Classic DocuSign Experience (CDSE) Admin tool, go to the “Features” page.
- Search for “event”. Check the checkbox for “Publish each event without aggregation”:
In June or July, we plan to make the new feature available to production accounts.
In June, controlling the option will be added to the new System Updates panel. The panel is only available via the New DocuSign Signing Experience’s Admin panel.
Checking for issues: try the Send Individual Messages feature early!
In tests by our customers who beta tested the new feature, switching to Send Individual Messages (SIM) rarely caused problems, especially if you only subscribe to Envelope Completed events.
If you are subscribing to additional events, check for the following:
- The larger number of SIM messages received can overload a listener. Solution: Limit the events in the Connect subscription/configuration to only the events that you need to be notified about.
- For each envelope, early SIM messages (eg Envelope status: Created and first recipient status: Sent) will not include data items generated when the Envelope reaches the Sent status. Eg, If your listener was depending on the Envelope.SentTime field, this could be a breaking change. Solution: testing will quickly spot these types of issues. Limit the events in the Connect subscription/configuration to only the events that you need to be notified about.
- Handling re-sent messages. If a notification fails, then it will be tried again 24 hours later. When it has been successfully, resent the message will include the envelope’s status at the time the event occurred.
The status of the envelope and its recipients is included in the notification when it is generated. Since notifications are sent in order, the notification that is received last will include the most recent information.
In Aggregation mode, the envelope status is retrieved from the platform when the notification is sent, not when the envelope event occurred.
Testing: Activate and deactivate the new feature
During your testing, you can activate and deactivate the SIM feature. Then leave it activated after your testing is complete.
Auto-Activation
In the future, we will change the default configuration to use SIM. At some point in the future, perhaps September, 2018 or later, the SIM feature will be auto-activated for all accounts that aren’t using it at that time.
SIM Details
In the past, the Connect and eventNotification features would aggregate messages sent to the customer’s listener. In addition, each message would reflect the envelope’s status when the message was sent, not when the event occurred.
Starting with the Spring release, customers can set Connect to “Send Individual Messages.”
With the new feature, developers can simplify their integration software since it is no longer necessary to infer that a notification message had been aggregated together with a later message.
What are the differences between “Aggregate messages” and “Send Individual Messages?”
| Aggregate messages | Send Individual Messages | |
| Message content | Messages reflect the envelope status when the message is sent to the listener | Messages show the envelope status as it was when the event was triggered |
| Ordering the messages | Messages show the current envelope status.
requiresAcknowledgement should be set to true. Messages are sent in the order that the events occurred except for notification failures. When a failed notification is retried, it will be out of order if there were subsequent events for the envelope. Messages can be ordered using the TimeGenerated element. |
Messages show the envelope status when the event occurred.
requiresAcknowledgement should be set to true. Messages are sent in the order that the events occurred. When a message’s delivery fails, it is added to the failure/retry queue. Subsequent messages for the same Connect configuration (subscription) will be queued behind the failed message. After the first message is successfully retried, the subsequent messages will then be sent. In all cases, the messages will be sent in the order they were created. Messages can be ordered using the TimeGenerated element. |
Example: Messages sent for a specific envelope
In this example, an envelope is sent to Sue Signer. After Sue signs, a cc recipient, Charlie Copy, will receive a copy of the envelope. Sequential routing is used.
For illustrative purposes, the Connect subscriptions in this example have been set to generate event notifications for all envelope and recipient statuses. In this example, if SIM is off and Sue opens and then signs the envelope relatively quickly, the “delivered” message will usually be aggregated with the “completed” message.
| Sent with Aggregated messages? | Sent with Send Individual Messages? | |
| Message 1, the first notification message.
Envelope status: Created; Sue Signer: Sent; Charlie Copy: Created. |
No
(Aggregated with the next message) |
Yes |
| Message 2
Envelope status immediately moved to Sent Envelope status: Sent; Sue Signer: Sent; Charlie Copy: Created. |
Yes | Yes |
| Message 3
Sue opens and then signs the message Envelope status: Sent; Sue Signer: Delivered; Charlie Copy: Created. |
No
(Aggregated with the next message) |
Yes. The delivered message is sent even though the status was quickly changed to completed (signed) |
| Message 4
Sue completed (signed) the envelope Envelope status: Sent; Sue Signer: Completed; Charlie Copy: Created. |
No
(Aggregated with the next message) |
Yes |
| Message 5
Envelope sent to Charlie Copy Envelope status: Sent; Sue Signer: Completed; Charlie Copy: Completed. |
No
(Aggregated with the next message) |
Yes |
| Message 6
Envelope complete Envelope status: Completed; Sue Signer: Completed; Charlie Copy: Completed. |
Yes | Yes |
In this scenario, the listener received messages 2 and 6 when aggregation is on. With Send Individual Messages, the listener receives six messages from the Connect system.
FAQ
Q: How does an account turn SIM on and off? A: Use the Connect setting “Publish each event without aggregation” in the Classic Admin tool. This setting controls all Connect and eventNotification processing for the account. Starting in June, 2017, the feature can also be controlled through the “System Updates” screen on the NDSE admin tool. If the SIM option is not available, then consult your technical support contact to enable it.
Q: Is there any extra charge for SIM? A: No, it’s included with the Connect and eventNotification features.
Q: Can some account Connect configurations be set with SIM on and others with SIM off? A: No. Each account either has SIM on or off.
Q: What’s the default? A: For now, the default is SIM off.
Q: Do I get extra messages when SIM is on? A: With SIM on, you will get all the event notification messages that you subscribed to. If you only subscribed to Envelope.Completed messages then you will only receive those messages. With SIM, those messages will be delivered more reliably. If you subscribe to additional events, you will reliably receive their notifications if you activate SIM.
Q: As an integration developer, SIM sounds great! Any pitfalls to watch out for? A: Yes, test your listener to ensure that it works with SIM. If you’re only subscribing to Envelope Completed notifications, switching to SIM is usually seamless.
Q: I use DocuSign for Salesforce (DFS). Can I also use SIM? A: Yes. SIM has been tested with DFS.
Q: I use Connect for eOriginals, Box or OneDrive. Can I also use SIM? A: Yes. SIM works with all three.
Q: What are the “important bugs” that SIM fixes? A: If SIM is not enabled, it is possible, though rare, for notification messages to be not sent or duplicated. SIM solves these problems. DocuSign recommends that all integrations be upgraded to use SIM.
