Business Rule Commands¶

Business rules can be manipulated from a Repository level and from an Entity level.

The commands that can be performed against a business rule (or rules) are as follows:

Command	Purpose
get	Get a list of rules that match the filter criteria
add	Add a new business rule
edit	Edit an existing business rule
run	Run a business rule

Glossary¶

Abbreviations used in this document:

Term	Meaning
EID	Entity ID (integer)
AID	Attribute ID (integer)
RID	Rule ID (integer)

Columns¶

The business rule view has the following columns:

Human Name	Column Name	Description
Name	actual_name	Test name
Description	actual_description	Test Description
Threshold	_actual_threshold	Compliance Threshold Percentage
Derived	_inheriting	Is this rule derived from a library entity
Library	_eLibName	Associated library entity containing this rule
Enabled	_check	True if the test is enabled
Priority	actual_priority	Priority of the rule
Priority Description	_priority_description	Description of the priority
Index Control	_index_control	Compliance Threshold Percentage
Index Threshold	_index_threshold	Compliance Threshold Percentage
Result	_result	Result of the test
Passing Fraction	_actual_fraction	Percentage of rows that pass the test
Status	_dirty_flag	Indicates whether the test is out of date
Expression	_predicate	The Business Rule Test
Filtering	_is_filtering	Are the rows being filtered
Filter Expression	_filter_predicate	The Business Rule Filter
Filter Error Count	_filter_error_count	Number of rows that caused an error while running the filter
Filter First Error Row	_filter_first_error_row	First row that caused a filter error
Filter First Error	_filter_first_error	Error message for first row failing the filter
Grouping	_is_grouping	Are the rows being grouped
Group Count	_group_count	Number of groups found
Group Function	_group_function	Business Rule Group-by function
Group Error Count	_group_error_count	Number of rows that caused an error in the group function
Group First Error Row	_group_first_error_row	First row that caused a group function error
Group First Error	_group_first_error	Error message for first row failing the group function
Aggregating	_is_aggregating	Are the rows being aggregated
Passing Aggregate	_aggregate_pass	Aggregate value across the passing rows
Failing Aggregate	_aggregate_fail	Aggregate value across the failng rows
Aggregate Method	_aggregate_method	Method used to aggregate
Aggregate Function	_aggregate_function	Business Rule Aggregate function
Aggregate Error Count	_aggregate_error_count	Number of rows that caused an error in the aggregate function
Aggregate First Error Row	_aggregate_first_error_row	First row that caused an aggregate function error
Aggregate First Error	_aggregate_first_error	Error message for first row failing the aggregate function
Fail Count	_row_fail_count	Number of Rows that Fail the Test
Pass Count	_row_pass_count	Number of Rows that Pass the Test
Rows Processed	_row_total	Number of Rows processed
Row Total	row_total	Total Number of Rows
Created By	CREATED_BY	Who created this business rule
Date Created	_created_date	When this business rule was created
Edited By	EDITED_BY	Who changed this business rule
Date Changed	_edited_date	When this business rule was changed
Error Count	_row_error_count	Number of rows that caused an error while running the test
First Error Row	_first_fail_row	First row that caused an error
First Error	_first_error	Error message for first failing row
Referenced Attributes	refd_atts	A list of the attributes referenced by this rule
XML	actual_predicate	Business Rule represented in XML
Sequence Number	seqno	Sequence number identifying the rule
Identifier	actual_uuid	The rule identifier
Local identifier	_local_identifier	A unique identifier for the rule
Rule Categories	_rule_categories	Business Rule categories

Index Control¶

Index Control is optional; if it is specified, it must be one of the following values:

Value	Description
0	Normal
1	Unlimited
2	Limited

If Index Control is 2 (Limited), the Index Threshold must also be specified.

Aggregate Method¶

Possible values for the aggregate method are:

Value	Description
0	Sum
1	Average
2	Maximum
3	Maximum
4	Count

Get¶

An individual business rule can be retrieved using a GET with the rule ID.

If the rule ID is unknown, or if more than one rule is required, various filters can be used to limit the number of rules listed.

{
    "command": "get",
    "options": {
        "where": "where clause",
        "in": [
            "column_name1 value1",
            "column_nameN valueN"
        ],
        "keyPattern": "key pattern",
        "keyPatternList": [
            "key pattern 1",
            "key pattern N"
        ]
    }
}

The options key is required.

keyPattern and keyPatternList cannot be specified at the same time.

The where clause is an expression used to filter the business rules. The expression for the where clause uses “Human Name” to specify the column names.

For example:

{
    "where": "'Sequence Number' > 15"
}

The in clause is an array of column names and values. The column names should be taken from “Column Name”.

For example:

{
    "in": [
        "_inheriting 1",
        "_actual_threshold 10"
    ]
}

Add¶

To add a business rule, the request may contain the fields below:

{
    "command": "add",
    "data": {
       "name": "Rule4",
       "description": "description",
       "threshold": "100",
       "enabled": "1",
       "expression": "attr2>0",
       "filterExpression": "new2>9",
       "groupExpression": "new5=0",
       "groupLimit": "0",
       "aggregateExpression": "acc_id<0",
       "aggregateMethod": "0",
       "priority": "1",
       "threshold": "100",
       "ruleKeywordIdList": "1 0: 2 1"
    }
}

The required fields for adding a rule are:

expression
threshold
name

The additional expressions (aggregateExpression, filterExpression, groupExpression) are optional; it is possible to add a business rule without specifying any of these expressions.

Field	Description	Values
expression	Humanized expression
threshold	Numerical threshold value	Between 0 to 100
enabled	Name of the library rule	0 or 1
description	Description of the library rule
filterExpression	Humanized expression for filter
aggregateExpression	Humanized aggregate expression
groupExpression	Humanized group expression
groupLimit	Numerical value for group limit
aggregateMethod	Name of aggregate method	A number indicating the aggregate method to be used (see above)
indexControl	Numeric value	A number indicating how indexes are controlled (see above)
indexThreshold	Valid only if indexControl is 2
priority	Numeric value between 1 and 10
ruleKeywordIdList	Array of keyword IDs	List of <category_id keyword_id> separated by colon. a value of 0 in keyword_id fields specify that the rule is attached to all the keywords of that category.

Edit¶

{
    "command": "edit",
    "data": {
        "entity": 1,
        "ruleId": 2,
        "name": "Rule4",
        "description": "description",
        "enabled": "1",
        "expression": "attr2>0",
        "filterExpression": "new2>9",
        "groupExpression": "new5=0",
        "groupLimit": "0",
        "aggregateExpression": "acc_id < 0",
        "aggregateMethod": "0",
        "priority": "1",
        "threshold": "100",
        "ruleKeywordIdList": "1 0: 2 1"
    }
}

The table below shows all the fields that are available for edit.

Field	Description	Values
expression	Humanized expression
threshold	Numerical threshold value	Between 0 to 100
enabled	Name of the library rule	0 or 1
description	Description of the library rule
filterExpression	Humanized expression for filter
aggregateExpression	Humanized aggregate expression
groupExpression	Humanized group expression
groupLimit	Numerical value for group limit
aggregateMethod	Name of aggregate method	A number indicating the aggregate method to be used (see above)
indexControl	Numeric value	A number indicating how indexes are controlled (see above)
indexThreshold	Valid only if indexControl is 2
priority	Numeric value between 1 and 10
ruleKeywordIdList	Array of keyword IDs	List of <categoryId keywordId> separated by colon. A value of 0 in keywordId fields specify that the rule is attached to all the keywords of that category.

The entity and ruleId must be specified, either in the URL or the body. All other fields are optional.

Run¶

To run a business rule, the request will look like:

{
    "command": "run",
    "data": {
        "entity": "EID",
        "option": "Analysis options (see below)",
        "ruleIds": [
            "EID AID RID"
        ]
    }
}

The entity field is optional see options table below:

where Entity ID is required, it can be given as entity field or within a URL link.

where Entity ID is optional, it can be given if you want to only run rules for a given entity.

The option field is required.

The analysis options (for the option field) are as follows:

Option	Purpose
-all	Run all rules for a given entity (Entity ID is required)
-dirty	Run all updated rules for a given entity (Entity ID is required)
-selected	Run all selected rules for a given entity (Entity ID is required)
-allentity	Run all entity rules (Entity ID is ignored)
-selectedentity	Run the selected entity (Entity ID is ignored)
-dirtyentity	Run all updated entity rules (Entity ID is optional)

The ruleIds field is optional:

It is only required if using the following options: “-selected” or “-selectedentity”.

The ruleIds field not required when a rule ID is given in the URL link.

If ruleIds field is present it must contain one or more key patterns for the rules to be run. The key patterns for an individual rule are dependent upon the option used.

When using the “-selected” option, the API expects list of key patterns containing just the Rule ID. For example, to run several business rules (1 0 4, 1 0 5) for a single entity, you would use the following:

{
    "command": "run",
    "data": {
        "entity": "EID",
        "option": "-selected",
        "ruleIds": [
            "4",
            "5"
        ]
    }
}

When using the “-selectedentity” option, the API expects list of key patterns containing Entity ID, Attribute ID and Rule ID. For example, to run several business rules (1 0 4, 2 0 5, 3 0 7) for different entities, you would use the following:

{
    "command": "run",
    "data": {
        "option": "-selectedentity",
        "ruleIds": [
            "1 0 4",
            "2 0 5",
            "3 0 7"
        ]
    }
}

When using the “-allentity” option without using the “where” clause, a separate analysis job is scheduled for each entity.

The response will be dependent on number of separate jobs scheduled.

If multiple jobs were scheduled then response is a list of job urls:

{
  "urls": [
    "/api/repositories/jupiter/scheduler/52",
    "/api/repositories/jupiter/scheduler/53",
    "/api/repositories/jupiter/scheduler/54"
  ]
}

If a single job is scheduled then the response is a single job url:

{
  "url": "/api/repositories/jupiter/scheduler/55"
}

Using “where” clause with Run command¶

The “where” clause is only supported when running entity business rule, the request will look like:

POST /api/repositories/(string: repository)/entities/(int: entityID)/businessrules¶

Run a list of entity business rules for all Entity that match various criteria.

JSON Parameters:
	body – The request body

POST /api/repositories/test/entities/0/businessrules HTTP/1.1
Content-Type: application/json

{
    "command": "run",
    "data": {
        "option": "-allentity",
        "where": "Threshold >= 10"
    }
}

The following conditions will apply to run a entity business rule using “where” clause:

It is supported only when calling /api/repositories/test/entities/0/businessrules endpoint.
The entityId in the endpoint must be set to 0.
The option field is required and must be set as “-allentity”.
The where field is required and must contain a humanised expression required to match required criteria.

The response will be dependent on the number of separate jobs scheduled. One job will be scheduled for each entity where the where clause is applicable.