Estendibilità di ThingWorx > Estensioni > Creazione di categorie di verifica personalizzate mediante un'estensione
Creazione di categorie di verifica personalizzate mediante un'estensione
Utilizzando ThingWorx Java SDK è possibile creare messaggi ed eventi di verifica personalizzati. Sebbene non sia possibile aggiungere eventi personalizzati tramite ThingWorx Composer, esistono due modi per aggiungere categorie e messaggi di verifica del cliente:
• Da Composer. Per ulteriori informazioni, vedere Categorie di verifica personalizzate .
• Creando un'estensione Java basata su ThingWorx Extension SDK, illustrata in questo argomento. Questo metodo richiede anche l'utilizzo delle tabelle di localizzazione, ma la creazione dei token può essere programmatico o interattivo tramite l'interfaccia utente di Composer.
Questo argomento illustra il processo di creazione di un'estensione che aggiunge eventi, messaggi e categorie di verifica personalizzati per gli eventi sottoposti a verifica. È possibile aggiungere una categoria di verifica personalizzata creando un'estensione ThingWorx personalizzata che includa un'entità con gli attributi obbligatori per l'evento Verifica.
È possibile utilizzare ThingWorx Extension SDK per creare estensioni basate su Java. L'SDK consente di accedere alle classi e alle API ThingWorx Platform supportate. In questo modo si espongono i metodi e i servizi incorporati, semplificando la creazione e la gestione delle entità in ThingWorx Platform. Per ulteriori informazioni sulle classi disponibili nella piattaforma, fare riferimento alla documentazione di Javadoc.
Per creare un'estensione per la verifica, attenersi alla procedura descritta di seguito.
Informazioni preliminari
Scaricare il software seguente dalla pagina PTC Software Downloads per ThingWorx Foundation.
• Plug-in Eclipse per le estensioni ThingWorx
• ThingWorx Extension SDK
Per installare il plug-in Eclipse, attenersi alla procedura descritta di seguito.
1. Aprire Eclipse e scegliere un workspace.
2. Fare clic su Help > Install New Software.
Viene visualizzata la finestra Install.
3. Fare clic su Add.
Viene visualizzata la finestra di dialogo Add Repository.
4. Estrarre il contenuto del file thingworxeclipse-plugin-[versione].zip in una cartella con lo stesso nome, quindi selezionare la cartella.
5. Sotto ThingWorx selezionare la casella di controllo ThingWorx Extension Builder, quindi fare clic su Next.
6. Accettare il contratto di licenza, quindi fare clic su Finish. Viene visualizzato un messaggio relativo alla sicurezza.
7. Fare clic su OK per confermare l'installazione.
8. Al termine dell'installazione, riavviare Eclipse.
L'installazione è andata a buon fine se, facendo clic su File > New, nell'elenco è presente l'opzione ThingWorx Extension Project.
Creazione di un nuovo progetto di estensione
1. In Eclipse fare clic su File > New > Project. Viene visualizzata la finestra New project.
2. Espandere ThingWorx, selezionare ThingWorx Extension Project nell'elenco, quindi fare clic su Next.
3. Immettere un nome per il progetto di estensione e selezionare il file ThingWorxExtension-SDK-[version]-latest.zip scaricato in precedenza.
4. Selezionare Gradle o Ant come framework di creazione per l'estensione. A seconda della selezione, viene creato un file gradle.build o build-extension.xml per il progetto.
5. Immettere una versione del package e un nome fornitore, quindi fare clic su Finish.
Il progetto è ora presente nell'elenco nel riquadro Package Explorer.
Creazione di entità Tabella di localizzazione e definizione dei token
Prima di creare l'entità con l'evento Verifica, è necessario definire i token per la categoria e il messaggio di verifica personalizzati. È possibile definire i token all'interno delle entità Tabella di localizzazione da includere come parte dell'estensione. Quando si importa l'estensione, i token specificati vengono aggiunti automaticamente alle entità Tabella di localizzazione in ThingWorx Platform. È possibile creare un'entità Tabella di localizzazione esportando e modificando il modello XML di default per le tabelle di localizzazione.
Per esportare la tabella di localizzazione Default per l'inglese nella piattaforma, attenersi alla procedura descritta di seguito.
1. In Composer aprire il menu Importazione/Esportazione, quindi selezionare Esportazione.
2. In Opzione di esportazione selezionare In file nell'elenco a discesa.
3. Nel campo Entità selezionare la tabella di localizzazione Default.
4. Fare clic su Esporta.
Dopo avere esportato il file XML per la tabella di localizzazione Default, aprirlo come editor XML. È possibile aggiungere manualmente i token alla tabella di localizzazione come elementi Row nella sezione Rows. Ad esempio:
<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>
Nella tabella riportata di seguito viene descritta la sintassi dell'elemento Row per la categoria di verifica personalizzata.
Elemento
Valore
Descrizione
name
<![CDATA[audit.AuditCategory.ExampleCustomCategory]]>
La parte audit.AuditCategory. specifica il prefisso per definire un nome di categoria di verifica personalizzata. In questo esempio il prefisso è seguito dal nome di categoria seguente: ExampleCustomCategory
* 
Il nome della categoria deve essere univoco per la piattaforma. Non è possibile creare due token di categoria con lo stesso nome.
value
<value><![CDATA[ExampleCustomCategoryEN]]></value>
Definisce il valore del token della categoria personalizzata. È possibile includere caratteri alfanumerici, spazi e tratti di sottolineatura. Nell'esempio il valore viene impostato in modo da visualizzare la stringa seguente: Example Custom Category EN.
Nella tabella riportata di seguito viene descritta la sintassi dell'elemento Row per il messaggio di verifica personalizzato.
Elemento
Valore
Descrizione
name
<![CDATA[com.example.audit.ExampleCustomMessage]]>
Definisce il messaggio da visualizzare per la categoria di verifica. È necessario definire un prefisso e quindi specificare un nome univoco per il messaggio.
* 
Il nome del messaggio deve essere univoco per il server. Non è possibile creare due messaggi con lo stesso nome.
value
<![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]>
Definisce il valore del token della categoria personalizzata. È possibile specificare un messaggio semplice o includere parametri. I parametri possono fare riferimento a un valore e devono essere racchiusi tra due tratti di sottolineatura come segue:
__type__
È necessario includere una tabella di localizzazione per ogni lingua supportata dall'estensione. Ad esempio, per includere token giapponesi, è necessario creare un'entità Tabella di localizzazione ja e aggiungere i token necessari.
Una volta completate le modifiche alle tabelle di localizzazione, salvarle in una cartella denominata LocalizationTables in una posizione qualsiasi nel sistema.
Importazione di entità Tabella di localizzazione nell'estensione
Dopo avere aggiunto i token necessari, è possibile importare le entità Tabella di localizzazione esportate e modificate nella sezione precedente.
1. In Eclipse aprire il progetto di estensione, quindi fare clic su File > Import. Viene visualizzata la finestra Import.
2. Sotto ThingWorx selezionare Entity, quindi fare clic su Next.
3. Nel campo Source fare clic su Browse e selezionare la cartella LocalizationTables che contiene le entità Tabella di localizzazione.
4. Selezionare le entità che si desidera importare, quindi fare clic su Finish.
Le entità selezionate vengono aggiunte nella cartella /Entities/LocalizationTables/ del progetto di estensione.
Creazione di una nuova entità Oggetto e aggiunta di un evento Verifica
È possibile definire nuovi eventi aggiungendo annotazioni ai metodi all'interno di una classe. I metodi con annotazioni vengono importati come servizi ThingWorx che possono essere eseguiti nella piattaforma o nel mashup in fase di esecuzione. Per definire i servizi per un'entità ThingWorx nell'estensione, attenersi alla procedura descritta di seguito.
1. In Eclipse aprire il menu ThingWorx e selezionare un tipo di entità nell'elenco.
2. Immettere una cartella di origine e un package.
3. Immettere un nome per l'entità, quindi fare clic su Next.
4. Selezionare la casella di controllo Editable Extension Entity, quindi fare clic su Finish.
Il file di origine Java viene creato nel package specificato nella cartella /src e il file metadata.xml viene aggiornato automaticamente.
Attivazione della verifica per gli eventi
È possibile definire gli eventi nell'estensione che vengono attivati quando viene soddisfatta una serie di condizioni. È possibile utilizzare gli eventi per attivare i servizi con funzionalità personalizzate. Un evento richiede una data shape predefinita. La data shape memorizza i dati associati all'evento a cui può accedere una sottoscrizione. È possibile configurare gli eventi ThingWorx per registrare le informazioni per il sottosistema Verifica. Per attivare la verifica per un evento, è necessario assegnare all'evento gli aspetti seguenti:
• auditCategoryKey:customCategoryToken
• auditMessageKey:customMessageToken
È possibile aggiungere questi aspetti solo creando un'estensione del codice Java che aggiunge nuovi eventi e quindi definire manualmente gli aspetti dell'evento.
La sezione successiva fornisce un esempio di definizione degli aspetti per un evento.
Esempio: creazione di eventi Verifica personalizzati
Il codice riportato di seguito mostra un esempio di definizione di un evento Verifica denominato ExampleAuditedEvent all'interno di un modello di oggetto. Per l'evento sono state definite proprietà standard, quali name, description, category e la proprietà DataShape implementata. Gli aspetti necessari per la verifica sono definiti nel valore aspects.
Per ulteriori informazioni sulla definizione dell'evento, consultare la documentazione dell'API Javadoc ThingWorx per i seguenti elementi:
com.thingworx.metadata.annotations.ThingworxEventDefinition
Il codice seguente mostra una definizione di evento con gli aspetti necessari per la verifica:
@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
}
È possibile aggiungere nuovi eventi a un'entità ThingWorx all'interno di un'estensione attenendosi alla procedura descritta di seguito.
1. In Eclipse fare clic con il pulsante destro del mouse su un'entità nella cartella src, quindi selezionare ThingWorx > Add Event nel menu di scelta rapida.
2. Immettere le informazioni elencate di seguito.
◦ Un nome di evento
◦ Un nome di categoria
◦ La data shape implementata per l'evento. Nell'esempio specificato il valore è impostato su EntityReference
3. Fare clic su Finish.
Viene creato un nuovo evento per l'entità e le annotazioni specificate vengono aggiunte al file di origine Java per l'entità ThingWorx. Per default, gli aspetti necessari per la verifica non sono definiti. Per attivare la verifica per il nuovo evento, è necessario definire manualmente gli aspetti all'interno dell'origine Java, come indicato di seguito.
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
• audit.AuditCategory.ExampleCustomCategory - Specifica il nome del token per la categoria personalizzata definita nella tabella di localizzazione Default.
• com.example.audit.ExampleCustomMessage - Specifica il nome del token per il messaggio personalizzato definito nella tabella di localizzazione.
Aggiungere file JAR di terze parti
La cartella /lib contiene file JAR con classi Java personalizzate scritti per l'estensione, nonché file JAR di terze parti aggiuntivi richiesti dall'estensione.
Assicurarsi che il file metadata.xml contenga una voce per ogni file JAR.
* 
Non aggiungere all'estensione file JAR di terze parti già inclusi nella piattaforma ThingWorx.
Creazione dell'estensione mediante Gradle
Per creare l'estensione, definire un task di creazione.
1. Sulla barra degli strumenti di Eclipse fare clic sulla freccia accanto al pulsante Run e selezionare Run Configurations.
2. Nel riquadro di navigazione a sinistra fare clic con il pulsante destro del mouse su Gradle Task e scegliere New Configuration.
3. Immettere Build come nome di configurazione del task.
Nella scheda Gradle Tasks aggiungere i task riportati di seguito.
clean
build
* 
È possibile aggiungere il task al menu a discesa Run come collegamento selezionando la casella di controllo Run nella scheda Common all'interno della finestra Run Configurations.
4. Selezionare la directory di lavoro per il progetto, quindi fare clic su Apply.
5. Sulla barra degli strumenti fare clic sul comando Run, quindi selezionare Build.
Per le versioni precedenti di Eclipse, è possibile utilizzare anche il plug-in Gradle STS.
1. In Package Explorer fare clic con il pulsante destro del mouse sul file build.gradle e scegliere Run As > Gradle (STS) Build. Viene visualizzata una finestra di configurazione.
2. Nella scheda Gradle Tasks aggiungere i task riportati di seguito.
clean
build
3. Fare clic su Esegui. Nell'area della console Eclipse viene registrato un messaggio di completamento.
Nella cartella build > Distributions del progetto viene creato il file ZIP dell'estensione. È possibile importare il file ZIP come estensione in ThingWorx Platform.
Creazione dell'estensione mediante Ant
Se l'estensione utilizza Ant come framework di creazione, attenersi alla procedura descritta di seguito.
1. In Package Explorer fare clic con il pulsante destro del mouse sul file build-extension.xml e scegliere Run As > Ant Build.
2. Aggiornare il progetto di estensione.
In build > Distributions viene creato un file ZIP. È possibile importare il file ZIP come estensione in ThingWorx Platform.
Importazione dell'estensione
1. In Composer aprire il menu Importazione/Esportazione, quindi selezionare Importazione. Viene visualizzata la finestra di dialogo Importazione.
2. In Opzione di importazione selezionare Estensione nell'elenco a discesa.
3. Fare clic su Sfoglia, quindi selezionare il file ZIP di estensione creato nella sezione precedente.
4. Fare clic su Importa.
L'estensione viene importata.
Visualizzazione delle modifiche di verifica
In Composer sono visibili le modifiche riportate di seguito.
• Viene aggiunta una nuova entità con un evento Verifica.
• Alle tabelle di localizzazione vengono aggiunti token di localizzazione per le categorie e i messaggi di verifica personalizzati.
Per testare il nuovo messaggio e la nuova categoria di verifica personalizzati, eseguire l'evento personalizzato per l'entità aggiunta tramite l'estensione. È possibile visualizzare la cronologia di verifica eseguendo il servizio QueryAuditHistory o QueryAuditHistoryWithQueryCriteria con i parametri appropriati. Per ulteriori informazioni sui parametri disponibili, vedere l'argomento relativo all'implementazione in uso (Persistenza diretta o Tabella dati): Ricerca dei dati di verifica (interrogazioni, persistenza diretta) o Dati di verifica online e non in linea (tabella dati).
È stato utile?