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

Concepts

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.

Technically, these templates are PowerShell scripts implementing some tasks to handle.

System Requirements

Either server or agent have been developed as a very lightweight applications 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

Agent system requirements are limited to OS system requirements.

  • Microsoft Windows server (2012r2 or higher)
  • PHP interpreter (version 7.2 or higher)
  • cURL library

Infrastructure server is configured on SimpleOne instance as a dictionary record implementing appropriate business server and client logic.

Interaction procedure

Interaction configuring, if simplified, can be represented as described below:

  1. Install infrastructure agent on Microsoft Windows server in a customer infrastructure.
  2. Configure infrastructure server on SimpleOne instance.
  3. Configure tasks for infrastructure agent.
  4. After that, the interaction begins.
  5. Agent sends requests to server to get a job assignment. Request interval can be configured via Windows Task Scheduler (generally, it is 1 minute).
    1. If there are no tasks to run, the agent performs further attempts within the intervals configured.
    2. If there are any tasks to run, the agent starts executing them in turn.
      1. Whether tasks were completed successfully or not, the agent will connect to the server to report execution.

Please note that you need to allow "agent→server" connections in your firewall rules.

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

Setting up infrastructure server

Please complete the steps below to add the server parameters into the appropriate table:

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

MID Server form fields

FieldMandatoryDescription
NameYThe infrastructure server name displayed on the list.
HostnameYThe hostname of the external server to which to connect.
Last ConnectYThe date and time of the latest connect. This field is populated automatically and always read-only.
UserYThe system user name with access to the infrastructure agent functionality.

Infrastructure agent contains two .bat files:

  • one for adding the infrastructure agent starting up into the external server schedule;
  • and one for removing it from the scheduler.

This functionality allows monitoring task processing with at a given interval.

Configuring infrastructure agent

To configure your infrastructure agent, you need to find the .env configuration file in the \bin directory where the infrastructure agent was installed. Copy your *.env.example file into the *.env one and modify it in appropriate with your instance settings.

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


Infrastructure Server configuration file description

FieldDescription
MID_API_USERNAMEThe system user name with granted access to the infrastructure agent functionality.
MID_API_PASSWORDThe password of the appropriate user.
MID_API_SERVERIDThe ID of the server configured earlier in the MID Server table.
MID_API_ENDPOINTLink to the SimpleOne instance.

Adding 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; please 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 changes.

Script form fields

FieldMandatoryDescription
NameYThe infrastructure server name displayed on the list.
DescriptionNBrief script description.
Is ActiveNSelect this checkbox to make the script active or inactive.
ScriptY

Type your script here, handling necessary tasks and duties related to the corresponding activities.

In these scripts, you can use variables facilitating data exchange within customer infrastructure and SimpleOne instance bundle.

As an example, you can make such a definition in your MID Script:

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

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

MID Queue Request
{"param1":"String value"}

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

MID Queue Response
Title:
String value

Setting 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 changes.

MID Queue form fields

FieldMandatoryDescription
RequestNType the request to the external server in the JSON format.
ResponseNServer response containing command output (the stdout response) and other feedback. This field is populated automatically.
DescriptionNA brief job description.
ServerYReference to the record containing information about the infrastructure server configured earlier in the MID Server table.
ScriptYReference to the record containing the infrastructure script that was set up earlier in the MID Script table.
StatusN

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

  • Created - the job was just created but not yet processed.
  • Processing - the job is processing now, and no error code was returned.
  • Done - the job was completed successfully, and the error code 0 was returned.
  • Error - the job was completed with errors, and any other error code was returned.
  1. If there is more than one job in the queue, they will be executed sequentially, one by one, from old to new.
  2. If an external server is not responding for a minute, the script will be terminated by timeout. Note: in this case, the corresponding task will not return the error code.
  3. You can run a job manually if necessary. For this, run the command:
php.exe bin\agent mid:run-job

Where run:job is a job name you need to execute.

Note: bin\agent is a pathway relatively infrastructure agent installation folder. In the case of you are in the another folder, please specify the full path; otherwise, the job may not be executed.

Processed at
The date and time when the request was processed.

  • No labels

© 2019-2023, SimpleOne

https://simpleone.ru