Install and Configure Southbound Service

Overview

The installation package includes the setup of the Southbound Service from APM to the EAM system. This topic outlines the steps that you must complete to deploy and configure this module for the first time. These instructions assume that you have completed the steps for deploying the basic APM system architecture.

Note: This service can be deployed on the APM Connect Server, APM server, or a dedicated server. The service should have access to the APM Connect Postgres Staging Database.

Install Southbound Service

Before You Begin

Before you run the Southbound Service installer, you must ensure that:

Your system meets the System Requirements.
You have access to the Southbound Service installation package.
You can access the APM server host URL and ActiveMQ from the server where the installation is planned.
You have access to the Postgres IR database of the APM Connect server.

Procedure

Sign in as a user with administrative privileges to the server where you plan to install the application.
Access the APM distribution package and then navigate to the folder where you downloaded the installer package.
Run APMConnect-Base.exe with administrative privileges.
The Setup - APMConnect window appears.
Select Next.
The Select Destination Location window appears.
Select Browse to navigate to the destination folder where the services must be installed.
Select Next.
The Select Components window appears.
Select the components you wish to install:
1. Install PostgreSQL: Used for the Intermediate Repository. Clear the checkbox if already in use.
2. Install Boomi: Select if Boomi is used without internet connectivity.
3. Install APM Connect Southbound Service: Select for the Southbound Interfaces.
Select Next.
The Select Start Menu Folder window appears.
Select Browse to select the folder for placing shortcuts, then select Next.
The Ready to Install window appears.
Review the installation settings and select Install.
The progress of the installation is displayed.
After the installation is complete, select Yes, restart the computer now and select Finish to restart the server.
The APM Connect Southbound Service is installed. Open Services.msc and validate that APM Connect Southbound Service is available in the Services panel.

What To Do Next

After installation, the Southbound Service will not be in the start state. Configure appsettings.json and then start the service manually.

Configure APMC Southbound Service

About This Task

You can configure the APM Connect Southbound Service using the appsettings.json configuration file available at the location, C:\\Program Files\APM.Connect.Southbound.

Procedure

Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).
Based on your requirement, set the following parameters:
- Logging: Logging Level
- FileWSDL: Contains the configuration for the EAM file receiver.
- AppConfiguration section contains the following parameters:
  - IR staging Database information (ADL 4.6 APM, General Recommendation)
    - IR_Host
    - IR_Port
    - IR_Database
    - IR_Schema
    - IR_UserId
    - IR_Password
  - ADL configuration
    - Default_Base_Directory - This is for the CSV file share for the DL between APM and the APMC Southbound Service.
    - Directory_Path - For the ADL root folder of the Scan and Archive.
    - Polling_Frequency_In_MilliSeconds
    - Max_File_Size_In_Bytes
    - Max_Filename_Length
    - Valid_Extensions
    - Valid_Zip_Extensions
  - APM (Application Server) configuration (ADL,V5 Audit JOB)
    - Apm_Api_Test_Path
    - Web_Api_Path
    - DatasourceId
    - Id. (user-id)
    - Password
  - EAM Server Connection Type Configuration (GENERAL RECOMMENDATION,WORKORDER GENERATION)
    - Sap_Connection_Type (Application/Message)
    - Use_API_Key (True/false)
    - API_Key
  - APM Application ActiveMQ Credentials - For the v5 Audit Job (Applicable only for OnPrem)
    - ActivemqName (Queue name were the Asset Ingestion Completion Messages are posted by the Ingestor)
    - ActivemqUri
    - ActivemqUsername
    - ActivemqPassword
  - UAA configuration (Applicable only for cloud)
    - Uaa_Token_Url
    - Uaa_Username
    - Uaa_Password
    - Uaa_Client_Id
    - Uaa_Client_Secret
    - Use_OAuth
  - Websocket Configuration (Application only for Cloud)
    - WebSocket_Api_Path. e.g., wss://<external-host>/conduit/api/v1
  - Ingestor Configuration
    - Ingestor_Api_Path
Note: For SSL configuration, refer the section Enable SSL for Southbound Service.
Save and close the file.

Example

Southbound Service Configuration example file:

//Please remove stars and fill values as mentioned
{
  "Urls": "http://0.0.0.0:5013",
  "Logging": {
    "LogLevel": {
      "Default": "Trace",
      "Microsoft.AspNetCore": "Trace"
    }
  },
  "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information",
  "FileWSDL": {
    "UrlOverride": "",
    "VirtualPath": "",
    "WebServiceWSDLMapping": {
      "EamFileReceiver": {
        "UrlOverride": "EamFileReceiver",
        "WsdlFile": "EamFileReceiver.wsdl",
        "SchemaFolder": "Schemas",
        "WsdlFolder": "Schemas"
      }
    }
  },
  "AllowedHosts": "*",
  "AppConfiguration": {
    "IR_Host": "****POSTGRES SERVER HOST****",
    "IR_Port": "5432",
    "IR_Database": "**IR_POSTGRES_DB_NAME**",
    "IR_Schema": "public",
    "IR_UserId": "postgres",
    "IR_Password": "**IR_POSTGRES_DB_PASSWORD**",
    "Is_Linux": false,
    "Linux_Base_Path": "",
    "Default_Base_Directory": "C:\\APMConnect",
    "Apm_Api_Test_Path": "/meridium/api/internal/connect/connectionstatus/ApmcToApm",
    "Use_SSL": false,
    "StoreLocation": "",
    "StorePassword": "",
    "CmmsId": "*******CMMS-ID*******",
    "Sap_Connection_Type": "Application",
    "Use_API_Key": false,
    "API_Key": "",
    "DownStream_Request_Timeout_In_Minutes": 2,
    "Directory_Path": "****ADL Directory folder[Example:\\\\APMCONNECTVM4.meridium.com\\APMConnect\\ADL]****",
    "Web_Api_Path": "http://******APM APPLICATION HOST NAME*******/meridium/api/v1",
    "Ingestor_Api_Path": "http://******APM APPLICATION HOST NAME*******/meridium/connect/api/v1",
    "DatasourceId": "******APM DATASOURCE*******",
    "Id": "bl",
    "Password": "",
    "Polling_Frequency_In_MilliSeconds": 0,
    "Max_File_Size_In_Bytes": 100000000,
    "Max_Filename_Length": 100,
    "Valid_Extensions": "zip,xlsx",
    "Valid_Zip_Extensions": "csv"
    "Enable_G2DL_Ingestion": true
  },
  "QueueOptions": {
    "ActiveMqHost": "**APM ACTIVE MQ HOST**",
    "ActiveMqPort": 61616,
    "FailoverHosts": [],
    "Username": "admin",
    "Password": "admin",
    "UseSsl": false
  },
   "ASPNETCORE_URLS": "http://+:5013",
  "DOTNET_PRINT_TELEMETRY_MESSAGE": false,
  "ASPNETCORE_ENVIRONMENT": "Production"
}

Customize Southbound Service

Southbound Service supports additional customization for custom RFC and custom field mapping (from APM to SAP) through template-based configuration.

Notification Create/Update/Close
Notification user status update
Work Order Creation

Custom Templates can be used for:

Map additional APM fields to APM connect baseline RFC parameters.
Triger custom RFC for below interfaces/endpoints mentioned in table.

The baseline template is available in <southbound Installation folder>\SouthboundService\Templates\sap and sap-pi.

Table 1. Default Templates
EAM System	Template	Description	Interface
SAP	createnotification.xslt	Create SAP notification from APM recommendations. Configure/refer XSLT sheet to validate/configure APM fields to SAP RFC parameters.	Recommendations
SAP	Createnotification_response.xslt	Create notification response from SAP. Configure/refer XSLT sheet to validate/configure SAP RFC response values to APM response load.	Recommendations
SAP	Updatenotification.xslt	Update SAP notification from APM recommendations. Configure/refer XSLT sheet to validate/configure APM fields mapping to SAP RFC parameters.	Recommendations
SAP	Updatenotification_response.xslt	Update notification response from SAP. Configure/refer XSLT sheet to map custom fields from SAP RFC response to APM response.	Recommendations
SAP	Updatenotification_userstatus.xslt	Update notification user status from APM to SAP. Configure XSLT sheet for additional fields mapping from APM to SAP RFC.	Recommendations
SAP	Updatenotification_userstatus_response.xslt	Response from SAP for update notification user status RFC call. Configure XSLT sheet to map additional/custom fields from RFC to APM response.	Recommendations
SAP	Closenotification.xslt	Close the SAP notification APM to SAP. Configure XSLT sheet for calling custom RFC or mapping additional/custom fields in SAP.	Recommendations
SAP	Closenotification_response.xslt	Response from SAP for close notification RFC call.	Recommendations
SAP	Createworkorder.xslt	Create SAP work order call for inspection and calibration tasks. Configure XSLT sheet for custom or additional fields mapping to SAP RFC parameters.	Work management interface
SAP	Createworkorder_response.xslt	Response from SAP for create work order RFC call. Configure for additional or custom fields mapping from SAP response to APM response.	Work management interface
SAP	Createworkorder_notification.xslt	Create SAP notification for inspection and calibration tasks instead of work order. Configure XSLT sheet for custom RFC or additional fields map from APM to SAP.	Work management interface
SAP	Createworkorder_notification_response.xslt	SAP response for create notification RFC call for inspection and calibration tasks. Configure for additional or custom fields map from SAP RFC response to APM response.	Work management interface
SAP	Functions.xslt	Used for APM connect xslt transformation.	APM Connect internal use.

Name Parameter Type Sample Config

Single value

Import & Export

Table 2. Supported Parameters
Name	Parameter Type	Sample Config
Single value	Import & Export	`<PARAMETER> <NAME>NOTIF_TYPE</NAME> <VALUE><xsl:value-of select='Fields/MI_REC_NOTIF_TYPE_C'/> </VALUE> </PARAMETER>`
Structure	Import & export	`<PARAMETER> <NAME>NOTIFHEADER</NAME> <VALUE> <LINE> <COLUMN> <NAME>EQUIPMENT</NAME> <VALUE> <xsl:value-of select='EquipmentID'/> </VALUE> </COLUMN> </LINE> </VALUE> </PARAMETER>`
Table	Table	`<PARAMETER> <NAME>NOTIFITEM</NAME> <VALUE> <xsl:for-each select='NotificationItems'> <LINE> <COLUMN> <NAME>ITEM_KEY</NAME> <VALUE> <xsl:value-of select='Item_Key'/> </VALUE> </COLUMN> <COLUMN> <NAME>ITEM_SORT_NO</NAME> <VALUE> <xsl:value-of select='Item_SortNumber'/> </VALUE> </COLUMN> </LINE> </xsl:for-each> </VALUE> </PARAMETER>`

<PARAMETER>
<NAME>NOTIF_TYPE</NAME>
<VALUE><xsl:value-of    select='Fields/MI_REC_NOTIF_TYPE_C'/>
</VALUE>
</PARAMETER>

Structure

Import & export

<PARAMETER>
<NAME>NOTIFHEADER</NAME>
  <VALUE>
   <LINE>
    <COLUMN>
      <NAME>EQUIPMENT</NAME>
       <VALUE>
                <xsl:value-of select='EquipmentID'/>
         </VALUE>
     </COLUMN>
</LINE>
</VALUE>
</PARAMETER>

Table

<PARAMETER>
                <NAME>NOTIFITEM</NAME>
                <VALUE>
                <xsl:for-each select='NotificationItems'>
                <LINE>
                <COLUMN>
                <NAME>ITEM_KEY</NAME>
                <VALUE>
                <xsl:value-of select='Item_Key'/>
                </VALUE>
                </COLUMN>
                <COLUMN>
                <NAME>ITEM_SORT_NO</NAME>
                <VALUE>
                <xsl:value-of select='Item_SortNumber'/>
                </VALUE>
                </COLUMN>
                </LINE>
                </xsl:for-each>
                </VALUE>
                </PARAMETER>

Note: The RAW Data Type is not supported.

Example: Map additional APM fields to baseline SAP RFC’s.

Requirement: Map additional below two fields from APM recommendation to SAP notification creation RFC.

CC_REC_CODIN_GROUP_CHR (Coding Group)

Navigate to <southbound installation folder>\southbound\SouthboundService\Templates\SAP or SAP-PI).
Access the createnotification.xslt file in an application that can be used to modify XSLT files (for example, Notepad++).
Search for SAP input parameter name defined in RFC (“NOTIFHEADER”) and add the following additional XML tag to map values from APM recommendation fields.

Example: Custom RFC call

Requirement: APM connect Southbound Service provide the capability to call custom SAP RFC’s. Call custom SAP RFC (ZMIAPM_CREATE_NOTIF) to create SAP notification.

Navigate to <southbound installation folder>\southbound\SouthboundService.
Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).
Search for "Generalisable" and set the value as true:
"EnableGenericRfc" : true
Navigate to <southbound installation folder>\southbound\SouthboundService\Templates\SAP or SAP-PI.
Access the createnotification.xslt file in an application that can be used to modify XSLT files (for example, Notepad++).
Search for “<NAME>/MIAPM/CREATE_NOTIF</NAME>” and replace the baseline SAP RFC name with custom RFC name as follows:
<NAME >ZMIAPM_CREATE_NOTIF </NAME>
Note: Ensure that you update all the RFC parameters names and columns correctly if they are different than baseline APM connect RFC. That is, update the import parameters with “Z_NOTIFHEADER” instead of “NOTIFHEADER”.
Save the template.

Uninstall Southbound Service

Procedure

Open the APMConnect - Uninstaller application.
Select Remove APM Connect Southbound Service checkbox and select Uninstall.
Open services.msc and verify that the service is removed from the Windows Service Panel.

Enable SSL For Southbound Service

About This Task

The following procedure outlines the necessary configurations to enable SSL for the Southbound Service, based on Microsoft documentation.

Procedure

Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).

Insert the following JSON block at the top of the settings under the root in the appsettings.json file:

SSL Configuration

 "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://test.domain.com:5013"
      }
    },
    "Certificates": {
      "Default": {
          "Path": "C:\\temp\\meridium_SAN_04212024.pfx",
          "Password": "K2p8HBxb"
      }
    }
},

Modify the ASPNETCORE_URLS property to utilize HTTPS. Ensure that the property is set to use HTTPs on port 5013:
```
"ASPNETCORE_URLS": "https://+:5013"
```
Restart the service to apply the configuration changes.
Enable SSL for downstream service
1. To enable SSL in Southbound Service for downstream interactions (SAP, Maximo etc.), update the below configuration properties in appsettings.json file, under the AppConfiguration section:
  
  Note: When interacting securely with APM and EAM systems, it is essential to combine both servers' certificates into a single pfx file.
  
  SSL for Down Stream service interaction:
```
"Use_SSL": true,
"StoreLocation": "C:\\Certs\\TestSSL\\FileName.pfx",    //File should be in PFX format only.
"StorePassword": "xyz",    // Encrypted password is also supported. Use only the crypto utility tool in southbound service to encrypt the password.
```
2. Restart the service again to ensure that the changes take effect.

Log Archive Configuration

About This Task

This procedure outlines the steps to update the log configuration for the Southbound Service using NLog as the logging framework.

Procedure

Locate and navigate to the bin folder of the Southbound Service.
Open the file nlog.config file.
Add the following properties in the target xsi:type="File" section of the nlog.config file, to enable archival and deletion of logs:
1. archiveFileName: Specify the location and name of the archived file.
2. archiveEvery: Define a time interval for the archival of logs.
3. maxArchiveDays: Set the number of days the file will remain archived before deletion.
4. archiveNumbering: Define the format of the archive file name, replacing {#} in archiveFileName.
5. archiveAboveSize: Set the threshold value (in bytes) for log file size, triggering the generation of a new log file.
Configuration Sample:
```
<target xsi:type="File" name="allfile" fileName="c:\ProgramData\Meridium\Logs\APM.Connect.Southbound_${shortdate}.log"
    layout="${longdate}|${uppercase:${level}}|${mdlc:item=TenantId:whenEmpty=na}|${logger}|${message} ${exception}"
    archiveFileName="c:\ProgramData\Meridium\Logs\APM.Connect.Southbound_${shortdate}.{#}.log"
    archiveEvery="Day" maxArchiveDays="30" archiveNumbering="DateAndSequence" archiveAboveSize="2000000"/>
```

APM Connection String Configuration

About This Task

This procedure outlines the steps required to update the connection string in the APM system to redirect Southbound requests to the NextGen ETL Service.

Procedure

Navigate to Admin >Operation Manager >Connections.
Select APM Connect option.
Under General settings, locate the connection string that requires modification.
Update the connection string to following format:
http://apm-classic-apm-connect-southbound-broker:5000/ (for pre/prod/eu)