Introduction to Fluent Rules

Basic steps to create a Rule Class

Rules, which are written in Java, contain specific structure and metadata for describing and validating the Rule. The steps below should be used to write a Rule:

• Write a Java class that implements the com.fluentretail.rubix.v2.rule.Rule Interface.
•  Implement the 'run' method which receives the current event context as a parameter.
• Define the Rule metadata via the @RuleInfo annotation .
• Define additional Rule metadata via the @EventAttributes and @Param* annotations.

💡 Let's take a look at an example of a Rule.    

Rule Interface and Actions for Rules

Rule Interface

For a Java class to be defined, as a Rule, it must implement the  com.fluentretail.rubix.v2.rule.Rule interface which defines a class as a Rubix compatible executable Rule. The com.fluentretail.rubix.v2.rule.Rule  provides access to the GraphQL API Client.

The Rule interface declares a run method that takes in a Context. To learn more read Rule Development Guidelines & Recommended Practices and the Write your first custom Rule using the Fluent Rules SDK (Hello World) guide.

Context parameter provides access to :

• Orchestrateable Entity e.g. context.getEntity()
• API Client  e.g. context.api()
• Source Event e.g. context.getEvent()
• Rule Parameters e.g. context.getProp()

Available Actions for Rules

Rules have Actions as an output. These Actions are provided by the Rubix SDK, and handled in a very specific way by the Workflow engine. Actions are not immediately executed synchronously within the Rule's run method. They are simply queued, and executed at the end of the execution context.

context.action().<ActionName> method returns the ActionFactory which provides the supported output actions for a rule.

There are four possible Actions available to your Rules, examples for each Action are provided in the next section:

• SendEventAction: SendEventAction produces an event, however that event could be for flow control, notification of other workflows, or future-dated events.
• WebhookAction: provides an integration ability, whereby data can be sent to an external endpoint.
• MutateAction: provides an action that mutates data (create or update an entity) within the Fluent Platform 
• LogAction: provides the ability to add a custom Orchestration Audit Event

To learn more read Rule Actions.

Examples of Rule Actions

Flow control

Notify another workflow

Notify another retailer

Future-dated/Scheduled

Mutate action

Webhook action

Log action

To learn more read Rule Actions, Designing Rules, and Event Context.

Rule Annotations

In this lesson, you will learn about  Rule Annotations and different types of Annotations.

Annotations are used to provide additional information. It can be viewed as a tag that represents metadata like Rule class details, params, event attributes, etc.

RuleInfo Annotation 

Describes the metadata for the Rule. It is important to annotate the Rule as accurately as possible.

The information in the Rule Info is used in the following ways:

• To validate the Rule for Workflow Execution.
• To provide data to display in the Workflow Builder and Rule Library.

The Rule Info includes the following properties:

• name - this is the Rule name. 
• description - this is a parameterised string used to describe the behaviour of the Rule, as well as indicate what and how the Rule Parameters are used.
• accepts - this is a list of EventInfo Annotations to describe the acceptable entity types
• produces - this uses an EventInfo Annotation to describe the Event that the rule outputs
• exceptions - this is a list of RuleExecutionException classes that this rule might throw( Exception Management)

Note: The description property is also used by the Modeller to display form fields for Parameter values. It is important that all parameters defined for the rule via the @Param<Type> annotations are reflected in the description. To learn more read Rule Info Annotation.

An Example is given below:

EventInfo Annotation

The EventInfo Annotation describes the Event-specific metadata applicable to either the incoming event (Rule Info accepts property) or the outgoing action event (Rule Info produces property).

The Event Info includes the following properties:

• eventName - the Name of the Event produced by this Rule.
• entityType - the Entity Type of the Events accepted by this Rule, or the Entity Type of the Event produced by this Rule.
• entitySubType - the Sub Type of the Entity of the Event produced by this Rule.
• status - the Status of the Entity of the Event produced by this Rule.

If the Event produced by the Rule should inherit the parent event context, you can set the produces RuleInfo property to the following, and the Rubix Engine will automatically inherit the parent event values at runtime

An Example is given below:

Event Attributes and Rule Parameters

Declaring Event Attributes Required by the Rule:

The Event Attribute type is used to provide configuration guidance to the Workflow, which is used to drive User Actions on the front end. When using a complex event attribute type such as a JSON object, it is helpful to provide a meaningful name for that type to the workflow configurators and frontend developers. Event Attributes are also considered "optional" in that the Rule should validate and handle it if they are not present

The EventAttribute Annotation declares the Event Attributes the Rule requires from the Event.

It contains 2 properties:

• name - the Name of the Event Attribute.
• type - the Type of the Event Attribute.

An example :

@EventAttribute(name = "EventAttribute1", type = "STRING")

Declaring Rule Parameters Required by the Rule

Parameters are not Event Attributes. Parameters are the configuration of a specific Rule instance within a Ruleset.

For example, the SendEvent Rule contains a string parameter named eventName, which is set during the configuration of the Rule within a Ruleset within a Workflow.

The ParamString annotation:

The ParamString Annotation defines a Parameter for the Rule of type String.

It contains 3 properties:

• name - The name of the Parameter. It is a required field
• description - The description of the Parameters. It is a required field
• defaultValue - This is the default value of the Parameter. It is an optional field

An example :

@ParamString(name = "ParamString1", description = "Parameter String 1", defaultValue = "PS1")

To learn more read Rules SDK - Event Attributes and Rule Parameters.

An Example is given below:

💡 Let's see an example which illustrates annotations.

• Name - The name of the rule how it appears in the editor. *A combination of the accountId, plugin namespace and rule name will fully qualify a rule in the workflow. For example:  TESTACCOUNT.base.ForwardIfOrderAttributeExists
• Description - The description is how the Rule appears in the editor. Placeholders (like *"{" + PROP_EVENT_NAME + "}") represent parameters and are substituted with form fields in the editor. Every defined parameter must appear in the description and every placeholder in the description must have a corresponding @Param defined.
• Accepts - For this example we're restricting the Rule to apply only to Order actions. Accepts is an array, so we could add additional Entity types by adding more. If we are not using accepts  then  it means the rule will work on any orchestrateable entity. @EventInfo annotations. Accepts is used to validate workflows when they are updated and also to filter the Rule list in the editor. 
• Produces - The rule produces an event which is defined in the produces section. Since the event name is defined via a parameter the eventName is defined as "{" + PROP_EVENT_NAME + "}". The entity type/subtype/status defaults to the same value as the current event.
• Event attributes - The list of attributes which this rule expects to be present in the incoming event attributes. The event attribute annotations of all rules within a ruleset define the interface contract of the ruleset.
• ParamString - This annotation is used for Rule parameters. For example if the Rule takes 2 string parameters, one for attribute name and other for the outgoing event name. Parameterising allows the Rule to be re-usable in different ways.
• Slf4j - The @Slf4j annotation enables the logging which is currently visible only to Fluent SRE team, but in the future will be available to partners as well

Run Method

The run method is the entry point of the Rule. This is the method where you write the functionality of your Rule. It also provides an instance of the current context into the method to write your rule logic in there.

Below you will find five stages (or phases) that we recommend for you to consider in your run method.

• Validation stage
• Retrieve data/query stage 
• Write conditional logic stage
• Build action data stage 
• Produce action stage

⚠️ You will learn about each run method stage with an example in the following section.

Below is an example of a run method configured with the required stages:

To learn more read The run Method.