Business Rule Commands ====================== Business rules can be manipulated from a :doc:`repository` level and from an :doc:`entity` level. The commands that can be performed against a :doc:`business rule ` (or rules) are as follows: .. csv-table:: :header: Command, Purpose :widths: 20, 80 `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: .. csv-table:: :header: Term, Meaning :widths: 30, 70 EID, Entity ID (integer) AID, Attribute ID (integer) RID, Rule ID (integer) Columns ~~~~~~~ The business rule view has the following columns: .. csv-table:: :header: Human Name, Column Name, Description :widths: 25, 25, 50 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 .. _brc_index_control: Index Control ------------- Index Control is optional; if it *is* specified, it must be one of the following values: .. csv-table:: :header: Value, Description :widths: 20, 80 0, Normal 1, Unlimited 2, Limited If Index Control is 2 (Limited), the Index Threshold must also be specified. .. _brc_agg_method: Aggregate Method ---------------- Possible values for the aggregate method are: .. csv-table:: :header: Value, Description :widths: 20, 80 0, Sum 1, Average 2, Maximum 3, Maximum 4, Count .. _brc_get: Get ~~~ An individual :doc:`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. .. code-block:: json { "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: .. code-block:: json { "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: .. code-block:: json { "in": [ "_inheriting 1", "_actual_threshold 10" ] } .. _brc_add: Add ~~~ To add a :doc:`business rule `, the request may contain the fields below: .. code-block:: json { "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 :doc:`business rule ` without specifying any of these expressions. .. csv-table:: :header: Field, Description, Values :widths: 20, 30, 50 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 (:ref:`see above `) indexControl, "Numeric value", A number indicating how indexes are controlled (:ref:`see above `) indexThreshold, "Valid only if `indexControl` is 2" priority, "Numeric value between 1 and 10" ruleKeywordIdList, "Array of keyword IDs", List of separated by colon. a value of 0 in keyword_id fields specify that the rule is attached to all the keywords of that category. .. _brc_edit: Edit ~~~~ .. code-block:: json { "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. .. csv-table:: :header: Field, Description, Values :widths: 20, 30, 50 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 (:ref:`see above `) indexControl, "Numeric value", A number indicating how indexes are controlled (:ref:`see above `) indexThreshold, "Valid only if `indexControl` is 2" priority, "Numeric value between 1 and 10" ruleKeywordIdList, "Array of keyword IDs", List of 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. .. _brc_run: Run ~~~ To run a :doc:`business rule `, the request will look like: .. code-block:: json { "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: .. csv-table:: :header: Option, Purpose :widths: 20, 80 -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: .. code-block:: json { "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: .. code-block:: json { "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: .. code-block:: json { "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: .. code-block:: json { "url": "/api/repositories/jupiter/scheduler/55" } Using *"where"* clause with Run command --------------------------------------- The *"where"* clause is only supported when running :doc:`entity business rule `, the request will look like: .. http:post:: /api/repositories/(string:repository)/entities/(int:entityID)/businessrules :synopsis: List business rules matching certain criteria Run a list of entity business rules for all :doc:`entity` that match various criteria. :jsonparam body: The request body .. code-block:: http 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 :doc:`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. If multiple jobs were scheduled then response is a list of job urls: .. code-block:: json { "urls": [ "/api/repositories/jupiter/scheduler/56", "/api/repositories/jupiter/scheduler/57", "/api/repositories/jupiter/scheduler/58" ] } If a single job is scheduled then the response is a single job url: .. code-block:: json { "url": "/api/repositories/jupiter/scheduler/59" }