Written for Frends version 5.5.

In this guide you will learn how to configure an isolated Frends environment and install an on-premise Frends Agent to start executing your integrations on-premise with only logging and configuration done in the cloud.

See this article for technical information about the Agent


You will need the following prerequisites to follow through with this guide:

  1. Admin access to your Frends tenant to access the Environment view

  2. A server that you have Admin access to with the following requirements:

  • Windows Server 2019 or later or any Windows 10 based system, with .NET framework 4.7.1. For the cross-platform agent, .NET 6.0 is required.

  • The host machine should preferably have 4 vcpu, 8 GB of RAM, and at least 100 GB of disk space. However, the memory usage depends greatly on the processes running on the agent: if there are hundreds of processes or e.g. processes doing XSL transforms on large XML files, you may need more memory. You should also be fine with less memory if there are only a handful of processes running on the agents. Also, if you plan to store a lot of files you should have more disk space.

  • If the agent is not getting a heavy load, e.g. it is used in the development environment, or you plan to scale it if needed the host machine should have at minimum 2 vcpu, 4 GB of RAM, and 32 GB of disk space.

  • It is usually better to have two frends Agents with less capable hardware than one with powerful hardware. See "Agent installation variations" at the end of this document for further information.

  • Outbound internet access through port 443 (for HTTPS) and ports 9350 through 9354, and 5671 and 5672 (for Azure Service Bus you can learn more about Azure Service bus here https://docs.microsoft.com/en-us/azure/service-bus-messaging/)
    Because the IP addresses of the Azure services may change, these have to opened without IP restrictions.

  1. (Optional) The server should have a designated name using any DNS-service

  2. (Optional) The server should have a valid SSL certificate installed if you want to publish API's from the Server with a valid SSL certificate 

Setting up your environment

Before installing your on-premise Agent for on-premise integration executions or hybrid integration solutions you will need to set up an environment in the frends environment view.

  • Access the environment view from the top menu and select the environment, for example Development, Test or Production, you want to include the agent in. You can do this by simply opening up the environment view and selecting the environment from the menu, alternatively you can also create a new environment to install your agent in.

  • After selecting the desired environment click on the "+ New Agent group" button and give your Agent group a unique name that will distinguish it from other Agent groups within the same environment. A good practice is to use a logical name such as "LocalDataCenter" or "PrivateCloudByISP" etc.

  • After naming the Agent Group click on the "+ New Agent" button to start the configuration process for your new Agent.

Configuring your Agent

Configure the Agent with the following information:

  • Name for Agent - Give the Agent a unique name to distinguish it from other Agents within the same Agent group. A good practice here is to use the logical name of the server you are installing the Agent to as the Agent name.

  • Username for Agent - Enter the Windows or Active Directory user name the Agent service is going to be executing as here following the format DOMAIN\Username

  • Password for Agent - Give the password that is associated with the username you provided above

  • Ports for REST API (HTTPS) and (HTTP) - Choose the ports that the Agent will be using to expose any REST API services. Note that if you want to have the standardized ports 80 for HTTP and 443 for HTTPS you will need to make sure no other service is using those ports at the server.

  • External Address - If your server is hooked up to a DNS service, you can optionally provide the name of the server to help with publishing API's through frends's API Management Features

  • SSL Certificate thumbprint - If you have a valid SSL certificate for the server you can choose the correct certificate by giving the certificate thumbprint here. Note that if left empty the Agent will generate a self-signed certificate for SSL communication.
    NOTE: Make sure to remove any additional characters such as spaces or hidden characters. (older versions of Windows add an invisible character in the beginning of the thumbprint when copy pasting from the Certificate manager)

That's it! You're done configuring the Agent and can move on to installing the Agent.

Installing the Agent

Now that you have your Environment and Agent configured it's time to download the installer package and install the Agent on your server. You should be able to see the Agent now in the Environments view with offline status as it has not yet been installed.

  • Download the Agent from the Environments view by clicking the download icon on the Agent

  • After downloading the Agent copy the Agent installer package to your chosen server and un-zip the installer package to a temporary location. It's a good practice to archive the Agent installer packaged on the server if you might want to re-install the agent later, though you can also always download the installer from the frends environment view.

  • The un-zipped installer package should have two files: a config file and the Frends.Agent.Installer.Bundle double click the Frends.Agent.Installer.Bundle to start the installation.

  • In the installer you can set the installation location through the options menu. By default, the installer installs under C:\Program Files\HiQ Finland\FRENDS Agent.

  • After accepting the Terms and Conditions click the "Install" button to start the installation

  • If the installation was successful, you are now done! You have a working frends Agent installed on your server and you can start deploying and executing integrations with it.

  • You should now be able to see the Agent appear online in the Environments view:

  • You are able to view the current status of the Agent and read an Event stream from the Agent to detect or debug any issues remotely through the frends UI.

Verifying the Agent is functioning

After you have successfully installed your frends Agent you can now see the newly installed Agent in the Environment and Agent Group selector in the Process -view. If you select your newly created environment, you should see a message: "No processes". This means that we can now deploy a process to our newly created environment to verify that everything works as it should:

You should be able to see the process update and the process trigger activate in the new environment if the deployment was successful.

You can also check the deployment directory in the newly installed Frends Agent server in the folder:

C:\Users\{YOUR AGENT USERNAME}\AppData\Local\HiQ Finland\Frends Agent\processes

Inside the folder you can see all the integration processes as well as their versions deployed to the agent and all of their source code and compiled code that the Agent executes.

Debugging Installation Problems

Wrong username or password

If you get the following error: Failed to create user. ({error reference code} {Your Agent username}, there is most likely something wrong with the user account you provided the Agent. To solve this go through the following list:

  • Confirm that the username and password are both correct

  • Check that the Agent user is part of the local "Administrators" group.

  • Make sure that in the Windows "Local Security Policy" settings under "User Rights Assignment" the Agent user has the following rights set: Log on as a service and Log on as a batch job

Best Practices

Name your environments with descriptions of the environments function such as for example Development, Test, Production, PartnerNetworkOne and PartnerNetworkTwo.

Name your Agent groups using the different Agents deployment strategies as a basis inside each environment, for example inside the Production environment there might be three Agent groups; Internal, Public Cloud and Hybrid

Name your individual Agents with a reference to the server the Agent is installed on or even the server name or IP address itself.

Agent installation variations

The Agents and Agent groups can be configured in multiple different ways for different kind of needs.

Multiple agents in a agent group with a shared SQL database

If the agent group has a connection string set the agents will use the shared SQL database and all triggers are available in High Availability mode.

This is the most common mode of installing multiple Agents in one Agent group and should be used in most cases.

Multiple agents without a shared SQL

If no connection string is set all the agents will use a local database for storing configuration information. The first agents will be a so called "Primary agent", this agent will be able to execute all triggers. The other agents will be able to run Http, Api and Servicebus Triggers. If this mode is selected Schedule and File Triggers will not be run in High Availability mode. 

This mode of installation is useful if you do not have a SQL server but still want to have redundancy and load balancing for HTTP processes.

Agent without bundled localdb.

If you already have a SQL server installed you do not need to download the bundled version of the agent that includes localdb. When downloading this lighter version you may install multiple agents on the same machine. This can be useful when you for example want to run test and development agents on the same machine.

Cross-platform agent

If the agent group Cross-Platform is set, you can download the .NET 6.0 cross-platform version of the agent. There is a separate download option for Linux and Windows:

There is a separate guide for the Linux installation.

Did this answer your question?