Создание пользовательских категорий аудита с помощью расширения

Расширяемость ThingWorx > Расширения > Создание пользовательских категорий аудита с помощью расширения

Используя пакет ThingWorx Java SDK, можно создавать пользовательские события и сообщения аудита. Несмотря на невозможность добавления пользовательских событий в ThingWorx Composer, существует два способа добавления пользовательских категорий и сообщений аудита.

• Через Composer. Дополнительные сведения см. в разделе Пользовательские категории аудита .

• Путем создания расширения Java на основе ThingWorx Extension SDK, описание которого приведено в данном разделе. Для этого способа также требуется использование таблиц локализации, но создание лексем может быть программным или интерактивным с использованием интерфейса пользователя Composer.

В этом разделе рассматривается процесс создания расширения, предназначенного для добавления пользовательских событий, сообщений и категорий для событий, подлежащих аудиту. Пользовательскую категорию аудита можно добавить путем создания пользовательского расширения ThingWorx, содержащего сущность с требуемыми атрибутами для события аудита.

Для создания расширений на основе Java можно использовать ThingWorx Extension SDK. SDK позволяет получить доступ к поддерживаемым классам ThingWorx Platform и интерфейсам API. Значит, становятся доступными встроенные сервисы и методы, что упрощает создание и управление сущностями в ThingWorx Platform. Дополнительные сведения о доступных классах в платформе см. в документации Javadoc (на английском языке).

Чтобы создать расширение для аудита, выполните следующие шаги.

1. Загрузите и установите необходимое программное обеспечение.

2. Создайте проект нового расширения.

3. Создайте сущности таблиц локализации и определите лексемы.

4. Импортируйте сущности таблиц локализации в расширение.

5. Создайте новую сущности вещи и определите событие аудита.

6. Включите аудит для события.

7. Постройте расширение с помощью Gradle или Ant.

8. Импортируйте расширение.

9. Просмотрите сообщение аудита, инициируя событие.

Перед началом работы

Загрузите следующее программное обеспечение со страницы PTC Software Downloads (Загрузки ПО PTC) для ThingWorx Foundation:

• Подключаемый модуль Eclipse для расширений ThingWorx

• ThingWorx Extension SDK

Чтобы установить подключаемый модуль Eclipse, выполните следующие действия.

1. Откройте Eclipse и выберите рабочую область.

2. Щелкните Help > Install New Software.

Откроется окно Install.

3. Щелкните Добавить.

Откроется диалоговое окно Add Repository.

4. Распакуйте содержимое файла thingworxeclipse-plugin-[версия].zip в папку с тем же именем, а затем выберите папку.

5. В разделе ThingWorx установите флажок ThingWorx Extension Builder, а затем нажмите кнопку Next.

6. Примите лицензионное соглашение, а затем нажмите кнопку Finish. Откроется сообщение безопасности.

7. Нажмите кнопку OK для подтверждения установки.

8. Перезапустите Eclipse после завершения установки.

Чтобы проверить установку, щелкните File > New. Опция ThingWorx Extension Project становится доступной в списке.

Создайте проект нового расширения.

1. В Eclipse щелкните File > New > Project. Откроется окно New Project.

2. Разверните ThingWorx, выберите ThingWorx Extension Project из списка и нажмите кнопку Next.

3. Введите имя для проекта расширения и выберите файл ThingWorxExtension-SDK-[version]-latest.zip, который был загружен ранее.

4. Выберите Gradle или Ant как платформу компоновки для расширения. В проекте создается файл gradle.build или build-extension.xml в зависимости от сделанного выбора.

5. Введите версию пакета и наименование продавца, а затем нажмите кнопку Finish.

Проект появится на панели Package Explorer.

Создание сущностей таблицы локализации и определение лексем

Перед созданием сущности с событием аудита необходимо определить лексемы для пользовательской категории аудита и сообщения. Можно определить лексемы в сущностях таблицы локализации, которые можно включить как часть расширения. При импорте расширения указанные лексемы автоматически добавляются в сущности таблицы локализации в ThingWorx Platform. Можно создать сущность таблицы локализации путем экспорта и изменения XML-шаблона по умолчанию для таблиц локализации.

Чтобы экспортировать таблицу локализации Default для английского языка на платформе, выполните следующие шаги.

1. В Composer откройте меню Импорт/экспорт и выберите Экспорт.

2. В поле Опция экспорта выберите в выпадающем списке В файл.

3. В поле Сущность выберите таблицу локализации Default.

4. Щелкните Экспорт.

После экспорта XML-файла для таблицы локализации Default откройте его в редакторе XML. Можно вручную добавить лексемы в таблицу локализации как элементы Row в разделе Rows. Например:

В следующей таблице описан синтаксис элемента Row для пользовательской категории аудита.

Элемент

Значение

Описание

name

<![CDATA[audit.AuditCategory.ExampleCustomCategory]]>

Часть audit.AuditCategory. определяет префикс для определения наименования пользовательской категории аудита. В этом примере за префиксом идет следующее наименование категории: ExampleCustomCategory

Наименование категории должно быть уникальным для платформы. Нельзя создать две лексемы категории с одинаковым наименованием.

value

Определяет значение лексемы пользовательской категории. Можно включать буквенно-цифровые символы, пробелы и символы подчеркивания. В этом примере значение задается для отображения следующей строки: Example Custom Category EN.

В следующей таблице описан синтаксис элемента Row для пользовательской категории аудита.

Элемент

Значение

Описание

name

<![CDATA[com.example.audit.ExampleCustomMessage]]>

Определяет сообщение, отображаемое для категории аудита. Необходимо определить префикс, а затем указать уникальное наименование сообщения.

Наименование сообщения должно быть уникальным для сервера. Нельзя создать два сообщения с одним и тем же наименованием.

value

<![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]>

Определяет значение лексемы пользовательской категории. Можно указать простое сообщение или включить параметры в сообщение. Параметры могут ссылаться на значение и должны быть заключены в два символа подчеркивания следующим образом:

__type__

Необходимо включить таблицу локализации для каждого языка, поддерживаемого расширением. Например, чтобы включить японские лексемы, необходимо создать сущность таблицы локализации ja и добавить требуемые лексемы.

Завершив внесение изменений в таблицы локализации, сохраните их в папке с именем LocalizationTables в любом месте вашей системы.

Импорт сущностей таблицы локализации в расширение

После добавления требуемых лексем можно импортировать сущности таблицы локализации, которые были экспортированы и изменены в предыдущем разделе.

1. В Eclipse откройте проект расширения, а затем щелкните File > Import. Откроется окно Импорт.

2. В поле ThingWorx выберите Entities и нажмите кнопку Next.

3. В поле Source щелкните Browse и выберите папку LocalizationTables, содержащую сущности таблицы локализации.

4. Выберите сущности, которые нужно импортировать, и нажмите кнопку Finish.

Выбранные сущности будут добавлены в папку /Entities/LocalizationTables/ для проекта расширения.

Создайте новую сущность вещи и определите событие аудита.

Можно определить новые события, добавляя аннотации к методам в классе. Аннотированные методы импортируются как сервисы ThingWorx, которые могут выполняться на платформе или в мэшапе во время выполнения. Чтобы определить сервисы для сущности ThingWorx в расширении, выполните следующие шаги.

1. В Eclipse откройте меню ThingWorx и выберите тип сущности из списка.

2. Введите исходную папку и пакет.

3. Введите имя для функции, а затем щелкните Далее.

4. Установите флажок Editable Extension Entity и щелкните Finish.

Исходный файл Java создается в указанном пакете в папке /src, а файл metadata.xml обновляется автоматически.

Включение аудита событий

Можно определить события в расширении, которые инициируются при выполнении набора условий. События можно использовать для запуска сервисов с пользовательскими функциональными возможностями. Для события требуется предопределенная структура данных. В структуре данных хранятся данные, связанные с событием, доступ к которым можно получить по подписке. Можно настроить события ThingWorx, чтобы записывать в журнал информацию о подсистеме аудита. Чтобы включить аудит для события, необходимо назначить событию следующие аспекты:

• auditCategoryKey:customCategoryToken

• auditMessageKey:customMessageToken

Можно добавить эти аспекты, создав расширение кода Java, в котором добавляются новые события, а затем вручную определите аспекты для события.

В следующем разделе приведен пример определения аспектов для события.

Пример. Создание пользовательских событий аудита

Следующий код демонстрирует пример определения события аудита с наименованием ExampleAuditedEvent в шаблоне вещи. Для события определены стандартные свойства, такие как name, description category и реализованное DataShape. Требуемые аспекты для аудита определяются в значении aspects.

Дополнительные сведения об определении события см. в документации ThingWorx Javadoc API для следующих условий:

com.thingworx.metadata.annotations.ThingworxEventDefinition

Следующий код демонстрирует определение события с необходимыми аспектами для аудита.

@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
}

Можно добавить новые события в сущность ThingWorx в расширении, выполнив следующие шаги.

1. В Eclipse щелкните правой кнопкой мыши сущность в папке src и выберите в контекстном меню ThingWorx > Add Event.

2. Введите следующую информацию:

◦ Наименование события

◦ Наименование категории

◦ Реализованный профиль данных для события. В приведенном примере задается значение EntityReference.

3. Нажмите кнопку Finish.

Для сущности создается новое событие, и указанные аннотации добавляются в исходный файл Java для сущности ThingWorx. По умолчанию требуемые аспекты для аудита не определены. Чтобы включить аудит для нового события, необходимо вручную определить аспекты в источнике Java следующим образом:

aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}

• audit.AuditCategory.ExampleCustomCategory - указывает наименование лексемы для пользовательской категории, определенной в таблице локализации Default.

• com.example.audit.ExampleCustomMessage - указывает наименование лексемы для пользовательского сообщения, определенного в таблице локализации.

Добавление сторонних JAR-файлов

Папка /lib содержит JAR-файлы с пользовательскими классами Java, написанными для расширения, а также дополнительные JAR-файлы сторонних изготовителей, требуемые для расширения.

Убедитесь, что файл metadata.xml содержит запись для каждого JAR-файла.

Не добавляйте в свое расширение сторонние JAR-файлы, которые уже включены в платформу ThingWorx.

Построение расширения с помощью Gradle

Чтобы построить расширение, создайте задание построения.

1. На панели инструментов Eclipse щелкните стрелку рядом с кнопкой Run и выберите Run Configurations.

2. На левой навигационной панели щелкните правой кнопкой мыши Gradle Task и выберите New Configuration.

3. Введите Build для наименования конфигурации задания.

На вкладке Gradle Tasks добавьте следующие задания:

clean
build

Можно добавить задание как ярлык в выпадающий список Run, установив флажок Run на вкладке Common в окне Run Configurations.

4. Выберите рабочую папку для проекта и щелкните Apply.

5. На панели инструментов щелкните команду Run, а затем выберите Build.

Для более ранних версий Eclipse можно также использовать подключаемый модуль Gradle STS:

1. В окне проводника пакетов щелкните правой кнопкой мыши файл build.gradle и выберите Run As > Gradle (STS) Build. Откроется окно конфигурации.

2. На вкладке Gradle Tasks добавьте следующие задания:

clean
build

3. Щелкните Выполнение. Сообщение об успешном выполнении регистрируется в области консоли Eclipse.

ZIP-файл расширения создается в папке build > Distributions в проекте. Этот ZIP-файл можно импортировать как расширение в ThingWorx Platform.

Построение расширения с помощью Ant

Если расширение использует Ant как платформу построения, выполните следующие шаги.

1. В окне проводника пакетов щелкните правой кнопкой мыши файл build-extension.xml и выберите Run As > Ant Build.

2. Обновите свой проект расширения.

ZIP-файл создается в разделе build > Distributions. Этот ZIP-файл можно импортировать как расширение в ThingWorx Platform.

Импорт расширения

1. В Composer откройте меню Импорт/экспорт и выберите Импорт. Откроется диалоговое окно Импорт.

2. В разделе Опция импорта выберите Расширение в выпадающем списке.

3. Щелкните Обзор, затем выберите ZIP-файл расширения, который был создан в предыдущем разделе.

4. Щелкните Импорт.

Расширение импортируется.

Просмотр изменений аудита

В Composer видимыми являются следующие изменения.

• Добавляется новая сущность с событием аудита.

• В таблицы локализации добавляются лексемы локализации для пользовательских категорий аудита и сообщений.

Чтобы проверить новую пользовательскую категорию аудита и сообщение, выполните пользовательское событие для сущности, которая была добавлена с помощью расширения. Можно просмотреть историю аудита, выполнив сервис QueryAuditHistory или QueryAuditHistoryWithQueryCriteria с подходящими параметрами. Дополнительные сведения о доступных параметрах см. в разделе, посвященном используемой реализации (непосредственное хранение или таблица данных): Поиск данных аудита (запросы, непосредственное сохранение) или Интерактивные и автономные данные аудита (таблица данных).

Было ли это полезно?