Extensibilité de ThingWorx > Extensions > Création de catégories d'audit personnalisées à l'aide d'une extension
Création de catégories d'audit personnalisées à l'aide d'une extension
Vous pouvez créer des événements et des messages d'audit personnalisés à l'aide du SDK Java ThingWorx. S'il vous est impossible d'ajouter des événements personnalisés via ThingWorx Composer, l'ajout de catégories et de messages d'audit personnalisés peut en revanche s'effectuer de deux manières différentes :
• Via Composer. Pour en savoir plus, consultez le manuel anglais Catégories d'audit personnalisées .
• En créant une extension Java basée sur le SDK ThingWorx Extension, comme expliqué dans cette rubrique. Cette méthode nécessite également l'utilisation de tables de localisation, mais la création des jetons peut être réalisée par programmation ou de manière interactive via l'interface utilisateur de Composer.
Cette rubrique décrit le processus de création d'une extension qui ajoute des événements d'audit personnalisés, ainsi que des messages et des catégories d'audit pour les événements audités. Vous pouvez ajouter une catégorie d'audit personnalisée en créant une extension ThingWorx personnalisée incluant une entité avec les attributs requis pour l'événement d'audit.
Vous pouvez utiliser le kit Extension SDK ThingWorx pour créer des extensions basées sur Java. Le SDK vous permet d'accéder aux classes et API ThingWorx Platform prises en charge. Il expose les services et méthodes intégrés, ce qui facilite la création et la gestion des entités sur ThingWorx Platform. Pour plus d'informations sur les classes disponibles dans la plateforme, consultez la documentation Java.
Pour créer une extension pour l'audit, procédez comme suit :
Avant de commencer
Téléchargez le logiciel suivant à partir de la page Télécharger un logiciel PTC pour ThingWorx Foundation :
• Plug-in Eclipse pour les extensions ThingWorx
• ThingWorx Extension SDK
Pour installer le plug-in Eclipse :
1. Ouvrez Eclipse et choisissez un espace de travail.
2. Cliquez sur Help > Install New Software.
La fenêtre Install s'ouvre.
3. Cliquez sur Add.
La boîte de dialogue Add Repository s'ouvre.
4. Extrayez le contenu du fichier thingworxeclipse-plugin-[version].zip dans un dossier portant le même nom, puis sélectionnez le dossier.
5. Sous ThingWorx, cochez la case ThingWorx Extension Builder, puis cliquez sur Next.
6. Acceptez le contrat de licence, puis cliquez sur Finish. Un message de sécurité s'affiche.
7. Cliquez sur OK pour confirmer l'installation.
8. Redémarrez Eclipse à l'issue de l'installation.
Vous pouvez vérifier votre installation en cliquant sur File > New. L'option ThingWorx Extension Project est disponible dans la liste.
Création d'un nouveau projet d'extension
1. Dans Eclipse, cliquez sur File > New > Project. La fenêtre New Project s'ouvre.
2. Développez ThingWorx, sélectionnez ThingWorx Extension Project dans la liste, puis cliquez sur Next.
3. Entrez un nom pour le projet d'extension et sélectionnez le fichier ThingWorxExtension-SDK-[version]-latest.zip que vous avez téléchargé précédemment.
4. Sélectionnez Gradle ou Ant comme structure de génération pour l'extension. Cela crée un fichier gradle.build ou build-extension.xml pour le projet, en fonction de votre sélection.
5. Entrez une version de package et un nom de fournisseur, puis cliquez sur Finish.
Le projet est désormais répertorié dans le volet Package Explorer.
Création d'entités de table de localisation et définition de jetons
Avant de créer l'entité avec l'événement d'audit, vous devez définir des jetons pour la catégorie et le message d'audit personnalisés. Vous pouvez définir des jetons dans les entités de table de localisation que vous pouvez inclure dans l'extension. Lorsque vous importez l'extension, les jetons spécifiés sont automatiquement ajoutés aux entités de table de localisation dans ThingWorx Platform. Vous pouvez créer une entité de table de localisation en exportant et en modifiant le modèle XML par défaut des tables de localisation.
Pour exporter la table de localisation Default pour l'anglais dans la plateforme, procédez comme suit :
1. Dans Composer, ouvrez le menu Importer/Exporter, puis sélectionnez Exporter.
2. Sous Option d'exportation, sélectionnez Vers un fichier dans la liste déroulante.
3. Sous le champ Entité, sélectionnez la table de localisation Default.
4. Cliquez sur Exporter.
Une fois que vous avez exporté le fichier XML de la table de localisation Default, ouvrez-le dans un éditeur XML. Vous pouvez ajouter manuellement des jetons à la table de localisation en tant qu'éléments Row dans la section Rows. Par exemple :
<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>
La table suivante décrit la syntaxe de l'élément Row pour la catégorie d'audit personnalisée :
Elément
Valeur
Description
name
<![CDATA[audit.AuditCategory.ExampleCustomCategory]]>
La section audit.AuditCategory. spécifie le préfixe pour définir un nom de catégorie d'audit personnalisé. Dans cet exemple, le préfixe est suivi du nom de catégorie suivant : ExampleCustomCategory
* 
Le nom de la catégorie doit être unique pour la plateforme. Vous ne pouvez pas créer deux jetons de catégorie portant le même nom.
value
<value><![CDATA[ExampleCustomCategoryEN]]></value>
Définit la valeur du jeton de catégorie personnalisée. Vous pouvez inclure des caractères alphanumériques, des espaces et des traits de soulignement. Dans cet exemple, la valeur est définie de façon à afficher la chaîne suivante : Example Custom Category EN.
La table suivante décrit la syntaxe de l'élément Row pour le message d'audit personnalisé :
Elément
Valeur
Description
name
<![CDATA[com.example.audit.ExampleCustomMessage]]>
Définit le message à afficher pour la catégorie d'audit. Vous devez définir un préfixe, puis fournir un nom unique pour le message.
* 
Le nom du message doit être unique pour le serveur. Vous ne pouvez pas créer deux messages portant le même nom.
value
<![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]>
Définit la valeur du jeton de catégorie personnalisée. Vous pouvez spécifier un message simple ou y inclure des paramètres. Ces derniers peuvent référencer une valeur et doivent être entourés de deux traits de soulignement comme suit :
__type__
Vous devez inclure une table de localisation pour chaque langue prise en charge par votre extension. Par exemple, pour inclure des jetons japonais, vous devez créer une entité de table de localisation ja et ajouter les jetons requis.
Lorsque vous avez terminé d'apporter des modifications aux tables de localisation, enregistrez-les dans un dossier nommé LocalizationTables n'importe où sur votre système.
Importation d'entités de table de localisation dans l'extension
Une fois que vous avez ajouté les jetons requis, vous pouvez importer les entités de table de localisation que vous avez exportées et modifiées dans la section précédente :
1. Dans Eclipse, ouvrez le projet d'extension, puis cliquez sur File > Import. La fenêtre Import s'affiche.
2. Sous ThingWorx, sélectionnez Entities, puis cliquez sur Next.
3. Dans le champ Source, cliquez sur Browse et sélectionnez le dossier LocalizationTables contenant vos entités de table de localisation.
4. Sélectionnez les entités que vous souhaitez importer, puis cliquez sur Finish.
Les entités que vous avez sélectionnées sont ajoutées au dossier /Entities/LocalizationTables/ du projet d'extension.
Création d'une nouvelle entité objet et ajout d'un événement d'audit
Vous pouvez définir de nouveaux événements en ajoutant des annotations aux méthodes d'une classe. Les méthodes annotées sont importées en tant que services ThingWorx pouvant être exécutés dans la plateforme ou dans l'application composite au moment de l'exécution. Pour définir les services d'une entité ThingWorx dans l'extension, procédez comme suit :
1. Dans Eclipse, ouvrez le menu ThingWorx et sélectionnez un type d'entité dans la liste.
2. Spécifiez un dossier source et un package.
3. Donnez un nom à votre entité, puis cliquez sur Next.
4. Cochez la case Editable Extension Entity, puis cliquez sur Finish.
Le fichier source Java est créé dans le package spécifié dans le dossier /src et le fichier metadata.xml est mis à jour automatiquement.
Activation de l'audit d'événements
Vous pouvez définir dans votre extension des événements qui sont déclenchés lorsqu'un ensemble de conditions est rempli. Vous pouvez utiliser des événements pour déclencher des services avec des fonctionnalités personnalisées. Un événement nécessite une forme de données prédéfinie. La forme de données stocke les données associées à l'événement, accessibles via un abonnement. Vous pouvez configurer les événements ThingWorx pour consigner des informations pour le sous-système d'audit. Pour activer l'audit d'un événement, vous devez y affecter les éléments suivants :
• auditCategoryKey:customCategoryToken
• auditMessageKey:customMessageToken
Vous pouvez uniquement ajouter ces éléments en créant une extension de code Java qui ajoute de nouveaux événements, puis définir manuellement ces éléments pour l'événement.
La section suivante fournit un exemple de définition des caractéristiques d'un événement.
Exemple : création d'événements d'audit personnalisés
Le code ci-après illustre un exemple de définition d'un événement d'audit nommé ExampleAuditedEvent dans un modèle d'objet. L'événement possède des propriétés standard définies, telles que name, description, category et la DataShape implémentée. Les caractéristiques requises pour l'audit sont définies dans la valeur aspects.
Pour plus d'informations sur la définition d'événements, recherchez l'élément suivant dans la documentation de l'API ThingWorx :
com.thingworx.metadata.annotations.ThingworxEventDefinition
Le code suivant présente une définition d'événement avec les caractéristiques requises pour l'audit :
@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
}
Vous pouvez ajouter de nouveaux événements à une entité ThingWorx dans une extension en procédant comme suit :
1. Dans Eclipse, cliquez avec le bouton droit sur une entité dans le dossier src, puis sélectionnez ThingWorx > Add Event dans le menu contextuel.
2. Spécifiez les informations suivantes :
◦ Un nom d'événement
◦ Un nom de catégorie
◦ La forme de données implémentée pour l'événement. Dans l'exemple fourni, la valeur est définie sur EntityReference.
3. Cliquez sur Finish.
Un nouvel événement est créé pour l'entité et les annotations spécifiées sont ajoutées au fichier source Java de l'entité ThingWorx. Par défaut, les caractéristiques requises pour l'audit ne sont pas définies. Pour activer l'audit du nouvel événement, vous devez définir manuellement les caractéristiques de la source Java, comme suit :
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
• audit.AuditCategory.ExampleCustomCategory : spécifie le nom du jeton pour la catégorie personnalisée que vous avez définie dans la table de localisation Default.
• com.example.audit.ExampleCustomMessage : spécifie le nom du jeton pour le message personnalisé que vous avez défini dans la table de localisation.
Ajout de fichiers JAR tiers
Le dossier /lib contient des fichiers JAR avec des classes Java personnalisées écrites pour l'extension ainsi que des fichiers JAR tiers supplémentaires requis par l'extension.
Assurez-vous que le fichier metadata.xml contient une entrée pour chaque fichier JAR.
* 
N'ajoutez à votre extension aucun fichier JAR tiers déjà inclus dans la plateforme ThingWorx.
Génération de l'extension à l'aide de Gradle
Pour générer l'extension, créez une tâche de génération.
1. Dans la barre d'outils Eclipse, cliquez sur la flèche en regard du bouton Run, puis sélectionnez Run Configurations.
2. Dans le volet de navigation de gauche, cliquez avec le bouton droit sur Gradle Task, puis sélectionnez New Configuration.
3. Spécifiez Build comme nom de configuration de la tâche.
Dans l'onglet Gradle Tasks, ajoutez les tâches suivantes :
clean
build
* 
Vous pouvez ajouter la tâche sous la forme d'un raccourci à la liste déroulante Run en cochant la case Run dans l'onglet Common de la fenêtre Run Configurations.
4. Sélectionnez le répertoire de travail de votre projet, puis cliquez sur Apply.
5. Dans la barre d'outils, cliquez sur la commande Run, puis sélectionnez Build.
Pour les anciennes versions d'Eclipse, vous pouvez également utiliser le plug-in Gradle STS :
1. Dans l'explorateur de packages, cliquez avec le bouton droit sur le fichier build.gradle et sélectionnez Run As > Gradle (STS) Build. Une fenêtre de configuration s'affiche.
2. Dans l'onglet Gradle Tasks, ajoutez les tâches suivantes :
clean
build
3. Cliquez sur Run. Un message de réussite est consigné dans la zone de la console Eclipse.
Le fichier ZIP d'extension est créé dans le dossier build > Distributions de votre projet. Vous pouvez importer ce fichier ZIP en tant qu'extension dans ThingWorx Platform.
Génération de l'extension à l'aide d'Ant
Si votre extension utilise Ant en tant que structure de génération, procédez comme suit :
1. Dans l'explorateur de packages, cliquez avec le bouton droit sur le fichier build-extension.xml et sélectionnez Run As > Ant Build.
2. Actualisez votre projet d'extension.
Un fichier ZIP est créé sous build > Distributions. Vous pouvez importer ce fichier ZIP en tant qu'extension dans ThingWorx Platform.
Importation de l'extension
1. Dans Composer, ouvrez le menu Importer/Exporter, puis sélectionnez Importer. La boîte de dialogue Importer s'ouvre.
2. Sous Option d'importation, sélectionnez Extension dans la liste déroulante.
3. Cliquez sur Parcourir, puis sélectionnez le fichier ZIP d'extension que vous avez créé dans la section précédente.
4. Cliquez sur Importer.
L'extension est importée.
Affichage des modifications d'audit
Dans Composer, les modifications suivantes sont visibles :
• Une nouvelle entité avec un événement d'audit est ajoutée.
• Les jetons de localisation pour les catégories et les messages d'audit personnalisés sont ajoutés aux tables de localisation.
Pour tester la nouvelle catégorie et le nouveau message d'audit personnalisés, exécutez l'événement personnalisé de l'entité que vous avez ajoutée à l'aide de l'extension. Pour consulter l'historique d'audit, exécutez le service QueryAuditHistory ou QueryAuditHistoryWithQueryCriteria avec les paramètres appropriés. Pour plus d'informations sur les paramètres disponibles, consultez la rubrique pertinente pour l'implémentation que vous utilisez (Persistance directe ou Table de données) : Recherche de données d'audit (requêtes, persistance directe) ou Données d'audit en ligne et hors ligne (table de données).
Est-ce que cela a été utile ?