Erweiterungsfunktion mit benutzerdefinierter Eigenschaft

Das folgende Beispiel zeigt, wie Anforderungen in ein anderes Package verschoben werden. Dabei werden nur die Anforderungen verschoben, die sich in einem bestimmten Zustand befinden. Der Zustand wird hier durch eine benutzerdefinierte Eigenschaft abgebildet.

Damit Sie im Projekt mit Erweiterungsfunktionen arbeiten können, müssen Sie folgende Voraussetzungen erfüllen:

• im Service-Manager für den Service den Node.js-Server einrichten
• zum Editieren benötigen Sie ein entsprechendes Tool, z.B. Visual Studio Code

Benutzerdefinierte Eigenschaften anlegen

Als erstes benötigen Sie für das hier verwendete Beispiel zwei benutzerdefinierte Eigenschaften. Eine Referenzeigenschaft für den Stereotypen Package sowie eine benutzerdefinierte Eigenschaft für den Stereotypen Requirement.
Damit Sie die Stereotypen erweitern können, benötigen Sie Administratorrechte.

Referenzeigenschaft anlegen

1. Öffnen Sie über das Auge das Fenster Stereotypen, indem Sie Stereotypen anzeigen klicken.
2. Gehen Sie zum Stereotypen Package und wählen den Kontextmenübefehl Eigenschaften.

3. Wechseln Sie in die Registerkarte Referenz-Eigenschaftstypen und legen über die Plus-Schaltfläche die Eigenschaft Archiv an.
4. Tragen Sie einen Namen, z.B. Archiv ein und wählen in der Spalte Stereotyp des referenzierten Elements über die […]-Schaltfläche den Stereotypen Package aus.

5. Bestätigen Sie mit OK.

Benutzerdefinierte Eigenschaft anlegen

1. Gehen Sie zum Stereotypen Requirement und wählen den Kontextmenübefehl Eigenschaften.
2. In der Registerkarte Eigenschaftstypen legen Sie über die Plus-Schaltfläche eine Eigenschaft vom Typ Aufzählung an und definieren verschiedene Zustände.
3. Speichern Sie mit OK.

Erweiterungsfunktion anlegen

Als nächstes legen Sie eine Erweiterungsfunktion an. Standardmäßig befinden sich die Erweiterungsfunktionen im Fenster Einstellungen im Package Erweiterungsfunktionen. Sie können eine Erweiterungsfunktion auch in einem anderen Package anlegen.

1. Wählen Sie über das Kontextmenü eines Packages den Befehl Weitere anlegen/ Erweiterungsfunktion.
2. Vergeben Sie einen Namen und wählen einen Stereotypen aus.Da die Funktion auf einem Anforderungspackage angewendet werden soll, wählen Sie hier Package oder einen Substereotypen wie Requirements aus. Die benötigten Request- und Response-Schemata lassen Sie sich ganz einfach von objectiF RPM erstellen, genauso wie das Quellcode-Verzeichnis mit der Einstiegsdatei.
3. Markieren Sie die Optionen Request-Schema automatisch anlegen, Response-Schema automatisch anlegen und Verzeichnis mit Einstiegsdatei generieren.
4. Geben Sie in der Registerkarte Beschreibung falls notwendig eine Beschreibung ein. Diese wird Ihnen später beim Anwenden der Erweiterungsfunktion angezeigt.
5. Wechseln Sie in die Registerkarte Parameter und erstellen über die Plus-Schaltfläche einen Parameter zu der benutzerdefinierten Eigenschaft Zustand.

Mit der hier gewählten Definition wird später bei der Ausführung der Funktion der Zustand abgenommen automatisch vorgeschlagen, der aber auch überschrieben werden kann.

6. Speichern Sie mit OK die Erweiterungsfunktion.

Mit dem Anlegen der Erweiterungsfunktion werden automatisch neben den Quellcode-Dateien auch die Schemas erstellt.

Schema definieren

In den Schemas definieren Sie, welche Daten von vom Tool für die Erweiterungsfunktion zur Verfügung gestellt werden bzw. welche Daten geändert werden können. Aus dieser Schema-Definition erzeugt objectiF RPM dann ein JSON-Schema für die spätere Ausführung der Erweiterungsfunktion.

Damit die Erweiterungsfunktion ausgeführt werden kann, werden für dieses Beispiel folgende Informationen benötigt:

• das Package, in dem sich Anforderungen befinden
• nur Anforderungen im Zustand abgenommen werden verschoben
• das Zielpackage muss bekannt sein

1. Wählen Sie auf dem Schema Anforderungen archivieren (Request) den Kontextmenübefehl Bearbeiten.

2. In der Registerkarte Schema klappen Sie die Eigenschaften unter Package auf, indem Sie auf den kleinen Pfeil klicken.

3. Wählen Sie zunächst die Eigenschaft Id aus und setzen Sie die Option Ist aktuell Pflicht, indem Sie auf das Ausrufezeichen-Symbol klicken.

4. Scrollen Sie weiter bis zu Anforderungen und wählen dort ebenfalls die Eigenschaft Id.

5. Scrollen Sie weiter runter bis Sie zu der Eigenschaft Aktueller Zustand kommen. Hier markieren Sie die Eigenschaft Id und Name.

6. Weiter gehts mit der Eigenschaft Besitzer. Hier markieren Sie wieder die Eigenschaft Id.

7. Als letztes scrollen Sie zu Anforderungen und klappen die benutzerdefinierte Eigenschaft Archiv auf. Hier markieren Sie wieder die Eigenschaft Id.

8. Speichern Sie mit OK.

Funktion entwickeln

Jetzt schreiben Sie die Funktion, bspw. in Visual Studio Code. Sie können natürlich auch ein anderes Programm verwenden. 

1. Wählen Sie das Verzeichnis Anforderungen archivieren aus und klicken im Kontextmenü auf Verzeichnis in VS Code öffnen.
2. In Visual Studio Code wählen Sie die Datei index.js aus.

3. Die generierte Einstiegsdatei können Sie jetzt mit eigenen Code erweitern.
   Der Code zu diesem Beispiel könnte so aussehen:

Im Parameter source wird in unserem Beispiel das Package mit den Anforderung übergeben, params enthält den zusätzlich definierten Parameter Zustand als params.stateName.

Die Funktion überprüft, ob dem Anforderungspackage ein Archivpackage zugeordnet ist. Wenn ja, wird sich dessen Id in der Variable targetOwnerId gemerkt. Anschließend wird das Package nach Anforderungen (source.requirements) durchsucht und dabei geprüft, ob es Anforderungen mit dem Zustand abgenommen gibt. Ist das der Fall, werden die Anforderungen in das Archivpackage verschoben.

Abschließend wird zum Speichern der Änderungen die Funktion Response.updateSourceAndPrintMessage aufgerufen, die eine Erfolgs- oder Fehlermeldung ausgibt.

Beachten Sie, dass im Code die technischen Namen aus der Schema-Definition verwendet werden müssen, mit der Konvention, dass der erste Buchstabe klein geschrieben wird. Die genauen Bezeichner-Namen können Sie im JSON-Schema finden, indem Sie auf dem Extension-Schema den Kontextmenü-Befehl JSON-Schema ansehen wählen.

Funktion verfügbar machen

Die Erweiterungsfunktion können Sie jetzt im Projekt verfügbar machen, indem Sie einen Befehl anlegen, einen Task oder eine Aktion definieren.

In diesem Beispiel wird ein Menüpunkt für das Kontextmenü festgelegt.

1. Gehen Sie dazu ins Backstage-Menü des Projekts und wählen Sie Kommandos für Erweiterungsfunktionen.

2. In der Sicht klicken Sie auf die Plus-Schaltfläche.
3. Im Folgedialog tragen Sie im Feld Name ein, wie der Befehl im Kontextmenü angeboten werden soll. 
4. Unter Auszuführende Erweiterungsfunktion wählen Sie über die […]-Schaltfläche die Erweiterungsfunktion aus und geben im Feld Sichtbarkeit auf Stereotyp den Stereotypen Package an. 

5. Markieren Sie die Option Anzeigen auf oberster Menüebene und wählen anschließend über das Drop-Down-Menü eine Menügruppe aus.
   Weitere Angaben, wie Icon, Lokalisierung und Gewicht sind optional.
6. Speichern Sie mit OK.

Funktion ausführen

Bevor Sie die Erweiterungsfunktion ausführen, erstellen Sie ein Archivpackage und geben für das Package, das die Anforderungen enthält an, in welches Package die Anforderungen verschoben werden sollen. Öffnen Sie über Bearbeiten die Eigenschaften des Packages und wechseln in die Registerkarte Weitere Eigenschaften.

Außerdem müssen den Anforderungen über die Registerkarte Weitere Eigenschaften der definierte Zustand zugewiesen werden. Erst dann können diese in das dafür vorgesehene Package verschoben werden.

1. Wählen Sie über das Kontextmenü eines Packages den Befehl Anforderungen archivieren.

2. Den Folgedialog können Sie einfach mit OK bestätigen, da der definierte Wert bereits vorausgewählt ist. Alternativ können Sie den Wert auch überschreiben.

In der Ausgabe finden Sie eine Meldung, dass acht Anforderungen archiviert wurden…

… und im angegebenen Package finden Sie die Anforderungen.