Summary
Introduced with release v10.4 this feature enables users, through the platform UI, to configure triggers that send API payloads to external Web service endpoints. This mechanism allows external systems to initiate workflows based on Xytech-generated messages and make calls back to the platform API to retrieve additional information.
This feature enhances the existing Event Trigger functionality by adding a new notification type. New setup items now exist to define external host URLs and their endpoints. Each trigger specifies the fields used to dynamically generate the JavaScript Object Notation (JSON) payload and the external endpoint to which the payload will be sent. [10229]
Figure 1 - Webhooks Related Data Objects
What's new in release v10.6
- Ability to define custom headers for Export Adaptors
- Enhanced URL fail-over logic for Outbound Connections
Setup Items
Outbound Connection
Outbound Connection defines and sets up the external system’s URL and authentication that are common to one or more endpoints defined by the External Adaptor.
Figure 2 - Standard Layout of an Outbound Connection
| Setting | Description |
|---|---|
| Description | Enter a label for the connection, such as the name and version of the external system or interface. |
| External Key | Optionally enter a label to identify the external system, as with any Xytech document. |
| Authentication Method |
Select the method used to log in to the external system:
|
|
Base URL 1 Base URL 2 |
Enter the base URL(s) of the external system. Base URL 1 is required. Base URL 2 is optional. See note below on Base URL fail over |
|
Username |
Enter the login account used to authenticate to the external system. |
|
Password |
Enter the password used to authenticate to the external system. |
Base URL Fail-over
Where you have specified a secondary URL, the fail-over logic will be enabled.
If Base URL 1 does not respond after the retry count (set in the Export Adaptor), the system will then fail over to Base URL 2.
Assuming Base URL 2 is successful, all following triggers will first be sent to Base URL 2.
If Base URL 2 fails to respond, the system will fail back to Base URL 1.
If both Base URLs are unavailable, the system will give up after the fail-over Base URL fails to respond. (It will not continue to flip-flop between Base URLs.)
Export Adaptor
Export Adaptors define the endpoint(s) for an Outbound Connection. An Export Adaptor is assigned to a specific Event Trigger so that the triggered payload knows where to be sent.
Figure 3 - Standard Layout for External Adaptor Setup
| Setting | Description |
|---|---|
| Description | Enter a label for this adapter, such as the purpose and criteria of the message. |
| Output Type | Select the type of system to which messages will be sent. Currently, only REST is supported. |
| Output Format | Select the standard used to format outbound data, either JSON or XML. |
| Response Format | Not used - (will be used from release v11 for response parsing) |
| Output Method | Select the method or verb used to send messages. Available options include POST, PATCH, PUT, and DELETE. |
| Connection | Select the Outbound Connection for this Export Adaptor. |
| Endpoint | Add the endpoint of the API and include the initial backslash. E.g. /orders. The endpoint can include URL Parameters, as described in URL Parameters below If there is no endpoint and the payload can be sent to the base URL, simply add a forward slash ‘/’ into the endpoint field. |
| Retry Count | If there is no response from the endpoint, the retry count defines the number of times the system will attempt to send the payload before trying the other Outbound Connection URL (if one has been defined). |
| Retry Delay | The duration in seconds between retries when an outbound message does not receive a response. |
| Time Out | The duration in seconds to wait for a response from the endpoint. |
| Disable Logging | Select (check) to stop capturing activity into the Export Adapter Log. The default setting is deselected (cleared). |
| Headers | Provides the ability for the webhook to send custom headers and whether they are to be treated as Content Headers (default = false) |
URL Parameters
URL Parameters can be added to endpoints and include a combination of static text and dynamically populated values from the triggered document. Use the same field naming convention as defining the payload template for an Event Trigger.
Examples:
-
-
{APIbaseURL}/{endpoint}/external_key=[DOC.external_key]
-
{APIbaseURL}/{endpoint}/job_no=[DOC.job_no]/jm_episode
-
Event Trigger
The Webhooks functionality builds on the existing Event Trigger features of the Media Operations Platform, providing a notification template option where you can assign an Export Adaptor and the payload template.
The Event Trigger defines the criteria that determine when a payload is sent, the method and content of the payload, and the Export Adapter to which it is sent.
- The Event Triggers and Conditions tabs determine the criteria of when to send payloads.
- The Notifications tab determines the method used to send the payload.
- The Notification Template tab determines the destination of the trigger content.
Refer to the Online Help for more information about Event Triggers and how to configure them.
Figure 4 - Event Trigger Source
| Event Trigger options |
|---|
| Active | Select (check) to make this payload active, or deselect (clear) to stop sending messages for this payload. |
| Event Code | Use the event code of NOTIFY |
| Event | Description of the trigger |
| Event Type |
Select when to trigger: INSERT sends messages when a record is first created. UPDATE sends messages when a record is modified. DELETE sends messages when a record is deleted. |
| Document | Select the data object for the trigger. |
| Doc Table Name | Select the sub-table of the document for the trigger. |
| Access | Select Global to trigger payloads for the entire system, or select an access method (Division or Work Group) to limit payloads to a specific subset of the system. |
| Division | When Access is set to Division, select the Division for which payloads will be sent. Only documents related to the selected Division will generate payloads. |
| Work Group | When Access is set to Work Group, select the Work Group for which payloads will be sent. Only documents related to the selected Work Group will generate payloads. |
Conditions — Defines the field conditions that initiate a trigger, such as when a specific field is set or modified.
Figure 5 - Event Trigger Conditions
Notifications — Establishes the notification type – select ‘Email/Alert’ for webhooks.
Figure 6 - Event Trigger Notification Type
Notification Template — Defines the action to take for the trigger.
Figure 7 -Event Trigger Layout for Export Adaptor
Export Adaptor
Select the Export Adaptor to use, as configured in the Export Adaptor section above.
Generate Default Template
Click to generate a standard payload template for the selected Document, Event Type, and Export Adaptor.
If any of the Document, Event Type, or Export Adaptor Type definitions change, you should re-generate the default template which will overwrite the previous template. If manual changes have been made to the template, you can update manually or note the additions prior to regenerating the template and reapply the changes.
Export Adaptor Template
- Displays the payload template used to generate the payload.
- Either in JSON or XML format. (The format of the template should match the format specified in the Export Adapter that will use the template.)
- Caution needs to be taken to ensure correct syntax is used and avoid adding carriage returns that add invisible or illegal characters.
- It’s recommended to construct the template in a syntax-checking text editor outside of the Xytech UI first before pasting it back into the UI to avoid errors.
- If there are errors, this will be visible in the export adaptor log during trigger sending and will fail to send.
- Users can add document fields to the payload using the syntax [DOC.fieldName]
Optionally, users can drag and drop a field from the Template Fields list on the left into the payload template field. Note that you can only use fields from the triggered document and not related tables.
Figure 8 - Dragging a field from the Template Fields list into the payload template.
Prefix File Naming Conventions
- The generic ‘DOC’ prefix before the field name is an abbreviation/placeholder for the triggered document. E.g. DOC.wo_no_seq
- You can also use the table name as the prefix to the field name.
E.g. jm_work_order.wo_no_seq
Export Adaptor Logs
When Export Adaptors are enabled for logging, all external communications will be logged into the Export Adaptor Log to assist with auditing and troubleshooting. (By default, logging is enabled for all adaptors.) From the navigation menu, click System and click Export Adaptor Logs to view the log entries.
Figure 9 - Export Adaptor Logs List
Click the ID in the Export Adaptor Log No column to view the details of a log entry, including all relevant values such as date times and request/response payloads.
Figure 10 - Export Adaptor Log Entry
The Action Menu in individual documents also displays the Export Adaptor Logs for that specific item. For example, when viewing a Work Order, the Action filters the log entries to that specific Work Order only.
Figure 11 - Export Adaptor Logs on the Work Order Action Menu
Auto Log Clean-Up
To prevent the log tables from growing exponentially due to large payload values, a periodic clean-up process removes the request and response payloads from "old" log items. The system retains the log entry that provides information that the payload was sent but removes the payloads. The default setting for this process is to clean up log items older than 60 days. This setting can be manually overwritten if required via the Application Server configuration settings.
Webhook Errors Notification
If you want to be notified by email or an alert pop-up when a webhook fails to send or receives an error response, you can set up an additional Event Trigger on the Export Adaptor Log with a condition set to trigger on receiving an error response status code (or whatever is the most appropriate trigger condition for your integration).
Troubleshooting
Trigger Condition Report
While testing an Event Trigger, it’s recommended to validate the trigger conditions by using the Event Trigger Report run from the modified record to check whether the trigger condition is met prior to saving the record.
Test by Creating a Mock Web Service using Postman
There are many ways to create a mock Web service for testing. One of the easiest is to use Postman.