Installation and Deployment

Upgrade from any version V1.0.0 through V2.0.0

1. Uninstall APM Connect.
2. Complete the steps to deploy the APM Connect Base for the first time.

The topics outline 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 Predix Essentials system architecture.

1. On your APM Connect server, access the APM Connect installation package, navigate the Installer folder, and then open the package.
2. Double-click the file APMConnect-Base.exe.
3. On the message that asks if you want the installer to make changes to your machine, select Yes.
4. In the Setup - APM Connect window, select Next.
5. In the Select Destination Location window, select the destination to which you want to save the software by doing one of the following:
   • To select the default location (C:\APMConnect), just select Next.
   • To use a different location, navigate to the folder you want to use, select OK, and then select Next.
6. In the Select Components window, select the components to you want to install, and then select Next.
   • Install open Java Development Kit [Zulu 11.48.21] (uncheck if Zulu Java already installed)
   • Install PostgreSQL (required unless using external database): If you are using an external database configuration, clear the check box.
   • Install APM Connect Container (required unless already installed): If you have previously installed the APM Connect Container, clear the check box.
   • Install APM Connect JobServer (required unless already installed): If you have previously installed the APM Connect JobServer, clear the check box.
7. Select Next.

   The screen appears.

   

8. In the Select Start Menu Folder, select the folder where the Start Menu folder is saved by doing one of the following:
   • To select the default folder (APMConnect), select Next.
   • Navigate to the folder to which you want to save the Start Folder, select Ok, and then select Next.

   The Select Additional Tasks screen appears.

   

9. In the Select Additional Tasks window, select any additional tasks the installer should perform based on your APM Connect and the APM Connect components you are deploying, and then select Next.
   • Create a desktop shortcut: If you do not want to create a shortcut on your desktop, clear the box.
   • Set JAVA_HOME environment variable: If Java is already installed, and an environment variable does not need to be created, clear the check box.
   • Tomcat Windows service: If the Tomcat Windows service does not need to be created, clear the check box.
   • APMConnect Container service: If you don't want to install the APM Connect Container service, clear the check box.
   • Configure APMConnect Container service: If you don't want to configure the APM Connect Container service, clear the check box.
   • Install APM Connect Container service SAP JCO driver software: If your source system is SAP, select this check box.
   • Configure APM Connect JobServer Service: If you do not want to configure the APM Connect JobServer service, clear the check box.
10. Select Next.
11. In the Ready to Install window, review the items to be installed, and then select Install.

    If you selected Install APM Connect Container service SAP JCO driver software in the previous window, the Select the SAP JCO Driver Location window appears.

    Note: If you did not select Install APM Connect Container service SAP JCO driver software, the Select the Job Location screen appears, and you can proceed to Step 13.

SAP JCO driver installation:

12. Optional: In the Select the SAP JCO Driver Location window, in the SAP Bundle box, specify the location of the file sapjco3.jar, which is part of the SAP Java Connector Files (SAP JCO) that you downloaded from the SAP marketplace.
13. If you selected Install APM Connect Container service SAP JCO driver software in the previous window, the Select the SAP JCO Driver Location window appears.
    • To select the default location (C:\APMConnect\Downloaded Jobs Package), select Next.
    • To select a different location, select Browse..., navigate to the location where the jobs package is located, select OK, and then select Next.
    Note: The jobs package is not part of the APM Connect Installation package. Instead, you will receive it as a separate artifact (for example, download from a designated ftp site).

APM Connect set up:

14. In the Select the APMConnect License file window, select the folder that contains the APMConnect license.
    • To select the default location (C:\APMConnect\license), select Next.
    • To select another location, select Browse..., navigate and select the folder that contains the license, select Ok, and then select Next.
15. In the APMConnect Server Information window, in the Hostname: box, enter the name of your APM Connect server, and then select Next.

After the progress bar indicates that the APM Connect installer is finishing installation, the Java SE Development Kit installer starts.

Zulu JDK setup:

16. In the Zulu JDK - Setup Wizard window, select Next.
17. In the Custom Setup window, select Next.
18. In the Ready to Install window, select Install.
    The Zulu JDK installation progress bar appears. the screen appears.
19. In the Completed Zulu JDK window, select Finish.

    Java is installed.

20. A popup appears for the setup of the JavaHome environment variable. Select OK.
21. A command window appears to the setup of the JavaHome, After its completion Press any Key to Continue.
    Zulu Java is installed.

PostgreSQL setup:

22. In the Setup - PostgreSQL window, select Next.
23. In the Installation Directory window, select the location to install PostgreSQL.
    • If you are satisfied with the default location (C:\Program Files\PostgreSQL\11), select Next.
    • If you want to change the location where the software will be installed, select the button, navigate to the location where you want to install PostgreSQL for APM Connect, and then select Next.
24. In the Select Components Window Uncheck the Stack Builder, and select Next.
    
25. In the Data Directory window, select Next.

    The Password screen appears.

26. In the Password window, in the Password , and in the Retype password box, enter a password, and then select Next. Enter the password as postgres.
    Tip: This password will be used as a service account for PostgreSQL, and is needed in later configuration. Be sure to record it. If this password is changed necessary configurations will be required for TAC (Talend Application Center) setup to accept new password.Additionally, this documentation assumes admin as the password, and uses it in subsequent default configurations.
27. Select Next.
28. In the Port window, specify the port number. If you are satisfied with the default port,
    • To select the default port (5432) select Next.
    • In the Port box, enter the port on which you prefer the server to listen, and then select Next.
    Tip: The port number is needed in later configuration. Be sure to record it. Additionally, these instructions and all subsequent instructions assume that the default port 5432 is used.
29. In the Advanced Options window, select Next.
30. In the Pre Installation Summary window, Select Next.
31. In the Ready to Install window, Select Next.

    An installation progress bar appears.

32. After the installation bar indicates that the installation is complete, in the Completing the PostgreSQL Setup Wizard window appears. Select Finish.
    Note: After the database installation is complete, if a message appears asking you to restart your computer, select No to continue APM Connect installation.

Complete setup:

33. In the Completing the APM Connect Setup Wizard window, make sure Yes, restart the computer now is selected, and then select Finish.

    The APM Connect installer has completed its operations, and the machine should restart automatically.

34. Optional: If the machine does not do so automatically, restart your machine.

Using the APM Connect Administration Center, you can run extraction and load jobs. Before you can begin running jobs, you must set up the APM Connect Administration Center. This topic explains how to access and deploy the APM Connect Administration Center for the first time.

1. Open a web browser, and then enter the following URL into your web browser: http://localhost or hostname provided:8080/apmconnect/.
2. In the Data Parameters window (if it appears, refer to the Step 3), in the Password box, enter postgres, and then select OK.
3. If the TAC license file was not provided during the install step you will get the Database Parameters window to setup the license. If already provided you will get the APM Connect Login Page (Check step 5).
4. Select .

   The Database parameters window appears, and a check is performed by the APM Connect Administration Center.

   

   Important: If your license does not validate as shown in the previous image, you can validate your license manually.
5. If your license validates, in the Database parameters window, select Go to login page.

   The Login page appears.

   
6. In the Login window, enter the required information and then select Login.
   1. In the Login box, enter the default username: [email protected].
   2. In the Password box, enter the default password: admin.

   The APM Connect Administration Center is successfully deployed, and the APM Connect Administration Center Welcome page appears.

   
7. Add an APM Connect Service User using the following steps:
   1. Select Users in the Menu Pane, and then select Add.
   2. Add the following information:
      • Login ID – preferably an e-mail id. For example, [email protected]
      • First Name and Last Name – Add an identifier name
      • Password – Preferably admin or user defined
      • Type – Data Integration/ESB
      • For the Role select all the roles except Auditor
   3. Select Save.
8. Logout of the APM Connect Administration Center and then log back in as the Service user that you setup in Step 7 (For example, [email protected]/admin).
9. Select a Project on the Welcome page.
   Note: If no project is displayed you can add a new project titled APMCONNECT_UNIFIED_PLATFORM with Project Type value set as Data Integration/ESB and Storage value set as None.
10. In the Menu pane select Project Authorizations
    
11. In the Project section select the project APMCONNECT_UNIFIED_PLATFORM, and provide the Read and Write access to the newly created service user.
12. In the Menu pane select Servers to check the execution server details.
13. If no Server is displayed, then add a server with Label value set as JobServer and other values configured as shown below:
    
14. Select Save.
15. In the Menu pane select Job Conductors to check if any jobs are deployed.
    Note: If jobs are not deployed then the APM Connect jobs provided need to be deployed manually.

1. On the APM Connect server, go to the folder <root:>\APMConnect\.
2. Create a folder JobWatcher.
3. Create files named APMC_Service.properties and joblist.csv in the <root:>\APMConnect\JobWatcher folder according to the details given below.

   Enter the parameters in the APMC_Service.properties file as shown in the example below:

   Parameter	Description
   JOB_LIST=C:/APMConnect/JobWatcher/joblist.csv	Job list to monitor
   TAC_PWD=XXXXX	TAC password
   [email protected]	TAC user
   HOSTNAME=roaperflabvm3.meridium.com	TAC hostname
   LOCALUSER=Administrator	System user

   Enter the list of jobs that need to be triggered if not running in the joblist.csv file.

4. Navigate to the folder containing the updated jobs package and copy the jobWatcher.zip file.
5. On your APM Connect server, navigate to <root:>\APMConnect-jobMonitor and paste the jobWatcher.zip file.
6. Extract the contents of the jobWatcher.zip file.
7. Create a task JobWatcher_APMConnect in Windows Task Scheduler, and perform the following actions:
   1. Create a trigger that runs at startup, and another that runs on a daily schedule.
      Note: You can configure both triggers to repeat the task every five minutes indefinitely.
   2. Create an action to start a program. Browse for the jobWatcher_run.bat batch file.

To allow connections from the Predix Essentials Server to APM Connect, you must update the PostgreSQL networking configuration. This topic describes how to perform the configuration update.

1. On the machine on which you installed APM Connect, navigate to your PostgreSQL installation files. The default location is <root:>\Program Files\PostgreSQL\11\data.
2. Locate the configuration file pg_hba.conf, then right-click on the file, and then open it with a text editor.

   The file pg_hba.conf opens in the text editing application.

3. Scroll down to the end of the document and locate the following line of text: host all all 127.0.0.1/32 md5
   
4. Add a host all all statement specifying the IP address of the Predix Essentials Server using method md5.
5. Save the file, and then close the text editor.

1. Shut down Tomcat (Stop service: APMConnect_Tomcat).
2. Navigate to the Tomcat conf sub-folder, C:\APMConnect\tac\apache-tomcat-9.0.45\conf.
3. Take backup of server.xml and then edit the server.xml file.
4. Locate and uncomment the SSL-enabled HTTP connector (it is commented out by default).
5. Modify the connector config* as shown below:

    <Connector  
            protocol="org.apache.coyote.http11.Http11NioProtocol"   
            port="8443" maxThreads="200" 
            scheme="https" secure="true" SSLEnabled="true"  
            clientAuth="false" sslProtocol="TLS" 
            keystoreFile="full path to keystore file " 
            keystorePass="talend"/> 

   
6. Remove the tcnative-1.dll DLL from the Tomcat bin folder. You can move the file to an archive directory or rename it. For example, you can re-name it to tcnative-1.dll.DISABLED.
7. Restart Tomcat.
8. Navigate to the base Tomcat landing page over HTTPS, https://localhost:8443/apmconnect/ and check if the HTTPS protocol is supported.
   Note: If self-signed certificates are used, the browser displays the link as not secured. These keys are self-signed. In a production system, you should use a Certificate Authority (CA). For more information, refer to SSL/TLS Configuration How-To.

1. Shut down APM-CONTAINER. (Stop service: APM-CONTAINER)
2. Navigate to the runtime etc sub-folder, C:\APMConnect\runtime\etc\.
3. Take backup of org.ops4j.pax.web.cfg and edit org.ops4j.pax.web.cfg to change the highlighted parameters in the file.
   
4. Restart APM-CONTAINER service
5. Navigate to the base container landing page over HTTPS https://localhost:9001/services and check if the HTTPS protocol is supported.
6. Import the created .cer file into the Trusted Root Certification Authorities section .
7. Navigate to the Connection page and change the Connection String to https://localhost:9001/services.

1. Log in to your application, and then access the certificate information from your browser.
   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.
   The Export File Format window appears.
4. Select DER encoded binary X.509 (.cer), and then select Next.
   The File to Export window appears.
5. Select Browse….
   The Save As window appears.
6. Save the file to any temporary directory under the name certificate.cer. If you have a chain of certificates, you can import multiple certificates into a single truststore name, For example, cert1.cer, cert2.cer, certN.cer.
7. Select Next.
8. Select Finish.
   The Certificate Export Wizard window appears.
9. Select OK.
10. On the APM Connect server, access the Command Prompt window as an Administrator, and then navigate to the location of the %JAVA_HOME%/bin on your machine.
11. Enter keytool commands for the Key.
    Following command imports multiple certificates in to single keystore. If you have one certificate to import, use one command.

    keytool -import -alias cert1 -file C:\APMConnect\cert1.cer -keystore C:\ APMConnect \truststore.ts

    keytool -import -alias cert2 -file C:\ APMConnect \cert2.cer -keystore C:\ APMConnect \truststore.ts

    keytool -import -alias cert3 -file C:\ APMConnect \cert3.cer -keystore C:\ APMConnect \truststore.ts

    Certificate Management Tool appear in the Command Prompt.
12. Enter a password and then re-enter the password to confirm.
    In the Command Prompt window, you are asked if you want to trust the certificate.
13. For yes, enter y.
    The keystore file is created.
14. Copy truststore.ts file from C:\ APMConnect \truststore.ts.
15. Add the JVM Parameters in Karaf container configuration file, C:\APMConnect\runtime\etc\APM-CONTAINER-wrapper.conf.
    Locate # JVM Parameters in file and add the following parameter at last after 12the parameter:

    wrapper.java.additional.13=-Djavax.net.ssl.trustStore=“C:/APMConnect/runtime/etc/keystores/truststore.ts”

    wrapper.java.additional.14=-Djavax.net.ssl.trustStorePassword=”Password”

16. Access the Job Context file and Services Configuration files, 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.
17. Restart the APM-Container services.

Before you can upgrade the APM Connect Base, you must uninstall your current version of APM Connect.

1. On the APM Connect server, access the Uninstall or Change a Program section of the Control Panel.
2. Select APMConnect <version>, right-click, and then select Uninstall.
3. Access the Uninstall or Change a Program section of the Control Panel again, select the Java programs (for example, Java 1.7.71 and Java SE Development Kit 1.7.71), right-click, and then select Uninstall.
4. On the APM Connect server, locate the folder C:\APMConnect, and then delete it.
   Tip: If files are locked and prevent you from deleting this folder, you may need to restart the APM Connect server machine.
5. Restart the APM Connect server machine.

   APM Connect is uninstalled.