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

XML-Variable (xml-variable)

Name des XML-Variable-Objekt, dass zur Speicherung der Informationen genutzt wird

Key (xml-variable-key)

Key in dem XML-Variable-Objekt, der verwendet werden soll

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: AE12-0000 (AE12-0000), AE12-0010 (AE12-0010), AE12-0011 (AE12-0011), AE12-0012 (AE12-0012), AE12-0020 (AE12-0020), AE12-0021 (AE12-0021), AE12-0030 (AE12-0030), AE12-0031 (AE12-0031), AE12-0032 (AE12-0032), AE12-0050 (AE12-0050), AE12-0060 (AE12-0060), AE12-0065 (AE12-0065), AE12-4000 (AE12-4000), AE12-5000 (AE12-5000), AE121-0000 (AE121-0000), AE121-0010 (AE121-0010), AE121-0020 (AE121-0020), AE122-0010 (AE122-0010), AE122-0090 (AE122-0090), AE122-6000 (AE122-6000), AE122-6010 (AE122-6010), AE123-2004 (AE123-2004), AE123-2005 (AE123-2005), AE123-9000 (AE123-9000), AE123A-0000 (AE123A-0000), AE123A-0010 (AE123A-0010), AE123A-0011 (AE123A-0011), AE123A-0012 (AE123A-0012), AE123A-0020 (AE123A-0020), AE123A-0021 (AE123A-0021), AE123A-0030 (AE123A-0030), AE123A-0031 (AE123A-0031), AE123A-0050 (AE123A-0050), AE123A-0060 (AE123A-0060), AE123A-0065 (AE123A-0065), AE123A-0100 (AE123A-0100)

Tests (tests)

Die ausgewählten Tests werden ausgeführt

Mögliche Werte: Überprüfe die Ordnerstruktur (folders), Verwendung von Include-Objekten (includes), Überprüfe den Titel der Objekte (title), Überprüfe Metadaten-Variable (metadata), Überprüfe Agenten (agent), Überprüfe Aliases von Workflow-Aufgaben (task-alias), Überprüfe das Namensschema für Objekte (object-name), Inhalt der Dokumentation (documentation)

Test-Konfigurationsdatei (test-config-file)

Pfad zur Konfigurationsdatei für Compliance-Tests

Beschreibung

Unter Compliance im Bereich des 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 best4Automic 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: 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. 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" ],
    "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) defeniert 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.

In der Beispielkonfiguration sind insgesamt vier 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 und letzte Regel bezieht sich auf die strukturierte Dokumentation names Details von JOBI- und JOBP-Objekten. Hier wird geprüft, ob der Knoten /Content/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" ]
        }
    ]
}

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 Configurationen 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 Ersetzungparameter einem gewissen Format entspricht.

  • name: Der Name des JOBI-Objekts, dass 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 Package. Die verpflichtenden Felder für den Namen sowie die Versionsnummer werden immer 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 überpürft die korrekte Benennung aller Objekte eines Package. Dabei wird ein regulärer Ausdruck auf die Objekte angewendet, dem alle Objekte entsprechen müssen. In dem regulären Ausdruck kann die best4Automic Expression %(package) vorkommen um den Namen des Package im Ausdruck zu verwenden.

Die folgende Beispielkonfiguration überprüft, ob die Objekte Namen haben, die dem Schema <Package-Name>.<Objekttyp>.<Beschreibung> folgen.

"object-name" : {
    "regex" : "%(package)\\.(CONN|CALL|LOGIN|QUEUE|DOCU|JOBS|JOBG|JOBI|JOBF|JOBP|EVNT|SCRI|VARA|JSCH|PRPT|STORE)\\.[A-Z_0-9-.#$@]+"
}

Test: title

Dieser Test überprüft, ob die Objekte eines 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
        }
    ]
}

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