• Starter
• Business
• Enterprise
• On-Premise
• Add-on

Overview

This article outlines how to install, configure and monitor the remote Integration Agent. 

Add new Integration Agent

Step 1. Open Agentswindow. Click Add button.

Step 2. Enter the Agent name, click Save.

Download and install the Integration Agent

Install the Integration Agent on Windows

Step 1. In Agentswindow select previously created Integration Agent. 

Step 2. Click Downloadat the bottom of the screen.

Step 3. Select Windowstab. Click Agentbutton.

Step 4. Run the downloaded installer.

Step 5. Enter your Etlworks Integrator User ID (or email) and the Etlworks Integrator cloud instance URL.

Install the Integration Agent on Linux

You must have Java 8 installed on a Linux box. Once you are done installing Java 8, proceed to the following:

Step 1. In Agentswindow select previously created Integration Agent. 

Step 2. Click Downloadat the bottom of the screen.

Step 3. Select Linuxtab.

Step 4. Click Agentbutton.

Step 5. Create a folder for the agent in the hard drive, for example, /opt/agent.

Step 6. Extract the archive file into this folder.

Install a license

The Windows and Linux installers require an online license.

To obtain and install the license:

Step 1. Open Agentswindow. Select the Agent to download the license for. 

Step 2. Click Downloadat the bottom of the screen.

Step 3. Click Licensein the first tab. The licenses for Windows and Linux are the same.

 

Step 4. Check if Agent is running:

Step 5. If Integration Agent is running stop Agent service:

Windows

Linux

Step 6. Copy the license file into the AGENT_HOME/license.

Step 7. Start Agent service:

Windows

Linux

Configure the Integration Agent to run as a Windows Service

By default, the Windows installer already installs the Integration Agent as a Windows Service so this step is optional.

If you will ever need to re-install Integration Agent as a Windows Service here are the steps:

1. Open elevated Command Prompt (Admin).
2. cd into the directory where you have installed the agent, for example, cd c:\integration-agent.
3. Execute install.cmd.
4. Verify that service is installed by opening the Services desktop app. There must be a service with the name IntegrationAgent and description Etlworks LLC. Integration Agent.

Remove the Windows Service

Here's how you can do this:

1. Open elevated Command Prompt (Admin).
2. cd into the directory where you have installed the agent, for example, cd c:\agent.
3. Execute remove.cmd.
4. Verify that service is no longer in the list of the available Windows Services.

Start and stop the Windows Service

Stop agent using Etlworks Integrator

1. Check if the Agent is running.

2. If it is running click the Online link, then click the Stop button.

3. The text in the STATUS column should change to Offline.

Start/stop agent using the command line

Here's how to start:

1. Open elevated Command Prompt (Admin).
2. cd into the directory where you installed the agent, for example cd c:\integration-agent.
3. Execute start.cmd.

Here's how to stop:

1. Open elevated Command Prompt (Admin).
2. cd into the directory where you installed the agent, for example cd c:\integration-agent.
3. Execute stop.cmd.

Start/stop agent using the Windows Services desktop app

Here's how to start:

1. Open the Services desktop app.
2. Locate IntegrationAgent.
3. Choose the service name and click Start.

Here's how to stop:

1. Open the  Services desktop app.
2. Locate IntegrationAgent.
3. Choose the service name and click Start.

Change JRE and JVM memory parameters in Windows

The Agent (Windows versions) is bundled with the JRE (Java Runtime Environment). JRE and JVM memory parameters are configured in AGENT_HOME/install.cmd.

set JAVA_HOME=%PR_PATH%\jre
set PR_JVM=%JAVA_HOME%\bin\server\jvm.dll
set PR_JVMOPTIONS=-Xmx3000m

You can change the JRE to any valid JRE installed in the machine (must be Java 8). Similarly, you can also change the maximum memory that JVM can allocate. The default is 3000 MB which might not be enough if you are going to processing large datasets.

Change the JRE or JVM memory parameters

Here's how you can do this:

1. Stop the Windows Service.
2. Modify AGENT_HOME/install.cmd and save it.
3. Start the Windows Service.

Configure the Integration Agent to run as a Linux Service

Amazon Linux on AWS and CentOS

Here's how you can do this:

1. Install jsvc: sudo yum install jsvc.
2. Copy provided integrationagent file into the /etc/init.d folder.
3. If needed, modify /etc/init.d/integrationagent file using commands specific to your Linux distro. To edit the file, you can use the following command:
   sudo sed -i -e 's/\r//g' /etc/init.d/integrationagent
   For example, you might need to modify the JAVA_HOME variable or JVM parameters.
4. Make sure that integrationagent is executable: chmod +x /etc/init.d/integrationagent.

Ubuntu

Here's how you can do this:

1. Install jsvc: sudo apt-get install jsvc.
2. Copy provided integrationagent file into the /etc/init.d folder.
3. Modify /etc/init.d/integrationagent:

    ## Source function library for Amazon Linux.
   
    #. /etc/rc.d/init.d/functions <- comment out this line
   
    ## Source function library for Ubuntu Linux.
   
    . /lib/lsb/init-functions <- uncomment this line

   You might also need to modify the JAVA_HOME variable or JVM parameters.
4. Make sure that integrationagent is executable: chmod +x /etc/init.d/integrationagent.

Start and stop Linux Service

Here's how to start:

1. Open the terminal.
2. sudo service integrationagent start.

Here's how to stop:

1. Open the terminal.
2. sudo service integrationagent stop.

Change JRE and JVM memory parameters in Linux

Here's how you can do this:

1. Open /etc/init.d/integrationagent in any editor.
   For example:
   sudo sed -i -e 's/\r//g' /etc/init.d/integrationagent
2. Modify JAVA_HOME and/or JAVA_OPTS.
3. Click Save.
4. sudo service integrationagent stop.
5. sudo service integrationagent start.

Run the Integration Agent as a standalone app

Typically the Integration Agent runs as a Windows or Linux service. It is however possible to run as a standalone application.

Windows

1. Open elevated Command Prompt (Admin).
2. cd into the directory where you installed the agent, for example cd c:\integration-agent.
3. Execute integrationagent.exe standalone.

Cross-platform (Linux, OS/X, Windows) 

Make sure that the default Java version is Java 1.8. To confirm run java -versionin the terminal. The output should be Java(TM) SE Runtime Environment (build 1.8.0_build).

1. Open terminal.
2. cd into the directory where you installed the agent.
3. Execute java -jar integrationagent.jar standalone.

Configure the Integration Agent

After installing the Integration Agent as a service, it is fully functional and ready to go.

Later you can configure notifications, monitoring, and other parameters.

To configure the Integrator Agent (note the Agent can be running):

Step 1. In Agentswindow select previously created Integration Agent. 

Step 2. Select the Parameters tab.

Step 3. Modify parameters and click the Save button. If the Agent is running it will reconfigure itself at runtime. If the Agent is not running it will apply configuration changes on the next restart.  

Configuration parameters

Email

This group of parameters is used to configure the SMTP sender which sends email notifications on the specific events. 

• SMTP Host: SMTP Hostname that should be used to send emails from the agent.
• SMTP Port: SMTP Port that should be used to send emails from the agent.
• SMTP User: SMTP User that should be used to send emails from the agent.
• SMTP Password: SMTP Password that should be used to send emails from the agent.
• FROM: the email address that will be used to send emails from.
• TO: the comma-separated list of email addresses that should receive notifications.
• CC: the comma-separated list of email addresses that should be added to CC.
• BCC: the comma-separated list of email addresses that should be added to BCC.
• TLS Enabled: switch the connection to a TLS-protected.

Notifications

Use this group of parameters to enable email notifications for specific events.

The SMTP sender must be configured.

• On Success: if this parameter is enabled and the SMTP sender is configured the agent will send email notification on each successful flow execution.
• On Fail: if this parameter is enabled and the SMTP sender is configured the agent will send an email notification on each failed flow execution.
• On Shutdown: if this parameter is enabled and the SMTP sender is configured the agent will send email notification on shutdown.
• On License Issue: if this parameter is enabled and the SMTP sender is configured the agent will send an email notification on any issue related to the license verification.
• On Status Change: if this parameter is enabled and the SMTP sender is configured the agent will send email notification on any status change, including reaching and clearing dangerous thresholds.   

Web Server

This group of parameters is used to configure the Web Server embedded into the Integration Agent. The Web Server is used to display the Integration Agent dashboard when running the Agent on-premise.

• Web Server Enabled: enable or disable the embedded webserver.
• Host: the webserver hostname or IP address.
• Port: the webserver port number.

Monitoring

This group of parameters is used to set warning and critical thresholds (in %) for the health status of the agent. 

• Memory Utilization High Threshold (%): once memory utilization reaches configured in this field threshold the agent's status will be changed to warning. The default is 80%.
• Memory Utilization Critical Threshold (%): once memory utilization reaches configured in this field threshold the agent's status will be changed to critical. The default is 90%.
• Error Ratio High Threshold (%): once the number of errors compared to successful executions reaches configured in this field threshold the agent's status will be changed to warning. The default is 10%.
• Error Ratio Critical Threshold (%): once the number of errors compared to successful executions reaches configured in this field threshold the agent's status will be changed to critical. The default is 25%.

Logging

This group of parameters is used to configure how the Integration Agent uploads logs to the cloud Etlworks Integrator.

• Upload console log files: if this parameter is enabled the Agent uploads each Flow executing log to the cloud Etlworks Integrator. The parameter is disabled by default. The console logs can be viewed in the Flow Statistics dashboard. 
• Maximum log file size to upload (MB): log files with size over a specified amount in MB will not be uploaded. Note that this configuration can be limited by outside factors, such as the file upload limit set on the network proxy side.

Miscellaneous

This group of parameters is used to configure time-outs.  

• Shutdown time out (ms): the shutdown time out is how long the Integration Agent waits for the running flows to finish before it initiates the shutdown sequence. Encreasing the timeout will give running flows more time to finish but will increase the agent's shutdown time.  Note that prior to shutting down the Agent will attempt to cancel currently running flows. Most flows will stop almost immediately but if the flow is busy it can take minutes.  The default value for this parameter is 300000ms which is 5 minutes.
• Agent Ping Delay (seconds): the amount of delay in seconds between consecutive calls from the Agent to the Etlworks Integrator instance to get the latest configurations and report status. Decreasing the value of this parameter will make the Integration Agent more responsive but will increase the chatter between the Agent and the Etlworks Integrator instance. The default value for this parameter is 1 minute.

Upgrade the Integration Agent to the latest version

To upgrade the Integration Agent to the latest version:

Step 1. Open Agentswindow. 

Step 2. Select any Agent and click Downloadat the bottom of the screen.

Step 3. Select Windows or Linuxtab.

Step 4. Click Agent update.

Step 2. If the Integration Agent is running Stop Agent service:

Windows

Linux

Step 3. Delete content of the lib folder and copy content lib folder in the zip file into AGENT_HOME/lib. 

Step 4. Start Agent service:

Windows

Linux

Monitor the Integration Agent

Agent's status

Each running Integration Agent reports status to the host Etlworks Integrator once a minute. Use Agent Ping Delayto change the frequency. 

The status of the specific Integration Agent is displayed in the grid under the STATUS column.

Available statuses

• Offline: the Agent is offline (not running)
• Online: the Agent is online (running and the scheduler is enabled).
• Online (suspended): the Agent is online but the scheduler is suspended, hence no Flows can be executed automatically by the Agent. It is still possible to execute Flows manually.

Agent's Dashboard

The Agent's Dashboard displays information about various statuses, scheduler, JVM, and running flows.   

To open the Agent's Dashboard click status link in the Agents window.

The status of the Agent recorded during the latest communication session will be displayed in the popup window.

Email notifications

Notifications can be sent by the Agent or by the Etlworks instance.

Configure Agent to send email notifications

You can configure the following email notifications. To receive notifications the SMPT email sender must be configured. 

• On Success: if this parameter is enabled and the SMTP sender is configured the agent will send email notification on each successful flow execution.
• On Fail: if this parameter is enabled and the SMTP sender is configured the agent will send an email notification on each failed flow execution.
• On Shutdown: if this parameter is enabled and the SMTP sender is configured the agent will send email notification on shutdown.
• On License Issue: if this parameter is enabled and the SMTP sender is configured the agent will send an email notification on any issue related to the license verification.
• On Status Change: if this parameter is enabled and the SMTP sender is configured the agent will send email notification on any status change, including reaching and clearing dangerous thresholds.  

Configure Etlworks instance to send email notifications

Step 1. Make sure the SMTP sender is configured under Configuration->Email.

Step 2. Click Configure flow notifications.

Step 3. Enable notifications and enter the email address(s) to receive notifications. 

Stop the Integration Agent

To request Integration Agent to stop open the Agent's Dashboard by clicking status link in the Agents window, then click the Stopbutton. Note that is not possible to request a stop for the Agent which has been already stopped or requested to stop. 

Confirm that you really wish to stop the Agent.

 

Suspend the Integration Agent

The Integration Agent can be suspended. In this mode, the Agent is running but no Flow can be executed automatically by the scheduler.  Note that in this mode it is still possible to execute Flows manually. Use this mode to debug issues with the Agent.   

To suspend the Agent:

Step 1. In Agentswindow select previously created Integration Agent. 

Step 2. Enable Suspended at the bottom of the screen. Click Savebutton. 

Actions Queue

When the user triggers any action, such as Run Flow, Stop Flow, Stop Agent the action is added to the queue. The actions in a queue are executed in order on the next communication session between the Agent and the Etlworks Integrator.  

View Actions

If there are actions in a queue the View Actions button becomes green.

Click the button the see the actions. 

From there you can:

• Remove the action from the queue.
• Check the estimated time when the top action in a queue will be executed.