Package: Compliance

The module evaluates if the objects of a package follow a configurable set of rules. Different tests can be used to verify these rules.

Designation

Name

pm.Compliance

Configuration

Optionen

Package (package)

Name of the package

Tests (tests)

The selected tests will be executed

Test Configuration File (test-config-file)

Path to the configuration file for the compliance tests

Ausgabe

XML Variable (xml-variable)

name of the XML variable object used to store the information

XML Variable Source Connection (xml-variable-source)

If given it defines an alternative b4A connection where to find the variable objectMögliche Werte: <TabItem b4A Verbindungen>

Description

Compliance in the area of b4A Package Management refers to adherence to coding guidelines, process design and documentation guidelines. These rules are defined in each environment and compliance is important from several points of view. With this module, b4A Package Management offers support. The objects and structures of a package can be checked on the basis of an expandable set of tests. Each of these tests is configurable and can therefore be adapted to the individual rules of the environment.

The results of a compliance check are saved in an XML variable. Each individual test will save its results in a separate key in the variable in an XML structure. Which rules the tests can check, how they are configured and how the results are reported are described below.

Function & configuration

As an example of a configuration file, the distribution contains a file compliance.json-example in the conf directory. This can be used as the basis for your own configuration. To do this, this file must exist in the same directory under the name compliance.json.

The format of the configuration file is JSON. The file contains an object in which there is a key pm. This is assigned another object in which there is a key compliance. This in turn contains an object tests. This contains the named configuration objects for each individual test. For example, the configuration for the test alias can be found in the following location.

{
    "pm" : {
    "compliance" : {
        "tests" : {
            "alias" : {
                "types" : [ "JOBP" ],
                "matches" : [
                    { }
                ]
            },
        }
    }
}

Test: agent

This test checks whether the agents set for JOBS and JOBF objects comply with the rules of the environment. Agents can be set in various ways. The following can be distinguished from this test:

• AGENT: The name of an agent is entered directly
• AGENT_GROUP: An agent group has been entered in the attributes for the agent
• VARIABLE: Instead of an agent and an agent group, a script variable has been entered (e.g. &MY_AGENT#)
• GENERIC_AGENT: The attributes for the agent contain one of the default values (e.g. <UNIX> or <WINDOWS>)
• RESOLVE_VARIABLE: A character string for resolving a variable was entered for the agent (e.g. {MY_CLIENT_SETTINGS,SAP_AGENT,1})

The following example shows a configuration for the test in which only script variables and the resolving of variables are permitted. If other techniques are to be allowed, the corresponding keywords must be added to the allowed list.

"agent" : {
    "allowed" : [ "VARIABLE", "RESOLVE_VARIABLE" ]
}

Test: configuration

This test checks the configuration objects of the package. Two different aspects are checked here. The first is to ensure that the separator is written correctly for configuration objects. This is checked by looking at the ending of the objects. If an object ends with the name of a connection or environment and does not contain a valid separator, this may be an error. As this is not unique, such a hit can be evaluated as an error or warning or even completely ignored. The setting possibleMissingReportAs must be set to one of the values error, warning or ignore.

"links" : {
    "possibleMissingReportAs" : "warning"
}

Test: task-alias

This test checks whether an alias has been set for workflow tasks and whether this corresponds to a valid format. The tasks to be checked can be restricted based on the object type. The format of the set alias can be checked with a list of regular expressions. Expressions can be specified that must apply and those that must not.

In the following sample configuration, only tasks of workflows that are of type JOBP are examined. At the same time, a user-defined attribute with the name BBC_SEMANTIC_TYPE#, which has the value ACTION, must be set on these workflows. The specified rules are used to check whether the alias contains at least one character and whether the character string is not "UC4".

"alias" : {
    "types" : [ "JOBP" ],
    "customAttribute": {
        "name" : "BBC_SEMANTIC_TYPE#",
        "value" : "ACTION"
    },
    "matches" : [
        {
            "regex" : ".+",
            "positive" : true
        },
        {
            "regex" : "UC4",
            "positive" : false
        }
    ]
}

The entry matches is a list of objects that can be extended as required. Each additional entry must contain the key regex with a regular expression and the key positive. If positive has the value true, then the regular expression must apply. If the value false is set here, the expression must not apply.

Test: documentation

This test checks the content of the documentation tabs of objects. Both text and structured documentation of the objects can be checked. Each of the specified rules (key matches) defines the parameters of the rule with three to four attributes

• name: The attribute defines the name of the documentation tab. If the name begins with @, the system searches for structured documentation with this name.
• regex: A regular expression that is applied to the lines of the text documentation or to the content of a node in the structured documentation.
• object-types: A list of object types that defines which objects this rule should be applied to. If the object type of an object is not included, then this rule is not considered for the object.
• object-name-pattern: This parameter is optional and can be used to restrict the application of the rule based on a regular expression for the object name.
• node: This attribute is only required for rules that refer to structured documentation and then specifies the XML node to which the rule should be applied.
• attribute: If this attribute is specified, it is not the XML node itself that is checked, but the named attribute of the XML node that was set in the name attribute

A total of five rules are defined in the sample configuration. The first three rules refer to the text documentation with the name Docu which is defined by the attribute name. The attribute object-types is used to define the object types to which these rules should apply. While the first two rules are to be checked for JOBI objects, the third rule is only checked for JOBP objects. All these rules search for lines that correspond exactly to the specified text in the attribute regex. The fourth rule relates to the structured documentation named Details of JOBI and JOBS objects. It checks whether the node /Content/Test exists and whether the content is not empty. The last rule also refers to the structured documentation named Details, but for JOBP objects. Here, the system checks whether a Test attribute exists for the /Content/Test node and whether the content is not empty.

"documentation" : {
    "matches" : [
        {
            "name" : "Docu",
            "regex" : "# Description",
            "object-types" : [ "JOBI" ]
        },
        {
            "name" : "Docu",
            "regex" : "# Input",
            "object-types" : [ "JOBI" ]
        },
        {
            "name" : "Docu",
            "regex" : "# Description",
            "object-types" : [ "JOBP" ],
            "object-name-pattern" : ".*\\.VARA\\.METADATA"
        },
        {
            "name" : "@Details",
            "node" : "/Content/Test",
            "regex" : ".+",
            "object-types" : [ "JOBS", "JOBI" ]
        },
        {
            "name" : "@Details",
            "node" : "/Content/Test",
            "attribute" : "Test",
            "regex" : ".+",
            "object-types" : [ "JOBP" ]
        }
    ]
}

Test: folders

This test checks the folder structure of the package. There is no further configuration in the JSON file for this test, as the folder structure is already defined in the pm.conf file. The test uses this configuration to check the correct structure of the package. All missing subfolders in the package generate a warning. Only the folder for configurations must exist. If this is missing, the test returns an error status.

Test: includes

This test checks the use of JOBI objects in the processes of objects. A list of rules can be specified for the test, which examine various points. Each rule consists of the following attributes.

• type : The type of the rule can have the following values

  • EXISTS: To check whether a JOBI object exists
  • REPLACEMENT: To check whether the replacement parameter corresponds to a certain format.

• name: The name of the JOBI object to be searched for

• process: The process in which to search for the JOBI object. Possible values are: pre, main, post, child-post and event

• positive: If the value of this attribute is true, then the rule must apply for the test to be successful. If the value is false, the rules must not apply.

• object-types: This attribute contains a list of object types to which this rule should be applied.

The following sample configuration shows three rules that check for the existence of JOBI objects. While the first rule searches in the pre process, the second rule goes to the post process and the third searches in the main process. All three perform this search exclusively for objects of type JOBS. The special feature of the third rule is the value false for the attribute positive. This means that the rule states that the JOBI object mentioned must not occur in the process. The last rule checks the format of the replacement parameter of JOBI objects. The regular expression specifies that the text to be replaced must begin and end with a $ character.

include BBC.SHARED.JOBI.NOT_FOUND2 $ARG1$ = "Test"

"includes" : {
    "rules" : [
        {
            "type" : "EXISTS",
            "name" : "BBC.SHARED.JOBI.RESOLVE_AGENT_GROUP",
            "process" : "pre",
            "positive" : true,
            "object-types" : [ "JOBS" ]
        },
        {
            "type" : "EXISTS",
            "name" : "BBC.SHARED.JOBI.NOT_FOUND",
            "process" : "post",
            "positive" : true,
            "object-types" : [ "JOBS" ]
        },
        {
            "type" : "EXISTS",
            "name" : "BBC.SHARED.JOBI.NOT_FOUND2",
            "process" : "main",
            "positive" : false,
            "object-types" : [ "JOBS" ]
        },
        {
            "type" : "REPLACEMENT",
            "regex" : "\\$[A-Za-z0-9_]+\\$",
            "object-types" : [ "JOBS" ],
            "process" : "pre"
        }
    ]
}

Test: metadata

This test checks the metadata of a b4A Package. In the first phase, basic points are checked:

• Can a metadata variable be found?
• Can the metadata be read?
• Is the metadata variable in the correct folder?

The mandatory fields for the name and version number are then checked for existence and correctness. Other fields can be checked by defining rules for them in the configuration. Each rule refers to a field and can perform a list of checks for it.

In the following sample configuration, two checks are defined for the Description field. Each of the checks consists of two values. The key rege defines a regular expression and the key positive states whether the expression must be true or exactly the opposite for the test to be successful. The first check is to ensure that the description does not only consist of spaces and the second check is to ensure that the description does not only contain the word test.

"metadata" : {
    "fields" : {
        "description" : [
            {
                "regex" : "[^ \\t]+",
                "positive" : false
            },
            {
                "regex" : "test",
                "positive" : false
            }
        ]
    }
}

Test: object-name

This test checks the correct naming of all objects of a . The regular expression from pm.conf is applied to the objects, to which all objects must correspond. There are no other configuration settings for this test.

Test: left

This test searches for links in the . If any are found, this can be reported as an error or warning or even ignored. In the latter case, this is only shown in the test report. With the value error for the key reportAs, any links found are reported as errors and with the value warning as warnings. All other values result in no negative feedback.

"links" : {
    "reportAs" : "error"
}

Test: title

This test checks whether the objects of a have a title and whether this corresponds to the specified regular expressions. Several checks can be defined. Each check is made up of two attributes. The regex key defines the regular expression and the positive key defines whether the title must match the expression or exactly the opposite. If positive is set to false, the title must not match the regular expression.

The following example configuration ensures that the title is not empty and that it does not consist of just one of the words test, UC4 or example.

"title" : {
    "matches" : [
        {
            "regex" : ".+",
            "positive" : true
        },
        {
            "regex" : "(test{{UC4}}example)",
            "positive" : false
        }
    ]
}

Test: schedule-variables

The schedule definitions that can exist as a configuration object in a are checked by this test. All values in such a variable are checked. The information on runtime monitoring, variables and PromptSets is only checked if it is an XML variable, as these are not contained in the static variables. The following questions are answered with the check:

• Schedule object

  • Does the object exist and is it a Schedule object?

• Per schedule entry

  • Does the start time have the correct format?

  • Is the object to be started set and can it be started?

  • Calendar conditions

    • Is the rule for the calendar conditions set correctly?
    • Do the calendar objects exist and do the events exist in the conditions?

  • Runtime monitoring

    • Is the object to be started in the event of runtime violations set and does it exist?

    • Maximum runtime monitoring

      • Is a valid method set?
      • Is the duration specified correctly for the Fixed method?
      • Is the time specified in the correct format for the Real method?

    • Minimum runtime monitoring

      • Is a valid method set?
      • Is the duration specified correctly for the Fixed method?

  • Variables

    • Do all entries have a valid key?

  • PromptSets

    • Does the PromptSet object exist?
    • Are there the variables of all entries in the PromptSet?

Test: slo

This test can check some settings of SLO objects. These include the monitoring status (active) and the service selection. Only the topmost group is supported for the selection and no subgroups.

{
  "active": true,
  "selection": [
    "..."
  ]
}

Several rules can be defined for checking the service selection, which are applied to all SLO objects of a . For each rule, you can define whether it must apply to all or at least one SLO object.

A list of rules is defined under the selection key. Each rule is defined by an object with the following structure.

{
  "strategy": "ALL",
  "attribute": "OBJECT_NAME",
  "operator": "STARTS_WITH",
  "valueRegEx": "^%(package)"
}

strategy

Can contain the values ALL or ONE and defines whether the rule must apply to all SLO objects of the or to at least one.

attribute

Defines the attribute for the rule. The following values can be used here:

• OBJECT_NAME
• OBJECT_TYPE
• OBJECT_TITLE
• QUEUE
• ARCHIVE_KEY1
• ARCHIVE_KEY2

operator

Specifies the operator that should apply to the rule. The following operators are available:

• STARTS_WITH
• ENDS_WITH
• EQUALS
• NOT_EQUALS
• CONTAINS

Only the operators EQUALS and NOT_EQUALS are valid for the attribute OBJECT_TYPE.

Test: static-varas

This test can be used to check the keys of static variables using a regular expression. The following sample configuration checks all static variables that end with .VARA.SETTINGS with regard to the length and characters used for the keys. This configuration ensures that the keys can be successfully read by the GENERATE_SCRIPT_VARS function. The positive attribute can also be used to negate the check using the value false.

{
  "matches": [
    {
      "name": ".*.VARA.SETTINGS",
      "keyRegex": "[A-Za-z0-9_@§#]{1,31}$",
      "positive": true
    }
  ]
}

Test: unique-title

This test checks whether the objects of a b4A Package have unique titles. This only applies to other objects in the same b4A Package. There are no other configuration settings for this test.

A complete configuration for the test looks like this:

{
  "active": true,
  "selection": [
    {
      "strategy": "ALL",
      "attribute": "OBJECT_NAME",
      "operator": "STARTS_WITH",
      "valueRegEx": "^%(package)"
    },
    {
      "strategy": "ALL",
      "attribute": "OBJECT_NAME",
      "operator": "CONTAINS",
      "valueRegEx": "^%(package)"
    },
    {
      "strategy": "ONE",
      "attribute": "OBJECT_TYPE",
      "operator": "EQUALS",
      "valueRegEx": "JOBZ"
    }
  ]
}

Results

Each of the tests logs the results in an XML variable specified when the module is started. A separate key is used in the variable for each test, which corresponds to the name of the test (e.g. metadata, includes or folders). Such an entry can look like this.

<?xml version="1.0" encoding="UTF-8"?>
<best4Automic version="4.3.0">
    <pm>
        <compliance>
            <tests>
                <test key="object-name">
                    <title>Check the naming scheme for objects</title>
                    <result>Failed</result>
                    <details>The object BBC.MAIL.SQLI.GET_DOCU_OBJECTSVARA does not match the naming scheme</details>
                </test>
            </tests>
        </compliance>
    </pm>
</best4Automic>

The XML structure used is the same for all tests. Each structure begins with /best4Automic/pm/compliance/tests/test. The results are recorded below this tree. The name of the test is defined again in the test node (here object-name). The first child node title defines the translatable name of the test. The result of the test is recorded via the result node. Possible values are Failed, Succeeded, Skipped and Warned. The last node details contains the detailed textual report on the test. The example shows that the test failed because the object BBC.MAIL.SQLI.GET_DOCU_OBJECTSVARA has an unaccepted name.

Evaluation

set &hnd# = PREP_PROCESS_VAR( "TESU.B4A_PM.VARA.COMPLIANCE@XML" )
:process &hnd#
: set &key# = get_process_line( &hnd#, 1 )
: set &title# = get_var( "TESU.B4A_PM.VARA.COMPLIANCE@XML", &key#, '/best4Automic/pm/compliance/tests/test["&key#"]/title/text()' )
: set &result# = get_var( "TESU.B4A_PM.VARA.COMPLIANCE@XML", &key#, '/best4Automic/pm/compliance/tests/test["&key#"]/result/text()' )
: set &details# = get_var( "TESU.B4A_PM.VARA.COMPLIANCE@XML", &key#, '/best4Automic/pm/compliance/tests/test["&key#"]/details/text()' )
: print "Key: &key# (&title#)"
: print " Result: &result#"
: print " Details: &details#"
:endprocess