Custom Rule Action
Rule Actions are Used to Integrate External Systems to Squidex, Learn How to Extend the Rule System Using Custom Actions
Last updated
Rule Actions are Used to Integrate External Systems to Squidex, Learn How to Extend the Rule System Using Custom Actions
Last updated
We will use the WebhookAction as an example to show you the basic principles.
To get started with your first rule action you might want to gain an understanding about the rule system first. Please read the following document before you continue:
In the first step, let's define an action class.
The action class has several purposes:
It provides general metadata, such as the name of the action.
It holds all configuration values for your rule action.
It is used to automatically create the editor that is then used to create or edit an action.
Let's have a look at the WebhookAction:
The metadata is provided with the [RuleAction] attribute and is mainly used in the Management UI.
You need to provide the following information:
The properties of your action class hold the configuration values. You can only use primitives that can be serialized to JSON, such as string, bool or int.
Each property can also have a:
An optional name that is shown as label.
An optional description that is rendered after the input field.
A hint that describes whether the property supports formatting via scripting or placeholders. More about this later.
A hint that the property is required. This will add validation to the API and the Management UI.
An optional data type to define the HTML control that is used:
As you know from the documentation concerning the rule system, the rules are executed in two steps:
The event is converted to a job that includes all formatted data.
The job is then executed.
We see this structure in the action handlers:
The WebhookJob contains all data that we want to store in the database and is a simplified version in this example.
The first method we need to override is used to create the job:
As you can see, we create the job from the passed in action and also provide a short description about what we've done.
We use the Format method to call the RuleEventFormatter that has been passed in via the constructor to apply formatting rules to our configuration values.
Whenever we do this, we must add the [Formattable] attribute to the properties to point out this behavior to the end users.
The second method is used to execute the job. We do not have access to our original configuration values anymore, therefore it is important to add all required information to the job:
In this case, make an HTTP call with the provided request URL and body. We have to return a result object to indicate whether our job was successful or not.
Either way, exceptions are always handled but using the approach above we can provide an optional request dump with all necessary information to make debugging easy. This type of request dump should contain the request body and response or headers.
The passed in cancellation token should be used to handle timeouts correctly and the cancel long running requests when they have exceeded the allowed execution limit.
We are almost done! Now, let's register the rule action, so for that, write a custom plugin:
That's it!
If you have written a custom rule action for a public system, like an SaaS solution, you can provide your implementation as a pull request.
| Metadata | Description |
|---|---|
| Control | When |
|---|---|
(1) Icon
The icon as an SVG document. It must be white only.
(1) IconColor
The background color for your icon.
(2) Display
A display name that describes what the action does.
(3) Title
A title that describes the system that is integrated.
(4) Description
A short description about the action
(5) ReadMore
An optional link to additional information, e.g. the website of the integrated solution.
Checkbox
Used when the type of the property is boolor bool?.
Number Input
Used when the type of the property is int or int?.
URL Input
Used with with the attribute
[Editor(RuleFieldEditor.Url)].
Password Input
Used with the attribute
[Editor(RuleFieldEditor.Password)].
Email Input
Used with the attribute
[Editor(RuleFieldEditor.Email)].
Text Area
Used with the attribute
[Editor(RuleFieldEditor.TextArea)].
Input
For all other cases.
