Install Local Connector

Last modified by Danniar Firdausy on 2024/07/09 14:48

Note that the functionality mentioned in this microlearning will become obsolete when migrating to the new generation runtime.

In this microlearning, we will focus on installing the eMagiz environment locally
Should you have any questions, please contact academy@emagiz.com.

1. Prerequisites

To install a runtime, please be aware that eMagiz needs an environment that satisfies certain requirements. These requirements can be different depending on your architectural choices. Most common is the connector inside your network and a JMS and container running outside the network. In that case, if you are running only connectors in this environment, please keep the following requirements in mind:

  • OS with support for Java
  • OS user with granted security rights to run startup services (Windows services)
  • The correct Java installation (Java 8 SE JRE for example) with NO automatic updates. OpenJDK 8 is currently the recommended version for eMagiz installations.
  • NTP synchronization – all eMagiz service instances should use the same time and settings.
  • Access to the internet
  • Outbound JMS traffic - port 8443 (and 8444 in case of failover situation) - amqp.emagiz.com / cloudXXXX.emagizcloud.com
    • General monitoring data to eMagiz iPaaS
    • Specific JMS traffic to eMagiz JMS Server
  • Outbound HTTPS traffic
  • Hardware requirements
    • Modern CPU
    • Enough Disk Space according to sizing calculations
  • Enough Memory according to sizing calculations
  • JAVA_HOME variable is properly set

2. Key concepts

eMagiz uses a runtime component as a container where flow components can be deployed in. There are infrastructure components that act as flows, and there are functional flow components. Furthermore, there are routing and error flows. By deploying these runtimes across various locations across the integration architecture, you can make these flows work as a chain to realize a complete integration. In the platform training, you need to use the JMS runtime and container runtime and make this run on your local machine.

3. Run eMagiz on a local laptop

3.1 Run eMagiz on a local laptop

Download the eMagiz runtime of your connector, JMS, or container via the eMagiz Deploy phase in the Containers tab on the server where it needs to be installed. Please note the environment you want the runtime of. If you download the runtime of the wrong environment you will send to or receive data from the wrong environment. For example, you want to test a flow but by downloading the runtime from the incorrect environment you end up sending data to the Production environment. In the case below, we see that we are downloading a connector runtime ordsys for the Test environment.

crashcourse-platform-deploy-install-local-connector--download-runtime.png

3.2 Unzip the runtime

Now that we have downloaded the zip it is time to unzip your download package into a directory that is not too deep into the directory structure.
A directory structure that is too deep will cause issues when extracting the runtime.
You could for example use: C://eMagiz/test but it is best to not use: C://Programs/eMagiz/test/connector/appeee/installation

After you have unpackaged the zip you need to open the folder to access its contents.

3.3 Run the runtime

In the Bin folder, you can validate if the service can make a connection via karaf.bat. To check the connection of the service, use the right mouse button then execute the file as Administrator. Please make sure that before you try this you verify that your JMS is running.

crashcourse-platform-deploy-install-local-connector--run-karaf-as-admin.png

A screen will pop up and will show you the following.

crashcourse-platform-deploy-install-local-connector--karaf-pop-up.png

Use the command ‘log:tail’ to see the full log. You will see the full stack trace. If the installation is successful, you should see something like this as a result:

org.eclipse.gemini.blueprint.extender - 2.1.0.RELEASE |  Application context successfully refreshed ApplicationContext(bundle=nl.capesystemsintegration.demo.bus.commupd.ordsys.connector-infra.spring, config=nl.capesystemsintegration.demo.bus.commupd.ordsys.connector-infra.spring_1.0.0.52.xml))

If you see the expected logging, verify in eMagiz if:

  • You can reach the runtime via the runtime dashboard.
  • You see runtime statistics in Manage.

If you see an error or the popup closes itself immediately, please check the above steps and requirements. If the popup closes this is probably due to a mismatch between the Java version and runtime version. Please look back at the section explaining how to set JAVA_HOME for more information. If all the above steps are correct and you are not able to identify the issue, please contact your implementation partner.

4. Key takeaways

  • eMagiz has a runtime software component that allows running flows inside. It is generic for all types of flows that exist in eMagiz
  • Using the JMS and the Container runtimes created by the eMagiz Portal, you can test your work properly during the microlearning training sessions
  • Above instructions are also valid for making the installation on a server where a runtime needs to be deployed locally.

5. Suggested additional readings

If you are interested in this topic and want more information on it you can read the following microlearnings: