VCSI: Editable Business Rules Format

To support the Version Control System Integration (VCSI), JavaScript-based business rules can be created, maintained, and tested outside STEP. This allows customers and partners to govern the lifecycle of business rules in a standard source code control system such as Git, and from there, be able to deploy appropriate versions of the business rules to the various STEP systems that are part of a Development, Testing, Acceptance, and Production (DTAP) environment.

This topic describes the following in detail:

• Editable Business Rule Format

• Options for Export

• Options for Import

• REST Resources for Testing and Validation

Note: For on-premises systems, this feature requires the 'configuration-management' add-on component.

Editable Business Rule Format

Business rules can be exported as *.js files that can be edited outside STEP and imported back into a STEP system, creating, or updating a business rule. This format is available for business conditions, actions, functions, and libraries of 'Global' scope created using the business rule format introduced with STEP 7.0. Each file represents a single business rule and contains all information necessary to create / update the rule on import.

In the *.js files, metadata and definitions of non-JavaScript operations and preconditions ('Applies if') is output in comment sections, while the JavaScript for the individual operations and preconditions are wrapped in functions with objects provided by the execution context as parameters (binds, messages, function input parameters, and referenced libraries).

For example, consider a simple business action with two operations - one JavaScript operation as shown below:

and also, the following non-JavaScript precondition:

When exported using the default settings, the business actions are represented in the generated file as follows:

Note: When exporting business rules in editable format using a change package, the export contextId and workspaceId are not populated. When editing the business rule, also specify the intended context and workspace for import.

/*===== export metadata =====
{
  "contextId" : "Context1",
  "workspaceId" : "Main"
}
*/
/*===== business rule definition =====
{
  "id" : "CreateReference",
  "type" : "BusinessAction",
  "setupGroups" : [ "Actions" ],
  "name" : "Create Reference",
  "description" : null,
  "scope" : "Global",
  "validObjectTypes" : [ "SalesItem" ],
  "allObjectTypesValid" : false,
  "runPrivileged" : false,
  "onApprove" : "Never",
  "dependencies" : [ ]
}
*/
/*===== business rule plugin definition =====
{
  "pluginId" : "JavaScriptBusinessActionWithBinds",
  "binds" : [ {
    "contract" : "CurrentObjectBindContract",
    "alias" : "node",
    "parameterClass" : "null",
    "value" : null,
    "description" : null
  }, {
    "contract" : "ReferenceTypeBindContract",
    "alias" : "refType",
    "parameterClass" : "com.stibo.core.domain.impl.ReferenceTypeImpl",
    "value" : "PrimaryProductImage",
    "description" : null
  }, {
    "contract" : "AssetBindContract",
    "alias" : "asset",
    "parameterClass" : "com.stibo.core.domain.impl.FrontAssetImpl$$Generated$$7",
    "value" : "P_AC-AXPFX769",
    "description" : null
  } ],
  "messages" : [ {
    "variable" : "AssetNotFoundError",
    "message" : "Asset with ID \"P_AC-AXPFX769\" could not be found",
    "translations" : [ ]
  } ],
  "pluginType" : "Operation"
}
*/
exports.operation1 = function (node, refType, asset, AssetNotFoundError) {
  if (asset == null) {
	  throw new AssetNotFoundError();
  }

  if (node.getReferences(refType).isEmpty()) {
	  node.createReference(asset, refType);	
  }
}
/*===== business rule plugin definition =====
{
  "pluginId" : "ValidHierarchiesBusinessCondition",
  "parameters" : [ {
    "id" : "HierarchyRoots",
    "type" : "java.util.List",
    "values" : [ "step://product?id=I-Level1-1" ]
  } ],
  "pluginType" : "Precondition"
}
*/

The logic of the JavaScript operation is wrapped in a function. In the example, this function is exported in line with the Node.js module system convention. The case-sensitive property ConfigurationManagement.BusinessRuleConverter.ExportFormat in the sharedconfig.properties file on the application server can be used to change this. The valid values of this property are:

• 'NodeExport' (default; Node.js module system)

• 'EcmaScriptExport' (ECMAScript module system compliant format)

• 'NoExport' (functions not exported)

The format for business libraries differs as a library in STEP already holds a number of JavaScript functions that can be called from other business rules. To make these functions available to other modules, the functions are exported when the 'NodeExport' or 'EcmaScriptExport' settings are used.

For a JavaScript library example, consider a library with the following content:

function isProductBelow(prod, checkProdID) {
	if(!isProduct(prod)) throw "Function only works with Products";
	if(checkProdID == "Product hierarchy root") return true;
	if(prod.getID() == "Product hierarchy root") throw "The top level Product is never below another Product.";
	var currentParentId;
	var currentProd = prod;
	while (true) {
		currentParentId = currentProd.getParent().getID();
		if(currentParentId == "Product hierarchy root") return false;
		else if (currentParentId == checkProdID) return true;
		else currentProd = currentProd.getParent();
	}
}

function isProduct(obj) {
	return obj instanceof com.stibo.core.domain.Product;
}

When exported with the ConfigurationManagement.BusinessRuleConverter.ExportFormat property set to the default 'NodeExport' value, the following is appended to the file, allowing you to require / import the functions from another Node.js module. Everything below, including the comment, is ignored when the library file is imported in STEP.

/*===== business library exports - this part will not be imported to STEP =====*/
exports.isProductBelow = isProductBelow
exports.isProduct = isProduct

Important: While it is possible in STEP to call functions in other business libraries from within a library function, this functionality is not supported when calling the exported library functions from another module.

To allow library functions that call functions in other referenced libraries to be executable outside STEP, these can be modified so that you can pass the library as a parameter. For example, assume that there is a library function like the one that follows:

//"lib" is alias for a referenced library with a function getUpc()
function setUpc(node, attributeId) {
  node.getValue(attributeId).setSimpleValue(lib.getUpc());
}

This function can be modified as shown below, allowing it to pass the library as a parameter when invoking the function outside STEP.

function setUpc(node, attributeId, passedLib) {
  if (lib == null) {
    lib = passedLib;
  }
  node.getValue(attributeId).setSimpleValue(lib.getUpc());

Note: Adding an extra optional parameter does not require that the JavaScript calling the function be modified.

Options for Export

Business rules can be exported to the editable format manually or via an outbound integration endpoint (OIEP).

Manual export

To manually export business rules individually, from a System Setup node that houses business rules, right-click and select the 'Export in Editable Format' option as shown below:

Outbound Integration Endpoint

When 'Convert business rules to editable format' is set to Yes, the post-processor converts business rules in the STEPXML to the editable format and represents them in a single *.js file instead of representing them in a STEPXML file.

As shown below, set the 'Convert business rules to editable format' parameter to Yes when using the configuration management STEPXML Splitter post-processor for OIEPs:

or when using the Change Package Git Delivery method on an OIEP, where the STEPXML splitter is integrated:

For details, refer to the VCSI: STEPXML Splitter Post-processor in OIEP topic.

Options for Import

Business rules and data files can be imported manually or via an inbound integration endpoint (IIEP).

Manual import

Manually importing business rules in the Editable Format involves the following requirements and configuration.

Prerequisites

Each editable business rule file (.js extension) must include a valid "contextId" and the "workspaceId" must be set to "Main".

Configuration

To import a single business rule manually, from the File menu, select Import and then Import Business Rule from Editable Format, as shown below.

Inbound Integration Endpoint

The configuration management STEPXML Joiner pre-processor can be used to import multiple business rules via an IIEP. The pre-processor accepts a *.ZIP file containing STEPXML files as input as well as business rule_.js files that the pre-processor will convert to STEPXML and merge into the STEPXML file delivered to the import process.

Prerequisites

The file(s) to be imported must comply with these requirements:

• The file must be a ZIP file and can contain multiple individual business rule files (with .js extension) and STEPXML files (with .xml extension).

• Each file included in the ZIP file must contain one object as produced in the STEPXML Splitter or with the delivery method of Change Package Git Delivery.

• Groupings of the same object super type (i.e., products or entities or classifications, etc.) are supported. Files containing mixed object super types (such as entities and products, or classifications and products, etc.) are not supported by the STEPXML Joiner.

• Each editable business rule file (.js extension) must include a valid contextId and the workspaceId must be set to "Main", regardless of the STEPXML Joiner pre-processor configuration for the 'Import context' parameter.

• When the STEPXML Joiner pre-processor is configured to derive the import context from input files, each STEPXML file must include a valid ContextID and the WorkspaceID must be set to "Main".

• Each .js business rule file name must start with the text BusinessRule_ followed by the JavaScript file name.

For example, consider importing two STEPXML files, each containing one attribute, and an editable JavaScript business rule file. When originally exported manually, the business rule was named 'InitiateToWorkflow.js'. The name of the .js file must be changed before generating the ZIP file so it includes the expected BusinessRule_ prefix. The files included in the ZIP files are named as follows:

• Attribute_ModelNumber.xml

• Attribute_UPC.xml

• BusinessRule_InitiateToWorkflow.js

In this example, the three files are zipped and the file is named: Sprint8ConfigurationFiles.zip. The ZIP file is sent to the IIEP using the REST Receiver, and the REST API V2 endpoint 'upload and invoke' is used to post the ZIP and start the import process.

Note: When exporting business rules in editable format using Change Package Git Delivery, the export contextId and workspaceId are not populated. When editing the business rule, also specify the intended context and workspace for import.

For details, refer to the 'STEPXML Joiner Pre-processor for IIEP' section of the topic.

Note: When importing a business rule, all valid object types included in the import will be added to the existing list of valid object types for that rule.

REST Resources for Testing and Validation

Available REST resource operations allow:

• Testing JavaScript on a running STEP server.

• Validating the syntax of a business rule in the editable format on a STEP server.

The REST resource for testing JavaScript is available at http(s)://[step-hostname]:[step-port]/configuration-management/test-javascript?context=[context-id]&workspace=[workspace-id] and allows clients to execute ECMAScript 5-compliant JavaScript on a running STEP server in a non-committing mode with access to a STEP Manager that gives access to the standard STEP Scripting API.

As an example, POSTing the function shown below to https://[step server]/configuration-management/test-javascript?context=Context1&workspace=Main returns "Context1":

function getContextId(manager) {
	return manager.getCurrentContext().getID();
}
getContextId(manager);

The resource for validating a business rule definition in the editable format is available at http(s)://[step-hostname]:[step-port]/configuration-management/validate-business-rule. The resource allows clients to POST a complete business rule definition and validates the business rule in these steps:

• Model validation - validates the overall structure and determines if the business rule metadata is correct (syntax check only).

• Domain validation - validates existence of the operation and precondition option and checks if the correct parameters have been supplied (values are not checked).

• Conversion validation - validates if the business rule definition can successfully be converted to STEPXML.

The resource returns a Boolean indicating if the business rule is valid and includes a list of any encountered errors.

Example response:

{
    "valid": false,
    "errors": [
        "'businessRuleDefinition.id': may not be null"
    ]
}

These REST resources:

• Use basic authentication and the user invoking the resources must have a privilege that includes the 'Test JavaScript' setup action.

• Require the property ConfigurationManagement.TestJavascript.Enabled (which defaults to 'false') in the sharedconfig.properties file to be set to 'true' on systems to be used for tests and validation.

Note: Documentation and an example step.js Node.js module that wraps the REST resources and can be used together is available from the Technical Documentation accessible at [system]/sdk or from the system Start Page.

Additional VCSI information can be found in the following topics:

• VCSI: Change Package Git Delivery Method in OIEP

• VCSI: Git Delivery Method in OIEP

• VCSI: STEPXML Joiner Pre-processor Options in IIEP

• VCSI: Example Setups

• VCSI: Considerations and Limitations