You have two options for integrating with an application or database that is behind a firewall:
- Whitelist integator.io IP addresses to allow integrator.io to connect to your application or database directly
- Use an on-premise agent to connect to your application or database – without whitelisting
What is an on-premise agent?
An on-premise agent is a Windows software program that runs on your server, typically behind the firewall and within the same network as the systems you want to connect to. It establishes a secure tunnel to connect to integrator.io.
Since the agent makes calls to integrator.io, there is no need to open holes in the firewall by whitelisting IP addresses. The default ports for HTTPS (443) and SSH (22) should be defined on outbound rules in the firewall.
The on-premise agent allows integration with all supported SQL databases, MongoDB, DynamoDB, REST, and HTTP connections.
Set up your agent
Step 1: Download and install the agent software
- Navigate to Resources > Agents.
- Click + Create agent.
- Name your agent. You can also add a description.
- Click Save. Your agent now appears in the list.
- From the Install column, click the Download option and choose the operating system (currently, Windows).
- After it has downloaded, install and open the agent software.
Step 2: Install the agent
If you downloaded the agent on the target computer, open the agent’s setup file, agent-windows.exe, from your browser and proceed to install it.
Otherwise, copy the downloaded file to the server, and double-click to launch setup.
Caution: Before starting an installation to upgrade the agent, disable any flows that rely on a running agent. The connections will not be able to use the agent’s access during the brief setup process, and the flows may fail.
The setup first prompts you to Choose installation options:
- Select whether to install the agent for all users or the currently logged-in profile.
- Click Install.
- Assuming you downloaded the agent directly from https://integrator.io or https://eu.integrator.io, give Windows permission to trust the downloaded executable and proceed.
- After installation, you have the option to Run agent before completing. Make sure that Run agent is checked and click Finish.
The Agent shortcut is added to your desktop and Windows programs, and the software opens to ask you for an integrator.io token.
Step 3: Enter agent token
Communication between the agent and integrator.io is secured by an access token. To generate this token and provide it to the installed agent:
- Return to integrator.io and navigate to Resources > Agents.
- In the list of agents, click Show token.
Important: Keep this token secure. Click Actions > 
Generate token to get a new access token and automatically revoke the previous token.
- Click the copy icon (
) next to the unmasked access token to copy it to your clipboard.
- In the agent software, enter the access token. The agent will automatically start communicating with integrator.io.
The agent should now be online, indicated with a green circle in the list. (Refresh the page if the view hasn’t updated.)
Step 4 (optional): Run the agent as a Windows service
Note: To take advantage of the Windows service option, you must be running at least v3.0. Older agent versions are not automatically updated by Celigo. Repeat Step 1 to download the latest version.
If you’ve followed the steps up to this point, the agent is running as a standard Windows executable. You may choose to run it instead as a Windows service to take advantage of the following benefits:
- The agent will run silently and continuously after installation and each time the system starts up
- The agent will run regardless of which user account is logged on
- As a service, the agent can be managed and monitored from remote systems
To run the agent as a Windows service:
Double-click the Agent shortcut on your desktop.- Choose Install service.
- The agent will confirm successful installation.
- Click OK to dismiss the user interface.
If you later decide that you prefer to run it as an executable, in the taskbar or in the background, double-click the Agent shortcut and click Uninstall service.
Step 5: Set up your connection
- Create a connection in integrator.io, either from the Resources > Connections menu or by adding a new source or destination app in Flow Builder.
- For the Mode setting, choose On-premise (the default is Cloud).
- In the Agent drop-down list, choose your agent from the list.
When creating an integrator.io connection that uses an on-premise agent, your settings will depend on whether the agent is installed on the same server as the application or database.
- Same server – set the Base URI to localhost or 127.0.0.1
- Different servers on the same network – use the hostname or IP address as the Base URI of the system the application or database is running on
Exports and imports that leverage a connection through an on-premise agent do not need any special configuration, since the agent configuration is fully contained within the connection settings. Once the connection is established, you can build flows and integrations as normal.
FAQs
- Is it possible to run multiple agents on the same machine?
- Does the on-premise agent need to be installed on the same machine as the system to be integrated?
- What steps do I need to take when migrating an agent-based flow between sandbox and production environments?
- How can I reopen the agent window and make changes, after it’s set to run in the background?
- How can I keep my agent from stopping unexpectedly?
- Which IP addresses does the agent use to communicate with integrator.io?
- Q7. How can I access my on-premise agent logs?
Q1: Is it possible to run multiple agents on the same machine?
A: No, you can run only one instance of the agent on a machine. However, note that the same agent can be used to allow integrator.io to talk to multiple databases and applications on the same network as the agent.
Q2. Does the on-premise agent need to be installed on the same machine as the system to be integrated?
A: Agents can be installed on any machine within the same network as the server running the system to be integrated.
Q3. What steps do I need to take when migrating an agent-based flow between sandbox and production environments?
A: You can easily migrate flows between environments by cloning flows. When setting up a cloned flow, you will be prompted to supply connection details, either with a new or existing connection. If the sandbox and production systems’ being integrated are on the same network, then the best approach is to use the same on-premise agent for connections to both sandbox and production systems. If you choose to use separate agents for each environment, remember that they must be installed on different machines (see Q1, above).
Q4. How can I reopen the agent window and make changes, after it’s set to run in the background?
A: Most agent installations choose to Run in background (see step 2, above), in which case the program, On-Premise Agent – integrator.io, is not visible in the Windows taskbar.
To restore the agent user interface and make any changes or view activity logs, simply double-click the program’s shortcut.
Q5. How can I keep my agent from stopping unexpectedly?
A: Use a small and dedicated Windows server, then run the agent in the background. Make sure not to use that machine for anything else.
Q6. Which IP addresses does the agent use to communicate with integrator.io?
A: If you need to open up outbound traffic for an agent running in your environment:
- Whitelist the integrator.io IP addresses for the U.S. or the EU for the HTTPS protocol.
- Whitelist the agent-extension server IP addresses for the U.S. or the EU for the SSH protocol.
Q7. How can I access my on-premise agent logs?
A: You can access your logs through the agent's desktop application by clicking View Logs or by using the directory at C:\users\<UserName>\AppData\Roaming\Agent.
Comments
7 comments
Can you provide instructions on how to install this agent software on linux machine using command line. One of our use cases involves installing on a server with no UI access. Command line is the only option - can you provide any details?
How can you run the agent as a service?
I can answer both Rahul's and Damon's questions, based upon conversations I've had with support as of a couple months ago:
Rahul: Linux support is in Beta, and not currently supported specifically because it is a GUI app, not a command line app. There is no command line support.
Damon: Probably for a similar reason to the above, it's not currently supported to run the agent as a service.
... the agent appears to be intended to support development from your local machine, where you can restart at will, rather than used in production to circumvent firewall restrictions. I have found it to be only semi-reliable. Thankfully, I only need it for development purposes - in roughly 4 months, it's had to be restarted roughly twice.
In any event, to make this work *best* you'll need a windows machine with network access to the resource you're trying to connect to, and you'll need login access to that machine to be able to restart if it goes down.
I know that Celigo is actively working on many areas of their system, this may be one of them, so I suggest opening a new ticket with support or otherwise talking to your rep about what they're working on here if you need a better solution.
Appears Microsoft believes this agent download is malicious now.
Thanks, Damon Betlow. I'm glad you brought it to our attention (in-house we install agents regularly and skip past that warning along with the OS permission prompts on subsequent tests).
We're currently in the process of adding a higher code-signing certificate, so that Windows Defender will trust agent-windows.exe. Bottom line: if you've downloaded it directly from integrator.io, you're safe.
Where can I find the minimum machine requirements for running an Agent as a Service? We are planning to run this on a Windows virtual machine and want to allocate appropriate resources.
Hi, Sikich NetSuiteDev. I hope this broad guideline answers your question:
https://docs.celigo.com/hc/en-us/community/posts/360048137011/comments/360013339911
It's also very easy to install if you want to analyze the processing usage.
Please sign in to leave a comment.