Configuring ServiceMax Integration
The following sections provide detail on the configurations for ServiceMax Integration on the ThingWorx side. Refer to the ServiceMax IoT Enablement Guide available from your ServiceMax instance for details on configurations needed on the ServiceMax side.
* 
Create a system account in ServiceMax representing the ThingWorx system. In the following sections, we use thingworx@svmx.ptc.com. Work with your ServiceMax representative to create an account for your ServiceMax environment. This ServiceMax user is used when configuring the ServiceMax Connector.
Permissions for ServiceMax Integration
Only Controls Engineers (who are part of the Administrators user group) can perform the steps to configure ServiceMax Integration.
Users with the following roles can view and execute all ServiceMax Integration components.
Controls Engineer
Maintenance Engineer
Maintenance Manager
Enabling Application Keys in HTTP Requests
If you are running ThingWorx 8.1 or later, follow the steps below to set the Allow Application Key as URL Parameter option. This setting allows an application key to be used when accessing ThingWorx from ServiceMax, so that the user is not required to enter credentials.
1. In ThingWorx Composer, select System, then Subsystem.
2. Click PlatformSubsystem.
3. Under Configuration, select the Allow Application Key as URL Parameter checkbox.
4. Click Save.
Setting Up ServiceMax
The following section describes the configuration needed on the ThingWorx side. Refer to the ServiceMax IoT Enablement Guide available from your ServiceMax instance for details on configurations needed on the ServiceMax side.
Configuring the ServiceMax Connector
The following steps are required to send transactions from ThingWorx to ServiceMax, such as cases, service requests, and work orders.
1. Prerequisites:
A Salesforce ID intended to be used for system integration between ThingWorx and ServiceMax.
A Salesforce Connected App in your Salesforce organization. Work with your ServiceMax representative to determine the proper Salesforce Connected App to use for this integration, and your specific Salesforce configuration. You need both the "Consumer Key" and "Consumer Secret" from the Salesforce Connected App.
2. Gather the following information from Salesforce:
Information
Notes
userID
User name for the ServiceMax system user. For example, thingworx@svmx.ptc.com
Password
The password for the system user.
OAuth endpoint
Depending on the type of your organization, there may be two endpoints:
Sandbox: https://test.salesforce.com/services/oauth2/token
Production and others: https://login.salesforce.com/services/oauth2/token
Consumer Key
Consumer Secret
svmxapiVersion
1.0 – Version 1 of the ServiceMax IoT Events
2.0 – Version 2 of the ServiceMax IoT Events
3. In ThingWorx Composer, find and edit the configuration on PTC.SCA.SCO.Connector.ServiceMaxConnector.
4. Enter the values from step 2 into the equivalent configuration fields, and click Save.
ServiceMax Connector
Salesforce
Example
username
User Id
thingworx@svmx.ptc.com
password
Password
mypassword12345
authenticationURL
OAuth endpoint
http://login.salesforce.com/services/oauth2/token
consumerKey
Consumer Key
3MVG9FS3IyroMOh4wFW1xUosABhe3SJ
consumerSecret
Consumer Secret
8122336483569005441
5. Validate your ServiceMax Connector configuration.
a. In ThingWorx Composer, view the PTC.SCA.SCO.Connector.ServiceMaxConnector entity. Click Services.
b. Click Test for the TestConnection service method.
c. Click Execute Service.
d. If your ServiceMax Connector is properly configured, it returns OK.
If your ServiceMax Connector is not properly configured, review the error message from Salesforce, and check your configuration settings.
Adding Parameters to the ServiceMax API
You can add parameters to the ServiceMax API request by overriding the createOthersInfoTable to provide additional field values to be added to the ServiceMax object. In addition, custom changes to the ServiceMax application must be made in order to map the additional field values. Work with your ServiceMax representative to determine the necessary parameters.
To perform the override:
1. In ThingWorx Composer, view the PTC.SCA.SCO.AssetService.Connector.ServiceMaxTemplate thing template.
2. Under Services, view the createOthersInfoTable service.
3. Select the script text, and copy it to the clipboard.
4. Locate the PTC.SCA.SCO.AssetService.Connector.ServiceMax thing, and open it for editing.
5. Under Services, click Override service icon to override the createOthersInfoTable service script.
6. Paste the copied script into the script editor.
7. Make your changes to the script, and click Done. See the example script provided below.
8. Click Save.
* 
A trigger or custom event handler must exist to expose the additional fields in the ServiceMax object.
// Create the InfoTable using the appropriate data shape
var params = {
infoTableName : "InfoTable",
dataShapeName : "PTC.SCA.SCO.AssetService.Connector.ServiceMaxApiPayloadDS.OthersDS"
};
result = Resources["InfoTableFunctions"].CreateInfoTableFromDataShape(params);
/*** DO NOT MAKE MODIFICATIONS ABOVE THIS LINE ***/
/*
* For version 2 of the ServiceMax API we will use the serial number to map
* requests to installed products
* If different matching is required then this section needs to be changed
* to include the field(s) configured
* for matching. Refer to the "Configuring Installed Product Lookup" in
* the ServiceMax IOT Enablement guide for details.
*
* Multiple rows can be added to the InfoTable; one for each name/value
* pair to appear in the Others section of the API payload.
* Follow the pattern below to add additional rows
*/

var othersObj = new Object();
othersObj.FieldName = "SerialNumber";
othersObj.FieldValue = dataShapeObj.AssetSerialNumber;
result.AddRow(othersObj);

/*
* Example to add more Thing properties to the InfoTable
*
* This example uses the thing name based in the dataShapeObj argument
* to look up the Thing and grab properties from it.
*
* The resulting JSON sent to the ServiceMax API looks like:
* "Others" : { "SerialNumber":"value", "IsConnected":"value",
* "LastConnection":"value" }
*/
var t = Things[dataShapeObj.AssetThingName];
var othersObj = new Object();
othersObj.FieldName = "IsConnected";
othersObj.FieldValue = t.isConnected;
result.AddRow(othersObj);
var lastConnectedUTCTime=new Date(t.lastConnection.getUTCFullYear(),
t.lastConnection.getUTCMonth(), t.lastConnection.getUTCDate(),
t.lastConnection.getUTCHours(), t.lastConnection.getUTCMinutes(),
t.lastConnection.getUTCSeconds());
var othersObj = new Object();
othersObj.FieldName = "LastConnection";
othersObj.FieldValue = dateFormat(lastConnectedUTCTime, "yyyy-MM-dd HH:mm:ss.sss");;
result.AddRow(othersObj);
ServiceMax End Points — Version 1 and Version 2
The following table lists the differences between Version 1 and Version 2 ServiceMax endpoints.
ServiceMax Event
ServiceMax Version 1 Endpoint
ServiceMax Version 2 Endpoint
Create Case
createCase
CreateCase
Create Service Request
alertHandler
CreateServiceRequest
Create Work Order
createSR
CreateWorkOrder
ServiceMax Event Priority
ThingWorx uses a 10-degree priority scale (1 – 10) for alerts. ServiceMax uses a 3-degree priority scale (1 – 3).
Alert mapping is transformed to service mapping internally as:
ThingWorx alert priority 8 – 10 = ServiceMax Event Priority Low (1)
ThingWorx alert priority 4 –7 = ServiceMax Event Priority Medium (2)
ThingWorx alert priority 1 – 3 = ServiceMax Event Priority High (3)
Was this helpful?