Skip to main content
Matrix42 Self-Service Help Center

Matrix42 Worker Engine

Overview

Workflow Engine is a special module of the Workspace Management application which is responsible for managing the execution of workflows and handling such tasks as starting, resuming, terminating Workflows, monitoring and persisting the Workflow instance state. The Workspace Management application supports two alternative implementations of the Workflow Engine, the basic one which is based on Microsoft AppFabric, and a new one, based on Matrix42 Workers

Architecture

Matrix42 Worker is a Windows Service that can be installed on the Application Server or on any other computer in an Organization. Matrix42 Worker Engine is based on the Message Queue Architecture, which means all the commands for executing Workflows, like starts a new one, or resume the Workflow, first are added to the Message Queue.  Matrix42  Workers continuously watch the Queue and poll the messages from it one by one. Such an approach solves the following challenges:

  • Scalability
    Add additional Worker instance to the Cluster if the Queue starts growing and the current number of active Workers are not coping with the Workflow commands processing.  Using such solutions as Kubernetes allows automatic scaling when additional instances of Workers are created or disposed of automatically, depending on the workload.
  • Reliability
    The Queue has high availability, which guarantees the Workflow command is stored in the Queue. The messages stay in Queue until they are successfully processed. 

WorkersArch.png

Matrix42 Workers & Workflows

In contrast to AppFabric execution, the Matrix42 Worker is an external Windows process and all Business Components and other resources hosted on Application Server are not accessible on Worker. That limitation puts additional requirements to Workflow Activities running on Worker. For example, if the Activity requires executing Business Logic, it needs to be triggered over the Web Service. 

Delivered with the Product standard Workflow Activities that consider Matrix42 Worker specifics and can be executed on Worker are marked as Worker Compatible. The Workflow can be executed on Matrix42 Worker only when all the Workflow Activities of the Workflow are Worker Compatible.

Matrix42 Workers & Data Gateways

Since 10.0.1 release, Matrix42 Worker becomes the universal approach for executing asynchronous background tasks in the Digital Workspace Platform. It also can play the role of the data gateway, or in other words, can be installed remotely and carry out the tasks for collecting data for Data Providers (as Matrix42 Data Gateway does).

Default Data Gateway tasks

Previously, all tasks were executed by the Data Gateway. Since 10.0.1 release the Matrix42 Workers that are run on the Application Server are assigned with App Server default Data Gateway by default. Thus the following tasks are executed by the Matrix42 Workers instead of the App Server Data Gateway by default:

Further, this list will be completed and all available tasks that are still executed by App Server default Data Gateway will be run by Matrix42 Workers while the Matrix42 Data Gateway service will be discontinued.

Security

Authentication Token

Matrix42 Workers uses the Token Authentication with API Token to set up connectivity with the Application  Server. The API Token is provided on Worker installation or automatically generated for the Default Worker (Worker installed on Application Server). The provided Token is encrypted with the Machine Key and stored in the Matrix42.Worker.host.exe.config file. The API Token is sent to the Application Server for checking the validity on Matrix42 Worker process start. If the Token is valid and not expired the Server issues the short-time Access Token which is used for any other operation with the Server.

Trusted Worker

Trusted Worker mechanism was introduced to guarantee data security. It is critical for the Matrix42 Worker to have a direct connection to the SQL server, as it dramatically improves the performance.

Generally, the connection string is sent to the worker.  This approach is acceptable only when the integrated security is used. 

For the cases when the SQL authentication is used (when connection string keeps password and username ) the data security cannot be guaranteed. Therefore the Trusted Worker mechanism is introduced.

The worker can be installed anywhere: in the local network, behind a DMZ (a physical or logical subnetwork that contains and exposes an organization's external-facing services to an untrusted, usually larger, network such as the Internet). 

Diagram.png

The Administrator must explicitly set the Trusted Worker attribute when SQL authentication is used (SA password) and the Matrix42 Worker service runs on other computers in the local network or behind the DMZ,  but not on the Application Server. 

  • Only Trusted Workers can execute both Workflow tasks and assigned Data Gateway tasks.

All worker instances that run on the Application Server are marked as trusted by default.

  • Not Trusted Workers: the workers that are marked as not trusted can execute only the tasks of the manually assigned Data Gateway. By Default the Data Gateway is not assigned. Other tasks (like workflows or later on send e-mail tasks as well) are processed by the Trusted Worker. 

Default Matrix42 Worker

The Product Setup automatically installs the Matrix42 Worker on the Application Server. It guarantees the overall System is operable and able to handle all commands assigned for Workers right after the Setup is over and no other extra activities are required.

If the Matrix42 Worker is already installed, then the Setup validates the API Token assigned to Worker, and in case it is not valid anymore, or even expiring within next month, the Setup reissues a new API Token to avoid the cases when the connection of the Worker with Server is lost due to expired token.

Installing Worker

The System allows installing an unlimited number of Matrix42 Workers. Adding additional Worker to a Farm allows to scale the System and make it more reliable and adjustable for various infrastructure challenges like unexpected growth of the system resource usage.

To install worker, in Administration application, open the management area Services & Processes → Workflows → Workers:

  1. Run "Download Worker" action: the System automatically generates a new archive which already includes the basic configuration settings like Application Server URL and name of the Service Account.
  2. Extract the received archive file on the computer where you want to install the Matrix42 Worker.
  3. Run "InstallWorker.cmd": the batch file runs the signed Powershell script. Depending on the Domain Policies, the execution of the Powershell file can be rejected due to unknown publisher. In this case, make sure the certificate used by Configure.ps1 is installed into the Trusted Publishers Certificate Store on the Local Machine.
  4. Proceed with the installation steps:

    1) Service Name
    Verify if the Worker service name is correct. Different Worker instances running on the same machine should have different service names.


    2) Server URL
    Verify if the Server URL is correct, otherwise, provide the URL of the Application Server.

    3) Valid API token
    The Worker requires the valid API token to authenticate with the Server. Please provide the valid token for the user with the Administrative rights. If you do not have a prepared token, it can be generated. See "Generate API Token" for more details. 
    The provided token is encoded with the machine-key and stored in the config file.

    4) Server connection
    The System checks the validity of the provided credentials and sets up the connection with the Server.
    If you have a connectivity problem and got a message the server cannot be contacted and the trusted SSL/TLS secure channel cannot be established, then please check that the Application Server certificate is installed on the local machine to Trusted Root Authorities.

    5) Set the Service Account
    Matrix42 Worker uses Integrated Security to work with the Product databases. Therefore the Service account should have the db_ownerpermissions to the databases. By default, the installation suggests the Service account which is used on Application Server, but if necessary, it can be changed.
  5. The installation registers and starts "Matrix42 Worker" Windows service.

Multiple Matrix42 Workers can be installed on the same computer. For that provide the unique name for Windows Service during the installation or specified it in the Worker config file before running the installation script

Updating Worker

Matrix42 Worker, in general, does not require any manual operation for updates, as it is automatically updated any time the relevant resource on Application Server changes. It means that as soon as the Application Server is updated with a new version or the patch, the next moment all related Matrix42 Workers will be automatically updated.

Nevertheless, there are a few cases that require manual update operations.

Updating API Token

On installing the Matrix42 Worker the API Token is provided, which is used for communication with the Application Server.  The token is encrypted with the machine key and stored in the Config file. When the API token becomes invalid (either removed from Server or expires) the Matrix42 Worker is not able to communicate with the Server. To troubleshoot the issue, the new API Token needs to be provided for the Matrix42 Worker.

  1. Generate a new Token. See "Generate API Token" for more details.
  2. In the Matrix42 Worker Application folder start "UpdateToken.cmd" and follow instructions.
  3. Windows service "Matrix42 Worker" will be restarted to apply configuration changes.

Manage Matrix42 Workers

Once the Matrix42 Worker is installed it automatically registers itself in the Application. All registered Matrix42 Workers, as well as their current statuses, can be found in Administration application in the management area Services & ProcessesWorkflowsWorkers:

workers.png

Using Matrix42 Workers as Data Gateway

To use Matrix42 Workers as Data Gateway, in Administration application, open Services & Processes → Workflows → Workers → choose Worker.

Worker preview page shows the reference to the Data Gateway

worker_preview.png

The reference can be changed or removed in the edit mode. Click Edit action:

  1. In Data Gateway, choose the necessary option or remove the Data Gateway:
    worker_data_gateway.png  

    Data Gateway options:
    - Set:
    by default, the App Server Data Gateway is assigned for the Workers running on App Server. This reference defines the relation between the Data Gateway and the Worker which is currently executing the tasks that were previously assigned to the Data Gateway. 
    - Not set: if the relation is not set the Worker executes only the workflow tasks.
  2. Click Done;
  3. Restart the Matrix42 Worker service to apply the configuration changes. Data Gateway does not need any extra configuration and stops executing the tasks that were reassigned to the Matrix42 Workers.

The edited Matrix24 Worker will execute the tasks that were previously handled by the specified Data Gateway.

You can assign more than one Matrix42 Worker to the same Data Gateway.

Other information

The following sections of the preview show additional worker information:

  • Worker Applications status of the Data Providers and Workflows 
  • Database connections are necessary for workflows processing:
Databases Possible Status

Production

  • Direct Access
  • Web API
  • None

Instance Store

  • Direct Access
  • None

Monitoring

  • Direct Access
  • None

 

  • Was this article helpful?