Package: Compliance

Das Modul evaluiert ob Objekte eines Package einer konfigurierbaren Menge an Regeln folgen. Verschiedene Test können genutzt werden, um diese Regeln zu überprüfen.

Bezeichnung

Name: pm.Compliance

Konfiguration

Gruppe: Optionen

Package (package)

Name des Package

Tests (tests)

Die ausgewählten Tests werden ausgeführt

Mögliche Werte: Verwendung von Include-Objekten (includes), Überprüfe Aliases von Workflow-Aufgaben (task-alias), Überprüfe Agenten (agent), Suche nach Verknüpfungen (links), Überprüfe die Ordnerstruktur (folders), Überprüfe Metadaten-Variable (metadata), Schedule Variablen (schedule-variables), Service Level Objectives (slo), Überprüfe den Inhalt von statischen Varas (static-varas), Konfigurationsobjekte (configuration), Überprüfe den Titel der Objekte (title), Überprüfe das Namensschema für Objekte (object-name), Inhalt der Dokumentation (documentation), Eindeutige Objekttitel (unique-title)

Test-Konfigurationsdatei (test-config-file)

Pfad zur Konfigurationsdatei für Compliance-Tests

Gruppe: Ausgabe

XML-Variable (xml-variable)

Name des XML-Variable-Objekts, das zur Speicherung der Informationen genutzt wird

Quellverbindung für die Variable (xml-variable-source)

Ist die Option gesetzt, dann definiert diese eine alternative b4A Verbindung unter der die Variable gefunden werden kann.

Mögliche Werte: <definierte b4A Verbindungen>

Beschreibung

Unter Compliance im Bereich des b4A Package Management versteht man die Einhalten von Coding Guidelines, Prozessdesign und Dokumentationsrichtlinien. Diese Regeln werden in jeder Umgebung definiert und die Einhaltung ist aus mehreren Gesichtspunkten wichtig. Mit diesem Modul bietet das b4A Package Management eine Unterstützung. Auf Basis von einer erweiterbaren Menge an Tests können die Objekte und die Strukturen eines Package überprüft werden. Jeder dieser Tests ist konfigurierbar und kann so an die individuellen Regeln der Umgebung angepasst werden.

Die Ergebnisse eines Compliance Check werden in einer XML-Variable gespeichert. Jeder einzelne Test wird seine Ergebnisse in einem eigenen Key in der Variable in einer XML-Struktur speichern. Welche Regeln die Tests überprüfen können, wie diese konfiguriert werden und in welcher Form die Ergebnisberichte erfolgen wird im Folgenden beschrieben.

Funktion & Konfiguration

Als Beispiel für eine Konfigurationsdatei enthält die Distribution im conf-Verzeichnis eine Datei compliance.json-example. Diese kann als Grundlage für eine eigene Konfiguration genutzt werden. Dafür muss diese Datei im selben Verzeichnis unter dem Namen compliance.json existieren.

Das Format der Konfigurationsdatei ist JSON. Die Datei enthält ein Objekt in dem es einen Schlüssel pm gibt. Diesem ist ein weiteres Objekt zugeordnet in dem es einen Schlüssel compliance gibt. In diesem ist wiederum ein Objekt tests enthalten. Darunter sind die benannten Konfigurationsobjekte für jeden einzelnen Test enthalten. Beispielsweise ist die Konfiguration for den Test alias an folgender Stelle zu finden.

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

Test: agent

Dieser Test überprüft bei JOBS- und JOBF-Objekten, ob die gesetzten Agenten den Regeln der Umgebung entsprechen. Agenten können auf verschiedene Arten gesetzt werden. Von diesem Test können die folgenden unterschieden werden:

AGENT: Es ist direkt der Name eines Agenten eingetragen
AGENT_GROUP: In den Attributen für den Agent wurde eine Agentengruppe eingetragen
VARIABLE: Anstelle eines Agent und einer Agentengruppe wurde eine Script-Variable eintragen (z.B. &MY_AGENT#)
GENERIC_AGENT: Dei Attribute für den Agent enthalten einen der Vorgabewerte (z.B. <UNIX> oder <WINDOWS>)
RESOLVE_VARIABLE: Für den Agent wurde eine Zeichenkette zum Auflösen einer Variable eingetragen (z.B. {MY_CLIENT_SETTINGS,SAP_AGENT,1})

Das folgende Beispiel zeigt eine Konfiguration für den Test in dem nur Script-Variablen und das Auflösen von Variablen erlaubt sind. Sollen weitere Techniken erlaubt werden, dann sind die entsprechenden Schlüsselworte in der Liste allowed zu ergänzen.

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

Test: configuration

Dieser Test überprüft die Konfigurationsobjekte des Package. Hierbei werden zwei verschiedene Aspekte geprüft. Beim ersten geht es darum sicherzustellen, dass der Separator bei Konfigurationsobjekten korrekt geschrieben ist. Dies wird geprüft, indem die Endung der Objekte betrachtet wird. Endet ein Objekt mit dem Namen einer Verbindung oder Umgebung und enthält keinen gültigen Separator, dann kann dies ein Fehler sein. Da dies nicht eindeutig ist, kann solch ein Treffer als Fehler oder Warnung gewertet oder sogar komplett ignoriert werden. Dafür ist die Einstellung possibleMissingReportAs auf einen der Werte error, warning oder ignore zu setzen.

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

Test: task-alias

Dieser Test überprüft, ob für Aufgaben von Workflows ein Alias gesetzt wurde und ob dieser einem gültigen Format entspricht. Dabei können die zu untersuchenden Aufgaben auf Basis des Objekttyps eingeschränkt werden. Das Format des gesetzt Alias kann mit einer Liste von regulären Ausdrücken geprüft werden. Dabei können Ausdrücke angegeben werden die zutreffen müssen und welche, die es nicht dürfen.

In der folgenden Beispielkonfiguration werden nur Aufgaben von Workflows untersucht, die vom Typ JOBP sind. Gleichzeitig muss an diesen Workflows ein benutzerdefiniertes Attribut mit dem Namen BBC_SEMANTIC_TYPE# gesetzt sein, das den Wert ACTION hat. Durch die angegebenen Regeln wird geprüft, ob der Alias mindestens ein Zeichen enthält und ob die Zeichenkette nicht „UC4“ ist.

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

Der Eintrag matches ist eine Liste von Objekten, die beliebig erweitert werden kann. Jeder weitere Eintrag muss den Schlüssel regex mit einem regulären Ausdruck sowie den Schlüssel positive enthalten. Besitzt positive den Wert true, dann muss der reguläre Ausdruck zutreffen. Ist hier der Wert false gesetzt darf der Ausdruck nicht zutreffen.

Test: documentation

Dieser Test prüft den Inhalt der Dokumentation-Reiter von Objekten. Dabei können sowohl Text- als auch strukturierte Dokumentationen der Objekte geprüft werden. Jede der angegebenen Regeln (Schlüssel matches) definiert mit drei bis vier Attributen die Parameter der Regel

name: Das Attribut definiert den Namen des Dokumentation-Reiters. Beginnt der Name mit einem @, dann wird eine strukturierte Dokumentation mit dem Namen gesucht.
regex: Ein regulärer Ausdruck, der auf die Zeilen der Text-Dokumentation oder auf den Inhalt eines Knoten in der strukturierten Dokumentation angewendet wird.
object-types: Eine Liste von Objekttypen, die definiert auf welche Objekte diese Regel angewendet werden soll. Ist der Objekttyp eines Objektes nicht enthalten, dann wird diese Regeln nicht betrachtet für das Objekt.
object-name-pattern: Dieser Parameter ist optional und kann genutzt werden um die Anwendung der Regel auf Basis eines regulären Ausdrucks für den Objektnamen einzuschränken.
node: Dieses Attribut wird nur für Regeln benötigt, die sich auf eine strukturierte Dokumentation beziehen und legt dann den XML-Knoten fest auf den die Regel angewendet werden soll.
attribute: Ist dieses Attribut angegeben, wird nicht der XML-Knoten selbst geprüft, sondern das benannte Attribut des XML-Knotens, das in dem Attribut name gesetzt wurde

In der Beispielkonfiguration sind insgesamt fünf Regeln definiert. Die ersten drei Regeln beziehen sich auf die Text-Dokumentation mit dem Namen Docu was durch das Attribut name definiert wird. Mit dem Attribut object-types werden die Objekttypen festgelegt auf sich diese Regeln beziehen soll. Während die ersten beiden Regeln JOBI-Objekten geprüft werden sollen wird die dritte Regel nur bei JOBP-Objekten geprüft. Alle diese Regel suchen nach Zeilen, die genau dem angegebenen Text in dem Attribut regex entsprechen. Die vierte Regel bezieht sich auf die strukturierte Dokumentation names Details von JOBI- und JOBS-Objekten. Hier wird geprüft, ob der Knoten /Content/Test existiert und ob der Inhalt nicht leer ist. Die letzte Regel bezieht sich ebenfalls auf die strukturierte Dokumentation names Details, allerdings von JOBP-Objekten. Hier wird geprüft, ob für den Knoten /Content/Test ein Attribut Test existiert und ob der Inhalt nicht leer ist.

"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

Dieser Test überprüft die Ordnerstruktur des Package. Für diesen Test gibt es keine weitere Konfiguration in der JSON-Datei, da die Ordnerstruktur bereits in der Datei pm.conf definiert ist. Der Test nutzt diese Konfiguration um die korrekte Struktur des Package zu überprüfen. Dabei erzeugen alle fehlenden Unterordner in dem Package eine Warnung. Nur der Ordner für Konfigurationen muss existieren. Fehlt dieser gibt der Test einen Fehlerstatus zurück.

Test: includes

Dieser Test überprüft die Verwendung von JOBI-Objekten in den Prozessen von Objekten. Für den Test kann eine Liste von Regeln angegeben werden, die verschiedene Punkte untersuchen. Jede Regeln besteht aus den folgenden Attributen.

type : Der Typ der Regel kann die folgenden Werte annehmen
- EXISTS: Zur Überprüfung, ob ein JOBI-Objekt vorhanden ist
- REPLACEMENT: Zur Überprüfung, ob der Ersetzungsparameter einem gewissen Format entspricht.
name: Der Name des JOBI-Objekts, das gesucht werden soll
process: Der Prozess in dem nach dem JOBI-Objekt gesucht werden soll. Mögliche Werte sind: pre, main, post, child-post und event
positive: Ist der Wert dieses Attributs true, dann muss die Regel zutreffen, damit der Test erfolgreich ist. Ist der Wert false, dann darf die Regeln nicht zutreffen.
object-types: Dies Attribut enthält eine Liste von Objekttypen auf diese Regel angewendet werden soll.

Die folgende Beispielkonfiguration zeigt drei Regeln, die auf die Existenz von JOBI-Objekten prüfen. Während die erste Regel im pre-Prozess sucht geht die zweite Regel auf den post-Prozess und die dritte sucht im main-Prozess. Alle drei führen diese Suche ausschließlich bei Objekten vom Typ JOBS durch. Die Besonderheit bei der dritten Regel ist der Wert false für das Attribut positive. Dadurch sagt die Regel aus, dass das genannte JOBI-Objekt in dem Prozess nicht vorkommen darf. Die letzte Regel überprüft dass Format des Ersetzungsparameter von JOBI-Objekten. Durch den regulären Ausdruck wird festgelegt, dass der zu ersetzende Text mit einem $-Zeichen beginnen sowie enden muss.

: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

Dieser Test überprüft die Metadaten eines b4A Package. In der ersten Phase werden grundlegende Punkte überprüft:

Kann eine Metadaten-Variable gefunden werden?
Können die Metadaten gelesen werden?
Liegt die Metadaten-Variable im richtigen Ordner?

Anschließend werden die verpflichtenden Felder für den Namen sowie die Versionsnummer auf Existenz und Korrektheit geprüft. Weitere Felder können überprüft werden indem in der Konfiguration Regeln dafür definiert werden. Jede Regel bezieht sich auf ein Feld und kann dafür eine Liste von Überprüfungen durchführen.

In der folgenden Beispielkonfiguration werden zwei Überprüfungen für das Feld Description definiert. Jede der Überprüfungen besteht aus zwei Werten. Der Schlüssel rege legt einen regulären Ausdruck fest und der Schlüssel positive sagt aus, ob der Ausdruck zutreffen muss oder genau das Gegenteil damit der Test erfolgreich ist. Zuerst wird geprüft, ob die Beschreibung nicht nur aus Leerzeichen besteht und in der zweiten Prüfung wird sichergestellt, dass die Beschreibung nicht nur das Wort test enthält.

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

Test: object-name

Dieser Test überprüft die korrekte Benennung aller Objekte eines b4A Package. Dabei wird der regulärer Ausdruck aus der pm.conf auf die Objekte angewendet, dem alle Objekte entsprechen müssen. Weitere Konfigurationseinstellungen gibt es für diesen Test nicht.

Test: links

Dieser Test sucht nach Verknüpfungen in dem b4A Package. Werden welche gefunden, dann kann dies als Fehler oder Warnung gemeldet oder sogar ignoriert werden. In letzterem Fall steht dies nur im Testbericht. Mit dem Wert error für den Schlüssel reportAs werden gefundene Verknüpfungen als Fehler und mit dem Wert warning als Warnung gemeldet. Alle anderen Werte führen dazu, dass keine negative Rückmeldung erfolgt.

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

Test: title

Dieser Test überprüft, ob die Objekte eines b4A Package einen Titel haben und ob dieser den angegebenen regulären Ausdrücken entspricht. Dabei können mehrere Überprüfungen definiert werden. Jede Überprüfung setzt sich aus zwei Attributen zusammen. Der Schlüssel regex legt den regulären Ausdruck fest und mit dem Schlüssel positive wird definiert, ob der Titel dem Ausdruck entsprechen muss oder genau das Gegenteil. Wird positive auf false gesetzt, dann darf der Titel dem regulären Ausdruck nicht entsprechen.

In der folgenden Beispielkonfiguration wird sichergestellt, dass der Titel nicht leer ist und das er nicht nur aus einem der Worte test, UC4 oder example besteht.

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

Test: schedule-variables

Die Schedule-Definitionen, die als Konfigurationsobjekt in einem b4A Package existieren können, werden durch diesen Test überprüft. Dabei werden alle Werte in einer solchen Variable kontrolliert.

Wert

Das Format der Startzeit (HH:MM) wird geprüft

Wert

Das Format der Liste wird geprüft

Bei jedem Element wird sicher gestellt, dass das Kalender-Objekt existiert und auch das Ergebnis im Kalender definiert ist

Wert

Der Wert muss leer sein oder eine der Zeichenketten ALL, NONE oder ONE enthalten

Wert

Das Objekt muss existieren

Das Objekt muss ausführbar sein

Wert

Das Objekt muss existieren

Das Objekt muss ein Schedule-Objekt sein

Test: slo

Dieser Test kann einige Einstellungen von SLO-Objekten überprüfen. Dazu gehören der Monitoring-Status sowie die Serviceauswahl. Bei der Auswahl wird nur die oberste Gruppe unterstützt und keine Untergruppen.

Für die Überprüfung der Serviceauswahl können mehrere Regeln definiert werden, die auf alle SLO-Objekte eines b4A Package angewendet werden. Dabei kann pro Regel definiert werden, ob diese auf alle oder nur mindestens ein SLO-Objekt zutreffen muss.

Unter dem Schlüssel selection wird eine Liste von Regeln definiert. Jede Regel wird durch ein Objekt mit der folgenden Struktur definiert.

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

strategy

Kann die Werte ALL oder ONE enthalten und definiert, ob die Regel auf alle SLO-Objekte des b4A Package zutreffen muss oder auf mindestens eins.

attribute

Definiert das Attribute für die Regel. Hier können die folgenden Werte genutzt werden:

OBJECT_NAME
OBJECT_TYPE
OBJECT_TITLE
QUEUE
ARCHIVE_KEY1
ARCHIVE_KEY2

operator

Legt den Operator fest, der bei der Regel zutreffen soll. Folgende Operatoren stehen zur Verfügung:

STARTS_WITH
ENDS_WITH
EQUALS
NOT_EQUALS
CONTAINS

Für das Attribute OBJECT_TYPE sind nur die Operatoren EQUALS und NOT_EQUALS gültig.

Test: unique-title

Dieser Test überprüft, ob die Objekte eines b4A Package eindeutige Titel haben. Dies bezieht sich ausschließlich auf andere Objekte des selben b4A Package. Weitere Konfigurationseinstellungen gibt es für diesen Test nicht.

Eine vollständige Konfiguration für den Test sieht wie folgt aus:

{
  "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"
    }
  ]
}

Ergebnisse

Jeder der Tests protokolliert die Ergebnisse in einer beim Start des Moduls angegebenen XML-Variable. Pro Test wird in der Variable ein eigener Key genutzt, der dem Namen des Tests entspricht (z.B. metadata, includes oder folders). Ein solcher Eintrag kann wie folgt aussehen.

<?xml version="1.0" encoding="UTF-8"?>
<best4Automic version="4.3.0">
    <pm>
        <compliance>
            <tests>
                <test key="object-name">
                    <title>Überprüfe das Namensschema für Objekte</title>
                    <result>Failed</result>
                    <details>Das Objekt BBC.MAIL.SQLI.GET_DOCU_OBJECTSVARA entspricht nicht dem Namensschema</details>
                </test>
            </tests>
        </compliance>
    </pm>
</best4Automic>

Die genutzte XML-Struktur ist bei allen Tests dieselbe. Jede Struktur beginnt mit /best4Automic/pm/compliance/tests/test. Unterhalb dieses Baums werden die Ergebnisse festgehalten. In dem Knoten test wird der Name des Tests noch einmal definiert (hier object-name). Der erste Kindsknoten title definiert den übersetzbaren Namen des Tests. Über den Knoten result wird das Ergebnis des Tests festgehalten. Mögliche Werte sind Failed, Succeeded, Skipped und Warned. In dem letzten Knoten details ist der detaillierte textuelle Bericht zum Tests zu finden. In dem Beispiel ist zu sehen, dass der Test fehlgeschlagen ist, weil das Objekt BBC.MAIL.SQLI.GET_DOCU_OBJECTSVARA einen nicht akzeptierten Namen hat.

Auswertung

: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