Service Connections

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:

• Matrix42 Accounts: use for connecting Matrix42 Cloud Services like Marvin, etc.
• Dropbox file storage
• Google Workspace: in particular, Google Drive
• Microsoft 365: 
  • One Drive
  • AAD (Delegated): stands for Azure Active Directory authorization with a specific personal account, i.e. login with username and credentials.  All communication is executed under user permissions. This option is considered more secure and therefore recommended for usage.
  • AAD (Application): in this scenario, the communication is based on Azure Active Directory Application permissions, the configuration requires Application client ID and client credentials.

Default-provided Services of the Service Connections

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

Service has the following configurable options:

• Name: internally used name of the service;
• Description: service provider description;
• Authentication Type: subsequent settings differ based on the selected Authentication Type. Currently, the system supports the following types of authentication:
  • OAuth (2.0): use this option if you want users to easily provide authorization to applications without needing to share private data or dig through developer documentation.
  • Username/Password: use this option if you expect developers to build internal applications that do not need to access more than a single user’s data.
  • JWT Authentication: JSON Web Tokens is a good way of securely transmitting information between parties because they can be signed, which means you can be sure that the senders are who they say they are.

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 the 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:

• Google Drive Tenant Configuration for Google Workspace Service Connection
• OneDrive Tenant Configuration for Microsoft 365 Service Connection
• Dropbox Tenant Configuration for Dropbox Service Connection

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.

Service Connections: adding a new Tenant configuration example with data from the 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.

Service Connections: adding a 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. 

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. 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.

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"

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:
  
  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"

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

• Sample queries for Microsoft 365 connection: Graph Explorer.

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 the 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 thePDRServiceConnectionClass 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:

Example #1: 

     param(
    [System.Guid] $id
    )
    
Add-Type -AssemblyName Microsoft.Practices.ServiceLocation
$iServiceConnectionManager = [Matrix42.ServiceConnection.Contracts.IServiceConnectionManager]
[Microsoft.Practices.ServiceLocation.ServiceLocator]::Current.GetInstance($iServiceConnectionManager)


Add-Type -AssemblyName Matrix42.ServiceConnection.BizLogic
$authInfo =[Matrix42.ServiceConnection.BizLogic.ServiceConnectionManager]::GetAuthInfo($id)
$authInfo.Schema
$authInfo.Token
 

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

Service Connection Validation 

Service Connection Validation is an Engine Activation that starts regularly and validates Service Connections that are present in the system.

It is available in Administration application → Services & Processes → Engine Activations → Service Connection Validation 

This Engine Activation is run once a day to: 

• Maintain active Connection: updates the access token required for the successful connection;
• Updates the Refresh Token if it has expired;
• Validates the Required Permissions: checks if the permissions for the connection are still granted.

Engine Activation marks the Service Connection as invalid if any of the validation parameters fail:

System Diagnostics

Service Connection Validation check is also run by System Diagnostics.

Run the System Diagnostics from the Home page of the Administration application to analyze the system for possible configuration problems:

 

Error details show the following message:

• The following Service Connections {Connection name 1, Connection name N} are broken. Please proceed to the Administration/Service Connection area to re-establish the connection or consider removing the Service Connection when it is not in use.

Go through the Service Connection Configuration section of this page to fix the issue and re-run the System Diagnostics.