Deployment

Deploy ServiceMax Adapters

To ensure that the ServiceMax adapter transfers data correctly between Predix Essentials, and ServiceMax, you must perform these steps.

Before You Begin

The correct version of Predix Essentials is installed.
The correct version of APM Connect is installed.
You have received the necessary information about the ServiceMax system the adapter is connecting to Predix Essentials.
Your ServiceMax system must be prepared correctly.

Procedure

Preparing the ServiceMax System

Load the Product Catalogue into ServiceMax. Make sure that all product external IDs in ServiceMax are identical to the product IDs you load into Predix Essentials.
Load account IDs into ServiceMax. These account IDs must match the Site Names you load into Predix Essentials.
Add Location Types FLOC and Ship To to the Location object in ServiceMax. If your source system uses a Location Type other than FLOC, use that type designation.

Upgrade the ServiceMax Adapters to ServiceMax UDLP V2.6.0

The following tables outlines the steps that you must complete to upgrade this module toServiceMax UDLP V2.6.0.

About This Task

These instructions assume that you have completed the steps for upgrading the basic system architecture.

These tasks may be completed by multiple people in your organization. We recommend, however, that the tasks be completed in the order in which they are listed.

Procedure

Upgrade from ServiceMax UDLP V2.2.0 through Maximo UDLP V2.5.0
On the APM Connect Server, run the third-party software batch file.
On the APM Connect Server, update existing jobs.

Create a ServiceMax EAM System Record

You must configure an EAM System record to establish a connection between any EAM system and Predix Essentials.

Procedure

Create a new EAM System record.
In the Datasheet ID box, select ServiceMax.
In the Name box, enter the name of your system.
If this system is the system to and from which you want to send data by default, select the Default EAM System? check box.
In the System Type box, select SERVICE_MAX.
In the User ID box, enter a valid User ID.
In the Password box, select .
In the Enter EAM System Password window, in the Password box, enter the password that is associated with the specified user ID.
In the Confirm Password box, reenter the password.
Select OK.
In the Connection String box, replace the template connection string with the URL of the ServiceMax application endpoint, for example, https://login.salesforce.com/services/oauth2/token.
In the Auth Client box, enter the ID of the client.
In the Auth Client Secret box, select .
In the Auth Client Secret box, enter the secret associated with the specified user ID.
In the Confirm Client Secret box, reenter the client secret.
Select OK.
Select .
The EAM System record is saved.
Select , and then select Test Connection.
The connection parameters are verified, and the System ID box is populated with your EAM System Name.

Results

An EAM system record is created for the EAM system that defines a connection with Predix Essentials. The ID for this EAM record should now be used in the Name field of a Site Reference record.
Linking an EAM system to an EAM System record enables the APM Connect Adapters to create Notifications against that EAM System.

Configure the ServiceMax Context File

This topic describes how to access and configure parameters in the context file.

About This Task

Before you can run a job, you must specify a set of connection parameters and corresponding values to establish connections between APM Connect components, Predix Essentials, and ServiceMax. Each of these connections is used when executing a job, and they are required. The connections are established via context files.

Procedure

On the APM Connect Server, navigate to the context file, and then open the context file to edit.

Important: Changes made to the context file will override changes made in the APM Connect Administration Center Context parameters section.

Interface Mode Selection
Parameter	Description	Default or Recommend Value
LOAD_MERIDIUM_APM	Determines if data will be loaded into the Meridium database.	The default value is true. true: data will be loaded into the Meridium database. false: data will not be loaded into the Meridium database.
LOAD_DIGITAL_APM	Determines if data will be loaded into the Predix database.	The default value is true. true: data will be loaded into the Predix database. false: data will not be loaded into the Predix database.
CMMS_ID	The CMMS ID used as the identifier for your ServiceMax System, taking the form <System ID>-<Client ID>. For example, if your System ID is D03 and your Client ID is 001, then your CMMS ID would be DO3-001.	This value is required. Enter your unique value.
SOURCE_SYSTEM_TYPE	Identifies the type of system connecting with Predix Essentials.	This value is required. You must enter the value SERVICEMAX.
Intermediate Repository (IR) Connection Parameters
Parameter	Description	Default or Recommended Value
IR_HOST	IP address of the IR.	Enter the host name of the PostgreSQL server. If you installed APM Connect using the default settings, then the value is localhost.
IR_PORT	Port number of the IR.	The default value is 5432.
IR_DATABASE	Database in which the IR data is stored.	Enter a name for the IR database. This value will be used to create the IR database.
IR_SCHEMA	The schema in which the IR database will be created.	The default value is public.
IR_USER_ID	The IR user name.	Enter the user name for the PostgreSQL database. The default user name is postgres.
IR_PASSWORD	The IR system password.	Enter the password for the PostgreSQL database that was created when running the installer.
APM Connection Parameters
Parameter	Description	Default or Recommend Value
APM_API_APP_SERVER	The Predix Essentials API application server name.	Enter the name of your Predix Essentials API Server.
APM_API_USE_SSL	Specifies whether the Predix Essentials API application uses SSL.	The valid values are: true: The API application uses SSL. false: The API application does not use SSL. The default value is false.
APM_APP_SERVER	The Predix Essentials application server name.	Enter the name of your Predix Essentials Server.
APM_DATASOURCE	The Predix Essentials data source to which the data will be exported.	Enter the name of your Predix Essentials data source.
APM_PASSWORD	The Predix Essentials Framework password.	Enter your unique value.
APM_USERID	The Predix Essentials Framework User ID.	Enter your unique value.
UNC_FILE_PATH	The path of the directory of the data loader file share.	Enter your unique value.
ServiceMax Organization Information
Parameter	Description	Default or Recommended Value
CUSTOMER_NAME	The coded customer name.	Enter your unique value, which was provided at installation.
ServiceMax Connection Parameters
Parameter	Description	Default or Recommended Value
SERVICEMAX_CLIENT_ID	ServiceMax client from which data will be extracted.	Enter your unique value.
CLIENT_SECRET	The secret associated to the ServiceMax Client.	Enter your unique value.
GRANT_TYPE	The value ServiceMax uses to grant access to the system.	The default value is password.
SERVICEMAX_TOKEN_REQUEST_URL	IP address of the ServiceMax Server that provides security tokens to users.	Enter your unique value.
USERNAME	ServiceMax system user ID.	Enter your unique value.
PASSWORD	ServiceMax system password.	Enter your unique value.
SERVICE_REQUEST_URL	The URL of the service that Predix Essentials uses to create service requests in ServiceMax.	Enter your unique value.
ROWS_TO_PROCESS	The number of assets to extract in each batch from ServiceMax.	The default value is 100.
LANGUAGE	The ServiceMax code that represents the language.	Must be a single character.
EXTRACT_NUM_PARALLEL_JOB	Determines the maximum number of background jobs allowed during execution.	The recommended value is 10.
IR_LOAD_NUM_PARALLEL_JOBS	The maximum number of IR load jobs in a single extraction.	The recommended value is 30.
MANUAL_RUN	Determines how the date parameters will be treated.	The default value is true. true: The dates specified in the context file will be used, and the dates of the last successful run stored in the database will not be updated. false: The date range used during the extraction will be the date of the last successful record, as stored in the database. Each time a Job is run successfully, the database is updated with those dates, and all subsequent runs will use the dates from the last successful record.
File System Parameters
Parameter	Description	Default or Recommended Value
PLSERVICEMAX_INPUT	Path of the directory you created in which ServiceMax writes files.	Enter your unique value.
PLSERVICEMAX_OUTPUT	Path of the directory where APM Connect will access the files written by ServiceMax.	Enter your unique value.
IR_TALEND_OUTPUT	The root directory for all internal file processing. This is the directory where files will be transformed.	Enter a file system location to which files will be written. You can create a directory in the following location: C:\IR\TalendOutput.
LOG_BASE_DIR	The directory path to the log file.	None.
SFTP_STAGING_DIR	Temporary storage location for files that are waiting to be loaded.	Enter your unique value, which was provided at installation.
USE_SSL	Determines if an SSL certificate will be used when transferring files.	Enter true. An SSL certificate is required, and true is the only valid value.
TRUSTSTORE_FILE	The directory path where the SSL certificate is stored.	Enter the directory path where the SSL truststore is stored on the APM Connect Server.
TRUSTSTORE_PASSWORD	The password to the SSL certificate file.	Enter your unique value, which was provided at installation.
Filter Parameters
Parameter	Description	Recommended or Default Value
CREATE_DATE_START	Date value that limits the data extracted to records created on or after the specified date.	Dates must be entered in the following format: YYYYMMDD.
CREATE_DATE_END	Date value that limits the data extracted to records created on or before the specified date.	Dates must be entered in the following format: YYYYMMDD.
CHANGE_DATE_START	Date value that limits the data extracted to records changed on or after the specified date.	Dates must be entered in the following format: YYYYMMDD.
CHANGE_DATE_END	Date value that limits the data extracted to records changed on or before the specified date.	Dates must be entered in the following format: YYYYMMDD.
CREATE_TIME_START	Time value that limits the data extracted to records created at or after the specified time.	Time must be in the following format: HHMMSS
CREATE_TIME_END	Time value that limits the data extracted to records created at or before the specified time.	Time must be in the following format: HHMMSS.
CHANGE_TIME_START	Time value that limits the data extracted to records changed at or after the specified time.	Time must be in the following format: HHMMSS.
CHANGE_TIME_END	Time value that limits the data extracted to records changed at or before the specified time.	Time must be in the following format: HHMMSS.
Equipment Filter Criteria
Parameter	Description	Recommended or Default Value
SERVICEMAX_MAX_ASSETID	Specifies the IDs of the assets that you want to extract.	Enter your unique value. Suppose that you want to extract assets between IDs 12345 and 98764. Your configuration would contain this statement: `<SERVICE_MAX_ASSETID>2345,98764</SERVICEMAX_ASSETID>`
SERVICE_MAX_WONUM	Specifies the Work Order numbers you want to extract.	Enter your unique value. Suppose you want to extract work orders between IDs 8756 and 9875. Your configuration would contain this statement: `<SERVICE_MAX_WONU>8756,9875</SERVICEMAX_WONUM>`
SERVICE_MAX_SRNUM	Specifies the Service Request numbers you want to extract.	Enter your unique value. Suppose you want to extract service requests a2C1I000000F2y and b2C1I000000F2z. Your configuration would contain this statement: `<SERVICE_MAX_SRNUM>a2C1I000000F2y, b2C1I000000F2z</SERVICEMAX_SRNUM>` Note: This filter will only extract service requests that do not have associated work orders.
EQUIPMENT_NO	Equipment that you want to extract.	The Equipment number cannot exceed 18 characters. You cannot exceed 500 Equipment numbers.
EQUIPMENT_CATEGORY	ID of the Equipment Category that will limit the Equipment extracted.	The Equipment Category cannot exceed one character.
EQUIPMENT_TYPE	ID of the Equipment Type that will limit the Equipment extracted.	The Equipment Type cannot exceed 10 characters.
EQUIPMENT_CLASS	ID of the Equipment Classification that will limit the Equipment extracted.	The Equipment Class cannot exceed 18 characters. If an Equipment has multiple classifications, as long as you specify one of those classifications, the Equipment record will be extracted.
Predix Parameters
Parameter	Description	Recommendation or Default Value
TOKEN_REQUEST_URL	The URL of the service that issues tokens for a client.	Enter your unique value.
CLIENT_ID	The client ID to access the Predix application.	Enter your unique value.
INGESTION_USERNAME	The user name to request asset data from the Predix application.	Enter your unique value.
INGESTION_PASSWORD	The password for the ingestion user name that requests asset data from the Predix application.	Enter your unique value.
ASSET_INGESTION_URL	The URL the Predix application uses to respond to requests for asset information.	Enter your unique value.
TENANT_UUID	The userid of the tenant used to access the Predix application.	Enter your unique value.
PREDIX_GRANT_TYPE	The value the Predix application uses to grant access to the system.	The default value is password.
Functional Location Filter Criteria
Parameter	Description	Recommended or Default Value
FLOC_NO	ID of the Functional Location that will limit the Functional Locations extracted.	The Functional Location number cannot exceed 40 characters. You cannot exceed 500 Functional Location numbers.
FLOC_TYPE	ID of the Functional Location Type that will limit the Functional Locations extracted.	Functional Location type cannot exceed 10 characters.
FLOC_CLASS	ID of the Functional Location Classification that will limit the Functional Locations extracted.	Functional Location class cannot exceed 18 characters.
FLOC_CATEGORY	ID of the Functional Location Category that will limit the Functional Locations extracted.	Functional Location category cannot exceed one character.
Work History Filter Criteria
Parameter	Description	Recommended or Default Value
NOTIFICATION_NO	Number that identifies the Notification record.	Notification Number cannot exceed 12 characters.
WORK_ORDER_NO	Number that identifies the Work Order record.	Work Order Number cannot exceed 12 characters.
NOTIFICATION_TYPE	Order type that limits the orders that you want to extract.	Notification type cannot exceed two characters.
WORK_ORDER_TYPE	ID of the work order that limits the orders that you want to extract.	Work Order type cannot exceed four characters.
WORK_ORDER_SYSTEM_STATUS	Work Order systems status that limits the work orders you want to extract.	Work Order System Status cannot exceed four characters.
WORK_ORDER_USER_STATUS	Work Order user status that limits the work orders that you want to extract.	Work Order User Status cannot exceed four characters.
NOTIFICATION_SYSTEM_STATUS	Notification system status that limits the notifications that you want to extract.	Notification system status cannot exceed four characters.
NOTIFICATION_USER_STATUS	Notification user status that limits the notifications that you want to extract.	User status cannot exceed four characters.
MAINT_PLANT	ID(s) of the Maintenance Plant whose data you want to extract.	Plant values cannot exceed four characters.
Miscellaneous Parameters
Parameter	Description	Recommended or Default Value
SITE_REFERENCE_EQUIP	Used to map the site reference value to a ServiceMax field. This dictates which ServiceMax field will be used as the site reference for Predix Essentials Equipment records.	You can enter a value defined in Predix Essentials. Note: The value that is entered will be applied to all records. -or- You can use the character # at the beginning and end of a Predix Essentials field name to indicate the field that is used to set the site reference. For example, if you wanted to use your ServiceMax maintenance plant field as your Predix Essentials site reference, you would enter a value in the following form: `<SITE_REFERENCE_EQUIP>#MI_EQUIP000_MAINT_PLANT_C#</SITE_REFERENCE_EQUIP>`.
SITE_REFERENCE_FLOC	Used to map the site reference value to a ServiceMax field. This dictates which ServiceMax field will be used as the site reference for Predix Essentials Equipment records.	Specify the value with either of the following methods: Enter a value defined in Predix Essentials. Note: The value that is entered will be applied to all records. You can use the character # at the beginning and end of a Predix Essentials field name to indicate the field that is used to set the site reference. For example, if you wanted to use your ServiceMax maintenance plant field as your Predix Essentials site reference, you would enter a value in the following form: <SITE_REFERENCE_FLOC>#MI_FNCLOC00_MAINT_PLANT_C#</SITE_REFERENCE_FLOC>.
Email Notification Parameters
Parameter	Description	Recommenced or Default Value
EMAIL_TO	The email address(es) to which the notification email will be sent.	Enter your unique value.
EMAIL_FROM	The email address from which the notification email will be sent.	Enter your unique value.
REPORT_TARGET_DIR	The directory path where the report file will be delivered.	Enter your unique value.
FAILURE_DETAIL_REPORT_JRXML_FILE_PATH	The directory path where the failure report file will be delivered.	Enter your unique value.
LOAD_SUMMARY_REPORT_JRXML_FILE_PATH	The directory path where the load complete report file will be delivered.	Enter your unique value.
SMTP_HOST	The SMTP host for the APM Connect Server installation.	Enter your unique value.
SMTP_PORT	The port for SMTP.	Default value is 25.
LOAD_SUMMARY_REPORT_ENABLED	Indicates whether the Load Complete report will be sent with every extraction.	True: The Load Complete report will be sent detailing the number of records that were extracted and successfully loaded into Predix Essentials. False: The Load Complete report will not be sent.
FAILURE_DETAIL_REPORT_ENABLED	Indicates whether the Failure Detail report will be sent when a record fails to load.	True : The Failure Detail report will be sent detailing the records that failed to load and the reason why. False: The Failure Detail report will not be sent.

Configure Site Reference Values

To assign site references to records using values other than those in the baseline configuration, you must modify the autojoin_control table in the Intermediate Repository.

About This Task

Note: Site Reference records corresponding to the site references that you specify must exist in Predix Essentials before you can transfer records.

Procedure

Configure the Site Reference Value to Use an Indirect Site Reference Value.
1. Access a database browser tool, and then access your Intermediate Repository (PostgreSQL) database.
2. Locate the autojoin_control table, and then locate the site_reference column.
  
  Tip: For details about what each column in the autojoin_control table contains, see About Site Filtering Configuration.
3. Update the value in the site_reference column using the format #FIELD_ID#, where FIELD_ID represents the ID of the field from which you want to populate the site reference value.
  For example, if you want the site reference value to be the value in the Functional Location field of the corresponding Equipment or Functional Location.
  - Where the value #MI_FNCLOC00_SERVICEMAX_SYSTEM_C# occurs, replace the value with #MI_FNCLOC00_FNC_LOC_DESC_C#
  - Where the value #MI_EQUIPOO_SERVICEMAX_SYSTEM_C# occurs, replace the value with #MI_EQUIP000_FUNC_LOC_C#
  When you import a record into Predix Essentials from your ServiceMax system, its Site Reference Key will be the value in the field that you specified. In the example above, the Site Reference Key will be the ServiceMax Maintenance Plant of the corresponding Equipment or Functional Location.
Configure the Site Reference Value to be A Specific Site Name.
1. Access a database browser tool, and then access your Intermediate Repository (PostgreSQL) database.
2. Locate the autojoin_control table, and then locate the site_reference column.
  
  Tip: For details about what each column in the autojoin_control table contains, see About Site Filtering Configuration.
3. Where the value #MI_EQUIPOO_SERVICEMAX_SYSTEM_C# occurs, replace the value with the Site name as defined in a Predix Essentials Site Reference record.
  When you import records into Predix Essentials from your ServiceMax system, its Site Reference Key will be the name of the Site as defined in the APM Site Reference record.

Configure MI_EQUIP000_CST_CNR_C as an Indirect Site Reference

In this example, the database browser tool used in this example is pgAdmin4, the IR database name is ServiceMax_UDLP_EAMClient. You can use the database browser of your choice.

On your APM Connect Server, open the application pgAdmin4.
The application pgAdmin4 opens, displaying your available servers.
Navigate the server tree to the appropriate IR database, access your tables.
In this example, the path is Servers(2)\roaperflabvm3\Databases\ServiceMax_UDLP_EAMClient\Schemas(1)\public\Tables (81). The list of tables in your IR database are visible.
Locate the table autojoin_control, then right-click the table, and then select View Data.
Select View All Rows.
The Query -1 section is populated with the autojoin table.
In each row, in the site_reference column, enter #MI_EQUIP000_CST_CNR_C#
Tip: This example assumes that the existing values in the site_reference column correspond to values in the MI_EQUIP000 and MI_FNCLOC00 families. If they do not, you must also update the apm_site_reference_family column to the corresponding family.
The value in the MI_EQUIP000_CST_CNR_C field will be used to populate the Site Reference Key in corresponding records.

Configure Predix Essentials to Create Notifications Recommendation Records

ServiceMax allows you to create Recommendation records in Predix Essentials that will be used to create ServiceMax Notifications automatically.

About This Task

For a Recommendation record to generate an ServiceMax Notification automatically, the Create Work Request field must exist on the Recommendation datasheet. This field is available on the baseline datasheets for the baseline Recommendation families from which you can create ServiceMax Notifications.

If you want to generate ServiceMax Notifications from Recommendation records that belong to customer-defined subfamilies of the root Recommendation family, in addition to implementing the correct rules (for an example of the rules that you will need to implement, you can look at any active baseline Recommendation family), you will need to add the Create Work Request field to the applicable datasheets for that family.

Tip: You can create multiple types of ServiceMax Notifications (for example, general) from Recommendation records. By default, Predix Essentials creates general notifications.

Procedure

If you want to create different Notification types, you will need to:

Add the Notification Type field to the datasheet.
Configure the Notification Type field to accept values other than general.
Note: In the baseline ServiceMax product, this field is disabled. If desired, you could configure it to be enabled so that users can enter a value directly in the Notification Type cell on the datasheet. You might also consider creating a Valid Values rule that provides a list of acceptable values so that users can select the desired value in the list.

Information to Complete ServiceMax and APM Connect Communications

To enable communications between ServiceMax and APM Connect, the ServiceMax administrator must update ServiceMax correctly. To configure communications, you must provide the ServiceMax administrator with specific information.

Provide the ServiceMax administrator with the userid configured in the context file as USERNAME for APM Connect.

Provide the ServiceMax administrator with the following information:

The EVENT NAME and CLASS NAME are APMServiceRequestEvent. The administrator will configure these values in the IoT Events section on the IoT Setup page in ServiceMax.
The INSTALLED PRODUCT FIELD NAME is Record ID and the EXTERNAL FIELD NAME is RecordID. The administrator will configure these values in the Installed Product Lookup section in the IoT Setup page in ServiceMax.