How to configure and use the Rosterfy / Docusign integration.
Overview
-
The Rosterfy / Docusign integration provides 4 main functions between the two platforms.
-
The main function is to trigger sending templates from within Docusign to go to Rosterfy users based on a trigger from within the Rosterfy platform
-
The system can syncronize the status of a contract in Docusign with Rosterfy, and on a contract being completed, trigger additional automated functionality
-
You can use the Docusign feature ‘Connect’ to do this in real time as well, however this will send all Docusign updates on your account to Rosterfy, so please consider any wider business uses of Docusign before implementing this
-
-
The system can extract data out of a completed contract back into the Rosterfy platform to update Rosterfy fields
-
The system can update Docusign prefill / recipient fields based on data in Rosterfy
Enabling the Integration
1. Go to Rosterfy integrations list under Settings -> Advanced
3. Click the Authorize button to load the list
4. You may be prompted to allow Rosterfy to access your Docusign account. You will need to allow this.
5. Once the authorization is complete, you will see a list of settings available. Docusign provides a list of accounts connected to specified user. Based on the account you select, will determine which contracts are available in Rosterfy
6. You can now synchronize your Docusign templates in this setup screen
Integration Settings
Connect Secret
The connect secret is used to authenticate any webhooks from Docusign in Rosterfy. Once you enable Connect in Docusign, you will be provided this value. When setting up in Docusign, you will need to tell Docusign where to send the webhook (URL to Publish). The address will be https://<<rosterfydomain>>/account/integration/webhook/contract:Docusign
Recipient Override
This is a configuration option to update recipients in a template sending list to be Rosterfy values. This setting is a JSON object with an example format below. You can add as many records as you need to this setting which will update recipients based on their role in Docusign.
{
"<<Docusign recipient role name>>": {
"email": "<<rosterfy entity>>.<<rosterfy attribute code>>",
"name": "<<rosterfy entity>>.<<rosterfy attribute code>>"
},
"<<Docusign recipient role name>>": {
"email": "<<rosterfy entity>>.<<rosterfy attribute code>>",
"name": "<<rosterfy entity>>.<<rosterfy attribute code>>"
}
}
For example, if you setup the below signing order in Docusign
You could then configure the recipient override setting to update recipient 2 and 3 by specifying the role name in the setting. Ie
{
"signer2": {
"email": "user.email",
"name": "user.first_name"
},
"signer3": {
"name": "role_offer.budget_owner",
"email": "role_offer.budget_owner_email"
}
}In this example, the system would go to the user related to the contract and update signer2 to use the email address, and go to the role offer associated with the contract and get the attribute ‘budget owner’ and update the recipient with the role ‘signer 3’
Attribute Extract
Fields that are extracted from Docusign back into Rosterfy. Following a similar setup to the above, you will specify a JSON object with the following format
{
"<<Docusign data label>>": "<<rosterfy entity>>.<<rosterfy attribute code>>",
"<<Docusign data label>>": "<<rosterfy entity>>.<<rosterfy attribute code>>",
}
When you setup a template in Docusign, you can specify a data label on any text fields which then are received back into the platform. Below is an example of where to set the data label.
Note the ‘*| |*’ around the data label is optional. This is the pattern used by Rosterfy for mail merge tags and is not needed for data labels (however it is needed for prefill which is below)
Assuming the setup above, you could then setup the attribute extract value to be
{
"role_offer_user_custom_text_attribute": "role_offer_user.custom_text_attribute"
}
This would then look at the documents in an envelope for any fields called ‘role_offer_user_custom_text_attribute’ and update in Rosterfy the role offer user record custom text attribute field with the code ‘custom_text_attribute’.
Is Draft Only
This setting will enforce that any contracts created by Rosterfy will be created in Docusign but only as a draft and not sent. All recipients and data will be updated in the documents, it just wont be sent
Template Recipients Only
This setting will not add a new recipient to a template to send to the relevant user. This means by default, any time a contract is sent to someone in Rosterfy, the system will go to Docusign, get the relevant template, add a recipient as the user in Rosterfy and send it. If you just want to use the defined recipients already on the template you should enable this option
Example Completed Settings
Other Configuration
Prefill Tags
In Docusign you can add to templates a ‘prefill’ field. These fields can then be updated by Rosterfy on envelope creation by adding any Rosterfy mail merge tags into the documents. To enable this, you need to configure any attributes in Rosterfy as ‘can be used in communications’ on the attribute setup.
In Docusign you will find the prefill on the template creation screen here:
Once you have added a prefill field, you will need to add a data label. The data label will be the Rosterfy mail merge tag, which is
*|<<rosterfy entity>>_<<rosterfy attribute code>>|*
If you add an attribute called ‘custom_text_attribute’ onto a role offer in Rosterfy, the label will be
*|role_offer_custom_text_attribute|*.
An example can be seen here.
Sending Contract
The last configuration available is how to trigger the contract sending in Rosterfy. Sending contracts is done by configuring an automation. Once you have set an automation trigger, you can then add an action which allows you to choose which template to send.
You can use the ‘Admin Console trigger’ to allow you to send contracts to users manaully through the admin console as seen below. This configuration will send a contract to all users with an ‘accepted' status on a role offer.
Synchronising Contract
If you go to the contact list under the users->contract menu, you can then see the list of contracts. For each contract template you can view the users that have been sent that contract (You can also view this on any users update page).
If you would like to synchronise the status between Docusign and Rosterfy, you can click the ‘synchronize’ button in the dropdown next to the user name. Please note due to Docusign restrictions this can only happen once every 15 minutes. This is also done automatically each night automatically for any incomplete contracts for a month after it is created.
