Extensibilidad de ThingWorx > Extensiones > Creación de categorías de auditoría personalizadas mediante una extensión
Creación de categorías de auditoría personalizadas mediante una extensión
Con ThingWorx Java SDK, se pueden crear mensajes y eventos de auditoría personalizados. Aunque no se pueden añadir eventos personalizados a través de ThingWorx Composer, hay dos maneras de añadir categorías y mensajes de auditoría del cliente:
• A través de Composer. Para obtener más información, consulte Categorías de auditoría personalizadas .
• Crear una extensión de Java basada en ThingWorx Extension SDK, que se explica en este tema. Este método también requiere el uso de tablas de localización, pero la creación de los tokens se puede realizar mediante programación o de forma interactiva a través de la interfaz de usuario de Composer.
En este tema se describe el proceso de creación de una extensión que añade eventos, mensajes y categorías de auditoría personalizados para eventos auditados. Es posible añadir una categoría de auditoría personalizada mediante la creación de una extensión personalizada de ThingWorx que incluya una entidad con los atributos necesarios para el evento de auditoría.
Se puede utilizar Extension SDK de ThingWorx para crear extensiones basadas en Java. El SDK permite acceder a las clases y API de ThingWorx Platform soportadas. De este modo, se exponen servicios y métodos integrados, lo que facilita la creación y gestión de entidades en ThingWorx Platform. Para obtener más información acerca de las clases disponibles en la plataforma, consulte la documentación de Javadoc.
Para crear una extensión para auditoría, siga estos pasos:
Antes de empezar
Descargue el siguiente software desde la página Descargas de software de PTC de ThingWorx Foundation:
• Plug-in de Eclipse para extensiones de ThingWorx
• Extension SDK de ThingWorx
Para instalar el plug-in de Eclipse:
1. Abra Eclipse y elija un espacio de trabajo.
2. Pulse en Help > Install New Software.
Se abre la ventana Install.
3. Pulse en Add.
Se abre el cuadro de diálogo Add Repository.
4. Extraiga el contenido del fichero thingworxeclipse-plugin-[versión].zip en una carpeta con el mismo nombre y, a continuación, seleccione la carpeta.
5. En ThingWorx, seleccione la casilla ThingWorx Extension Builder y, a continuación, pulse en Next.
6. Acepte el convenio de licencia y, a continuación, pulse en Finish. Se abre un mensaje de seguridad.
7. Pulse en Aceptar para confirmar la instalación.
8. Reinicie Eclipse una vez finalizada la instalación.
Para verificar la instalación, pulse en Fichero > Nuevo. La opción ThingWorx Extension Project está disponible en la lista.
Creación de un nuevo proyecto de extensión
1. En Eclipse, pulse en File > New > Project. Se abre la ventana New Project.
2. Expanda ThingWorx, seleccione ThingWorx Extension Project de la lista y, a continuación, pulse en Next.
3. Introduzca un nombre para el proyecto de extensión y seleccione el fichero ThingWorxExtension-SDK-[version]-latest.zip que se ha descargado anteriormente.
4. Seleccione Gradle o Ant como marco de compilación para la extensión. Se crea un fichero gradle.build o build-extension.xml para el proyecto, en función de la selección realizada.
5. Introduzca una versión de paquete y un nombre de distribuidor y, a continuación, pulse en Finish.
El proyecto se muestra ahora en el panel Package Explorer.
Creación de entidades de tabla de localización y definición de tokens
Antes de crear la entidad con el evento de auditoría, se deben definir los tokens para la categoría y el mensaje de auditoría personalizados. Es posible definir tokens dentro de las entidades de tabla de localización que se pueden incluir como parte de la extensión. Al importar la extensión, los tokens especificados se añaden automáticamente a las entidades de la tabla de localización en ThingWorx Platform. Se puede crear una entidad de tabla de localización mediante la exportación y modificación de la plantilla XML por defecto para las tablas de localización.
Para exportar la tabla de localización Default en inglés a la plataforma, realice los siguientes pasos:
1. En Composer, abra el menú Importar/Exportar y, a continuación, seleccione Exportar.
2. En Opción de exportación, seleccione A fichero de la lista desplegable.
3. En el campo Entidad, seleccione la tabla de localización Default.
4. Pulse en Exportar.
Después de exportar el fichero XML de la tabla de localización Default, ábralo con un editor XML. Los tokens se pueden añadir manualmente a la tabla de localización como elementos Row en la sección Rows. Por ejemplo:
<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>
En la siguiente tabla se describe la sintaxis del elemento Row para la categoría de auditoría personalizada:
Elemento
Valor
Descripción
name
<![CDATA[audit.AuditCategory.ExampleCustomCategory]]>
En la parte audit.AuditCategory. se especifica el prefijo para definir un nombre de categoría de auditoría personalizada. En este ejemplo, el prefijo va seguido del siguiente nombre de categoría: ExampleCustomCategory
* 
El nombre de categoría debe ser exclusivo para la plataforma. No se pueden crear dos tokens de categoría con el mismo nombre.
value
<value><![CDATA[ExampleCustomCategoryEN]]></value>
Permite definir el valor del token de categoría personalizada. Se pueden incluir caracteres alfanuméricos, espacios y guiones bajos. En el ejemplo, el valor se ha definido para mostrar la siguiente cadena: Example Custom Category EN.
En la siguiente tabla se describe la sintaxis del elemento Row para el mensaje de auditoría personalizado:
Elemento
Valor
Descripción
name
<![CDATA[com.example.audit.ExampleCustomMessage]]>
Permite definir el mensaje que se debe mostrar para la categoría de auditoría. Se debe definir un prefijo y, a continuación, proporcionar un nombre único para el mensaje.
* 
El nombre de mensaje debe ser único en el servidor. No se pueden crear dos mensajes con el mismo nombre.
value
<![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]>
Permite definir el valor del token de categoría personalizada. Se puede especificar un mensaje sencillo o incluir parámetros en el mensaje. Los parámetros pueden hacer referencia a un valor y deben incluirse entre dos guiones de subrayado, tal como se indica a continuación:
__type__
Se debe incluir una tabla de localización para cada idioma que soporte la extensión. Por ejemplo, para incluir tokens japoneses, se debe crear una entidad de tabla de localización ja y añadir los tokens necesarios.
Cuando haya terminado de realizar cambios en las tablas de localización, guarde estas en una carpeta denominada LocalizationTables en cualquier lugar del sistema.
Importación de entidades de tabla de localización a la extensión
Después de añadir los tokens necesarios, se pueden importar las entidades de tabla de localización que se han exportado y modificado en la sección anterior:
1. En Eclipse, abra el proyecto de extensión y, a continuación, pulse en File > Import. Se abrirá la ventana Importar.
2. En ThingWorx, seleccione Entities y, a continuación, pulse en Next.
3. En el campo Source, pulse en Browse y seleccione la carpeta LocalizationTables que contiene las entidades de tabla de localización.
4. Seleccione las entidades que desee importar y, a continuación, pulse en Finish.
Las entidades seleccionadas se añaden en la carpeta /Entities/LocalizationTables/ del proyecto de extensión.
Creación de una nueva entidad de cosa y adición de un evento de auditoría
Se pueden definir nuevos eventos añadiendo anotaciones a los métodos de una clase. Los métodos anotados se importan como servicios de ThingWorx que se pueden ejecutar en la plataforma o el mashup en tiempo de ejecución. Para definir los servicios de una entidad de ThingWorx en la extensión, realice los siguientes pasos:
1. En Eclipse, abra el menú ThingWorx y seleccione un tipo de entidad de la lista.
2. Introduzca una carpeta de origen y un paquete.
3. Introduzca un nombre para la entidad y, a continuación, pulse en Next.
4. Seleccione la casilla Editable Extension Entity y, a continuación, pulse en Finish.
Se crea el fichero Java de origen en el paquete especificado en la carpeta /src y el fichero metadata.xml se actualiza automáticamente.
Activación de la auditoría de eventos
Se pueden definir eventos en la extensión que se activen cuando se cumpla un conjunto de condiciones. Los eventos se pueden utilizar para activar servicios con funcionalidad personalizada. Un evento requiere una definición de datos predefinida. En la definición de datos se almacenan datos asociados con el evento, a los que puede acceder una suscripción. Se pueden configurar eventos de ThingWorx para registrar información del subsistema de auditoría. Para activar la auditoría de un evento, se deben asignar los siguientes aspectos al evento:
• auditCategoryKey:customCategoryToken
• auditMessageKey:customMessageToken
Solo se pueden añadir estos aspectos mediante la creación de una extensión de código Java que añada nuevos eventos y luego definir manualmente los aspectos del evento.
En la siguiente sección se proporciona un ejemplo para definir los aspectos de un evento.
Ejemplo: Creación de eventos de auditoría personalizados
En el siguiente código se muestra un ejemplo de una definición de evento de auditoría denominada ExampleAuditedEvent dentro de una plantilla de cosa. El evento tiene definidas propiedades estándar, tales como name, description, category y la instancia implementada de DataShape. Los aspectos necesarios para la auditoría se definen en el valor aspects.
Para obtener más información sobre la definición de eventos, consulte lo siguiente en la documentación de la API de Javadoc de ThingWorx:
com.thingworx.metadata.annotations.ThingworxEventDefinition
En el siguiente código se muestra una definición de evento con los aspectos necesarios para la auditoría:
@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
}
Para añadir nuevos eventos a una entidad de ThingWorx dentro de una extensión, realice los siguientes pasos:
1. En Eclipse, pulse con el botón derecho del ratón en una entidad de la carpeta src y, a continuación, seleccione ThingWorx > Add Event del menú contextual.
2. Introduzca la siguiente información:
◦ Un nombre de evento.
◦ Un nombre de categoría.
◦ La definición de datos implementada para el evento. En el ejemplo proporcionado, el valor se define en EntityReference.
3. Pulse en Finalizar.
Se crea un nuevo evento para la entidad y las anotaciones especificadas se añaden al fichero de origen Java para la entidad de ThingWorx. Por defecto, los aspectos necesarios para la auditoría no están definidos. Para activar la auditoría del nuevo evento, se deben definir los aspectos del origen Java de forma manual de la siguiente manera:
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
• audit.AuditCategory.ExampleCustomCategory: permite especificar el nombre de token de la categoría personalizada que se ha definido en la tabla de localización Default.
• com.example.audit.ExampleCustomMessage: permite especificar el nombre de token del mensaje personalizado que se ha definido en la tabla de localización.
Adición de ficheros JAR de terceros
En la carpeta /lib se incluyen ficheros JAR con clases Java personalizadas escritas para la extensión y otros ficheros JAR de terceros que se requieren para la extensión.
Asegúrese de que el fichero metadata.xml contenga una entrada para cada fichero JAR.
* 
No añada a la extensión ficheros JAR de terceros que ya estén incluidos en ThingWorx Platform.
Creación de la extensión mediante Gradle
Para crear la extensión, cree una tarea de compilación.
1. En la barra de herramientas de Eclipse, pulse en la flecha situada junto al botón Run y seleccione Run Configurations.
2. En el panel de navegación izquierdo, pulse con el botón derecho del ratón en Gradle Task y seleccione New Configuration.
3. Introduzca Build para el nombre de la configuración de la tarea.
En la ficha Gradle Tasks, añada las siguientes tareas:
clean
build
* 
Para añadir la tarea como acceso directo a la lista desplegable Run, seleccione la casilla Run de la ficha Common de la ventana Run Configurations.
4. Seleccione el directorio de trabajo del proyecto y, a continuación, pulse en Apply.
5. En la barra de herramientas, pulse en el comando Run y, a continuación, seleccione Build.
Para versiones anteriores de Eclipse, también se puede utilizar el plug-in de STS de Gradle:
1. En el explorador de paquetes, pulse con el botón derecho del ratón en el fichero build.gradle y seleccione Run As > Gradle (STS) Build. Se abre una ventana de configuración de webhook.
2. En la ficha Gralde Tasks, añada las siguientes tareas:
clean
build
3. Pulse en Ejecutar. Se registra un mensaje de operación correcta en el área de la consola de Eclipse.
El fichero ZIP de la extensión se crea en la carpeta build > Distributions del proyecto. Este fichero ZIP se puede importar como una extensión en ThingWorx Platform.
Creación de la extensión mediante Ant
Si la extensión utiliza Ant como marco de compilación, realice los siguientes pasos:
1. En el explorador de paquetes, pulse con el botón derecho del ratón en el fichero build-extension.xml y seleccione Run As > Ant Build
2. Renueve el proyecto de extensión.
Se crea un fichero ZIP bajo build > Distributions. Este fichero ZIP se puede importar como una extensión en ThingWorx Platform.
Importación de la extensión
1. En Composer, abra el menú Importar/Exportar y, a continuación, seleccione Importar. Se abre el cuadro de diálogo Importar.
2. En Opciones de importación, seleccione Extensión de la lista desplegable.
3. Pulse en Inspeccionar y, a continuación, seleccione el fichero zip de la extensión que se ha creado en la sección anterior.
4. Pulse en Importar.
Se importa la extensión.
Visualización de los cambios de auditoría
En Composer, están visibles los siguientes cambios:
• Se ha añadido una nueva entidad con un evento de auditoría.
• Se han añadido tokens de localización para las categorías y mensajes de auditoría personalizados a las tablas de localización.
Para probar la categoría y mensaje de auditoría personalizados nuevos, ejecute el evento personalizado para la entidad que se ha añadido a través de la extensión. El historial de auditoría se visualiza al ejecutar los servicios QueryAuditHistory o QueryAuditHistoryWithQueryCriteria con los parámetros adecuados. Para obtener más información sobre los parámetros disponibles, consulte el tema correspondiente a la implementación que se está utilizando (persistencia directa o tabla de datos): Búsqueda de datos de auditoría (consultas, persistencia directa) o Datos de auditoría en línea y fuera de línea (tabla de datos).
¿Fue esto útil?