Skip to main content
Matrix42 Self-Service Help Center

Creating a New Data Provider

With Matrix42 Software Asset and Service Management, you can create a custom Data Provider to import data from an external system of your choice. This tutorial outlines the steps that should be taken to create a Data Provider from scratch.

For a comprehensive step-by-step tutorial, watch our video located at the bottom of this article. It illustrates the procedure of creating a Data Provider that imports exchange rates for active currencies.

Preparations

To simplify the export of the implemented Custom Data Provider to a package, it is recommended to activate the "Customizations Recording" before doing any changes on the System.

Step 1. Establishing a Data Source

First, you must define which Matrix42 objects need to be updated and find the external source which could provide the required data. Then you should establish the correspondence between the data source and the Matrix42 Software Asset and Service Management data model:

  1. Go to Administration → Schema → Configuration Items to analyze the data model structure that you plan to update by a new Data Provider. You need to answer the following questions:
    • Objects of which configuration items are to be modified.
    • What the relations between the affected objects are.
    • Which attributes are mandatory.
    • How the received data will be matched with the existing objects.

In the video tutorial, only the Currency configuration item is affected. New fragments are added to the SPSCurrencyExchangeRateClassItem multi-fragment data definition.

 

 2. Determine a system that could provide the required data and the means of integrating with this system. In the tutorial, we use the public REST web service for retrieving up-to-date exchange rates in JSON format. 
Matrix42 Workspace Management delivers several workflow activities out of the box that can be used in a wide range of integration scenarios, for example:

  • Get Ldap Entries - obtains data from the directory services over the LDAP protocol.
  • HTTP Send - retrieves data over the HTTP protocol.
  • SendAndReceiveReply - obtains data from SOAP Web services.
  • ExecuteSqlQuery - gets data from relational database management systems (RDMS).
  • Invoke PowerShell - the PowerShell can be used to setup connectivity with the external System in a case there is none specific Workflow Activity

For specific cases, you might consider creating custom activities.

Step 2. Data Provider Configuration Form

The default Configuration Form for Data Providers (SPSGenericConnectorConfigurationClassBase) contains only basic attributes for configuration, which are common for any Data Provider. 

Attribute Name Description
Account, Password Optional. Credentials for authentication with the external System. The credentials are distributed to the Data Collector Workflow in ConfigurationInfo input arguments and can be accessed with the VB.NET expressions, like ConfigurationInfo.UserName or ConfigurationInfo.Password
Enabled Signals the Data Provider Framework to execute the Import for the Configuration or slip it.
Agent Reference to the Data Gateway where the Data Collection operation needs to be executed.

When additional configuration attributes need to be introduced in Data Provider (e.g. URL), the dedicated Connector Configuration From has to implemented and configured.

  1. In the Administration → Schema → Data Definition, create new Data Definition for keeping the additional Data Provider setting. For example:
    Internal Name: "CUSTGenericConnectorConfigurationClassExchangeRates".
    Display Name: "Exchange Rates Data Provider Configuration"
    Class Type: Data Definition
  2. In the Administration → Schema →  Configuration Items,  create a new Configuration Item which represents the new Data Provider Configuration From. For example:
    Internal name: "CUSTGenericConnectorConfigurationTypeExchangeRates"
    Display Name: "Exchange Rates Data Provider Configuration"
    Data Definition: CUSTGenericConnectorConfigurationClassExchangeRates (Mandatory),  SPSGenericConnectorConfigurationClassBase (Mandatory),  SPSCommonClassBase (Mandatory)
  3. Set CRUD permissions for the created Configuration Item "CUSTGenericConnectorConfigurationTypeExchangeRates"
    Set more details on "Set Configuration Item Permissions"
     
  4.  In the Administration → User Interfaces → Dialogs,  create a new Dialog for the just created Configuration Item. In the Layout Designer, author the layout for the Connector Configuration form.
    DO NOT FORGET, to add the default Configuration From attributes like "Agent", "Data Provider", "Enabled"
  5. Associate the designed Custom Connector Configuration form with the Data Provider.
    The Data Provider object has an attribute that defines the related Configuration form (SPSGenericConnectorClassBase.ConfigurationCI). It is not present in the User Interface, and needs to be set once directly in the Database. 
    update SPSGenericConnectorClassBase
    set ConfigurationCI = 'CUSTGenericConnectorConfigurationTypeExchangeRates'
    where Name = 'Currency Exchange Rates'
  6. Optionally, you may need to setup behavior for Custom Data Provider Configuration.

Some custom "Data Provider Configuration" requires setting a Password (SPSGenericConnectorConfigurationClassBase.Password), which needs to be properly encrypted. This logic is implemented in base Behavior for Data Provider Configuration.

INSERT INTO [Schema-MetaInfo] (Name, BelongsToType, Value, IsSchemaObject, Description)
VALUES('BehaviorType', '<Custom_Data_Provider_Configuration_CI_ID>', 
     'Matrix42.Connectors.BizLogic.EntityBehaviors.GenericConnectorConfigurationEntityBehavior, Matrix42.Connectors.BizLogic',
      0, '<Empty string or some description here>')

To make the change effective the "iisreset" is required.

Each custom Data Provider Configuration Form has to include the basic Data Definition "SPSGenericConnectorConfigurationClassBase"

For more information on how to design Data Model and build UI for it, please check:

Define Fleet Management Data Model and Customization Recording
Build basic Fleet Management Application

Step 3. Creating a Data Collector Workflow

A data collector workflow should be configured and run in order to retrieve the source data.

To create the workflow for collecting data:

  1. In the Workflow Studio, create a new workflow from the Connector Data Collector - WF Template workflow.
  2. In the Administration → Schema → Data Definition, edit the Package Item Type data definition by adding a new value to it. This value defines the type of imported object and will be used in the workflow.
    For example, for importing currency exchange rates, it should be the Exchange Rate object type.
  3. Use the integration activities to request data from an external system.
  4. Use the Connector Package activities to save the obtained data in a proper format as a package (it will be later used by the import definition).
  5. Use the Save, Check In, Release, and Publish actions for the workflow to activate it.

Step 3. Creating an Import Workflow

An import workflow obtains data from the data collector workflow and updates the corresponding Matrix42 Software Asset and Service Management objects with this data.

To create the import workflow:

  1. In the Workflow Studio, create a new workflow from the Connector Import - WF Template workflow.
  2. Under Collect Data → Wait Client drill down to the Run Client Workflow activity. In the Workflow property of this activity, specify the new data collector workflow created at the previous step.
  3. Use the Save, Check In, Release, and Publish actions for the workflow to activate it.

Step 4. Creating and Configuring the Data Provider

To start the import workflow, you need to create and configure the Data Provider object:

  1. Go to Administration → Integration → Data Providers and add a new Data Provider record.
  2. Add a Name for the new Data Provider.  
  3. Under Implementation, specify the customized import workflow to be implemented. 
  4. Save the Data Provider. Then open it for editing. 
  5. Add a configuration. Specify the Data Gateway on which the workflow will be executed and make sure that the Enable Import checkbox is selected for this configuration.
  6. Save changes for the configuration and Data Provider.
  7. Click Enable for the Data Provider to make it active.
  8. Click Activate to run the import workflow immediately.

 

Step 5. Creating an Import Definitions

An import definition correlates attributes of the Matrix42 Software Asset and Service Management object and the retrieved data. To add an import definition:

  1. Go to Administration → Integration → Import → Import Definitions and click the Create New Import Definition action.
  2. Specify the type of data source, destination data definition and reference to the source file that is generated by the import workflow.

The source file is saved to <Application Folder>\Messages\Data\<Data Provider Folder>\LastResult where <Application Folder> is usually C:\Program Files (x86)\Matrix42\Matrix42 Workplace Management and <Data Provider Folder> corresponds to the Data Provider name.

  1. Specify mapping rules that determine the correspondence between attributes in the source file and attributes of the destination data definition in Matrix42 Software Asset and Service Management.
  2. Enter the import definition name and save the changes.

At this step, you also need to reference the created import definition in the import workflow:

  1. Open the customized import workflow in the Workflow Studio and run the Check Out action for it.
  2. Add the Execute GDI Sequence activity and configure it to run the import definition that you have just created.
  3. Use the SaveCheck InRelease, and Publish actions for the workflow to make it active in the system.

Step 6. Validating the Data Provider

Matrix42 Software Asset and Service Management allows you to check the results of activating the Data Provider.
To view the data import results:

  1. Open the configuration object of the Data Provider and go to the Workflows dialog page. All relevant workflow instances and their statuses are listed here.
  2. The Last Result page of the configuration provides the date and outcome of the last import.
  3. The Import Logs page lists import definition logs of the last workflow instance. You can open the log record to view detailed data on imported objects.
  4. If applicable, you can also open the search page with Matrix42 Software Asset and Service Management objects that should have been updated by the data import. For example, for the sample Exchange Rates Data Provider, it will be the Currencies search page under Master Data → Means of Payment.

Step 7. Exporting the implemented Data Provider to Schema Scripts

All the changes implemented in the Tutorial, whereas creating Workflows, Configuration Items or Data Providers objects, have impacted only changes in Database. Extracting all these changes to Schema Scripts and packing them to Customization Package allows easily install the Data Provider on another Environment.

How to generate the Schema Scripts and implement them on the external environment please see details "Schema Scripts"

 

This video tutorial provides comprehensive guidance on creating a new Data Provider for importing currency exchange rates.