ThingWorx Erweiterbarkeit > Erweiterungen > Benutzerdefinierte Prüfungskategorien mithilfe einer Erweiterung erstellen
Benutzerdefinierte Prüfungskategorien mithilfe einer Erweiterung erstellen
Mit dem ThingWorx Java SDK können Sie benutzerdefinierte Prüfungsereignisse und -meldungen erstellen. Obwohl Sie keine benutzerdefinierten Ereignisse über ThingWorx Composer hinzufügen können, gibt es zwei Möglichkeiten, um Prüfungskategorien und -meldungen für Kunden hinzuzufügen:
• Über Composer. Weitere Informationen finden Sie unter Benutzerdefinierte Prüfungskategorien .
• Durch Erstellen einer Java-Erweiterung basierend auf dem ThingWorx Extension SDK, das in diesem Thema erläutert wird. Diese Methode erfordert auch die Verwendung von Lokalisierungstabellen, aber die Erstellung der Token kann programmatisch oder interaktiv über die Composer Benutzeroberfläche erfolgen.
In diesem Thema wird der Prozess zum Erstellen einer Erweiterung beschrieben, die benutzerdefinierte Prüfungsereignisse, -meldungen und -kategorien für geprüfte Ereignisse hinzufügt. Sie können eine benutzerdefinierte Prüfungskategorie hinzufügen, indem Sie eine benutzerdefinierte ThingWorx Erweiterung erstellen, die eine Entität mit den erforderlichen Attributen für das Prüfungsereignis enthält.
Sie können das ThingWorx Extension SDK verwenden, um Java-basierte Erweiterungen zu erstellen. Das SDK ermöglicht es Ihnen, auf unterstützte ThingWorx Platform Klassen und APIs zuzugreifen. Dadurch sind integrierte Dienste und Methoden verfügbar, was das Erstellen und Verwalten von Entitäten in ThingWorx Platform vereinfacht. Weitere Informationen zu den verfügbaren Klassen in der Plattform finden Sie in der Javadoc-Dokumentation.
Um eine Erweiterung für die Prüfung zu erstellen, führen Sie die folgenden Schritte aus:
Before you Begin
Laden Sie die folgende Software von der Seite PTC Software-Download für ThingWorx Foundation herunter:
• Eclipse-Plugin für ThingWorx Erweiterungen
• ThingWorx Extension SDK
So installieren Sie das Eclipse-Plugin:
1. Öffnen Sie Eclipse, und wählen Sie einen Workspace.
2. Klicken Sie auf Help > Install New Software.
Das Fenster Install wird geöffnet.
3. Klicken Sie auf Add.
Das Dialogfenster Add Repository wird geöffnet.
4. Extrahieren Sie den Inhalt der Datei thingworxeclipse-plugin-[version].zip in einen gleichnamigen Ordner, und wählen Sie dann den Ordner aus.
5. Aktivieren Sie unter ThingWorx das Kontrollkästchen ThingWorx Extension Builder, und klicken Sie dann auf Next.
6. Akzeptieren Sie den Lizenzvertrag, und klicken Sie dann auf Finish. Eine Sicherheitsmeldung wird geöffnet.
7. Klicken Sie auf OK, um die Installation zu bestätigen.
8. Starten Sie Eclipse neu, wenn die Installation beendet ist.
Sie können Ihre Installation überprüfen, indem Sie auf Datei > Neu klicken. Die Option ThingWorx Extension Project ist in der Liste verfügbar.
Neues Erweiterungsprojekt erstellen
1. Klicken Sie in Eclipse auf Datei > Neu > Projekt. Das Fenster Neues Projekt wird geöffnet.
2. Erweitern Sie ThingWorx, wählen Sie ThingWorx Extension Project in der Liste aus, und klicken Sie dann auf Next.
3. Geben Sie einen Namen für das Erweiterungsprojekt ein, und wählen Sie die Datei ThingWorxExtension-SDK-[version]-latest.zip aus, die Sie zuvor heruntergeladen haben.
4. Wählen Sie Gradle oder Ant als Framework zur Erstellung der Erweiterung aus. Dadurch wird die Datei gradle.build oder build-extension.xml für das Projekt je nach Ihrer Auswahl erstellt.
5. Geben Sie eine Paketversion und einen Anbieternamen ein, und klicken Sie dann auf Finish.
Das Projekt wird jetzt im Fensterbereich Package Explorer aufgelistet.
Lokalisierungstabellen-Entitäten erstellen und Token definieren
Bevor Sie die Entität mit dem Prüfungsereignis erstellen, müssen Sie Token für die benutzerdefinierte Prüfungskategorie und die Meldung definieren. Sie können Token in Lokalisierungstabellen-Entitäten definieren, die Sie als Teil der Erweiterung einschließen können. Wenn Sie die Erweiterung importieren, werden die angegebenen Token automatisch zu den Lokalisierungstabellen-Entitäten in ThingWorx Platform hinzugefügt. Sie können eine Lokalisierungstabellen-Entität erstellen, indem Sie die standardmäßige XML-Vorlage für Lokalisierungstabellen exportieren und ändern.
Um die Default-Lokalisierungstabelle für Englisch in der Plattform zu exportieren, führen Sie die folgenden Schritte aus:
1. Öffnen Sie in Composer das Menü Importieren/Exportieren, und wählen Sie dann Exportieren aus.
2. Wählen Sie unter Exportoption in der Dropdown-Liste die Option In Datei aus.
3. Wählen Sie im Feld Entität die Default-Lokalisierungstabelle aus.
4. Klicken Sie auf Exportieren.
Nachdem Sie die XML-Datei für die Default-Lokalisierungstabelle exportiert haben, wird ein XML-Editor geöffnet. Sie können Token manuell zur Lokalisierungstabelle als Row-Elemente unter dem Rows-Abschnitt hinzufügen. Zum Beispiel:
<Rows>
<Row>
<context/>
<name><![CDATA[audit.AuditCategory.ExampleCustomCategory]]></name>
<usage/>
<value><![CDATA[ExampleCustomCategoryEN]]></value>
</Row>
<Row>
<context/>
<name><![CDATA[com.example.audit.ExampleCustomMessage]]></name>
<usage/>
<value><![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]></value>
</Row>
</Rows>
In der folgenden Tabelle wird die Syntax des Row-Elements für die benutzerdefinierte Prüfungskategorie beschrieben:
Element
Wert
Beschreibung
name
<![CDATA[audit.AuditCategory.ExampleCustomCategory]]>
Der audit.AuditCategory.-Teil gibt das Präfix an, um einen benutzerdefinierten Prüfungskategorienamen zu definieren. In diesem Beispiel folgt nach dem Präfix der folgende Kategoriename: ExampleCustomCategory
* 
Der Kategorienname muss für die Plattform eindeutig sein. Sie können nicht zwei Kategorie-Token mit demselben Namen erstellen.
value
<value><![CDATA[ExampleCustomCategoryEN]]></value>
Definiert den Wert des benutzerdefinierten Kategorie-Tokens. Sie können alphanumerische Zeichen, Leerzeichen und Unterstriche einschließen. Im Beispiel wird der Wert so festgelegt, dass die folgende Zeichenfolge angezeigt wird: Example Custom Category EN.
In der folgenden Tabelle wird die Syntax des Row-Elements für die benutzerdefinierte Prüfungsmeldung beschrieben:
Element
Wert
Beschreibung
name
<![CDATA[com.example.audit.ExampleCustomMessage]]>
Definiert die Meldung, die für die Prüfungskategorie angezeigt werden soll. Sie müssen ein Präfix definieren und dann einen eindeutigen Namen für die Meldung angeben.
* 
Der Meldungsname muss für den Server eindeutig sein. Sie können nicht zwei Meldungen mit demselben Namen erstellen.
value
<![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]>
Definiert den Wert des benutzerdefinierten Kategorie-Tokens. Sie können eine einfache Meldung angeben oder Parameter in die Meldung einschließen. Die Parameter können einen Wert referenzieren und müssen wie folgt in zwei Unterstriche eingeschlossen werden:
__type__
Sie sollten eine Lokalisierungstabelle für jede Sprache einschließen, die von der Erweiterung unterstützt wird. Um beispielsweise japanische Token einzuschließen, müssen Sie eine ja-Lokalisierungstabellen-Entität erstellen und die erforderlichen Token hinzufügen.
Wenn Sie die Änderungen an den Lokalisierungstabellen abgeschlossen haben, speichern Sie sie in einem Ordner mit dem Namen LocalizationTables an einer beliebigen Stelle auf Ihrem System.
Lokalisierungstabellen-Entitäten in die Erweiterung importieren
Nachdem Sie die erforderlichen Token hinzugefügt haben, können Sie die im vorherigen Abschnitt exportierten und geänderten Lokalisierungstabellen-Entitäten importieren:
1. Öffnen Sie in Eclipse das Erweiterungsprojekt, und klicken Sie dann auf Datei > Importieren. Das Fenster Import wird geöffnet.
2. Wählen Sie unter ThingWorx die Option Entities aus, und klicken Sie dann auf Next.
3. Klicken Sie im Feld Source auf Browse, und wählen Sie den Ordner LocalizationTables aus, der die Lokalisierungstabellen-Entitäten enthält.
4. Wählen Sie die Entitäten aus, die Sie importieren möchten, und klicken Sie dann auf Finish.
Die Entitäten, die Sie ausgewählt haben, werden unter dem Ordner /Entities/LocalizationTables/ für das Erweiterungsprojekt hinzugefügt.
Neue Dingentität erstellen und Prüfungsereignis hinzufügen
Sie können neue Ereignisse definieren, indem Sie Anmerkungen zu Methoden innerhalb einer Klasse hinzufügen. Mit Anmerkungen versehene Methoden werden als ThingWorx Dienste importiert, die zur Laufzeit in der Plattform oder im Mashup ausgeführt werden können. Um die Dienste für eine ThingWorx Entität in der Erweiterung zu definieren, führen Sie die folgenden Schritte aus:
1. Öffnen Sie in Eclipse das Menü ThingWorx, und wählen Sie einen Entitätstyp aus der Liste aus.
2. Geben Sie einen Quellordner und ein Paket ein.
3. Geben Sie einen Namen für die Entität ein, und klicken Sie dann auf Next.
4. Aktivieren Sie das Kontrollkästchen Editable Extension Entity, und klicken Sie dann auf Finish.
Die Java-Quelldatei wird im angegebenen Paket unter dem Ordner /src erstellt und die Datei metadata.xml automatisch aktualisiert.
Prüfung für Ereignisse aktivieren
Sie können Ereignisse in der Erweiterung definieren, die ausgelöst werden, wenn ein Satz von Bedingungen erfüllt wird. Sie können Ereignisse verwenden, um Dienste mit benutzerdefinierten Funktionen auszulösen. Ein Ereignis erfordert einen vordefinierten Data Shape. Der Data Shape speichert dem Ereignis zugeordnete Daten, auf das über ein Abonnement zugegriffen werden kann. Sie können ThingWorx Ereignisse konfigurieren, um Informationen für das Prüfungsuntersystem zu protokollieren. Um die Prüfung für ein Ereignis zu aktivieren, müssen Sie dem Ereignis die folgenden Aspekte zuweisen:
• auditCategoryKey:customCategoryToken
• auditMessageKey:customMessageToken
Sie können diese Aspekte nur hinzufügen, indem Sie eine Java-Code-Erweiterung erstellen, die neue Ereignisse hinzufügt, und dann die Aspekte für das Ereignis manuell definieren.
Der nächste Abschnitt enthält ein Beispiel für die Definition der Aspekte für ein Ereignis.
Beispiel: Benutzerdefinierte Prüfungsereignisse erstellen
Der folgende Code zeigt ein Beispiel für eine Prüfungsereignisdefinition mit dem Namen ExampleAuditedEvent innerhalb einer Dingvorlage. Für das Ereignis sind Standardeigenschaften definiert, wie z.B. name, description, category und der implementierte DataShape. Die erforderlichen Aspekte für die Prüfung werden im aspects-Wert definiert.
Um weitere Informationen zur Ereignisdefinition zu erhalten, durchsuchen Sie die ThingWorx Javadoc API-Dokumentation nach Folgendem:
com.thingworx.metadata.annotations.ThingworxEventDefinition
Der folgende Code zeigt eine Ereignisdefinition mit den erforderlichen Aspekten für die Prüfung:
@ThingworxEventDefinitions{
events = {
@ThingworxEventDefinition(
name = "ExampleAuditedEvent",
description = "Event with Audit specific Aspects",
category = "Example",
dataShape = "EntityReference",
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
)
}
)
@ThingworxBaseTemplateDefinition(name = Thing.GENERIC_THING_TEMPLATE)
public class ExampleAuditedEventExtensionThingTemplate extends Thing {
// Customer business logic implementation
}
Sie können einer ThingWorx Entität innerhalb einer Erweiterung neue Ereignisse hinzufügen, indem Sie die folgenden Schritte durchführen:
1. Klicken Sie in Eclipse mit der rechten Maustaste auf ein Element unter dem Ordner src, und wählen Sie dann im Kontextmenü ThingWorx > Add Event aus.
2. Geben Sie die folgenden Informationen ein:
◦ Ereignisname
◦ Kategorienname
◦ Implementierter Data Shape für das Ereignis. Im bereitgestellten Beispiel wird der Wert auf EntityReferencefestgelegt.
3. Klicken Sie auf Finish.
Für die Entität wird ein neues Ereignis erstellt, und die angegebenen Anmerkungen werden der Java-Quelldatei für die ThingWorx Entität hinzugefügt. Standardmäßig sind die erforderlichen Aspekte für die Prüfung nicht definiert. Um die Prüfung für das neue Ereignis zu aktivieren, müssen Sie die Aspekte innerhalb der Java-Quelle wie folgt manuell definieren:
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
• audit.AuditCategory.ExampleCustomCategory – Gibt den Token-Namen für die benutzerdefinierte Kategorie an, die Sie in der Default- Lokalisierungstabelle definiert haben.
• com.example.audit.ExampleCustomMessage – Gibt den Token-Namen für die benutzerdefinierte Meldung an, die Sie in der Lokalisierungstabelle definiert haben.
JAR-Dateien von Drittanbietern hinzufügen
Der Ordner /lib enthält JAR-Dateien mit benutzerdefinierten Java-Klassen, die für die Erweiterung geschrieben wurden, und zusätzliche JAR-Dateien von Drittanbietern, die für die Erweiterung erforderlich sind.
Stellen Sie sicher, dass die Datei metadata.xml einen Eintrag für jede JAR-Datei enthält.
* 
Fügen Sie keine JAR-Dateien von Drittanbietern, die bereits in der ThingWorx Plattform enthalten sind, zu Ihrer Erweiterung hinzu.
Erweiterung mit Gradle erstellen
Um die Erweiterung zu erstellen, erstellen Sie eine Erstellungsaufgabe.
1. Klicken Sie in der Eclipse-Symbolleiste auf den Pfeil neben der Schaltfläche Run, und wählen Sie Run Configurations aus.
2. Klicken Sie im linken Navigationsbereich mit der rechten Maustaste auf Gradle Task, und wählen Sie New Configuration aus.
3. Geben Sie Build als Aufgabenkonfigurationsnamen ein.
Fügen Sie auf der Registerkarte Gradle Tasks die folgenden Aufgaben hinzu:
clean
build
* 
Sie können die Aufgabe als Verknüpfung zur Dropdown-Liste Run hinzufügen, indem Sie das Kontrollkästchen Run auf der Registerkarte Common im Fenster Run Configurations aktivieren.
4. Wählen Sie das Arbeitsverzeichnis für das Projekt aus, und klicken Sie dann auf Apply.
5. Klicken Sie in der Symbolleiste auf den Befehl Run, und wählen Sie dann Build aus.
Für ältere Versionen von Eclipse können Sie auch das Gradle-STS-Plugin verwenden:
1. Klicken Sie in Package Explorer mit der rechten Maustaste auf die Datei build.gradle, und wählen Sie Run As > Gradle (STS) Build aus. Ein Konfigurationsfenster wird geöffnet.
2. Fügen Sie auf der Registerkarte Gradle Tasks die folgenden Aufgaben hinzu:
clean
build
3. Klicken Sie auf Run. Eine Erfolgsmeldung wird im Eclipse-Konsolenbereich protokolliert.
Die ZIP-Erweiterungsdatei wird im Ordner build > Distributions des Projekts erstellt. Sie können diese ZIP-Datei als Erweiterung in ThingWorx Platform importieren.
Erweiterung mit Ant erstellen
Wenn Ihre Erweiterung Ant als Erstellungsframework verwendet, führen Sie die folgenden Schritte aus:
1. Klicken Sie in Package Explorer mit der rechten Maustaste auf die Datei build-extension.xml, und wählen Sie Run As > Ant Build aus.
2. Aktualisieren Sie das Erweiterungsprojekt.
Eine ZIP-Datei wird unter build > Distributions erstellt. Sie können diese ZIP-Datei als Erweiterung in ThingWorx Platform importieren.
Erweiterung importieren
1. Öffnen Sie in Composer das Menü Importieren/Exportieren, und wählen Sie dann Importieren aus. Das Dialogfenster Importieren wird geöffnet.
2. Wählen Sie unter Importoption in der Dropdown-Liste die Option Erweiterung aus.
3. Klicken Sie auf Durchsuchen, und wählen Sie dann die ZIP-Datei mit der Erweiterung aus, die Sie im vorherigen Abschnitt erstellt haben.
4. Klicken Sie auf Importieren.
Die Erweiterung wird importiert.
Prüfungsänderungen anzeigen
In Composer sind die folgenden Änderungen sichtbar:
• Eine neue Entität mit einem Prüfungsereignis wird hinzugefügt.
• Lokalisierungs-Token für die benutzerdefinierten Prüfungskategorien und -meldungen werden den Lokalisierungstabellen hinzugefügt.
Um die neue benutzerdefinierte Prüfungskategorie und -meldung zu testen, führen Sie das benutzerdefinierte Ereignis für die Entität aus, die Sie durch die Erweiterung hinzugefügt haben. Sie können den Prüfungsverlauf anzeigen, indem Sie den Dienst QueryAuditHistory oder QueryAuditHistoryWithQueryCriteria mit den entsprechenden Parametern ausführen. Weitere Informationen zu den verfügbaren Parametern finden Sie im Thema für die Implementierung, die Sie verwenden (direkte Persistenz oder Datentabelle): Prüfdaten durchsuchen (Abfragen, direkte Persistenz) oder Online- und Offline-Prüfungsdaten (Datentabelle).
War dies hilfreich?