Deployment

Upgrade from any version V1.0.0 through V1.0.3

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 GE Digital APM system architecture.

1. On your APM Connect server, access your APM Connect installation package, and then navigate to the Jobs folder.
2. Right-click on the folder ApplyThirdPartySoftware_0.1.zip, and then select Extract All.
3. In the Extract Compressed (Zipped) Folders window, select Extract.

   The files are extracted, and the folder ApplyThirdPartySoftware_0.1 appears in the same directory.

4. Download the third-party software files, and then create a directory on the APM Connect server containing those files.
5. Open a command prompt, and navigate to <root>ApplyThirdPartySoftware_0.1\ApplyThirdPartySoftware.
6. Enter the following command: ApplyThirdPartySoftware_run.bat --context_param JOBS_DIR=<JOB PACKAGE DIR> --context_param THIRD_PARTY_SOFTWARE_DIR=<YOUR THIRD_PARTY_SOFTWARE_DIR>.
   • <JOB PACKAGE DIR>: Replace with the filepath to the directory that contains the job zip files (for example, C:/APMConnect/Jobs).
   • <YOUR THIRD_PARTY_SOFTWARE_DIR>: Replace with the filepath for the directory that you created in step 4 (for example, C:/APMConnect/ThirdPartySoftware).

   Tip: When entering a directory in a command prompt window, the file path must use the forward slashes.

   The adapter jobs are updated with the third-party software component, and a message indicating that the update is complete appears in the command prompt window. Additionally, a new folder is created: updated_jobs.

   Note: The jobs contained in the updated_jobs folder are the jobs that you will use to facilitate the data transfer from the source to GE Digital APM.

   
   
   

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 Oracle Java JDK 1.8 (uncheck if java already installed): If Java JDK 1.8 is already installed on your machine, clear the check box.
   • 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.
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.
   • APMConnect Services: If the APM Connect Services do not need to be installed, 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.
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.
    • 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:

13. 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.
14. 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.

Java SDK setup:

15. In the Java SE Development Kit <JAVA_VERSION_NUMBER> - Setup window, select Next.
16. In the Select optional features to install window, select Next.

    The Java installation progress bar appears. the screen appears.

17. When the progress bar indicates that the process is complete, in the Destination Folder window, select Next to install Java in the default location.
    Important: These instructions assume that Java is installed in the default location.
18. After the progress bar indicates that the installation is complete, in the Successfully Installed Java SE Development Kit <JAVA_VERSION_NUMBER> window, select Close.

    Java is installed.

19. In the command prompt, press any key to continue.
20. In the Setup window, select OK.

PostgreSQL setup:

21. In the Setup - PostgreSQL window, select Next.
22. In the Installation Directory window, select the location to install PostgreSQL.
    • If you are satisfied with the default location (C:\Program Files\PostgreSQL\9.6), 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.
23. In the Data Directory window, select Next.

    The Password screen appears.

24. In the Password window, in the Password , and in the Retype password box, enter a password, and then select Next.
    Tip: This password will be used as a service account for PostgreSQL, and is needed in later configuration. Be sure to record it. Additionally, this documentation assumes admin as the password, and uses it in subsequent default configurations.
25. Select .
26. 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.
27. In the Advanced Options window, select Next.
28. In the Ready to Install window, Select Next.

    An installation progress bar appears. screen appears.

29. After the installation bar indicates that the installation is complete, in the Completing the PostgreSQL Setup Wizard window, clear the Stack Builder may be used to download and install additional tools, drivers and applications to complement your PostgreSQL installation check box, and then select Finish.

Complete setup:

30. 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.

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

Passwords in the context file are not encrypted by default. However, you can manually encrypt any password manually. This topic describes how to encrypt passwords.

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

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

3. Enter the password 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. Save the context file.
9. Repeat Steps 2-8 for all of the passwords you want to encrypt.

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:8080/apmconnect/.
2. In the Login window, in the Password box, enter admin, and then select OK.
3. 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.
4. If your license validates, in the Database parameters window, select Go to login page.

   The Login page appears.

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

Results

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

1. On the APM Connect server, if the service is running, stop the APM Connect service.
2. Navigate to C:\APMConnect\Utilities\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 RunDataLoaderRoute.kar file.
2. Navigate to the following path: <root:>\APMConnect\Utilities\runtime\deploy.
3. Right-click inside the folder, and then select Paste to copy the .kar 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\Utilities\runtime\bin. 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\Utilities\runtime\bin

8. After c:\APMConnect\Utilities\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 server, access the GE Digital APM distribution package, navigate to the folder \\Setup\Meridium APM Server and Add-ons, and then double-click the file Setup.exe.
2. Double-click the file .
3. In the Welcome window, select Next.
4. In the License Agreement window, read the License Agreement and, if you agree, select the I accept the terms of the license agreement check box, and then select Next.

   The screen appears.

5. In the Select Installation Location window, select Next to accept the default location.
6. In the Select the features you want to install window, select the Meridium Integration Services option, and then select Next.
   Note: While additional options are available for selection, these options are not meant to be installed on this server. These instructions assume that you want to install only Meridium Integration Services.
7. Select Next.
8. In the Websites window, select Next.
9. In the Complete the Installation window, select Install.

   The Setup Status window appears, displaying a progress bar.

10. In the Installation is complete screen window, select Finish.

    The Meridium Integration Services installation is complete.

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.

To allow connections from the GE Digital APM 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\9.3\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 GE Digital APM Server using method md5.
5. Save the file, and then close the text editor.

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.

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:8080/apmconnect/.
2. In the Login window, in the Password box, enter admin, and then select OK.
3. 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.
4. If your license validates, in the Database parameters window, select Go to login page.

   The Login page appears.

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

Results

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

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.

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 Services section of the Control Panel (in the Administrative Tools section of System and Security) and stop the following services:
   • APM-CONTAINER
   • 7.0.57 APMConnect_Tomcat
4. 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.
5. 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.
6. Access the Command Prompt window, and run the following commands:
   • SC DELETE APM-CONTAINER
   • SC DELETE APMConnect_Tomcat
7. Restart the APM Connect server machine.

   APM Connect is uninstalled.