Matrix42 Workflow Studio: Integration Activities

Last updated
Save as PDF

Overview

Integration Activities repository category contains workflow activities that are used specifically for integrating with other systems. They retrieve data from integrated systems and provide the synchronization between Matrix42 Workspace Management and these systems.

Activities for a Connector Package

Matrix42 Workspace Management provides a tool for the interprocess communications. The connector package feature of the Workflow Studio implements the communication between processes. It is particularly useful for synchronizing data between Matrix42 Workspace Management and external systems. The connector package is a set of XML files that are created by a workflow and can be used as a data source in another workflow. The package consists of a PackageInfo file and files with retrieved entries.

The workflow activities that are used for generating a connector package and passing it from one workflow to another are:

Connector Package
Add Connector Package Item
Add Connector Package Property
Send Package
Get Package

The Connector Package activity is a container for Add Connector Package Item and Add Connector Package Property activities.

Add Connector Package Item activities generate XML files with the retrieved entries.
Add Connector Package Property activities add custom properties for a package.

Custom properties along with the summarized data of the package are saved in the PackageInfo file. The PackageInfo file and XML files created by Add Connector Package Item activities constitute a connector package.

Send Package activity puts the created package of files to a specified path, and then the Get Package activity retrieves these files. This way the data can be transferred from one workflow to another.

Connector Package

It is the upper-level activity that creates a PackageInfo file and concatenates all XML files generated into a RAR archive. The connector package as a RAR archive is saved to a directory designated for temporary files.

Repository category: Integration

Properties:

Name	Description
DisplayName	Understandable name of the activity.
Has Result	Output property. It is the Boolean type value that defines if the package has been created or not.
Package Path	Output property. It returns a path to which the package files are saved.
Result Comment	Output argument that contains the execution result for this activity. It is created automatically and specifies the type and quantity of entries retrieved.
Accumulate Items	This checkbox should be selected if there is more than one Add Connector Package Item activity inside the Connector Package activity, and all of them retrieve entries of the same object type. By default, each package item activity creates one XML file. If several XML files contain entries of the same object type, it is reasonable to merge the data into one file. Clear the checkbox if multiple Add Connector Package Item activities retrieve entries of different object types.

The object type is selected explicitly when configuring the Add Connector Package Item activity.

Add Connector Package Item

It creates an XML file with data. The activity can be used only inside a Connector Package activity.

Repository category: Integration

Properties:

Name	Description
DisplayName	Understandable name of the activity.
Input	Data source that contains objects that need to be saved.
Object Type	Type of the object whose records will be saved. You can configure the set of values for this property in the SPSConnectorPackageItemPickupType data definition. The selected object type will be written to the Type attribute value of the PackageInfo/Items/PackageInfoItem element in the PackageInfo file.

Example: If you select Account in the Object Type field, the Add Connector Package Item activity will create an XML file titled Account.xml and the following element will be added to the PackageInfo file:

Input data

The activity receives the external data over the parameter "Input" and dynamically detects the items and properties of each data item. The input data can be represented as an enumerable collection of objects which implements System.Collections.IEnumerable interface (e.g. List<T>, Array, ArrayList). Each element of the data collection is an object of the following .NET types, which could be automatically transformed by the Activity at first to a collection of properties names and values, and then to XML Node:

.NET Type

Description

Hashtable,
Dictionary<string, T>

Dictionary keys are transformed to XML node name, and the values are rendered to XML node text. If the dictionary value also represents the Dictionary object, then values are added to the resulting XML node with a prefix.

Example of transformation:

Dictionary:

{
"key1": value1,
"key2": value2,
"sub_object": { "key1": 1, "key2": 2}
}

Final XML Node:

<object>
    <key1>value1</key1>
    <key2>value2</key2>
    <sub_object_key1>1</sub_object_key1>
    <sub_object_key2>2</sub_object_key2>
</object>

Example of the data generation:

The example demonstrates the way to generate the collection of Hashtables (could be used in Invoke PowerShell Activity):

$array = @("wert1","wert2","wert3", "wert4", "wert5")
for ($i=0; $i -lt $array.length; $i++){
    $obj = @{key = $array[$i]; indx = $i}
    $res.Add($obj)
}

System.Json.JsonObject

Represents the JSON object. The activity transforms JSON to XML node.

JSON Example
{
    "key1": "value1",
    "key2": {
            "sub_key1": 1,
            "sub_key2": {"test": 22},
        }
}

Final XML Node
<object>
    <key1>value1</key1>
    <key2_sub_key1>1</key2_sub_key1>
    <key2_sub_key2_test>22</key2_sub_key2_test>
</object>

System.Dynamic.
DynamicObject

https://docs.microsoft.com/en-us/dot...t?view=net-6.0

An object can be generated dynamically with Linq expression directly in Workflow Studio:

VB.NET Linq

From entry In Entries 
Select dn= entry("distinguishedName"), 
os = entry("objectSid")

Final XML Node
<object>
    <dn>CN=test,DN0imagoverum,DN=com</dn>
    <os>3B92E59F-8D00-4C7C-B0F2-431976A69F7D</os>
</object>

System.Data.DataRow

The Activity transforms the column name to XML node name and the column value to XML node text.

Add Connector Package Property

This activity adds a custom property for a connector package and writes this property to the PackageInfo file that is created by the Connector Package activity. Therefore, it can be used only inside a Connector Package activity.

Name	Description
DisplayName	Understandable name of the activity.
Name	Name of the property the way it will be written to the PackageInfo file.
Value	Value of the property to be written to the PackageInfo file.

Example: A data collection workflow retrieves records from a certain domain, and you need to add a custom property with the domain name to the PackageInfo file. The prerequisite will be to create a domain name variable and set the source of its value. The variable value can be set by using a Get Data activity. Once it is done, add an Add Connector Package Property activity inside a Connector Package activity and configure it. Specify the Nameproperty, for example, it can be "DomainName". Set the Value property by referencing the DomainName variable. As a result, after the workflow is executed and the PackageInfo file is created, it will contain the following element:

<Name>DomainName</Name>

<Value xsi:type="xsd:string">DomainName.com.de</Value>

</Property>

Send Package

The activity retrieves the package archive from the path where it has been saved by the Create Package activity and puts the package in a specific folder on the Matrix42 Workspace Management server.

Example: When the Send Package activity is used in the AD - Client workflow, it puts the package archive in the <Application Folder>\Messages\Data\LDAP\ folder.

In most cases, <Application Folder> is C:\Program Files (x86)\Matrix42\Matrix42 Workplace Management.

Repository category: Integration

Properties:

Name	Description
DisplayName	Understandable name of the activity.
File Name	Unique name of the package archive. For example, it can be based on the relevant Data Provider configuration.
Message Name	Name of the folder where the package will be put. For example, it can correspond to the Data Provider name.
Package Path	Source location of the package archive.

Get Package

The activity retrieves the package archive from the specified path, unzips it, saves package objects to a variable for further processing, and puts unzipped package item files in a specific folder.

Example: When the Get Package activity is used in the AD workflow, it retrieves the package archive by using its full path and file name: <Application Folder>\Messages\Data\LDAP\<Configuration GUID>. Then it unzips the archive and puts XML files that have been created by the Add Connector Package Item activities under <Application Folder>\Messages\Data\LDAP\Last Result.

In most cases, <Application Folder> is C:\Program Files (x86)\Matrix42\Matrix42 Workplace Management.

Repository category: Integration

Properties:

Name	Description
DisplayName	Understandable name of the activity.
Package	Output variable. It returns the package object and package item objects.
Package Path	Source location of the package archive. The property should be set based on the File Name and Message Name properties of the Send Package activity.

Activities for Managing Ldap Entries

Three out of the box workflow activities help to run basic LDAP protocol operations:

Get Ldap Entries searches for and retrieves entries from an LDAP server.
Create Ldap Entry adds objects on an LDAP server.
Update Ldap Entry updates objects on an LDAP server.

Get Ldap Entries

Retrieves entries of the specified type from an LDAP server.

Repository category: Integration

Properties:

Name	Description
Account	Username that is used to access the LDAP server.
AuthenticationType	Type of authentication.
Password	Password that is used to access the LDAP server.
Backup Domain Controller	Backup Domain Controller server.
Base DN	Base distinguished name for searching in the LDAP directory. If the Base DN is not specified, the entire directory is searched.
Domain Controller	Domain Controller server.
Domain Name	Name of the LDAP domain.
Entry Type	Type of the object to get. The Unknown value will fetch records of all object types that fit Query Filter within the base DN.
Exclude DN	Lower-level container within the base DN whose entries should not be retrieved by the activity.
Query Filter	Filter expression for searching in the LDAP directory.
Search Deleted	Select this checkbox if the activity should also search within the deleted objects.
Select Entry Properties	Object properties to get. Set the property either by using the drop-down list in each string or by entering the correct property name manually.
DisplayName	Understandable name of the activity.
Found Entries	Output property. It returns a list of LDAP objects found.

Create Ldap Entry

Creates an entry of the specified type on an LDAP server.

Repository category: Integration

Properties:

Name	Description
Account	Username that is used to access the LDAP server.
AuthenticationType	Type of authentication.
Password	Password that is used to access the LDAP server.
Container DN	LDAP container where the new entry will be created.
Domain Controller	Domain Controller server.
Domain Name	Name of the LDAP domain.
Entry Type	Type of the object that is created.
Name	The name attribute of the entry that has to be passed to an LDAP server.
DisplayName	Understandable name of the activity.
Object SID	Output property. It returns the Security Identifier of the created LDAP object.
USN Changed	Output property. It returns the uSNChanged attribute value of the created LDAP object.
Dynamic Collection	List of attributes and their values for the new LDAP object.
Static	The property provides an advanced interface for setting attribute values for the new LDAP object. The list of available attributes is filtered based on the value of the Entry Typeproperty. You can also enter a custom attribute.

Update Ldap Entry

Updates an entry on an LDAP server.

Repository category: Integration

Properties:

Name	Description
Account	Username that is used to access the LDAP server.
AuthenticationType	Type of authentication.
Password	Password that is used to access the LDAP server.
Domain Controller	Domain Controller server.
Domain Name	Name of the LDAP domain.
Fail If Not Updated	Boolean value that will define whether the workflow is marked as Failed when the entry cannot be updated.
Latest USN Changed	Value of the uSNChanged attribute of the entry in Matrix42 Workspace Management.
New Container DN	The new LDAP container if the entry should be updated and moved to another container on the LDAP server.
Object SID	Security Identifier of the entry.
DisplayName	Understandable name of the activity.
USN Changed	New value of the uSNChanged attribute that is assigned after the entry is updated on an LDAP server.
Dynamic Collection	List of attributes and their values for the updated LDAP object.
Static	The property provides an advanced interface for setting attribute values that need to be updated for the LDAP object. The list of available attributes is filtered based on the value of the Entry Type property. You can also enter a custom attribute.

Other Integration Activities

Encrypt Data

This activity can be used for encrypting data or decrypting encrypted data.

Repository category: Integration

Properties:

Name	Description
Data	Source data that should be either encrypted or decrypted.
Operation	Type of operation to be performed.
DisplayName	Understandable name of the activity.
Transformed Data	Output property. It returns the resulting data. This can be the same variable that is specified in the Data property.

Run Client Workflow

The activity launches another workflow that will be executed on the specified Data Gateway (Matrix42 Worker) service. This is useful when Matrix42 Workspace Management is installed outside the network where the workflow should be run or the executed Workflow refers a resource that is available only on a specific Matrix42 Worker (e.g. some software library or files).

As far as Client Workflow (implements Integration Context "Client Workflow") could be executed on remote Worker (Worker which does not have the direct SQL Connection to Database) only a limited amount of Workflow Activities can be used for authoring Workflow.

Repository category: Integration

Properties:

Name	Description
Data Gateway	The Data Gateway installation will execute the client workflow. At least one active Matrix42 Worker is assigned to the Data Gateway.
DisplayName	Understandable name of the activity.
Is Failed	The property indicates whether the workflow failed when the Data Gateway was executing it.
Arguments	List of input arguments that are received by the workflow and output arguments that are returned by the workflow.
Do not wait	Select this checkbox if the master workflow should not wait until the child workflow is finished.
Ignore Failure	Select this checkbox if the master workflow should continue even in case the child workflow fails.
Related Objects	Object(s) for which the initiated workflow instance should be referenced as related. These objects can be found on the Affected Objects page of the workflow instance dialog.
Workflow	Client workflow that will be run.