Introduction to Writing Business Rules

Software developers often write business rules in JavaScript since it provides the ability to precisely control the inputs, outputs, and outcomes. Developers may also use the information included in the STEP API Documentation, available at [system]/sdk or accessible from the Start Page. However, users who have a good understanding of their own STEP system but limited technical knowledge may want to modify existing JavaScript business rules or write new JavaScript business rules.

This topic discusses determining the type of business rule needed, understanding the business requirements, implementing the logical parts of the requirements, and testing that the business rule meets the goal.

Prerequisites

The example in this topic uses a business condition, which can be created and configured as follows:

  1. Create a new business condition. Refer to the Creating a Business Rule, Function, or Library topic here.

  2. Configure the Evaluate JavaScript operation. Refer to the Business Condition: Evaluate JavaScript topic here.

Determining the Business Rule Type

This example demonstrates how to write a business rule to read the value on an attribute and return 'true' or 'false' based on the value. This type of business rule is a 'check' or 'validation' rule, which means it is a business condition.

A business condition is used to determine if a subsequent action or decision is needed, for example:

  • Allow or reject the transition of a product in a workflow.

  • Allow or reject the approval of a product.

  • During import, reject object creation or modification.

Understanding the Requirements

Before writing the JavaScript code for a business rule, identify the logical parts of the requirements. In this example, the logical parts are:

  1. Get access to the object in context. This is the object that is being imported, getting approved, or transitioning in the workflow.

  2. Read the value of an attribute on the object.

  3. Compare the attribute value against a fixed value and determine if they match.

  4. Return 'true' if the values match or return 'false' if the values do not match.

Implementing the Plan

Translating the logical parts of these requirements into a JavaScript business condition includes the steps below.

Get access to the object in context

In a STEP business rule, the Evaluate JavaScript operation uses a 'bind' to access an object in context. 'Binds' allow accessing many types of data and configuration objects and allows the JavaScript code to act on them. A bind requires a variable to represent it within the code. The 'Current Object' bind gives access to values on the object being evaluated.

To implement this part of the business condition, add a bind for the current object:

  • Add 'productInContext' for the 'Variable name' parameter.

  • Select 'Current Object' from the 'Binds to' dropdown.

This binding creates the 'productInContext' variable, which represents the object that this business rule is processing and makes it available to the JavaScript code. Since the 'productInContext' variable is essentially a Java object, the code can read its parameters and invoke methods on the object. The available parameters and methods are documented in the Scripting API section of the STEP API Documentation, available at [system]/sdk or accessible from the Start Page.

For example, some of the methods are available for the 'Current Object' bind include:

productInContext.getName()
productInContext.getParent()
productInContext.getChildren()
productInContext.getValue()

Read the value of an attribute on the object

With access to the object in context, now the value of an attribute can be determined. In this example, the attribute ID is 'COLOR' and it is valid for the product being processed by the business condition.

Within the JavaScript code, the variable 'attributeValue' is defined to:

  • use the current object, indicated by the 'productInContext' bind variable.

  • use the method 'getValue' to get the value of the 'COLOR' attribute.

Add the following code to the JavaScript parameter:

var attributeValue = productInContext.getValue("COLOR").getSimpleValue();

Compare the attribute value against a fixed value

An if / else conditional statement compares the value of the current object to a fixed value and determines the outcome.

  • The if block specifies code to be executed if the condition is true.

  • The else block specifies code to be executed if the condition is false.

Add the following code to the JavaScript parameter:

if (attributeValue == "Green") {
	return true;
} else {
	return false;
}

Return 'true' or 'false'

The 'return' method (included above) generates the result of the business condition.

In this example, the result is:

  • True for objects with a value of 'Green' for the 'COLOR' attribute.

  • False for objects with any value other than 'Green' for the 'COLOR' attribute.

Testing the Business Rule

Before applying a business rule to your data, test your JavaScript against applicable objects to identify coding errors.

Note: Valid object types are defined when creating a business rule. Ensure that the object type of your test objects is set on the business rule. For more information, refer to the Testing a Business Rule topic here.

To verify the JavaScript code results, test against an object that should return 'true' and against one that should return 'false.'

On the Edit Operation dialog (shown in the previous section), click the Test JavaScript button.

On the Test & Time Business Rule dialog (shown below), select a test object (the object to run the business condition against) and click the Test button.

The 'productInContext' bind variable in the JavaScript code recognizes the 'Test Object' as the 'Current Object.'

  • The ALRM-03 product has the value of 'Green' and the business rule result is True.

  • The ALRM-04 product has the value of 'Black' and the business rule result is False.