The Webhook Integration is a simple, real-time event-notification system from Fewzion to another system (e.g. SAP, Ellipse) via a HTTP call. Hence, Webhooks allow you to see the change details that occurred on the Task data within Fewzion. Our Advanced Filter Expression tab provides the ability to apply filters by JavaScript to the changes that will result event notifications. So when an event is triggered by the applied conditions, a message will be send to the configured webhook’s URL.
The message will include the following information:
- Payload – the JSON representation of the payload which is sent by the Webhook
- Payload.Action – The action of the event (Add, Update, Delete)
- Payload.Type – The Type of the Model that is being updated such as 'Fewzion.Domain.Model.Task'
- Payload.Data – The JSON representation of the originating object
- Payload.Delta – The changes that have occurred in the operation leading to the raised Webhook event
- Request – The object that will house relevant information about the Request that caused the operation. It will contain information like Identity, Controller and Action
- Payload.Delta.HasChanged(PropertyName) - This method can be used to simply determine which properties have changed. It will use the existing data in the Delta object in order to return a Boolean. The occurred events with their Statuses are displayed on the Events tab
Step-By-Step Guide
This guide provides instructions on how to:
Editing a Webhook Integration
To Edit a Webhook Integration
1. Click on the Manage icon
2. Click List in the Integrations section
3. Double click on the name of the Webhook Integration (e.g. Mainstay (Webhook)) to edit it
Tip!
A Webhook Integration can have any names (e.g. WH) so check that the Integration Type is WebhookIntegration before editing an integration.To fill in the Webhook details
The Webhook details are displayed on the Details tab
Change the Name and the ShortCode displayed for the Webhook Integration in Fewzion if necessary
Enter the URL of the other system that will be called when an event happened
Select the Give Up After Minutes to specify the time period that after the Webhooks will stop trying to connect to the system (e.g. SAP) in case of non-response
Select "Enable Basic Authentication" and enter the Username and Password if the URL requires it
Info!
Give Up After Minutes time selection begins at 5 minutes and increases by 60.To check the applied Filter Expressions
The Filter Expression is displayed on the Advanced tab
Info!
The Filter Expression on the Advanced tab is disabled by defaultClick on the icon, to see this article on a new window in your browser.
When you tick the Enabled checkbox, the Edit button appears
Click Edit to add conditions to the Expression
Info!
For more information on the available objects and methods, see the Advanced Filter Expressions section.To check the occurred Events
The occurred Events are displayed on the Events tab
Info!
The Attempts column represents the number of tries until the Webhook call succeeded or reached the Give Up After Minutes time.Double click on the Event to see the details of a Webhook Event
Check the Webhook Event Details
Sometimes when the system (e.g. SAP, Ellipse) doesn’t respond to a Webhook Event call and it reaches the Give Up After Minutes value, the Webhook Event Status will become Abandoned.
Double click on the Event to see the details of a Webhook Event
In this example, the Response Status is InternalServerError (see below that was caused by a failed business rule ("Cannot change work order status") and as a result, the Webhook Event Status is Abandoned.
Click on the Run button to try to call the Webhook Event again
Info!
The OK button is equivalent to the Save button. To extend shown Event details, move the mouse over the Attempts column, click on the arrow, select Columns and select the necessary information.
Writing Advanced Filter Expressions
This section will introduce the available objects and methods (that can be used for Webhooks) and a practical example that shows the flexibility in the Filter Expression creation with Java Script.
Introducing Available Objects
By the definition, an Object refers to a particular instance of a class where the object can be a combination of variables, functions, and data structures. So what Objects can be used for our Webhook Integration?
Let's see an example!
Payload: {
Action:"update",
Type:"Fewzion.Domain.Model.Task",
Data:{
Id:"tasks-114900",
Process:"processes-11",
AddedBySystem:true,
Priority:"2A",
Description:"GCH006 - CODE A WEEKLY INSPECTION & GAS CALS",
WorkOrder:"999999-1",
Type:"TaskTypes-35",
Duration:2.0,
RequiredPeople:[],
RequiredEquipment:[],
AssignedProcessRequiredPeople:[],
AssignedProcessRequiredEquipment:[],
Changed:true,
ScheduledDate:"2015-10-29T00:00:00.0000000",
ScheduledShift:"Day",
CompletionPercentage:60,
AssignedPeople:[],
AssignedEquipment:[],
Locations:[],
Source:"Mainstay",
Attachments:[],
Deleted:false,
LastChanged:"2015-11-02T13:25:02.1094827"},
Delta:{
DocumentId:"tasks-114900",
Action:"Upd",
Changes:[{
Action:"Upd",
Property:"CompletionPercentage",
FromValue:70,
ToValue:60}],
DateTime:"2015-11-02T13:25:02.1084800"
HasChanged: function (propertyName) { return true or false;}
}
}
Request: {
Identity: "Username or APIKey",
HttpAction: "Put, Post or Patch - the name of the MVC Http Action",
HttpController: "Task - The name of the MVC HTTP Controller",
RequestUrl: "/API/v2/Tasks/ - The URL of the request"
}
Examples
Payload.Data.Process represents the Process (e.g. processes-11) of the taskPayload.Data.Source represents the Source (e.g. Mainstay) of the task
Payload.Action represents the Action (e.g. update) that occurred on the task
Payload.Type represents the Type (e.g. Fewzion.Domain.Model.Task) of the task
Delta.Action represents the Action (e.g. Upd) that occurred on the Delta
Delta.Changes[0].FromValue represents the From Value (e.g. 70) changes
Delta.HasChanged("CompletionPercentage") represents the change on the (e.g. CompletionPercentage) of the task
As you can see there are two Objects that can be used for our Webhook Integration:
- Payload object
The Payload object contains all attributes that specifies a task. As you can see, the name of the percentage completion attribute is CompletionPercentage. - Request object
The Request object allows you to create filters based on information relevant to the context of the request that made the change. A common example is using the Request.Identity property as this allows you to filter out changes made by SAP, or another system.
Introducing Available Methods
By the definition, a Method is a procedure associated with an Object class.
Our Webhook Integration uses only one Method: Payload.Delta.HasChanged("PercentageComplete") where the format is: Payload.Delta.HasChanged function (propertyName) { return true or false;}
Filter Expression Examples
Task: You would like to send a notification to Mainstay when the completion percentage of a Mainstay task is updated.
Let's see how can you achieve this with a Filter Expression!
First, you need to specify in your expression that
- the Tasks are from Mainstay (e.g. Payload.Data.Source == "Mainstay"),
- the action is Update (e.g. Payload.Action == "Update"),
- the change was not instigated by the Mainstay interface (e.g. Request.Identity != "YouAPIKey"), and
- the change occurs on the completion percentage value (e.g. Payload.Delta.HasChanged("PercentageComplete").
Info!
To specify the available attributes that can be tracked for changes (e.g. completion percentage), you need to look at the Payload object (see in the Introducing Available Objects section)So let's put it together!
1. Payload.Data.Source == "Mainstay" &&
2. Payload.Type == "Fewzion.Domain.Model.Task" &&
3. Request.Identity != "YouAPIKey" &&
4. Payload.Action == "Update" &&
5. Payload.Delta.HasChanged("PercentageComplete")
Info!
The Payload.Type field indicates the type of data (the model) that was changed in the event. In this example this would mean that the Payload.Data was of a Task.Well done! You just created your first Filter Expression!
A more advanced solution would use the { include: TheExpression } method
1. {
2. include: Payload.Data.Source == "MainStay" &&
3. Payload.Type == "Fewzion.Domain.Model.Task" &&
4. Request.Identity != "YouAPIKey" &&
5. Payload.Action == "Update" &&
6. Payload.Delta.HasChanged("PercentageComplete")
7. }
This could be expressed in a more complicated structure that demonstrates the flexibility of using this pattern:
1. {
2. include: function() {
3. return this.eventNotCausedByMainstay('[APIKey]') &&
4. this.correctSource('Mainstay') &&
5. this.correctModel('Fewzion.Domain.Model.Task') &&
6. this.onlyOnWantedActions(Payload.Action) &&
7. this.hasTargetedFieldsChanged();
8. },
9. Task: Payload.Data, // hard lock the data to a model to protect from accidental reuse of expression
10. eventNotCausedByMainstay: function (api) { return Request.Identity == api; },
11. correctSource: function (source) { return Task.Source == source; },
12. correctModel: function (model) { return model == 'Fewzion.Domain.Model.Task'; },
13. onlyOnWantedActions: function (action) { return action == 'Update' },
14. hasTargetedFieldsChanged: function () { return true; }
15. }
As you can see from the above, by using the object pattern on these expressions, it becomes possible for the user to define very complicated expressions, which can include functions and almost unlimited flexibility.
Comments
0 comments
Please sign in to leave a comment.