Skip to main content
Matrix42 Self-Service Help Center

Service Connections

Overview

Service Connections allow you to configure and maintain connections to 3-rd party services like Microsoft 365, Dropbox, or Google Workspace. With Service Connections, you can share data and files across your organization without sharing the credentials to these resources.

Once authorized, the users can get the necessary information and connect to provided services automatically, while credentials and access are securely managed by the system.

Service Connections are configured by the Administrator in the Administration application and include the following steps:

  1. Services: use the default-provided Services or add and configure new service provider, set authentication type and capabilities;
  2. Tenants: add a new tenant for the created service;
  3. Connections: add a service connection.

When everything is set up, Service Connections can be used in:

  1. Import Definitions
  2. HTTP Send Workflow Activity
  3. Invoke PowerShell Workflow Activity

Service Connections Configuration

Service Connections are configured by the Administrator in the Administration application → IntegrationService Connections.

Service Connections keep and maintain the information needed to set up the connectivity with the various external Services.

Services

Use the suggested or add a new service provider.

By default, the system has the following pre-configured services that can be easily adjusted and integrated, among them:

  • Dropbox file storage
  • Google Workspace (in particular, Google Drive)
  • Microsoft 365 (One Drive)

SC_services1.png

Default-provided Services of the Service Connections

You can add a new Service via the Administration application → IntegrationService Connections → Services → Add Service or adjust the default one with the Edit action for the suggested item.  

The new Service additionally requires adjustments in the PDRServiceConnectionProviderClass Data Definition, where Metadata in JSON format stores the information on how to download and process the link to the file from the created Service provider.

Service has the following configurable options:

  • Name: internally used name of the service;
  • Description: service provider description;
  • Authentication Type: currently the system supports OAuth (2.0) or Username/Password authentication. The subsequent settings differ based on the selected Authentication Type.

OAuth Authentication Type configuration

  • Grant Type: choose from the list of suggested OAuth 2.0 Grant Types. Available options:
    • Authorization code
    • Client credentials
    • Client Assertion
    • Authorization code with credentials
  • OAuth section depends on the selected Grant Type. Configurable options:
    • URL: the authorization code flow begins with the client directing the user to the authorization endpoint.
    • Token URL: before the DWP application can access private data using configured Service, it must obtain an access token that grants access to the Service resources.

In the Microsoft 365 OAuth configuration example, the {tenant-id} corresponds to the data from the Tenants configuration.

A Service can have more than one set of scopes in the Capabilities section. A pair of Service name and the name of the Scope can be chosen later when configuring the Connection, thus allowing you to set up different access levels to the same Service provider.

SC_Microsoft365.png

 

Services configuration example for OAuth Authentication Type

The System automatically tracks the Service Connection Token Expiration and refreshes the token over the OAuth refresh Token Mechanism.

Tenants

Visit the Service provider website to obtain OAuth 2.0 credentials such as a Client ID and Client Secret that are known to both Service provider and DWP application.

Very often you need to define the Authorization callback URL at the Service Provider settings:

  https://{your_domain_name}/wm/externalAuth/redirect.html.

For more information about Tenants configuration and credentials from the Service provider see also:

Use the obtained from the Service provider website data in the Tenants configuration as follows:

  • Name: internally used name of the Tenant;
  • Service: choose from the list of available Service providers;
  • Description: optional Tenant description;
  • Tenant: enter the ID. The name of this ID on the Service provider website may vary. Depending on the Service where you have registered the DWP. This might be the Tenant ID, Directory ID, etc.
  • Client ID: enter the ID. The name of this ID on the Service provider website may vary. Depending on the Service where you have registered the DWP. This might be the Client ID, Application ID, etc.
  • Client Secret: enter the client secret. When you save the Tenant configuration, the Client Secret will be encrypted and no longer visible in the Tenant configuration. You can use the Update Client Secret option if necessary later on when editing the Tenant configuration.

SC_Tenant_configuration4.png

Service Connections: adding new Tenant configuration example with data from Azure portal

Connections

On the last step of the configuration add a Service Connection and Setup Authentication:

  • Service: choose from the suggested options. The list includes a pair of configured Services and their Scope (see Capabilities section);
  • Tenant: choose from the available in the system Tenants;
  • Name: internally used name of the Connection;
  • Description: optional description.

SC_Connections.png

Service Connections: adding new Connection configuration example 

Click Setup Authentication and grant consent as suggested by the Service you are trying to connect to. The granted permissions correspond to the configured Scope of the chosen Service.

After the authentication is successfully completed, you can retrieve necessary files with the configured Service Connection via Import Definitions and, for example, connect to your Google Drive to import Tickets that are collected with some Google form or use REST API in the Workflow Studio with HTTP Send Workflow Activity. 

Service Connections Usage

Cloud Data Providers in Import Definitions

Import Definitions support processing files from the direct link to Cloud Drive (Google Drive, One Drive, Dropbox, etc). In such a way it is possible to execute Import Definition regularly using Engine Activations, and in a case when the file content has changed, the changes are applied automatically with the next run of the import.

Create a new Import Definition and choose the Cloud Drive in Data Source Definition configuration:

  • File Path: enter the path to the file in the cloud storage;
  • Cloud Drive Connection: choose from the available in the system connections.

SC_Import_definition.png

Choose the active CLoud Drive Connection and proceed to the next page of the Wizard. The System automatically validates the provided parameters and shows an error in case the connection is not set up of the referenced file is missing:

  • "The connection to the Cloud Drive {0} failed due to the following reason: {error message}"
  • "The file {0} cannot be found on the {1} Cloud Drive"

File Path is designed for the type of links that are suggested by the Service providers for sharing, for instance, in Google Drive, right-click on the file, choose the Get Link option and copy the suggested file path to the Import Definition. Use a similar approach to get the links from other Service providers.

SC_googledrive_getlink.png

Google Drive: get link option example with the link that can be used in the File Path of the Import Definition

 

 

HTTP Send Workflow Activity

To use Service Connections in the Workflows, configure the following properties of the HTTP Send Workflow Activity:

  • Service Connection: choose from the list of the configured in the system Service Connections:
    WF_activity_http_send_serv_connection.png
    The selected connection already includes all necessary authentication and authorization data to the requested resource.
  • Uri: specify the Uniform Resource Identifier (URI) of the Internet resource that responds to the request. Place the Uri in the double quotes, for example: 

"https://graph.microsoft.com/v1.0/me/drive/root"
WF_activity_http_send_uri.png

For more information on how to access the resources, see also: 

Invoke PowerShell Workflow Activity

To retrieve data via the Service Connection using Invoke PowerShell Workflow Activity you will need:

  1. Connection: configure a Service Connection as described in Connections section of this article. The pre-configured and working connection is a necessary prerequisite. The ID of the configured Connection can be found via Export action: export the Connection information to XML format and search for the ID element value in PDRServiceConnectionClass element.
  2. Workflow Studio: configure the properties of the Invoke PowerShell Workflow Activity in your Workflow as follows:
  • Run on Application Server: select this checkbox to run the script on the Application Server.
  • Script: enter the PowerShell script, executed by the workflow activity. Modify and extend the code example according to your needs:
   param(
    [System.Guid]$id
    )
    
   Add-Type -AssemblyName Matrix42.ServiceConnection.BizLogic
   
   $data =[Matrix42.ServiceConnection.BizLogic.ServiceConnectionManager]::Get($id)

To learn more about the Invoke PowerShell Workflow Activity see Matrix42 Workflow Studio: General Workflow Activities page.