Optional Configuration

Parameters in the context file are not encrypted by default, which results in values being transmitted in clear text over the network. However, you can manually encrypt any parameter manually.

1. On the machine on which you installed APM Connect, access the file EncryptString.zip, and unzip it.
2. Open the EncryptString folder, and then run EncryptString_run.bat.

   Command prompt opens, and then the Talend Open Studio window appears.

3. Enter the parameter value you want to encrypt in the Enter the text to be encrypted: box, and then select OK.
4. In the command prompt, copy the text between the banners that was generated.
   
5. Open the context file.
6. In the parameter you want to encrypt, paste the generated text.
7. In the parameter start tag, add encrypted="true" algorithm="aes128", as shown in the following image:

   

8. Repeat Steps 2-8 for all of the parameters you want to encrypt.
9. Save the context file.

1. On the APM Connect server, if the service is running, stop the APM Connect service.
2. Navigate to C:\APMConnect\runtime\etc.
3. Open the file users.properties in an application that you can use to modify a text file (for example, Notepad).
4. Change the passwords for the default user names.
5. Specify your own user names using the following format:

   user=password[,role] [,role] [,role]...

   - or -

   user=password[,group] [,group] [,group]...

   Note: For information about groups and defining roles, refer to the Talend documentation.
6. Save and close the file.
7. To specify authorizations for the jobserver, open the file users.csv.
8. Add the authorized user names and passwords in the following format:

   username,password

   Note: For information about jobserver requirements, refer to the Talend documentation.
9. Save and close the file.
10. To enable password encryption, open the file system.properties.
11. Add the following statements at the end of the file:

    
                      # edit config
                      config:edit org.apache.karaf.jaas
                      config:property-set encryption.enabled true
                      config:update
                      
                      # force a restart
                      bundle:restart
                   

12. Save and close the file.
13. Start the APM Connect service.

1. On your local machine, access and then copy the StageDataLoaderServices.jar file.
2. Navigate to the following path: <root:>\APMConnect\runtime\deploy.
3. Right-click inside the folder, and then select Paste to copy the .jar file into the Runtime folder.

   The new service is deployed to the APM Connect host.

1. On the APM Connect server, locate Command Prompt
2. Right-click on Command Prompt, and then select Run as administrator.

   

   The Administrator: Command Prompt window appears.

3. Change the directory to: C:\APMConnect\Utilities\runtime\bin.
4. In the Command Prompt, after the new directory path, enter: trun.

   A message appears in the Command Prompt, and another karaf@trun> prefix appears.

   Note: When you first start Karaf, it takes a few minutes to load all of the commands. So, if you attempt to enter the features:install command in Step 5 and receive an error message in the Command Prompt, try the command again in a few minutes.

   
   
   
5. In the Command Prompt, after karaf@trun>, enter features:install wrapper.

   Another karaf@trun> prefix appears.

6. After karaf@trun>, enter wrapper:install -s AUTO_START -n APM-CONTAINER -d APM-Container -D "APM Container Service".

   A service wrapper feature is now installed into the Runtime Container, and a batch file is created in your local APM folder.

   Tip: On your local computer, navigate to your APM Connect folder: C:\APMConnect\runtime\deploy. Notice that your local APM Connect folder now contains two new items: APM-CONTAINER-service.bat and APM-CONTAINER-wrapper.exe.

   Another karaf@trun> prefix appears.

7. After karaf@trun>, enter shutdown, and then enter yes to confirm you want to shut down karaf.

   Karaf is shut down, and another karaf@trun> prefix appears and the directory is changed toC:\APMConnect\runtime\bin

8. After C:\APMConnect\runtime\bin , enter APM-CONTAINER-service.bat install.
   

   The APM Container is installed, and a message appears indicating as such.

9. To start the APM Container, restart your machine.

1. On the APM Connect server, access Control Panel\Network and Internet, and then select Internet Options.

   The Internet Properties screen appears

2. Select the Security tab, then, in the Select a zone to view or change security settings section, select Local intranet, and then select Custom level....

   The Security Settings -Intranet Zone screen appears.

3. In the Settings section, access the Include local directory path when uploading files to a server, and select Disable.
4.  Select OK.

   The Security Settings -Intranet Zone screen closes.

5. On the Internet Properties screen, select Apply.

   Internet Explorer is configured accommodate APM Connect.

1. Start pgAdmin.
2. Right-click on a database, and then select Query Tool.

   The workspace for the selected database appears.

3. In the workspace, enter ALTER statements for each role to be changed using the following format:

    ALTER ROLE username SET PASSWORD TO 'newpassword'

4. At the top of the workspace, select .

   The query runs and the password is changed.

   Note: For more information about the PostgreSQL roles, see the PostgreSQL documentation.

If you want to use SSL for connections from APM Connect, this step is required.

1. Log in to your application, and then access the certificate information from your browser.
   Note: Typically, you can access certificate information by selecting the lock icon in the address bar.
   The Certificate window appears.
2. Select Details, and then select Copy to File....
   The Certificate Export Wizard window appears.
   
   
3. Select Next.
4. In the Export File Format window, select DER encoded binary X.509 (.cer), and then select Next.
5. In the File to Export window, select Browse….

   The Save As window appears.

6. Save the file to your Desktop under the name certificate.cer.
7. Select Next.
8. Select Finish.

   The Certificate Export Wizard window appears.

   
   
   
9. Select OK.
10. Copy the certificate.cer file, and then paste it into the folder that contains the Java files for your machine.
    Tip: For example, if your Java files are located at C:\Program Files\Java\jre7\bin, copy the certificate.cer file to that bin folder.
11. On the APM Connect server, access the Command Prompt window as an Administrator, and then navigate to the location of the Java files on your machine.
12. Enter keytool.
    Commands for the Key and Certificate Management Tool appear in the Command Prompt.
13. In the last line, C:\Program Files\Java\jre7\bin>, enter keytool –importcert –alias test –file certificate.cer –keystore publickey.store.
14. Enter a password, and confirm the password by reentering it.
    In the Command Prompt window, you are asked if you want to trust the certificate.
15. For yes, enter y.
    The keystore file is created.
16. For the Karaf service, navigate to the location of the Karaf JDK, and then repeat steps 12 through 15 using the path and password for the Karaf service JDK.
    • For the value of the keystore argument, use the file path of the Karaf JDK, (for example, C:\Program Files\Java\<JDK version>\jre\lib\security\cacerts).
    • The default password for keytool is changeit. Enter your unique value.
17. Access the context file, and then enter the following values for the corresponding parameters:

    • TRUSTSTORE_FILE: The location of the truststore file you created.

    • TRUSTSTORE_PASSWORD: The password you entered in the Command Prompt window when you installed the certificate.
    • USE_SSL: true.
    • APM_API_USE_SSL: true, if you are using SSL on the GE Digital APM Server.

To ensure proper communications between GE Digital APM and APM Connect, you must configure the server to use SSL.

1. Edit the file etc/org.ops4j.pax.web.cfg so that the HTTP feature uses SSL.
   When you are done, the file should look similar to this example, with your_password replaced with the passwords you will use.

   org.osgi.service.http.port=8040
   org.osgi.service.http.port.secure=9001
   org.osgi.service.http.secure.enabled=true
   org.ops4j.pax.web.ssl.keystore=${karaf.base}/etc/keystores/keystor.jks
   org.ops4j.pax.web.ssl.password=your_password
   org.ops4j.pax.web.ssl.keypassword=your_password
   #org.ops4j.pax.web.config.file=${karaf.base}/etc/jetty.xml
   

2. Enable HTTP client support in APM Connect.
   1. Navigate to C:\APMConnect\Utilities\runtime, and then enter bin/trun.
   2. At the prompt, enter feature:install http.
3. From a certificate authority, obtain two certificates: one for the server and one for the client.
   Important: Make sure you import the client certificate you receive into your application server.
4. In the APM Connect server, at the command prompt, import the server certificate into the server keystore.
   The command will resemble the following example.

   keytool -import -trustcacerts -keystore keystore.jks -storepass  keystore_password 
   -alias serverkey -file server.cer

5. In the APM Connect server, at the command prompt, import the client certificate into the server keystore.
   The command will resemble the following example.

   keytool -import -trustcacerts -keystore keystore.jks -storepass  keystore_password 
   -alias clientkey -file client.cer

6. In the APM Connect server, at the command prompt, verify that the client certificate is imported.
   1. In the APM Connect server, at the command prompt, enter keytool -list -v -keystore keystore.jks.
   2. At the password prompt, enter the keystore password.
      The system responds similarly to the following example.

      Keystore type: JKS
      Keystore provider: SUN
      Your keystore contains 2 entries
      ................
      Alias name: serverkey
      Creation date: Jun 1, 2018
      Entry type: PrivateKeyEntry
      ...............
      Alias name: clientkey
      Creation date: Jun 1, 2018
      Entry type: trustedCertEntry
      .............................

7. Test the APM Connect server configuration.
   1. Start the Karaf service.
      bin/client
   2. Install the WebConsole feature.
      karaf@trun> feature:install webconsole
   3. In a browser, enter https://localhost:9001/system/console.
      You should get an error message similar to the following:

      An error occurred during a connection to localhost:9001.
      
      SSL peer cannot verify your certificate.
      
      (Error code: ssl_error_bad_cert_alert)
      

   4. Import the client certificate from step 3 into your browser using the process for managing certificates for that browser.
   5. Repeat step 7.c to verify that the certificate imported successfully and you can access the APM Connect server.

1. Edit the file etc/org.apache.karaf.jaas.cfg.
2. Update the field values listed below:

   Field	Description
   encryption.enabled	By default it is set to False. Change the field value to True.
   encryption.algorithm	By default it is set to MD5. It can be changed to any of these values (MD2,MD5,SHA-1,SHA-256,SHA-384,SHA-512).
   encryption.encoding	By default it is set to hexadecimal. It can be changed to base64.

3. Restart the APM-Container Service.

   #    Licensed to the Apache Software Foundation (ASF) under one or more
   #    contributor license agreements.  See the NOTICE file distributed with
   #    this work for additional information regarding copyright ownership.
   #    The ASF licenses this file to You under the Apache License, Version 2.0
   #    (the "License"); you may not use this file except in compliance with
   #    the License.  You may obtain a copy of the License at
   #
   #       http://www.apache.org/licenses/LICENSE-2.0
   #
   #    Unless required by applicable law or agreed to in writing, software
   #    distributed under the License is distributed on an "AS IS" BASIS,
   #    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   #    See the License for the specific language governing permissions and
   #    limitations under the License.
   #
   ################################################################################
   
   #
   # Boolean enabling / disabling encrypted passwords
   #
   encryption.enabled = true
   
   #
   # Encryption Service name
   #   the default one is 'basic'
   #   a more powerful one named 'jasypt' is available
   #       when installing the encryption feature
   #
   encryption.name =
   
   #
   # Encryption prefix
   #
   encryption.prefix = {CRYPT}
   
   #
   # Encryption suffix
   #
   encryption.suffix = {CRYPT}
   
   #
   # Set the encryption algorithm to use in Karaf JAAS login module
   # Supported encryption algorithms follow:
   #   MD2
   #   MD5
   #   SHA-1
   #   SHA-256
   #   SHA-384
   #   SHA-512
   #
   encryption.algorithm = SHA-256
   
   #
   # Encoding of the encrypted password.
   # Can be:
   #   hexadecimal
   #   base64
   #
   encryption.encoding = base64
   

Whether you have multiple source systems or multiple plants connected to GE Digital APM, the configuration process is similar.

1. For each source system or plant, create an EAM System Record.
   Each source system or plant must have a unique system ID (CMMS-ID).

   Note: If you are configuring multiple plants from a single source system, the IP addresses, user IDs, and other addressing information will be the same as the first EAM System Record you defined for the source system.
2. Run the job addSourceSystem to add configurations to the existing Intermediate Repository database with a different system ID for each source system or plant and the appropriate system type (SAP, Maximo, or ServiceMax).
3. Configure context files for each of the source systems or plants so they have separate jobs for the Extractions.
   Important: Do not schedule the same interface job simultaneously from different source systems.
4. Set up RFC and Notifications from GE Digital APM to the source systems for either on-premise or cloud environments.

   Environment	Action
   On-premises	Deploy connectServices.jar service for the outbound interface to all the source systems from GE Digital APM.
   Cloud	Import the connectServicesCloudClient job for each source system using the same context file used for the Extraction. Note: You should use Intermediate Repositories on each EAM system clients to send data to a single GE Digital APM tenant. The tenant will have separate connectServicesCloudClient for each extraction context.

5. Optional: For each SAP system, run the Static Data job to extract data for each SAP system.

To enable data flow when there are multiple cultures configured for a single source system, you must complete the following steps.

1. Create a context file for each culture originating from a specific source system.
   1. Assign a CMMS_ID and TARGET_CMMS_ID that indicates the culture.
      For example, consider a source system that supports both French and Spanish. Your CMMS_ID and TARGET_CMMS_ID for the two systems could resemble SRC1_client_FR and SRC1_client_ES.
2. Create the Intermediate Repository database for the first CMMS_ID you define.
3. For each additional CMMS_ID defined in Step 1.a, run the addSourceSystem job.
4. For each CMMS_ID defined in Step 1.a, create an EAM system record, using the CMMS_ID in the System Name field.
5. Select Test Connection for each EAM System record you created.

1. Access the APM Connect Administration Center.
2. In the Menu pane, in the Settings section, select the Users tab.

   The Users workspace appears.

3. In the Users workspace, select the user whose password you want to change.
4. In the Data pane, select change password.
   

   The User Password window appears.

5. Enter the new password, and enter it again to confirm.
6. Select Validate.

   The password has been changed.

This topic describes how to create a service account user that has access to the SAP server and runs the Karaf service.

1. In the same domain as the SAP server, create an active directory user.
2. On the SAP server, create a new folder that will be shared with the new user you just created.
3. Right-click the new folder.
4. Select Properties.

   The <Folder Name> Properties window appears.

5. In the <Folder Name> Properties window, select the Sharing tab, and then select Share....
6. In the File Sharing window, in the text box, enter the user name of the service account user, and then select Add.

   The new user appears in the list of users.

7. In the Permission Level column, select , and then select Read/Write.
8. Select Share, and then close the windows.
9. On the APM Connect server, select the Windows Start button to open the Windows Start menu.
10. In the Search programs and files box, enter services.

    Services appears in the Programs list.

11. Select Services.
12. In the Services window, right-click the APM-CONTAINER service.
13. Select Properties.

    The APM-CONTAINER Properties (Local Computer) window appears.

14. In the APM-CONTAINER Properties (Local Computer) window, select the Log On tab.

    

15. In the Log On tab, select This account:, enter the name of the service account user, and then select OK.

1. If you receive the No token set error when accessing the APM Connect Administration Center, as shown in the following image, select Validate your license manually.
   

   The Validation request screen appears.

   

2. In the Validation request window, in the Validation message (put this message on the form of the next Link) box, copy the text.
3. In the Validation link (put the generated validation token to the next text Area) section, select link.

   If a browser opens, displaying the Enter your validation request page, skip to step 6.

   -or-

   If a browser does not open, proceed to the next step.

4. Complete the validation.

   Response from selecting link	How to complete validation
   A browser opens displaying Enter your validation request.	Proceed to the next step.
   A browser does not open.	Right-click link, and then select copy link text. Via email or chat, send the link to a machine with internet access that is not behind the firewall, and then, on that machine, paste the link into a browser.

5. Paste or enter the text from the Validation message (put this message on the form of the next Link) box into the box in the browser, and then select Get your validation token.
6. Select the copy button.
7. In the Copy your validation token, copy the text in the box.
8. Return to the APM Connect Administration Center.
9. Paste the token text into the Validate box.
10. Select Validate.

1. On the APM Connect server, navigate to Control Panel\System and Security\System to open system properties for the Windows machine.

   The View basic information about your computer screen appears.

2. In the Control Panel Home pane, select Advanced systems settings.

   The System Properties window appears, displaying the Advanced tab.

3. Select Environment Variables....

   The Environment Variables window appears.

4. In the System variables section, select New....

   The New System Variable window appears.

5. In the Variable name box, enter
   JAVA_HOME
6. In the Variable value box, enter the path to the root jdk installation directory.
   
7. Select OK, and then close the properties window.

   The Java environment variables are created.

1. Run the Task Scheduler as administrator.
   
2. In the Actions section select the Create Task option
   
   The Create Task window appears.
3. Select the Trigger tab to create a new trigger.
   
4. Select the Actions tab to configure the script.
   
5. Select Browse and navigate to the directory C:\APMConnect\utilities\tacDBBackup\PostgresTacDump.bat or copy and paste the path directly into the Program/Script field.
6. Select OK.
   The Task Scheduler window appears, asking for credentials.
7. Enter the user credentials.
   
8. Select OK.
   Tip: To make sure the task is scheduled correctly, run the task once and check if the backup is created in the C:\APMConnect\utilities\tacDBBackup directory.

   If the backup file created is 0 byte, then some parameters are incorrect. In this case, check if Postgres password, Hostname and Username are correct in PostgresTacDump.bat

   Note: The db_namename in the script and URL DB name in TAC(Database parameter) must be the same.
   
   The apmctac DB backup script is scheduled successfully.

1. Access your APM Connect Installation package, navigate to the Jobs folder, and then copy the file CheckConnections.jar.
2. On your APM Connect server, navigate to C:\APMConnect\Utilities\runtime\deploy.
3. In the deploy directory, paste the file CheckConnections.jar.

Jobs in the APM Connect Administration Center are run by users. The apmService user is required to facilitate communication between APM Connect and GE Digital APM.

1. In the APM Connect Administration Center, from the Menu pane, in the Settings section, select the Users tab, and then select Add.
2. In the Users pane, enter the user information into the empty fields as necessary according to the following table, and then select Save.

   Field	Description	Value
   Login	Email login for user	[email protected]
   First name	User first name	apm
   Last name	User last name	service
   Password	User password	apmConnect (default password)
   Type	Type of data migration	Data Integration/ESB
   Role	User role	Operation manager
   Active	Select check box to signify active user	Must select check box

A job is used to extract information from the source and push it into GE Digital APM. Before you can initiate a job using the APM Connect Administration Center, you must first load the jobs into the APM Connect Administration Center.

1. In the Menu pane, in the Conductor section, select the Job Conductor tab.
2. In the Job Conductor menu, select Add.

   The Execution task pane is enabled.

3. In the Execution task pane, in the Label box, enter a label for the job.
4. In the Description box, enter a description for the Job.
5. Select the Active check box.
6. In the Job section, select .
7. In the Import generated code window, select Browse, and then navigate to the folder containing the updated jobs package.
8. Depending on the type of deployment, select the file that contains the job based on the following tables.
   Note: You must import every job, or run the respective wrapper job, in the table for the respective deployment.

   Table 1. Maximo Adapter Jobs

   Job Name	Description
   CreateIntermediateRepository.zip	Creates the IR database.
   Extraction_Wrapper_Maximo.zip	Wrapper job for all Maximo Adapters allowing easy configuration of multiple Maximo Adapters jobs.

   Table 2. SAP and SAP PI Adapter Jobs

   Job Name	Description
   CreateIntermediateRepository.zip	Creates IR database.
   EncryptString.zip	Used to encrypt passwords.
   Extraction_Wrapper.zip	Wrapper job for all SAP Adapters allowing easy configuration of multiple SAP jobs.

   Table 3. SAP and SAP PI Cloud Adapter Jobs

   Job Name	Description
   CreateIntermediateRepository.zip	Creates Intermediate Repository database.
   Email_notifcation.zip	Allows for an email notification to be sent when a job or extraction fails. This report, the Failure Details report, provides the reason for why a record did not load.
   EncryptString.zip	Used to encrypt passwords.
   Extraction_Wrapper.zip	Wrapper job for all SAP Adapters allowing easy configuration of multiple SAP jobs. Note: This job can be used to run all of the Adapter jobs. It is recommended to use this job solely. Additionally, if you are using multiple SAP systems, you must use this job.

9. On the Import generated code window, select Launch upload.

   The Project, Branch, Name, Version, and Context boxes are automatically populated with appropriate values.

10. In the Execution Server list, select the server on which the task should be run.
11. Select Save.

    The Adapter Job is imported into the APM Connect Administration Center.

12. Repeat steps 2 through 11 for every job.

1. On the APM Connect server, locate Command Prompt
2. Right-click on Command Prompt, and then select Run as administrator.

   

   The Administrator: Command Prompt window appears.

3. Change the directory to: C:\APMConnect\Utilities\runtime\bin.
4. In the Command Prompt, after the new directory path, enter: trun.

   A message appears in the Command Prompt, and another karaf@trun> prefix appears.

   Note: When you first start Karaf, it takes a few minutes to load all of the commands. So, if you attempt to enter the features:install command in Step 5 and receive an error message in the Command Prompt, try the command again in a few minutes.

   
   
   
5. In the Command Prompt, after karaf@trun>, enter features:install wrapper.

   Another karaf@trun> prefix appears.

6. After karaf@trun>, enter wrapper:install -s AUTO_START -n APM-CONTAINER -d APM-Container -D "APM Container Service".

   A service wrapper feature is now installed into the Runtime Container, and a batch file is created in your local APM folder.

   Tip: On your local computer, navigate to your APM Connect folder: C:\APMConnect\runtime\deploy. Notice that your local APM Connect folder now contains two new items: APM-CONTAINER-service.bat and APM-CONTAINER-wrapper.exe.

   Another karaf@trun> prefix appears.

7. After karaf@trun>, enter shutdown, and then enter yes to confirm you want to shut down karaf.

   Karaf is shut down, and another karaf@trun> prefix appears and the directory is changed toC:\APMConnect\runtime\bin

8. After C:\APMConnect\runtime\bin , enter APM-CONTAINER-service.bat install.
   

   The APM Container is installed, and a message appears indicating as such.

9. To start the APM Container, restart your machine.