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

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

Note: It is recommended to take backup of the templates before they are modified.


Template Name	Description	Supported EAM System
closenotification.xslt	Template to customize close notification request workflow	SAP
closenotification_response.xslt	Template to customize close notification response workflow	SAP
createnotification.xslt	Template to customize create notification request workflow	SAP
createnotification_response.xslt	Template to customize create notification response workflow	SAP
createworkorder.xslt	Template to customize Inspection/Calibration Task workorder request workflow	SAP
createworkorder_response.xslt	Template to customize Inspection/Calibration Task workorder response workflow	SAP
createworkorder_notification.xslt	Template to customize Inspection/Calibration Task notification request workflow	SAP
createworkorder_notification_response.xslt	Template to customize Inspection/Calibration Task notification response workflow	SAP
functions.xslt	Data Transformation Functions	SAP
updatenotification.xslt	Template to customize update notification request workflow	SAP
updatenotification_response.xslt	Template to customize update notification response workflow	SAP
updatenotification_userstatus.xslt	Template to customize update notification user status request workflow	SAP
updatenotification_userstatus_response.xslt	Template to customize update notification user status response workflow	SAP

Custom RFC Mapping

The baseline template can be modified to call a custom RFC by changing the parameter for the Type RFC.

<TYPE>RFC</TYPE>
<NAME>Z_CREATE_NOTIF_CUSTOM</NAME>.(This can be any custom RFC name)

Custom Field Mapping

The baseline template can be modified to map an SAP field with the APM family field (SAP RFC should support custom fields as parameters). Existing mapping can be updated or new mapping can be added.

If Planner Group needs to be Mapped to SAP field PLANGROUP then modify the create notification template as below under the NOTIFHEADER section.

<COLUMN> 
<NAME>PLANGROUP</NAME>
<VALUE>
<xsl:value-of select='Fields/MI_PLANER_GRP'/>.(This can be the APM Field Name to be mapped)
</VALUE>
</COLUMN>

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)