확장을 사용하여 사용자 정의 감사 카테고리 만들기
ThingWorx Java SDK를 사용하여 사용자 정의 감사 이벤트 및 메시지를 생성할 수 있습니다. ThingWorx Composer를 통해 사용자 정의 이벤트를 추가할 수는 없지만 사용자 정의 감사 카테고리 및 메시지는 두 가지 방법으로 추가합니다.
• Composer를 통해. 자세한 내용은 사용자 정의 감사 카테고리 를 참조하십시오.
• 이 항목에서 설명하는 ThingWorx Extension SDK를 기반으로 Java 확장을 생성합니다. 이 방법을 사용하려면 로컬리제이션 테이블도 사용해야 하지만 Composer 사용자 인터페이스를 통해 토큰을 프로그래밍 방식 또는 대화식으로 생성할 수 있습니다.
이 항목에서는 감사된 이벤트에 대한 사용자 정의 감사 이벤트, 메시지 및 카테고리를 추가하는 확장을 생성하는 프로세스에 대해 설명합니다. 감사 이벤트에 대한 필수 속성이 있는 엔티티가 포함된 사용자 정의 ThingWorx 확장을 생성하여 사용자 정의 감사 카테고리를 추가할 수 있습니다.
Java 기반 확장은 ThingWorx Extension SDK를 사용하여 작성할 수 있습니다. SDK를 사용하면 지원되는 ThingWorx Platform 클래스 및 API에 액세스할 수 있습니다. 이 경우 기본 제공 서비스 및 메소드가 노출되므로 ThingWorx Platform에서 더 쉽게 엔티티를 만들고 관리할 수 있습니다. 플랫폼에서 사용할 수 있는 클래스에 대한 자세한 내용은 Javadoc 설명서를 참조하십시오.
감사를 위한 확장을 작성하려면 다음 단계를 수행하십시오.
8. 확장을 가져옵니다.
시작하기 전에
ThingWorx Foundation에 대한 PTC 소프트웨어 다운로드 페이지에서 다음 소프트웨어를 다운로드합니다.
• ThingWorx Extensions용 Eclipse Plugin
• ThingWorx Extension SDK
Eclipse 플러그인을 설치하려면 다음을 수행하십시오.
1. Eclipse를 열고 작업공간을 선택합니다.
2. > 를 클릭합니다.
설치 창이 열립니다.
3. 추가를 클릭합니다.
저장소 추가 대화 상자가 열립니다.
4. thingworxeclipse-plugin-[버전].zip 파일의 콘텐츠를 동일한 이름의 폴더에 추출한 다음 해당 폴더를 선택합니다.
5. ThingWorx에서 ThingWorx Extension Builder 확인란을 선택하고 다음을 클릭합니다.
6. 사용권 계약을 수락한 다음 마침을 클릭합니다. 보안 메시지가 열립니다.
7. 확인을 클릭하여 설치를 확인합니다.
8. 설치가 완료되면 Eclipse를 다시 시작합니다.
> 를 클릭하여 설치를 확인할 수 있습니다. 목록에서 ThingWorx Extension 프로젝트 옵션을 사용할 수 있습니다.
새 확장 프로젝트 만들기
1. Eclipse에서 > > 를 클릭합니다. 새 프로젝트 창이 열립니다.
2. ThingWorx를 확장하고 목록에서 ThingWorx Extension 프로젝트를 선택한 후 다음을 클릭합니다.
3. 확장 프로젝트의 이름을 입력하고 앞서 다운로드한 ThingWorxExtension-SDK-[version]-latest.zip 파일을 선택합니다.
4. Gradle 또는 Ant를 확장의 빌드 프레임워크로 선택합니다. 이렇게 하면 선택한 옵션에 따라 프로젝트에 대해 gradle.build 또는 build-extension.xml 파일이 생성됩니다.
5. 패키지 버전 및 공급업체 이름을 입력한 다음 마침을 클릭합니다.
이제 프로젝트가 패키지 탐색기 창에 나열됩니다.
로컬리제이션 테이블 엔티티 만들기 및 토큰 정의
감사 이벤트를 사용하여 엔티티를 만들기 전에 사용자 정의 감사 카테고리 및 메시지에 대한 토큰을 정의해야 합니다. 로컬리제이션 테이블 엔티티 내에 확장의 일부로 포함할 수 있는 토큰을 정의할 수 있습니다. 확장을 가져올 때 지정된 토큰이 ThingWorx Platform의 로컬리제이션 테이블에 자동으로 추가됩니다. 로컬리제이션 테이블에 대한 기본 XML 템플릿을 내보내고 수정하여 로컬리제이션 테이블을 만들 수 있습니다.
플랫폼에서 영어에 대한 Default 로컬리제이션 테이블을 내보내려면 다음 단계를 수행하십시오.
1. Composer에서 가져오기/내보내기 메뉴를 연 다음 내보내기를 선택합니다.
2. 내보내기 옵션 아래의 드롭다운 목록에서 파일로를 선택합니다.
3. 엔티티 필드에서 Default 로컬리제이션 테이블을 선택합니다.
4. 내보내기를 클릭합니다.
Default 로컬리제이션 테이블에 대한 XML 파일을 내보낸 후 XML 편집기에서 엽니다. 토큰을 로컬리제이션 테이블의 Rows 섹션 아래에 Row 요소로 수동으로 추가할 수 있습니다. 예를 들면 다음과 같습니다.
<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>
<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>
다음 표에서는 사용자 정의 감사 카테고리에 대한 Row 요소의 구문에 대해 설명합니다.
|
요소
|
값
|
설명
|
||
|---|---|---|---|---|
|
name
|
<![CDATA[audit.AuditCategory.ExampleCustomCategory]]>
|
audit.AuditCategory. 부분은 사용자 정의 감사 카테고리 이름을 정의하는 접두사를 지정합니다. 이 예에서 접두사 뒤에는 ExampleCustomCategory라는 카테고리 이름이 나옵니다.
|
||
|
value
|
<value><![CDATA[ExampleCustomCategoryEN]]></value>
|
사용자 정의 카테고리 토큰의 값을 정의합니다. 영숫자, 공백 및 밑줄을 포함할 수 있습니다. 이 예에서는 다음 문자열을 표시하도록 값이 설정됩니다. Example Custom Category EN
|
다음 표에서는 사용자 정의 감사 메시지에 대한 Row 요소의 구문에 대해 설명합니다.
|
요소
|
값
|
설명
|
||
|---|---|---|---|---|
|
name
|
<![CDATA[com.example.audit.ExampleCustomMessage]]>
|
감사 카테고리에 대해 표시할 메시지를 정의합니다. 접두사를 정의한 다음 메시지에 고유한 이름을 제공해야 합니다.
|
||
|
value
|
<![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]>
|
사용자 정의 카테고리 토큰의 값을 정의합니다. 간단한 메시지를 지정하거나 메시지에 매개 변수를 포함할 수 있습니다. 매개 변수는 값을 참조할 수 있으며 다음과 같이 두 개의 밑줄로 묶어야 합니다.
__type__
|
확장에서 지원하는 각 언어에 대한 로컬리제이션 테이블을 포함해야 합니다. 예를 들어, 일본어 토큰을 포함하려면 ja 로컬리제이션 테이블 엔티티를 만들고 필요한 토큰을 추가해야 합니다.
로컬리제이션 테이블에 대한 변경이 완료되면 시스템의 임의 위치에서 LocalizationTables라는 이름의 폴더에 저장합니다.
로컬리제이션 테이블 엔티티를 확장으로 가져오기
필요한 토큰을 추가한 후 이전 단원에서 내보내고 수정한 로컬리제이션 테이블 엔티티를 가져올 수 있습니다.
1. Eclipse에서 확장 프로젝트를 연 다음 > 를 클릭합니다. 가져오기 창이 열립니다.
2. ThingWorx에서 엔티티를 선택한 후 다음을 클릭합니다.
3. 소스 필드에서 찾아보기를 클릭하고 로컬리제이션 테이블 엔티티가 포함된 LocalizationTables 폴더를 선택합니다.
4. 가져올 엔티티를 선택한 다음 마침을 클릭합니다.
선택한 엔티티가 확장 프로젝트의 /Entities/LocalizationTables/ 폴더 아래에 추가됩니다.
새 사물 엔티티 만들기 및 감사 이벤트 추가
클래스 내의 메소드에 주석을 추가하여 새 이벤트를 정의할 수 있습니다. 주석이 추가된 메소드는 ThingWorx 서비스로 가져오게 되며 이 서비스는 실행 시간에 플랫폼이나 매쉬업에서 실행될 수 있습니다. 확장에서 ThingWorx 엔티티에 대해 서비스를 정의하려면 다음 단계를 수행하십시오.
1. Eclipse에서 ThingWorx 메뉴를 열고 목록에서 엔티티 유형을 선택합니다.
2. 소스 폴더와 패키지를 입력합니다.
3. 엔티티의 이름을 입력한 후 다음을 클릭합니다.
4. 편집 가능한 확장 엔티티 확인란을 선택한 다음 마침을 클릭합니다.
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
}
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 폴더의 엔티티를 마우스 오른쪽 버튼으로 클릭한 다음 상황에 맞는 메뉴에서 > 를 선택합니다.
2. 다음 정보를 입력합니다.
◦ 이벤트 이름
◦ 카테고리 이름
◦ 이벤트에 대해 구현된 데이터 셰이프입니다. 제공된 예에서는 값이 EntityReference로 설정되어 있습니다.
3. 마침을 클릭합니다.
엔티티에 대해 새 이벤트가 생성되고 지정된 주석이 ThingWorx 엔티티에 대한 Java 소스 파일에 추가됩니다. 기본적으로 감사에 필요한 측면은 정의되지 않습니다. 새 이벤트에 대해 감사를 사용하려면 다음과 같이 Java 소스 내에 수동으로 측면을 정의해야 합니다.
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
• audit.AuditCategory.ExampleCustomCategory - 사용자가 Default 로컬리제이션 테이블에 정의한 사용자 정의 카테고리에 대한 토큰 이름을 지정합니다.
• com.example.audit.ExampleCustomMessage - 사용자가 로컬리제이션 테이블에 정의한 사용자 정의 메시지에 대한 토큰 이름을 지정합니다.
타사 JAR 파일 추가
/lib 폴더에는 확장을 위해 작성된 사용자 정의 Java 클래스가 있는 JAR 파일과 확장에 필요한 추가 타사 JAR 파일이 포함되어 있습니다.
metadata.xml 파일에 각 JAR 파일에 대한 엔트리가 포함되어 있는지 확인하십시오.
 |
ThingWorx Platform에 이미 포함되어 있는 타사 JAR 파일은 확장에 추가하지 마십시오.
|
Gradle을 사용하여 확장 빌드
확장을 빌드하려면 빌드 작업을 만듭니다.
1. Eclipse 도구 모음에서 실행 버튼 옆에 있는 화살표를 클릭하고 실행 구성을 선택합니다.
2. 왼쪽 탐색 창에서 Gradle 작업을 마우스 오른쪽 버튼으로 클릭하고 새 구성을 선택합니다.
3. 작업 구성 이름에 대해 Build를 입력합니다.
Gradle 작업 탭에서 다음 작업을 추가합니다.
clean
build
build
|
|
실행 구성 창 내의 공통 탭에서 실행 확인란을 선택하여 작업을 실행 드롭다운에 바로 가기로 추가할 수 있습니다.
|
4. 프로젝트의 작업 디렉터리를 선택한 다음 적용을 클릭합니다.
5. 도구 모음에서 실행 명령을 클릭한 다음 빌드를 선택합니다.
이전 버전 Eclipse의 경우 Gradle STS 플러그인을 사용할 수도 있습니다.
1. 패키지 탐색기에서 build.gradle 파일을 마우스 오른쪽 버튼으로 클릭하고 > 를 선택합니다. 구성 창이 열립니다.
2. Gradle 작업 탭에서 다음 작업을 추가합니다.
clean
build
build
3. 실행을 클릭합니다. Eclipse 콘솔 영역에 성공 메시지가 로깅됩니다.
프로젝트의 > 폴더에 확장 ZIP 파일이 생성됩니다. 이 ZIP 파일을 ThingWorx Platform에 확장으로 가져올 수 있습니다.
Ant를 사용하여 확장 빌드
확장에서 Ant를 빌드 프레임워크로 사용하는 경우 다음 단계를 수행하십시오.
1. 패키지 탐색기에서 build-extension.xml 파일을 마우스 오른쪽 버튼으로 클릭하고 > 를 선택합니다.
2. 확장 프로젝트를 새로 고칩니다.
> 에 ZIP 파일이 생성됩니다. 이 ZIP 파일을 ThingWorx Platform에 확장으로 가져올 수 있습니다.
확장 가져오기
1. Composer에서 가져오기/내보내기 메뉴를 연 다음 가져오기를 선택합니다. Import 대화 상자가 열립니다.
2. 가져오기 옵션 아래의 드롭다운 목록에서 확장을 선택합니다.
3. 찾아보기를 클릭한 다음 이전 단원에서 만든 확장 ZIP 파일을 선택합니다.
4. 가져오기를 클릭합니다.
확장을 가져옵니다.
감사 변경 사항 보기
Composer에서 다음 변경 사항이 표시됩니다.
• 감사 이벤트가 있는 새 엔티티가 추가됩니다.
• 사용자 정의 감사 카테고리 및 메시지에 대한 로컬리제이션 토큰이 로컬리제이션 테이블에 추가됩니다.
새 사용자 정의 감사 카테고리 및 메시지를 테스트하려면 확장을 통해 추가한 엔티티에 대해 사용자 정의 이벤트를 실행합니다. 적절한 매개 변수와 함께 QueryAuditHistory 또는 QueryAuditHistoryWithQueryCriteria 서비스를 실행하여 감사 기록을 확인합니다. 사용 가능한 매개 변수에 대한 자세한 내용은 사용 중인 구현(직접 지속성 또는 데이터 테이블)에 대한 감사 데이터 검색(질의, 직접 지속성) 또는 온라인 및 오프라인 감사 데이터(데이터 테이블) 항목을 참조하십시오.