Integration Management
The Integration Manager allows the configuration of webhooks that can be used for certain system events (e.g. new task/project etc.) and also as workflow triggers on platforms like Slack and MS Teams.
What are webhooks?
Webhooks allow you to collect information about events as they happen in near real-time. Once you provide a URL and select the type of information that you want to receive, data is sent to you as the events take place. One way to generate webhooks is to use a platform such as Zapier.
Webhooks can be managed in the Screendragon Integration Manager. The Integration Manager allows you to choose the events that will trigger a webhook, meaning that you receive only the information that you want. We support the following events:
· New Task
· Task Update
· New Project
· Workflow Trigger
Event Data
When a webhook triggers based on your settings, a HTTP POST request is sent to the URL you’ve specified.
Different data is returned based on each event. Below is sample data for each event.
New Task and Task Update events
Task data:
- [[id]] Task ID
- [[name]] Task Name
- [[description]] Task Description
- [[status]] Current Task Status
- [[start_date]] Task Start Date
- [[end_date]] Task End Date
Standard data:
- [[user]] Full Name of user that triggered this webhook
- [[userid]] User ID of user that triggered this webhook
- [[username]] User Name of user that triggered this webhook
- [[form label]] The label from a form that we want to capture the data from.
New Project events
Project data:
- [[id]] Project ID
- [[name]] Project Name
Standard data:
- [[user]] Full Name of user that triggered this webhook
- [[userid]] User ID of user that triggered this webhook
- [[username]] User Name of user that triggered this webhook
- [[form label]] The label from a form that we want to capture the data from.
Workflow Trigger event
Project data:
- [[id]] Workflow ID
- [[submitter]] Submitter
- [[step]] Current Step
- [[status]] Current Workflow Status
Standard data:
- [[user]] Full Name of user that triggered this webhook
- [[userid]] User ID of user that triggered this webhook
- [[username]] User Name of user that triggered this webhook
- [[form label]] The label from a form that we want to capture the data from.
Example:
In this example, we will set up a workflow trigger. When a workflow moves from one step to another, the webhook is called.
- Provide a webhook URL (can be generated using a platform such as Zapier.)
- Set up the event in the Integration Manager:
- Click ‘Add New’ to create a new event
- Fill in the name of the event
- Select the type of event you want from the dropdown list – New Task, Task Update, New Project or Workflow Trigger
- Select the action you will be taking i.e. will you be sending Post, Put or Delete request
- Enter the URL of the webhook you will be sending data to
- Specify the body of data to be sent in the correct format
- Create a trigger in the Workflow Builder:
In the Workflow builder, you will need to create a new workflow trigger of type ‘Web Hook’ which fires on step entry:
The ‘Option’ drop-down menu is a list of the available events configured in the Integration Manager.
Slack
To configure a Slack webhook in the Integration Manager, use the following steps:
- Configure your Workspace App and generate the Incoming Webhook URL.
https://slack.com/intl/en-ie/help/articles/115005265063-Incoming-webhooks-for-Slack
- Your generic steps for entering title, selecting event etc.
- Build/Configure the body. For a detailed instructions please see:
https://api.slack.com/messaging/composing/layouts
E.g. For New Comment Event
{
"blocks":[
{
"type":"section",
"text":{
"type":"mrkdwn",
"text":" *[[user]]* has posted a new comment to the <[[item url]]|[[project]]> project."
}
},
{
"type":"section",
"text":{
"type":"mrkdwn",
"text":"[[comment]]"
}
}
]
}
Microsoft Teams
To configure a Teams webhook in the Integration Manager, use the following steps:
- Configure your Workspace App and generate the Incoming webhook URL.
Or
- Your generic steps for entering title, selecting event etc.
- Build/Configure the body. For a detailed instructions please see:
E.g. For New Comment Event
{
"type":"message",
"attachments":[
{
"contentType":"application/vnd.microsoft.card.adaptive",
"content":{
"type":"AdaptiveCard",
"body":[
{
"type":"TextBlock",
"size":"Medium",
"weight":"Bolder",
"text":"New Comment"
},
{
"type":"TextBlock",
"text":"*[[user]]* has posted a new comment to the [[project]] project.",
"wrap":true
},
{
"type":"TextBlock",
"text":"Check out [[[item url]]]([[item url]])"
},
{
"type":"TextBlock",
"text":"[[comment]]",
"wrap":true
}
],
"msteams":{
"width":"Full"
},
"$schema":"http://adaptivecards.io/schemas/adaptive-card.json",
"version":"1.2"
}
}
]
}
