The Workflow Webhooks provide System Admins with the ability to use the Rule builder to notify an external service of when a change has happened to a HighQ iSheet or file.
A system admin can add configuration to allow HighQ to connect to external services via an API.
'Connect to External services' is currently in Beta release and only available to selected customers.
Please confirm with your HighQ representative you have the ‘Connect to external services’ setting enabled for your instance.
Workflow Webhooks unlock the ability to sync or communicate with external services. As a system admin, set up your external services, then create Workflow rules that trigger when an iSheet record or file is created or updated. Use the Webhook to notify services such as Salesforce or Power Automate in order to create, process, update and track your work over multiple products.
Set up process
The steps needed to set up external services are:
- Confirm External services are active on your instance (with HighQ support)
- Check the configuration of the external service (i.e. URL and authentication type)
- Configure the service in System Admin
- Create a Workflow rule with an External service action
Request Body JSON examples are available below.
Configure the service in system admin
If you do not see the Connect External Service option, please ask your HighQ representative to enable Connect to external services for your instance.
Open System admin from the Profile menu, then select Connect External Service:
The External Services window opens:
Select Add to open the Add external service window:
Add a Name and URL for the external service.
The URL can be found in the settings for the external service. Please refer to the help for the external service on how to find this.
Only the POST request method is supported.
Authentication
Select the authentication type required.
Please check with your HighQ representative for specific configuration requirements. Webhooks supports OAuth2 or OpenURL.
Follow the instructions below for the appropriate authentication type.
OAuth2 authentication
Many services are authenticated through OAuth2, which allows the webhook to notify services such as Salesforce.
For instructions on setting up your sites with the Salesforce Integration, please view the Salesforce Add-in guide.
Select the OAuth 2.0 authentication type.
Only the Client Credentials grant type is supported:
Click Add to validate and create the new service.
If the validation fails, confirm all highlighted fields are correct:
OpenURL (No Auth) authentication
If the service requires OpenURL for authentication, such as Power Automate, follow the instructions below.
Please beware of the associated risks when connecting without secure authentication.
Select the No Auth authentication type.
Click Add to validate and create the new service.
If the validation fails, confirm all highlighted fields are correct:
Manage your external services
External services are shown in the External Services window:
Select the More actions icon to see more options:
- Edit - open the Edit external service window to update the service configuration
- Deactivate - set the status to Inactive - select Reactivate to change the status back to Active
- Remove - delete the external service - note, you cannot restore a removed service
The number amount of Active external connections varies depending on your configuration; Inactive connections do not count against this limit.
Please contact HighQ support for more information about the external connection limit.
Creating a Workflow rule with an external service
After you configure one or more external services, a system admin can use the Send to external service action in Workflow.
Add a new Action, either in a new or existing Rule.
The Send to external service action is available for the Add iSheet, update iSheet, Add file, or Update file triggers.
[screen]
Add an action to a rule
In the Action tab, select Send to external service, then the name of the service created in System Admin:
Then Save your Rule.
A site admin cannot create or edit a rule with an external service action, but is able to view the action:
Internal or External rules
To help manage your rules, you can see if a rule is Internal, External, or uses both actions (Internal and External) in the list of rules on your site.
The Type column shows the type of action or actions:
Workflow audit history
If you enable external services and the action is triggered, the Workflow audit history provides a Send to external service filter in the list of Actions.
The audit lists matching rules:
The Triggering object column includes a link to the record or file that triggered the rule and if the rule Failed, the Status column includes a link to further details for troubleshooting.
If you require support to help with troubleshooting, please include information from the Audit detail window (Copy the Rule action detail, Error message, API URL and Request values)
Support for external actions in Site templates
Workflow rules are supported when you Export or Import a Site template. However, rules with external actions are subject to some limitations.
Workflow rules that feature external connections are included in the exported template, however, if a template is imported to a new instance, a system admin must edit all rules that feature an external action to use the 'new' external service.
Rules with external actions are listed in the dependency report, below.
You must ask your HighQ representative to enable Connect to external services on a new instance if you need rules that use external actions.
Export dependency report
If your instance has rules with external actions, you see this when you export a site template:
Please check the description, review your Workflow rules on the new site and update any external service configurations.
Request Body JSON options
The Request Body JSON can include values from the list below:
Descriptions of content in the Request Body for iSheet and File Triggers based on Add/Update Operations.
Common Request body fields
1. instanceId - The HighQ Collaborate Unique ID for your instance
2. instanceBaseUrl - The HighQ Collaborate URL for your instance
3. timezone- The time zone configured in HighQ Collaborate
4. siteId - The ID of the Site in which the iSheet/File operation was performed
5. author - The ID of the User who performed the operation
6. moduleAlias - The Module Alias of the iSheet or File
iSheet Operation - Add/Edit
1. moduleAlias - SITE_MODULE_ISHEET
2. contentID - The ID of the iSheet record that was added or updated
3. isheetID - The ID of the iSheet that triggered the operation
File Operation - Add/Edit
1. moduleAlias - SITE_MODULE_DOCUMENTS
2. contentID - The ID of the File record that was added or updated (when the new file version was uploaded)
3. parentFolderId - The ID of the Folder in which the File was added or updated
4. documentExtension - The type of File
Common Request body fields related to Workflow tracking
1. workflowId - The ID of the Workflow in the site where the rule is configured.
2. ruleId - The ID of the Rule in Workflow.
3. ruleExecutionTimestamp - The timestamp value when the Rule was executed.
Examples
Trigger - When iSheet record is added
{
"instanceId": "parthpithadia_develop_feature2.1686832116640",
"instanceBaseUrl": "https://tr-ggh2y33.hqdev.highq.com/parthpithadia_develop_feature2",
"timeZone": "Asia/Calcutta",
"siteId": 5,
"workflowVersion": "23110",
"workflowId": 1,
"ruleId": 39,
"ruleExecutionTimestamp": 1697712006438,
"author": 100,
"triggerDetail": {
"moduleAlias": "SITE_MODULE_ISHEET",
"operation": "ADD_ITEM",
"contentDetail": {
"contentId": 111,
"isheetId": 13
}
}
}
Trigger - When iSheet record is updated
{
"instanceId": "parthpithadia_develop_feature2.1686832116640",
"instanceBaseUrl": "https://tr-ggh2y33.hqdev.highq.com/parthpithadia_develop_feature2",
"timeZone": "Asia/Calcutta",
"siteId": 5,
"workflowVersion": "23110",
"workflowId": 1,
"ruleId": 39,
"ruleExecutionTimestamp": 1697712006438,
"author": 100,
"triggerDetail": {
"moduleAlias": "SITE_MODULE_ISHEET",
"operation": "EDIT_ITEM",
"contentDetail": {
"contentId": 111,
"isheetId": 13
}
}
}
Trigger – When File is added
{
"instanceId": "parthpithadia_develop_feature2.1686832116640",
"instanceBaseUrl": "https://tr-ggh2y33.hqdev.highq.com/parthpithadia_develop_feature2",
"timeZone": "Asia/Calcutta",
"siteId": 5,
"workflowVersion": "23110",
"workflowId": 1,
"ruleId": 54,
"ruleExecutionTimestamp": 1697711405351,
"author": 100,
"triggerDetail": {
"moduleAlias": "SITE_MODULE_DOCUMENTS",
"operation": "ACTIVITY_DOCUMENT_ADDED",
"contentDetail": {
"contentId": 8,
"parentFolderId": 26,
"documentExtension": "png"
}
}
}
Trigger – When File is updated (New file version is uploaded)
{
"instanceId": "parthpithadia_develop_feature2.1686832116640",
"instanceBaseUrl": "https://tr-ggh2y33.hqdev.highq.com/parthpithadia_develop_feature2",
"timeZone": "Asia/Calcutta",
"siteId": 5,
"workflowVersion": "23110",
"workflowId": 1,
"ruleId": 54,
"ruleExecutionTimestamp": 1697711405351,
"author": 100,
"triggerDetail": {
"moduleAlias": "SITE_MODULE_DOCUMENTS",
"operation": "ACTIVITY_VERSION_UPLOADED",
"contentDetail": {
"contentId": 8,
"parentFolderId": 26,
"documentExtension": "png"
}
}
}
