Agents

3. Installing Integration Manager : Additional Installation Options : Agents

Share this page

Agents

Our agent technology allows centralized cloud management of on-premise integration jobs and related collateral. It allows secure cloud-to-communication without special firewall rules or VPN.

The following scenarios are candidates for executing an integration with the agent:

• Database connections that require drivers (such as ODBC) or connections on an internal network

• Web-based services that are housed internally and are not externally available

• Using source or target files that are located on an internal network

Agent System Requirements

Actian DataCloud Agent has the following system requirements.

Operating System and Software

• Microsoft Windows Server 2008 R2 (64-bit U.S. English edition) or later

• Java Runtime Environment 8 or higher

Hardware

Systems running DataCloud Agent should meet the following requirements:

• Multicore 64-bit processor, x86-64, 2 GHz or faster

• 40 GB free hard drive space

• 8 GB high-speed RAM minimum

• Outbound connection to the Internet

Note: The hardware requirements for the DataCloud Agent are comparable to those for the Standalone Engine package of Data Integrator. The Agent includes the standalone engine for local execution of integrations.

Installing Agents

Before You Begin

Observe the following points before you begin installing the DataCloud Agent.

• If you install the DataCloud Agent on a machine that is also running one of the following DataConnect services, you may incur additional configuration requirements to avoid conflicts:

– DataConnect Design Studio

– Integration Manager

– Standalone Engine

• You must initially log in to Integration Manager from the Agent to grant access to run jobs on your behalf. Ensure this access is available.

• Copy the installer to your local machine. Do not install over a network.

Network Port Access

The DataCloud Agent requires that the following ports be available on the machine where you are installing the Agent.

Port	Service	Inbound/Outbound	Local/Remote	Description
443	HTTP Secure	Inbound and Outbound	Remote	Secure HTTP port. Used to connect to the DataCloud for transmission of secure data.
9191	HTTP Connection	Inbound and Outbound	Local	Used internally by DataCloud Agent for the local administration and authentication page. These ports can be changed during installation. To change the ports after installation, see Agent Settings.
9192	HTTP Shutdown	Inbound and Outbound	Local

Installing on Windows

To install DataCloud Agent on Microsoft Windows

1. Download the latest DataCloud Agent installer from the Agents tab in Integration Manager.

2. Log in to Windows as either the Administrator user or a member of the Administrators user group.

3. Right-click on the installer, choose Run as Administrator, and then click Next. The installer file name is agent-dx-win64.exe.

4. Click Next to begin the installation.

5. Make changes to the Connection and Shutdown ports if needed.

6. Click Install.

The installer extracts the DataCloud Agent and installs the service.

7. Click Close when the installation is complete.

8. Launch the Agent Settings shortcut on your desktop.

9. Enter your DataCloud credentials and then click Authorize.

After the installation is complete, the agent runs as a Windows service called DataCloudAgent.

Licensing

DataCloud Agent does not require its own license. It will confirm with DataCloud that you have a cloud-enabled entitlement.

Installation Locations

DataCloud Agent installs data in the following locations:

Location	Purpose
C:\Program Files\Actian\Agent\Application\logs\Agent.log	Holds any logging related to the Agent core
C:\Program Files\Actian\Agent\Application\conf\Agent.properties	Contains configuration information for the Agent core (that is, logging, locations for API, and so on).
C:\Program Files\Actian\Agent\AgentInstaller.log	Holds any logging related to the Installation process
C:\ProgramData\Actian\Agent\EngineData	Holds execution engine logs and other internal data
C:\ProgramData\Actian\Agent\JobArtifacts	Holds artifacts and files downloaded from the cloud that are to be executed
C:\ProgramData\Actian\Agent\JobLogs	Staging area for logs before they are uploaded to the DataCloud

Uninstalling from Windows

Use the Windows Control Panel to uninstall DataCloud Agent.

To uninstall the agent

1. Open the Windows Control Panel.

2. Click Uninstall a program.

3. Select DataCloud Agent from the list of installed programs.

4. Click the Uninstall button to launch the wizard.

5. In the uninstallation wizard, click Uninstall.

6. Click Finish when the uninstallation is complete.

Managing the Agent

The DataCloud Agent service is managed through Windows Services Manager.

To manage the service

1. Open the Windows Control Panel.

2. Click System and Security and then go to Administrative Tools.

3. Double-click on Services.

4. Select Actian DataCloud Agent from the list of services.

5. Use the Start, Stop, and Restart links to manage the service.

To change the Windows account that runs the Agent

1. Log on to Windows on the machine running the Agent using the Administrator account.

2. Open the Server Manager.

3. Under Configuration, select Services.

4. Stop the Actian DataCloud Agent service.

5. Right-click on the Actian DataCloud Agent service and then select Properties.

6. Select the Log On tab.

7. Select the This Account option.

8. Enter the login credentials for the appropriate domain account.

9. Click Apply and then OK.

10. Start the Actian DataCloud Agent service.

Using DataCloud Agent

Jobs are scheduled and run using the DataCloud Agent through the Integration Manager console (powered by DataCloud). Log in to Integration Manager as an administrator or with the same user credentials used to register the agent.

Running Integrations with the Agent

You can configure specific integrations to run using the agent instead of running on the cloud. This gives the integrations access to files and databases from the system running the agent.

To configure an integration to run on the agent

1. Select the Templates tab in the Integration Manager console.

2. Create a new job template or select an existing one.

3. Set the Run on property from Cloud to Agent.

4. Create a new job config for the template.

5. Set the package, entry point, and enter any necessary parameters for the integration.

After you have created your template and a configuration, you can set a schedule or use the Run Configuration Now /download/attachments/7503963/cloud_run_now.png?version=1&modificationDate=1372799956000&api=v2

button to execute the integration.

Note: When you run a configuration, it executes on the configuration owner’s agent.

Agent Status

Click on the Agents tab in the Integration Manager console to see a list of the agents associated with your account. This view shows the registration, check-in, and status information for each agent.

Icon	Status	Description
	Online	The agent is online as of the last check-in time and is ready to receive jobs.
	Updating	The agent is being updated.
	Warning	The agent has not reported back to DataCloud in over 3 hours and requires attention.
	Error	The agent has not reported back to DataCloud in over 6 hours and requires attention.
	Offline	The agent is currently offline.

Tip: The Status field indicates the health of the agent and whether it can accept any commands from the cloud. If this status is a red “Error” state, you will not be able to submit jobs until the problem is resolved.

Managing Agents

The Actions drop-down menu for each agent lets you perform the following actions for the agents connected to your DataCloud account.

Action	Description
Update License	Sends the current Agent license from the DataCloud
Update Engine	Updates the processing engine in the agent to the latest version
Update Agent	Updates the agent framework to the latest version
Deregister	Revokes the Agent’s access to your account and sends a shutdown command to the remote service

Note: The agent must be in Online status for the Update License, Update Engine, or Update Agent actions to take effect.

Viewing Agent Logs

Agent logs are uploaded to Integration Manager upon job completion.

Logs also are temporarily stored locally in <installation>/Application/logs/Agent.log. If you report issues to Actian Support, you may be asked to send these logs to provide more information about problems the agent has encountered.

Updating DataCloud Agent

After you have installed Actian DataCloud Agent, you can use the Integration Manager console to perform updates at any time.

Note: The Agent license automatically updates weekly. The Agent service and engine do not automatically update.

When to Update

The DataCloud Agent uses a local version of the execution engine to run integrations transmitted from your DataCloud account.

If you have designed your integration using the current version of Design Studio but your Agent is still using an older version of the engine, this could cause compatibility issues when it comes time for your integration to run on the Agent.

Best Practice — Update your Agent and engine whenever you schedule a newly deployed integration to run using the Agent.

Updating the Agent

Before you begin the update process, make sure the computer running the Agent is connected to a constant power source (not running on battery power as in the case of a laptop). If the computer loses power or crashes during the update process, reinstall the agent manually. See Installing Agents.

To update the Agent service, engine, and license

1. Log in to the Integration Manager console.

2. Open the Agents page.

3. Locate your agent in the table.

4. Ensure the version (listed in the Version column) is 3.0.0 or higher.

5. Click the Actions drop-down menu and then select the appropriate option:

• Update Agent: Updates the Agent service and execution engine

• Update Engine: Updates the execution engine used by the Agent for running jobs

• Update License: Updates the engine license to the latest available for your account

Note: You might need to restart the Agent service after the update. See Managing the Agent.

Accessing On-premise File Storage with Agent

A common scenario for using DataCloud Agent to execute an integration is when you need to read or write a file stored either locally or on a network.

By default, the Agent runs using the Windows Local System account. This is usually sufficient to access files stored on the same machine as the Agent.

Files stored on a network require changing the account running the DataCloud Agent to use an account that has proper access to the network share (usually a domain account for the network). See Managing the Agent.

Tip: When designating a network resource during design, use the full network path (for example, \\servername\folder\filename.csv).

Agent Settings

DataCloud Account Management

The Agent installer adds an icon to your desktop to access the local Agent management page to set your DataCloud credentials.

Open the Agent Settings shortcut or go to http://localhost:9191/agent/settings in a browser on the computer running the Agent to access the Agent settings page.

Changing Ports

After installation, you can change the ports used by the local configuration page.

To change configuration ports

1. Log in to Windows as Administrator.

2. Open the following file using a text editor:

C:\Program Files\Actian\Agent\Application\conf\server.xml

3. To change the HTTP Connection port, edit the port value in the following section:

4. To change the HTTP shutdown port, edit the port value in the following line:

5. Save the changes to the file.

6. Restart the Agent service. See Managing the Agent.

Concurrent Execution

By default, the Agent executes one job at a time, with additional jobs going into the job queue. You can change this setting for the Agent to allow up to 4 concurrent executions (one concurrent execution per integration).

Caution! When the Agent operates in non-concurrent mode, jobs are executed by first-in-first-out (FIFO) order. If you allow concurrent executions, however, the jobs may not be executed in the order they were submitted. When designing your integrations, ensure you do not introduce dependencies that could lead to unexpected results if the jobs are executed out of order.

To change the concurrency setting

1. Log in to Windows as Administrator.

2. Open the following file using a text editor:

C:\Program Files\Actian\Agent\Application\conf\Agent.properties

3. Edit the following line to change the maximum concurrent executions to a value between 1 and 4.

agent.concurrency = 1

4. Save the changes to the file.

5. Restart the Agent service. See Managing the Agent.

Caution! Use care when editing the Agent.properties file. The Agent uses this file to locate its execution engine and connect to the DataCloud. Inadvertent changes could cause the Agent to stop working.

Best Practices for Using an Agent

To ensure your use of the Actian DataCloud Agent is successful, here are some important concepts and best practices.

• Ensure the agent can access your DataCloud account over the internet by providing your cloud account credentials and opening appropriate firewall ports (see Installing Agents). This lets you use the Integration Manager console to manage integrations and synchronize jobs with the agent.

• A successful agent installation includes the ability to access data sources in the on-premise environment. This requires that access be given for local data resources, including permissions, credentials, and installation of any necessary drivers or clients.

• No data is sent by the Agent to the DataCloud unless your design allows for it. Only deployed packages, logs, and job status details are exchanged. For this reason, the agent is ideal for handling sensitive data.

To fully test your design, use the on-premise version of Actian Data Integrator to design integrations destined for the agent. Talk to your Actian account executive to learn more.

Scheduling Agent Jobs

The Integration Manager console lets you set a schedule for agent-executed jobs using a cron expression, which is a specially formatted text string.

The example below is a cron expression representing a schedule that will run at 1:25 P.M. on the first day of each month.

0 25 13 1 * ? *

/download/attachments/7503960/cron_example_01.png?version=2&modificationDate=1386263344000&api=v2&effects=border-simple%2Cblur-border

Building a Cron Expression

A cron expression is composed of 6 or 7 values separated by spaces. Each of these values represents part of the schedule and can be either a number or a certain special character.

Expression Fields

Field	Required	Values	Special Characters
Second	Yes	0-59	, - * /
Minute	Yes	0-59	, - * /
Hour	Yes	0-23	, - * /
Day of Month	Yes	1-31	, - * / L W ?
Month	Yes	1-12 or JAN-DEC	, - * /
Day of Week	Yes	1-7 or SUN-SAT	, - * / # ?
Year	No	1970-2099	, - * /

Special Characters

Special characters allow you to specify wildcards, ranges, and other conditions for each field.

Character	Description	Examples
*	All values for the field are selected.	* in the Hour field means every hour.
?	No specific value required. Only usable in the Day of Month and Day of Week fields.	To set a schedule that runs on Sundays regardless of the day of the month, use a ? in the Day of Month field and a 1 in the Day of Week field.
-	Specify a range (inclusive) between 2 values.	1-3 in the Hour field (along with a 0 in the Minute and Second fields) is triggered at 1:00 A.M., 2:00 A.M., and 3:00 A.M.
,	Separate multiple values.	1,3 in the Hour field means 1:00 A.M. and 3:00 A.M.
/	Incremental trigger. Enter in the format X/Y, where X is the starting value and Y is the increment.	0/15 in the Minute field means the schedule begins at minute 00 and then runs every 15 minutes thereafter.
L	Last day of the month or week. Can be combined with other values in each field as illustrated below. • Day of Month: L-X, where X is a number of days to offset from the last calendar day of the month. • Day of Week: XL, where X is a day value (1-7).	L in the Day of Month field means the last calendar day of the month. L-2 in the Day of Month field means the second-to-last calendar day of the month. L in the Day of Week field simply means 7 (Saturday). 7L in the Day of Week field means the last Saturday of the month.
W	Weekday (Monday-Friday) nearest the given day. Enter in the format XW, where X is the day of the month.	12W in the Day of Month field is triggered on the 12th day of the month if that day falls on a weekday. If the 12th falls on a Saturday or Sunday, the schedule runs on the following Monday. LW in the Day of Month field is triggered on the last weekday of the month.
#	Exact monthly instance of the specified day of the week. Enter in the format X#Y, where X is the day of the week and Y is the instance. Note: A value using X#5 will not be triggered for the month if there are not 5 of day X within the month.	2#3 in the Day of Week field means the 3rd Monday each month.

Examples

Below are several examples of simple and complex cron expressions.

Simple Daily

Run the schedule at 9:00 A.M. every day.

0 0 9 * * ? *

Seconds	Minutes	Hours	Day of Month	Month	Day of Week	Year
0	0	9	*	*	?	*

Complex Daily

Run the schedule every 5 seconds for 1 minute beginning at 9:00 A.M. every day.

0/5 0 9 * * ? *

Seconds	Minutes	Hours	Day of Month	Month	Day of Week	Year
0/5	0	9	*	*	?	*

Simple Weekly

Run the schedule at 9:25 A.M. every Friday.

0 25 9 * * 6 *

Seconds	Minutes	Hours	Day of Month	Month	Day of Week	Year
0	25	9	*	*	6	*

Complex Weekly

Run the schedule at 9:00 A.M. every Friday, but only in January or February of 2019.

0 0 9 * 1,2 6 2019

Seconds	Minutes	Hours	Day of Month	Month	Day of Week	Year
0	0	9	*	1,2	6	2019

Monthly

Run the schedule at 9:00 A.M., 9:22 A.M., and 9:44 A.M. on the last Thursday of each month.

0 0,22,44 9 ? * L5 *

Seconds	Minutes	Hours	Day of Month	Month	Day of Week	Year
0	0,22,44	9	?	*	L5	*

Yearly

Run the schedule at 2:27 P.M., 3:27 P.M., and 4:27 P.M. on the weekday nearest the 12th day of the month every October.

0 27 14-16 12W 10 ? *

Seconds	Minutes	Hours	Day of Month	Month	Day of Week	Year
0	27	14-16	12W	10	?	*