The infrastructure agent is an Go application that can be run as a Windows service in order to facilitate communication and task handling between SimpleOne instance and external systems.

Concept

In SimpleOne, communication among the instance and customer infrastructure (for example, LDAP servers or mail servers) is implemented using the "server-agent" technology.

It is used for collaboration when integration with customer software is needed. Main aims of this collaboration are:

  1. Information synchronization on SimpleOne instance with predefined templates.
  2. Information synchronization on customer instances with predefined templates.

These templates are PowerShell scripts that implements some tasks to handle.

System Requirements


A server or agent have been developed as a very lightweight application and do not require many system resources, such as CPU, RAM or hard disk space.

Software requirements

SoftwareHW Requirements (minimum)SW Requirements
Agent
  • CPU: 1.4 GHz 64-bit processor.
  • RAM: 512 MB
  • HDD: 32 GB
  • Internet connection: 10/100/1000 Mbit/sec
  • Microsoft Windows server (2012r2 or higher)
  • PHP interpreter (version 7.2 or higher)


The infrastructure server is configured on the SimpleOne instance as a dictionary record, implementing appropriate business server and client logic.

Interaction procedure

To configure the interaction, complete the following steps:

  1. Install infrastructure agent on Microsoft Windows server in a customer infrastructure.
  2. Configure the infrastructure server on the SimpleOne instance.
  3. Configure the tasks for the infrastructure agent.

As a result, the interaction is configured and starts. The agent sends requests to the server to get a job assignment. The request interval usually takes couple of minutes.

  1. If there are no tasks to run, the agent performs further attempts within the intervals configured.
  2. If there are some tasks to run, the agent starts executing them.
    1. Whether tasks were completed successfully or not, the agent connects to the server to report on the execution.

You need to enable the "agent→server" connections in your firewall rules.

You can find graphical principles of this process on the diagram below:

Set up the infrastructure server


To add the server parameters into the appropriate table, complete the following steps:

  1. Navigate to MID servers → MID server.
  2. Click New and fill in the form.
  3. Click Save or Save and Exit to apply the changes.

MID Server form fields

FieldMandatoryDescription
NameYSpecify the infrastructure server name displayed on the list.
HostnameYSpecify the hostname of the external server to which to connect.
UserYSpecify a system user with access to the infrastructure agent functionality.


Infrastructure agent contains two .bat files:

  • one to add the launch of the infrastructure agent into the external server schedule;
  • and one to remove it from the scheduler.

This functionality allows you to monitor the execution of a task at a specified interval.

Configure the infrastructure agent 

  1. Download the infrastructure agent archive.
  2. On disk C, create a folder named MID_agent.
  3. Move the downloaded .exe and .env files to the created folder.

  4. In the .env file, set the following configurations:

FieldDescription
MID_API_USERNAMEThe system username with granted access to the functionality of the infrastructure agent.
MID_API_PASSWORDThe password of the specified user.
MID_API_SERVERIDThe server ID that is configured in the MID Server table.
MID_API_ENDPOINTLink to the SimpleOne instance.


Example of the configuration file:

MID_API_USERNAME=admin

MID_API_PASSWORD=123456

MID_API_SERVERID=157237947616342741

MID_API_ENDPOINT=https://instance.example.com/rest

Add scripts

After you set up your infrastructure agent, you need to configure the PowerShell scripts for it. 

Learning how to develop PowerShell scripts is out of scope of this article; refer to PowerShell product documentation.

  1. Navigate to MID Servers → MID Scripts.
  2. Click New and fill in the form.
  3. Click Save or Save and Exit to apply the changes.

MID Script form fields

FieldMandatoryDescription
NameYSpecify the infrastructure server name displayed on the list.
DescriptionNAdd a brief description of the script.
Is ActiveNSelect this checkbox to activate the script.
ScriptY

Specify a script that handles the necessary tasks and responsibilities associated with the corresponding activities.

In these scripts, you can use variables to facilitate the data exchange across the client infrastructure and the SimpleOne instances.

For example, you can make this definition in your MID Script:

$title='Title:\n';Write-Host($title);Write-Host($param1);

Then the value of the title variable should be transferred in the Request field of the related MID Queue record:

{"param1":"String value"}

After the script is executed, the Response field in the related MID Queue record is equal to:

Title:
String value



Set up a task

To set up a job on the external infrastructure element, you need to create a record in the MID Queue (sys_mid_queue) table. For this, please complete the steps below.

  1. Navigate to MID Servers → MID Queue.
  2. Click New and fill in the form.
  3. Click Save or Save and Exit to apply the changes.

MID Queue form fields

FieldMandatoryDescription
RequestNEnter a request to an external server in JSON format.
ResponseNThe server response containing the output of the command (the stdout response) and other feedback. This field is populated automatically.
DescriptionNSpecify a brief description of the job.
ServerYSpecify a record containing information about the previously configured infrastructure server in the MID Server table.
ScriptYSpecify a record containing the infrastructure script that you configured earlier in the MID Script table.
StatusY

The job status. This field is populated automatically. Available options:

  • Created – the job was just created but not yet been processed.
  • Processing – the job is processing now, and no error code is returned.
  • Done – the job is completed successfully, and the 0 error code is returned.
  • Error – the job is completed with errors, and any other error code is returned.
  1. If there is more than one job in the queue, they are executed sequentially, one after another, from old to new.
  2. If an external server does not respond within a minute, the script will time out. Note: in this case, the corresponding task does not return an error code.
  3. You can execute a job manually if necessary. To do this, run the command:
php.exe bin\agent mid:run-job

Where run:job is a job name you need to be executed.

Note: bin\agent is the path relative to the installation folder of the infrastructure agent. If you are in a different folder, specify the full path. Otherwise, the job may not be executed.


Processed atNThe date and time when the request was processed.