To Connect to a Thing from an External Analysis Tool
Prerequisites
Ensure that you have the following prerequisites set:
• A thing must exist in your ThingWorx instance
• A suitable ThingWorx event to trigger the analysis
It is likely that you have the ThingWorx event on the thing that you plan to connect to, or on the thing template or the thing shape that the thing implements.
Note the following points:
|
|
• You cannot run an active analysis on a thing for the same event or alert by using the same model on multiple connections or clients because this would overwrite the same properties.
• If the event does not get any inputs for 120 seconds, the client disconnects. If the agent crashes, the simulation jobs remain in the INPROCESS state, and once the agent is up and running, the INPROCESS job moves to the FAILED state, and a new simulation job starts.
• Analysis tools should implement session storage to remember choices made by users. This will let users make selections easily for the next session while using the Analytics Manager services.
|
Steps
The following section provides high-level steps and guidelines to connect to a thing from your analysis tool:
1. Configure connection to ThingWorx
Configure the appropriate parameter in the configuration file of your analysis agent to connect to the ThingWorx instance.
|
|
Ensure that you provide appropriate credentials or an application key to authenticate with the ThingWorx server.
|
2. Run the analysis agent
Run the agent either in the standalone or embedded mode.
Once the agent runs successfully, you should be able to successfully connect to ThingWorx.
3. Find the thing in ThingWorx
Use the ThingWorx services to find the thing on which you want to perform analysis.
4. Use an analysis event in Analytics Manager
The following table provides a list of steps that you need to perform to obtain an analysis event to perform analysis.
|
|
Ensure that you follow the steps in order. If you find an analysis event after Step 1, skip the rest of the steps.
|
|
Steps
|
Run Services
|
|
1. Search for an existing analysis event.
|
Run the FilterAnalysisEvents service to filter a list of events that have been already created on the thing that you have been connected to. You might get an empty result set, if the analysis events defined on the thing are in the ‘enabled’ state.
Once you obtain an event or a list of events, you can select the event on which you want to run the analysis.
|
|
2. Search for an existing analysis event that has been created on the thing template or thing shape that is implemented by the thing, and clone the analysis event.
|
• Run the FilterAnalysisEventForCloning service to filter out any events that have been defined on the thing, thing template, or thing shape. Only those events that are defined on thing templates and thing shapes that implement this thing are displayed in the results.
|
|
After you select the analysis event for cloning, copy the value of the key field of the selected event.
|
• Run the CloneAnalysisEvent service to clone the analysis event. Paste the value of the key field as the value of the eventId parameter of the CloneAnalysisEvent service.
|
|
3. If you do not find an existing analysis event that can be used or cloned, create an analysis event.
|
|
Do not create an analysis event unless required. Try to use an existing event.
|
|
Run the CreateAnalysisEvent service to create an analysis event.
|
5. Map inputs and results
◦ Use the
CreateAutoMappingFromEntity and the
CreateAutoMappingFromEvent services to automatically map inputs and results to the input and result data shapes, respectively. For more information, see
Services for Managing Data Mapping.
◦ Use the
IsResultMappingAvailableForEventId service to configure mapping of results back to the thing. For more information, see
Services for Managing Events.
6. Start and stop analysis
Use the
EnableAnalysisEvent and the
DisableAnalysisEvent services to start and stop analysis, respectively. For more information, see
Services for Managing Events.
If you have created a replay on your analysis event, use the
PauseReplay and
ResumeReplay services to start and stop analysis. For more information, see
Services for Managing Replays.
7. Clean up data
After you have completed the analysis, use the DeleteAnalysisEvent service if you have cloned an event, or use the DisableAnalysisEvent service to disable the event.
You can perform cleanup of data that was created in Analytics Manager and ThingWorx.
