OnPrem Agent v1.0.3
!! The OnPrem Agent CMD and OnPrem Agent Get Result actions mentioned in the following steps are available only for accounts that acquire the OnPrem Agent subscription.
The PROCESIO on-premises Agent or for short OnPrem Agent is a software application that can run both on Linux or Windows operating systems that monitor commands (further on called Tasks) sent by a process action from a PROCESIO process, executes the command, and gives back feedback on the result of the executed command so that it can be available in the process.
This guide will help you to understand how the mechanism works, how to install the OnPrem Agent and how to configure the OnPrem Agent CMD & OnPrem Agent Get Results process actions
This is the first version of the PROCESIO on-premises Agent that allows remote execution of actions from PROCESIO to a remote local machine that PROCESIO does not have direct access to.
Improved versions of the agent or of the entire mechanism might mean changes in the process or in the agents' configuration.
The current mechanism works as described in the following image:
Step 1: Install and configure the OnPrem Agent
The OnPrem Agent is a stand-alone application that needs to be copied on a remote machine where you want to execute commands from a PROCESIO process and then configured to run at the operating system startup. The agent is written in .Net6 C#.
1. Download the OnPremAgent_Net6_1.0.3.zip file and extract its contents in the location you want to install the agent into
The Agent file will be provided for accounts that acquire the OnPrem Agent subscription.
The file contents are as follows:
The actual Windows agent that needs to be executed at system startup
The actual Linux agent library that needs to be executed at system startup
Configuration file read by the agent the moment it is started in order to load the parameters: SecretAgentKey, HTTPDefault & Proxy (only if it is the case)
Where the agent logs are stored
other files & folders
Please do not modify or delete the files/folders that come in the above .zip archive as the agent will not function without those.
2. Edit the following files:
The content of this file is as follows:
Please change the value of the “SecretAgentKey” with some random complicated secret key. You need to write the secret key immediately after the “:“. If you write for example:
The secret key will be “ ThisI$0ran40mK3y“, so it will contain a space.
If the internet connection on the machine where you install the agent runs through a proxy, then you can add an additional parameter where you can set up the proxy server through you what the agent to connect to the internet:
3. Only for Linux - pre-requisites
Before running the agent on Linux environments please make sure you have the operating system up to date and the dotNet6 from Microsoft installed. To do that, please execute the following commands in the Terminal:
4. Starting the agent
- For Windows
Run the Agent_NetCore.exe file, directly or from the cmd:
- For Linux:
Run the following command in the Terminal:
5. Setting up the agent to run on OS startup
- For Windows
- For Linux
6. Getting the HOSTNAME
For Windows open the cmd and for Linux open the terminal and type:
The result of this command will be used to configure the PROCESIO process that will execute commands on a certain agent.
Step 2: Configure a process to execute commands on-premises
You will have to navigate to https://procesio.app login to the platform using your credentials and set the workspace to the workspace you have shared with your colleagues
Go to the Process Designer menu and choose to Create new.
1. Configure the process & variables
Give a name to your process, such as:
Go to the Custom Actions tab in the Actions panel
You should be able to see the OnPrem Agent CMD and OnPrem Agent Get Result actions. Drag them on the canvas and connect the process as seen below:
Go to process variables:
Add the following variables as seen in the next image
For the purpose of this example, please configure the default values for the EndPoint, SecretKey, and AgentSSID variables. You cand have those variables populated from other processes as well if you want.
For the purpose of this example, please populate the default values of the variables as follows:
- SecretKey: here you should put it exactly as you set up the SecretAgentKey in the PROCESIO_agent_settings.txt file from Step 1, 2. Edit the following files.
- AgentSSID: here you should put the HOSTNAME of the machine where the agent was installed. Please refer to Step 1, 6. Getting the HOSTNAME.
2. Configure the action “OnPrem Agent CMD“
Click on the action in the canvas and the action’s property panel will be displayed to the right of the screen.
You will notice that the action has 2 configuration tabs, as follows: Command and Configuration.
Please configure each of the tabs as follows:
- Configuration tab
The working directory parameter you can configure as you like, giving it a folder path on the machine where that agent runs. You can configure it as a variable or hard-coded, as you like. This parameter sets the working directory of the Command Prompt.
For time out (seconds) parameter if you set 0 or <0 values it will consider 600 seconds (10 minutes).
The task id parameter is an output parameter that returns the ID of the Task that was sent to the on-premise agent to execute. This parameter will be needed for the OnPrem Agent Get Result action.
- Command tab
In this section, you can either execute a file or execute commands. If you execute a file, the Commands to execute field will be ignored.
All fields in this section are optional.
If you execute a file, you can also add arguments for executing the specified file, by adding them in the Arguments for the file to execute field.
3. Configure the action “OnPrem Agent Get Results“
This action has only one tab (Configuration) and it has the following parameters:
The TaskId parameter which is an input for this action comes from the output of the OnPrem Agent CMD action.
4. Configure the Decisional
You need to configure the Decisional action so that if the task was not finished it should try again to check the status. We did this with this configuration:
RetriesAllowed > 0 means that the process should not try to get the result more than the number set in the variable RetriesAllowed. This condition prevents infinite loops.
TaskStatus = 0 OR TaskStatus = 1 means that the status of the task is ToExecute (0) or Executing (0) and for that reason, the process should use a delay action to wait some time before trying again to check the status.
5. Configure the Delay action
You need to configure the Delay action to be relevant to the task that you know you are running.
If the task you are going to run will execute fast (less than one second or a few seconds), it would be a good idea to set the delay to one or more seconds.
If the task you are going to run will execute in a few minutes you should set the delay to one or more minutes.
If the task you are going to run will take a few hours or longer you should adapt the delay to be relevant for the execution time of the task.
As a rule of thumb, adapt the delay time you set so the process will execute the minimum possible number of actions.
6. Configure the RetriesAllowed-- action
This action is a numerical Add operation action and it is intended to decrease by 1 the variable RetriesAllowed for every retry the process makes to get the result of the task. The purpose of this is to prevent infinite loops for tasks that might get stuck or take indefinite time to finish.
7. Save, Validate & Run the process
Now, you can save, validate & run the process.
Go to the instance of the process by clicking Check instance (it will be displayed for ~3 seconds after you run the process)
In the instance view, you will be able to see the outputs of the process:
In the DataResults output, it will be included all the information which is also visible if you were to execute those commands in a Command Prompt, except for the errors.
In the ErrorResults output, it will be included all the errors which come from executing the commands.
TaksLogs is a list of all the logs of the agent service if any. Generally, it will be in the case of errors inside the agent service.
TaskStatus will give the status of the task:
0 - ToExecute
1 - Executing
2 - SuccessfullyExecuted
3 - FinishedWithErrors
4 - TimedOut
TaskID is the ID of the task sent to be executed by the agent.