Configuration for Customizations

Overview

APM Connect supports customizations through different configuration options. These customizations can be achieved through control and configuration tables in IRDB for extractions and templates for the Southbound interfaces.

Note: These configurations are not mandatory if the interfaces need to be executed with baseline configuration.

Create the Intermediate Repository Database

This topic describes how to set up a repository in preparation to run your first job.

Before You Begin

Important: If you are using both the Data Loaders and an EAM Adapter, you need only one Intermediate Repository Database.

Before you can prepare and deploy the repository, you must import the CreateIntermediateRepository job.
If you are using the Data Loaders and the EAM Adapters, you must deploy and run the CreateIntermediateRepository job for each set of adapters.
For SAP adapters, you must first run the Static Data job.
For multiple EAM systems, the context file parameter values for a specific type of system must be identical except for the value of CMMS_ID.
For multiple EAM systems, the Intermediate Repository Connection parameters have the same values for all adapters connected to this APM system.

Important: Each time you run the CreateIntermediateRepository you recreate the APM database to the baseline settings, removing any previous configuration. When you run the addSourceSystem job, the job will add new source systems based on the CMMS_ID and the SOURCE_SYSTEM_TYPE. If the job is run an additional time with the same configuration, it will reset the control values of an existing source system.

Procedure

Log in to the APM Connect Administration Center web application.

Note: The user logging in must have access to the Job Conductor by being designated the Operations Manager role. By default, users designated as administrators do not have Job Conductor permissions.
In the Job Conductor workspace, in the appropriate project, select the CreateIntermediateRepository job.

Note: For ServiceMax, this job is called CreateIntermediateRepository_ServiceMax.
Select Context parameters.

The Context parameters section appears.

Configure the following parameter.


Context Parameter	Description
CONFIG_FILE_PATH	The file path to context files for the jobs. Important: You must change the default value to reflect the actual path to your configuration file. CMMS_ID and SOURCE_SYSTEM_TYPE must be set in the context file.

Select Run.
If you are configuring a single system, you have completed your configuration.
The intermediate repository database is created for the project.

If you are configuring multiple EAM systems, perform the remaining steps in this topic.

In the Job Conductor workspace, in the appropriate project, select the addSourceSystem job.

Configure the following parameter.


Context Parameter	Description
CONFIG_FILE_PATH	The file path to context files for the jobs. Important: You must change the default value to reflect the actual path to your configuration file. CMMS_ID and SOURCE_SYSTEM_TYPE must be set in the context file.

Select Run.
Repeat steps 6 through 8 for all adapters.

autoextractor_control Table

The purpose of the auto extractor control table is to specify the conditions and data extracted by the APM Connect interfaces. The structure of the table is outlined below, indicating the fields that must be updated during customization.


Field Name	Description	Configurable
autoextract_id	Auto-generated index	Do Not Modify
batch_name	Interface Batch Name	Do Not Modify
active	Inactive and will not run Active and will run	Yes
job_name	APM Connect sub-process name	Do Not Modify
filename	Filename returned by SAP	Do Not Modify
run_in_background	True - Run in SAP background False - Run in foreground	Yes
default_date_value	Date used when SAP returns a null date	Do Not Modify
field_separator	Indicates file delimiter in the file returned by SAP	Do Not Modify
abap_cursor_fetch_size	Invokes SAP to read large data sets as a batch of the size indicated	Do Not Modify
extract_schema_definition	An array utilized in SAP select statements when retrieving data Structure: “SAP Table Name \| SAP Field Name” Delimiter: “;”	Yes
join_condition	Join condition used when querying the data in SAP	Yes
where_condition	Where condition used when querying the data in SAP	Yes
for_all_entries_field_name	Field name used in SAP where a “For All Entries” statement is in use in the SAP Query	Do Not Modify
for_all_entries_field_type	SAP Field data type used in SAP where a “For All Entries” statement is in use in the SAP Query	Do Not Modify
for_all_entries_condition	Condition used in SAP where a “For All Entries” statement is in use in the SAP Query	Do Not Modify
object_list_type	Object to create a list of objects when utilizing the object_list_control table	Do Not Modify
object_type	Refers to SAP object, interface name, and SAP Table name when utilizing the object_list_control table	Do Not Modify
sap_background_job_name	When running in SAP background, this is the job name passed to SAP.	Yes
step_seq	Not in use	Do Not Modify
cmms_id	SAP System ID	Yes

autoloader_control Table

The purpose of the auto loader control table is to specify the condition under which the data extracted in active entries in the autoextractor_control is staged in temporary tables in the IRDB. The structure of the table is outlined below, indicating the fields that must be updated during customization.


Field Name	Description	Configurable
autoloader_id	Auto-generated index	Do Not Modify
batch_name	Interface Batch Name	Do Not Modify
active	Inactive and will not run Active and will run Note: You need to match active status for the same batch_name in autoextracor_control table	Yes
job_name	APM Connect sub-process name	Do Not Modify
filename	Filename returned by SAP that will load into IRDB temporary table	Do Not Modify
table_name	IRDB temporary Table Name	Do Not Modify
null_string	Default Date String	Do Not Modify
field_separator	Indicates file delimiter in the file returned by SAP	Do Not Modify
row_separator	Indicates new line indicator in the file returned by SAP	Do Not Modify
delete_where_clause	Utilized in multiple EAM system configurations to clear entries in temporary table for the EAM system that is being updated	Do Not Modify
object_type	Refers to SAP object, interface name, and SAP Table name when utilizing the object_list_control table	Do Not Modify
transform_job_name	APM Connect transformation sub-process name	Do Not Modify
cmms_id	SAP System ID	Yes

autojoin_control Table

The purpose of the auto join control table is to fetch the data loaded into the IRDB temporary tables and create the data payloads to be loaded into APM. The structure of the table is outlined below indicating the fields that should be updated during customization.


Field Name	Description	Configurable
autojoin_id	Auto-generated index	Do Not Modify
batch_name	Interface Name	Do Not Modify
table_name	The data table name to identify the data sheet when loading into APM.	Do Not Modify
sql_execution_order	Specifies the order of the data load for each batch_name	Do Not Modify
sql	The query to extract data from the temporary table in the IRDB.	Yes
site_reference	Site reference in APM can be an APM Family Field or a constant	Yes
apm_site_reference_column	Field name for Site Reference in APM	Do Not Modify
apm_site_reference_family	APM Family to fetch the site reference in which site_reference field resides.	Do Not Modify
use_relationship_lookup	Null – ignored Do not use relationships Use relationships	Do Not Modify
default_site_reference	Default Site is no site is configured	Yes
primary_family_id	APM Family ID	Do Not Modify
cmms_id	SAP System ID	Yes

southbound_mapping_control Table

The purpose of this table is to provide a dynamic mapping capability from APM fields (including custom fields) in the Recommendation to SAP fields supported by the baseline interface for notification creation. The request from APM has the following details:

Entity (EQ/FL) on which the request is being generated
Connection information of the EAM system
APM Family Fields (including custom fields) from the Recommendation

The structure of the table is outlined below, indicating the fields that must be updated during customization.


Field Name	Description	Configurable
southbound_mapping_control_id	Auto-generated index	Do Not Modify
apm_field_name	APM Field Name	Yes
target_field_name	SAP Field Name	Do Not Modify
target_field_map_name	SAP RFC Parameter Name	Do Not Modify
mapping_enabled	True – Will be pushed to SAP False – Will not be pushed to SAP	Yes
target_default_value	Default value in case data is not provided in the payload	Yes
cmms_id	SAP System ID	Yes

Configure Intermediate Repository Database

You can configure APM Connect to:

Extract data from your EAM system
Push APM data back into your EAM system

To enable these configurations, you can modify the table entries in the Intermediate Repository Database (IRDB).

CAUTION: Before editing the IRDB table entries, we recommend that you create a backup of the existing database. This ensures that you restore the database to the original state if required.

Create a Database Backup

Procedure

Select the Start button on Windows, right-click Command Prompt, and then select Run as administrator.
The Command Prompt window appears.
At the command prompt, enter the following command:
```
pg_dump -U postgres -Fc database_name > database.dump
```
where,
- database_name is the name of the database for which you want to create a backup.
- database.dump is the custom. Additionally, database.dump can be renamed to any name with a .dump extension.
Note: If you receive the “pg_dump” is not recognized as an internal or external command error message while executing the database backup command, run the command again using full path of the Postgres installation. For example, C:\Program Files\PostgreSQL\11\bin\pg_dump” U postgres -Fc database_name > database.dump

Restore Database From a Backup File

Procedure

Select the Start button on Windows, right-click Command Prompt, and then select Run as administrator.
The Command Prompt window appears.
At the command prompt, the following command:
```
pg_restore -U postgres -d database_name database.sql
```
In the command, replace postgres with a username with full access to the database labeled database_name. Additionally, database.sql can be renamed to any name with a .sql extension.

Note: If you receive the “pg_dump” is not recognized as an internal or external command error message while executing the database restore command, run the command again using full path of the Postgres installation. For example, C:\Program Files\PostgreSQL\11\bin\ pg_restore” -U postgres -d database_name database.dump

Configure Northbound and Southbound Data Extraction SAP Mapping

To facilitate a dynamic mapping capability for data extracted from SAP and pushed into APM, the below IRDB tables can be configured.

autoextractor_control
autoloader_control
autojoin_control
southbound_mapping_control

The structure of the tables and fields that are modified during configuration is outlined in subsequent sections of the documentation. Within each table are rows that correspond with steps for data extraction to support the following data types:

Asset Strategy Integration
Equipment
Equipment Technical Characteristics
Functional Location
Functional Location Technical Characteristics
Planned Work Interface
Static Data
Work Management Interface
Work History

Northbound Data Integration Data Flows

During the northbound data integration, each interface follows the following logic:'

Southbound Data Integration Data Flows

During the southbound data integration, each interface follows the following logic:

Configure Source System Custom Field Mappings or Default Values

APM Connect documents a baseline set of fields that are considered standard in the APM to SAP Notification Creation integration with SAP. Additionally, there is capability to configure these and other fields to be included in the Notification Creation process. For information on the available fields to add to mapping, refer to the List of attributes that can be added to Notification Creation from APM to SAP topic. This topic describes how to configure additional baseline fields or make changes to default values.

Before You Begin

To successfully perform this task, you must have the following:

Administrative rights to the APM Connect database from which you are retrieving the field values or setting the default values.
A database tool, such as DBeaver or DBVisualizer.

About This Task

There are times when you need to have information that is stored in APM displayed in your source system database. To achieve this goal, you need to modify tables used by APM to send data to your source system.

Note: If Custom field mappings are needed, or fields that are not in this list, customization options exist with our Integration Center of Excellence engagement process.

The following procedure describes how to either configure a mapping between APM and your source system or to set a default in your source system from APM.

The following image is an example of the southbound_mapping_control table as displayed by a database tool.

Note: This feature is not available for creating work orders.

Procedure

Using a database tool, navigate to the APM database you want to configure.
In the database navigation, in the Tables folder, select southbound_mapping_control.
Navigate to the target_field_name and target_field_map_name column you want to configure.

Configure the field mapping or default value for your source system.

Item to configure	How to configure
Field mapping	In the apm_field_name column, enter the name of the APM field that contains the value to apply in the source system, and then set the value in the mapping_enabled column to `true` For example, if you want to set the source system value of REPORTEDBY in map table REPORTEDBY_NOTIFHEADER from the APM field CurrentUserID, the table would resemble the following when you complete your update. Important: If, after configuring the mapping, you see a blank value for the field, make sure the value you entered in the apm_field_name column is correct.
Default value	In the target_field_default column, enter the value you want to be the default in your source system and set the value in the mapping_enabled column to `false`.

Item to configure

How to configure

Field mapping

In the apm_field_name column, enter the name of the APM field that contains the value to apply in the source system, and then set the value in the mapping_enabled column to true

For example, if you want to set the source system value of REPORTEDBY in map table REPORTEDBY_NOTIFHEADER from the APM field CurrentUserID, the table would resemble the following when you complete your update.

Important: If, after configuring the mapping, you see a blank value for the field, make sure the value you entered in the apm_field_name column is correct.

Default value

In the target_field_default column, enter the value you want to be the default in your source system and set the value in the mapping_enabled column to false.

Results

Your source system mappings or default values are configured.