State Change Rule
State Change rules track incoming events carrying data about specific objects from external systems. The event carries the external object status therefore State Change rules can be used to react to the change of the status of the object. When all the conditions have passed, an executable object is executed in the Automation Engine.
This page includes the following:
Defining a State Change Rule
To define a Rule you must satisfy two key elements.
- Set a Trigger using the Event Definition box.
- Define an Action to execute when one or more defined Event condition are met.
Trigger Section
To create a State Change Rule, first select at least one Event Definition which defines the structure of incoming events. An Event Definition variable is a static XML type, i.e. It stores static values or retrieves them from a particular dynamic data source. See: Variables and VARA Objects for further information.
-
Event Definition: Enter the Event Definition name or select an Event Definition using the combo list.
-
Group By: To check for the change status of an object you should first identify the objects that carry the status. The objects are identified by the Group By attributes that are selected from the event definition. Whenever a new event arrives the rule will use the Group By attributes as a key that will be used to search for the previous state.
Note: We recommend that you identify a minimum set of attributes to track, for example in a Team City Build Event, you could specify the Project as key attributes to track.
Important: The Group by attributes added in combination with key length determine the Event Engine memory usage. For example: if you define Project as a Group By attribute and you have 10 projects, then 1 state for each project is kept. Therefore the more projects the more states, the increase of memory usage.
- State Change Definition:Define the Attribute you would like to track, for example the status of a build object.
Note: The Attribute and Changed to sections are linked to your previously identified Group by attributes.
The following fields are available in the Trigger section.
| Field | Description |
|---|---|
| Event Definition |
Select an Event Definition to run a rule on. |
| Group by |
To check for the change status of an object you should first identify the objects that carry the status. The objects are identified by the Group By attributes that are selected from the event definition. Whenever a new event arrives the rule will use the Group By attributes as a key that will be used to search for the previous state. Notes:
|
| Attribute | This combo box allows you select which Event Definition Attribute should be tracked for state changes. |
| Changed to |
The boxes displayed in this section will differ based on your previously selected Parameter. String Attributes Usage: Free form text, multiple From and To states can be added. Form: <Attribute Name> changed from <From Status> to <To Status> (or <From Status> to <To Status>) Example: Set your Attribute as Project. In the From box, enter "OK" and in your To box you enter "Skipped". Click the Add button to confirm your state change. A small gray box gray is displayed with the state change name. To delete the state change, click the trash can symbol displayed in the box.
Numerical Attributes Usage: Integer based state changes are defined using set of operators in combination with defined numerical values. Form: <Attribute Name> became <From Status= Operator> <To Status = Value> (or <From Status= Operator> <To Status = Value>) Example: Set your Attribute to temperature to track a server room state. To make sure that the room temperature does not rise above a set number, use the greater than (>)operator. In the value box enter a value. Click the Add button to confirm your state change. A small gray box gray is displayed with the state change name. To delete the state change, click the trash can symbol displayed in the box. Note: The operator options are the same as those described in the Simple Rule.
Boolean Attributes Usage: Use when the state change outcome can only be one of two states. True or false. Form: <Attribute Name> changed to <Changed to Value> Example: Set your Attribute to statusFailed to track if a build has failed or not. Define your desired state by selecting True or False.
Note: The yellow header displays a description of the condition. |
|
Add Filter Expression |
The Filter Expression box serves as a pre-filter for your defined state change rule. Therefore if you defined one or more filter expression, your rule will not trigger, unless all defined expressions have been satisfied. |
Action Section
Define the Action to be taken when a condition or a number of conditions have been met. The following fields are available in the Action section.
| Field | Description |
|---|---|
| Execute |
When a condition is met the defined Action will be executed. For example an Agent has gone down and if this occurs a work flow is immediately started to restart it. |
| Map Variables |
It is possible to map the values from an event attribute to variables present on the promptset(s) of the executable. Example: If your executable has a promptset variable named "&STATUS#" and your Event Definition has an Attribute Key field called "status", they can be mapped using this feature.The "status" field value that the IA agent receives on its REST endpoint, is available to the executable, which is mapped to the variable "&STATUS#" . |
| Add (Button) |
Adds the specified mapping between the Attribute and Executable Variable. |
To Execute a Rule
-
Select the Attributes tab in the Rule Event object, then from the Agent combo box, select the IA Agent. Click Save.
- Click Execute to run the Rule.
Note: If you cancel or redeploy a rule, the Event Engine memory will be purged.