In this blog I will be testing with the WindchillSwaggerConnector, but most of the steps also apply to the generic SwaggerConnector.
Overview
The WindchillSwaggerConnector enables the connection to the Windchill REST endpoints through the Swagger (OpenAPI) specification. It is a specialized implementation of the SwaggerConnector. See Integration Connectors for documentation.
It relies on three components :
- Integration Runtime : microservice that runs outside of ThingWorx and has to be deployed separately, it uses Web Socket to communicate with the ThingWorx platform (similar to EMS).
- Integration Subsystem : available by default in 7.4 (not extension needed)
- Integration Connectors (WindchillSwaggerConnector) : available by default in 7.4 (not extension needed)
Currently, in 7.4, the WindchillSwaggerConnector does not support SSO with Windchill (it is more targeted for a "gateway type" integration). Note that the PTC Navigate PDM apps are using the WindchillConnector and not the WindchillSwaggerConnector.
Integration Runtime microservice setup
The ThingWorx Integration Runtime is a microservice that runs outside of ThingWorx. It can run on the ThingWorx server or a remote machine. It is available for download from the ThingWorx Marketplace (Windows or Linux). The installation media contains 2 files : 1 JAR and 1 JSON configuration file.
For this demo, I'm installing the Integration Runtime on a remote machine and will not be using SSL.
1. Prerequisite for the Integration Runtime : Oracle Jre 8 (and of course a ThingWorx 7.4 platform server accessible)
2. Create an ApplicationKey in the composer for the Integration Runtime to use for communication to the ThingWorx platform.
3. Configure the Integration Runtime communication - ThingWorx host, port, appKey, ... - this is done on the Integration Runtime server via the JSON configuration file.
My integrationRuntime-settings.json (sslEnable=false, storagePath is ignored) :
{
"traceRoutes": "true",
"storagePath": "/ThingworxStorage",
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "twx74neo",
"port": "8080",
"basePath": "/Thingworx",
"sslEnable": "false",
"ignoreSSLErrors": "true"
}
}
Note : It is important to completely remove the "SSL": {} block when not using SSL
4. Launch the Integration Runtime service (update the JAR and JSON filenames if needed)
java -DconfigFile=integrationRuntime-settings.json -jar integration-runtime-7.4.0-b12.jar
The Integration Runtime service uses Web Socket to communicate with the ThingWorx platform (similar to EMS). It registers itself with the ThingWorx platform.
Monitoring the Integration Runtime microservice
In the ThingWorx composer : Monitoring > Subsystems > Integration Subsystem
SMAINENTE1D1 is the hostname of my Integration Runtime server.
Custom WindchillSwaggerConnector implementation
Use the New Composer UI (some setting, such as API maps, are not available in the ThingWorx legacy composer)
1. Create a DataShape that is used to map the attributes being retrieved from Windchill
- WNCObjectDS : oid, type, name (all fields of type STRING)
2. Create a Thing named WNC11Connector that uses WindchillSwaggerConnector as Thing Template
3. Setup the Windchill connection under WNC11Connector > Configuration
- Authentication Type = fixed (SSO currently not supported)
- Username = <Windchill valid user>
- Password = <password for the Windchill user>
- Base URL : <Windchill app URL> (e.g. http://wncserver/Windchill)
4. Create an API maps under WNC11Connector > Services and API Maps > API Maps (New Composer only)
- My API Map : New API Map
- Mapping ID : FindBasicObjectsMap
- EndPoint : findObjects (choose the first one)
- Select DataShape : WNCObjectDS (created at step 1) and map the following attributes :
- name <- objName ($.items.attributes)
- type <- typeId ($.items)
- oid <- id ($.items)
After pressing [done] verify that the API ID is '/objects GET' (and not /structure/objects - otherwise recreate the mapping and choose the other findObjects endpoint).
5. Create a "Route" service under WNC11Connector > Services and API Maps > Services (New Composer only)
- Name : FindBasicObjects
- Type (Next to [Done] button) : Route
- Route Info | Endpoint : findObjects (same as step 4)
- Route Info | Mapping ID : FindBasicObjectsMap-xxxx created at step 4
Testing our custom WindchillSwaggerConnector
Test the WNC11Connector::FindBasicObjects service
Note that the id (oid) and typeId (type) are returned by default by the /objects REST API - objName has to be explicitly requested.
Monitoring the Integration Connector
In the ThingWorx composer : Monitoring > Integration Connectors
