Versions Compared

Old Version 3

changes.mady.by.user Igor Shakhbazyan

Saved on

compared with

New Version 4

changes.mady.by.user Igor Shakhbazyan

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The MID server is an PHP application that can be run as a Windows service intended for facilitating communication and task handling between SimpleOne instance and external systems.

Отсутствие документации, описания и схемы архитектурного решения, схемы взаимодействия с инстансом и инфраструктурой клиента, требований к ресурсам и публичной ссылки на скачивание самого MID сервера.

Concepts

Концепция MID заключается во взаимодействии между системой SimpleOne и внешними сервисами (например, серверами LDAP или почтовыми сервисами) со следующими целями:

  • синхронизация информации в системе SimpleOne по заранее заданным шаблонам.
  • синхронизация информации в сторонних системах по заранее заданным шаблонам.

Взаимодействие производится с помощью PHP-приложения, запускающегося в среде Windows. Для запуска необходимы интерпретатор PHP версии не менее 7.2 и curl. Принципиальная схема взаимодействия показана ниже

Image Removed

Как должно происходить взаимодействие:

  1. На инстансе SimpleOne устанавливается MID-сервер
  2. На вин-сервере во внешней инфраструктуре устанавливается MID-агент
  3. Агент отправляет запрос к серверу для получения задания (задания настраиваются пауэршел-скриптами в мид скрипт). Периодичность запросов задается планировщиком Windows
    1. Если правила файрвола не позволяют соединиться с сервером, то агент не сможет получить задания.
  4. При наличии заданий агент их выполняет, передает серверу сообщение об успешном или неуспешном выполнении.

Требования к ресурсам / System requirements

Как таковых требований к системным ресурсам у агента нет. Он устанавливается на сервере windows, соответственно, системные требования ограничены требованиями к серверу windows. Потребление ресурсов агентом минимально. Агент требует установленный интерпретатор пхп 7.2 (не меньше) и курл.

Требования к системным ресурсам сервера: устанавливается на инстансе симпла, много тоже не требует. Как и агент, требует пхп 7.2 минимум и курл.

To set up and configure your MID server, you'll need to have:

  1. A SimpleOne instance deployed in a cloud;
  2. An external Windows server with PHP 7.2 and CURL installed.
Note

Role required: admin.

To configure your MID server, you need to find the .env configuration file in the \bin directory where the MID server 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=http://simple.test/rest

MID Server configuration file description

FieldDescriptionMID_API_USERNAMEThe system user name with granted access to the MID agent functionality.MID_API_PASSWORDThe password of the appropriate user.MID_API_SERVERIDThe ID of the server configured earlier in the MID Server table.

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

It is used for collaboration when integration with 3rd-party software is needed. Main aims of this collaboration are:

  1. Information synchronization on SimpleOne instance with predefined templates.
  2. Information synchronization on 3rd-party instances with predefined templates.
Tip

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

SoftwareRequirements
Server
  • SimpleOne instance
  • PHP interpreter (version 7.2 or higher)
  • cURL library
Agent
  • Microsoft Windows server
  • PHP interpreter (version 7.2 or higher)
  • cURL library

Interaction procedure

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

  1. Install MID agent on Microsoft Windows server in a customer infrastructure
  2. Install MID server on SimpleOne instance.
  3. After that, 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 
    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 server to report execution.
Note

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:

Image Added

MID_API_ENDPOINTLink to the SimpleOne instance.


Setting up the MID 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

FieldDescription
NameThe MID server name displayed on the list.
HostnameThe hostname of the external server to which to connect.
Last connectThe date and time of the latest connect. This field is populated automatically and always read-only.
UserThe system user name with access to the MID agent functionality.


Tip

MID agent consists out of contains two .bat files:

  • the first one is to add one for adding the MID agent starting up into the external server schedule;
  • and the second one is to remove one for removing it from the scheduler.

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

Configuring MID server

To configure your MID server, you need to find the .env configuration file in the \bin directory where the MID server 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


MID Server configuration file description

FieldDescription
MID_API_USERNAMEThe system user name with granted access to the MID 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 MID server, you need to configure the PowerShell scripts for it. 

Note

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 script
  2. Click New and fill in the form.
  3. Click Save or Save and Exit to apply changes.

MID Script form fields

FieldDescription
NameThe MID server name displayed on the list.
DescriptionBrief script description.
Is activeSelect this checkbox to make the script active or inactive.
Script

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

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

FieldDescription
Status

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.
Tip
  1. If there is more than one job in the queue, then they will be executed sequentially, one by one, from old to new.
  2. If an external server is not responding for a minute, then 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:
Code Block
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 MID 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.


RequestType the request to the external server in the JSON format.
ResponseServer response containing command output (the stdout response) and other feedback. This field is populated automatically.
Description
Brief
A brief job description.
Processed atThe date and time when the request was processed.
ServerReference to the record containing information about the MID server configured earlier in the MID Server table.
ScriptReference to the record containing the MID script that was set up earlier in the MID Script table.


Table of Contents