Private SDK API

To enhance PowerShell scripting, the system exposes global PowerShell variables that provide direct access to the Private API, enabling commonly used functionalities without complex initializations

+ More

Table of Contents

Overview Usage Use in code PowerShell Integration Example Business Components Data Provider Methods Log Provider Parameters Methods Examples: Web API Client Parameters Methods Service Connection Manager Methods

Overview

The API is part of an SDK, accessed through assemblies or libraries rather than over the network. It's not exposed as REST endpoints. Allows creation of more efficient and performant solution, as using the Private API triggers execution “in-process”, contrary to Public API which leads to Web operation.

Usage

The Private SDK API can be utilized in custom component development, allowing seamless integration with the Product through supported extensibility models, such as:

Custom Web Services
Configuration Item Behavior
Workflow Activities
PowerShell

For more details, refer to: Extending ESM Platform Capabilities: Customization Options and Best Practices

Use in code

The reference to Private SDK component in code could be retrieved over the Dependency Injection mechanism over the constructor

using System.Web.Http;
using Matrix42.Common;
using Matrix42.Persistence.Contracts;

namespace Matrix42.Pandora.Services
{
    [RoutePrefix("api/customlogic")]
    public class CustomLogicController : ApiController
    {
        private ILog _log;
        private IDbProvider _dbProvider;

        public CustomLogicController(IDbProvider dbProvider, ILog log)
        {
            _log = log;
            _dbProvider = dbProvider;

        }

        [HttpGet, Route("custom")]
        public string[] CustomMethod([FromUri] string data)
        {
            _log.Info("Start Custom Method with parameter {0}", data);
            var tbl = _dbProvider.GetData("SPSActivityClassBase", "ID", $"Subject like '%{data}%'");
        }
    }
}

PowerShell Integration

The Product provides multiple integration points where custom logic can be implemented using PowerShell scripts, including:

To enhance PowerShell scripting, the system exposes global PowerShell variables that provide direct access to the Private API, enabling commonly used functionalities without complex initializations.

Available Global Variables:

Variable	Description
`$M42_DatabaseProvider`	Reference to the Data Provider component, offering easy access to the Data Layer and various CRUD operations.
`$M42_ServiceConnection`	Manages service connections, enabling seamless communication with external and internal services.
`$M42_Log`	Provides logging functionality for tracking and debugging operations.
`$M42_WebApiClient`	Reference to the WebClient Provider, which facilitates interaction with web APIs, simplifying HTTP-based integrations.

Example

#Read data from Data Layer
$dbData = $M42_DatabaseProvider.GetData("DWPSystemDiagnosticRuleClassBase", "ID,Title", "Disabled=0",$null)
# Write query results to log
foreach ($row in $dbData.Rows) {
  $M42_Log.Info("Rule {0} , ID= {1}", $row['Title'], $row['ID'])
}
# Get Access token from Service connection for further integrations
$authInfo = $M42_ServiceConnection.GetAuthData([System.guid]::New("4059eb6b-0af8-caa6-a69a-08dd5fbf9248"))
$M42_Log.Info("Service Connection {0} {1}", $authInfo.AuthHeader, $authInfo.Type)

# Get localization strings for KB Subject (Translation.GetLocalizationItemsById)
$arg = [Matrix42.Http.Client.Contracts.Argument]::new("id", "$($id)_SVMKBArticleClassBase_Subject")
$data = $M42_WebApiClient.Run([System.guid]::New("4ff4c98c-41ac-ca91-42a2-08d61fcebd53"), @($arg))

Business Components

Data Provider

The IDbProvider interface provides a set of methods for interacting with a database. It supports querying data from tables, updating records, deleting records, and executing SQL commands, with options for parametrized queries, custom query options, and ensuring the uniqueness of values. This interface is part of the Private SDK API.

Methods


DataTable GetData(string tableName, string columns, string whereExpression = null)
DataTable GetData(string tableName, string columns, string whereExpression = null, params (string name, object value)[] parameters);
DataTable GetData(string tableName, string columns, QueryOptions queryOptions)
T[] GetData<T>(string tableName, string columns, string whereExpression, Func<DataRow, T> func, params (string name, object value)[] parameters)
T[] GetData<T>(string tableName, string columns, QueryOptions queryOptions, Func<DataRow, T> func)
DataTable GetUnsecureData(string tableName, string columns, string whereExpression = null)
DataTable GetUnsecureData(string tableName, string columns, string whereExpression = null, params (string name, object value)[] parameters)
T[] GetUnsecureData<T>(string tableName, string columns, string whereExpression, Func<DataRow, T> func)
T[] GetUnsecureData<T>(string tableName, string columns, string whereExpression, Func<DataRow, T> func, params (string name, object value)[] parameters)
int GetRecordCount(string tableName, string whereExpression = null, Guid[] allowedTypes = null, bool isSecured = true)
void Update(string tableName, string columns, string sourceColumns, string where);
void Delete(string table, string whereExpression);
object GetValue(string tableName, Guid objectId, string column, string where = null)

#	Method	Description
1	GetData	Retrieves data from the specified table with optional filtering. Parameters: `tableName` (string): The name of the table to query. `columns` (string): The columns to retrieve. `whereExpression` (string, optional): The WHERE clause for filtering results. Returns: A `DataTable` containing the queried data. `DataTable GetData(string tableName, string columns, string whereExpression = null)`
2	GetData (with multiple Parameters)	Retrieves data from the specified table with optional filtering and parametrized queries. Parameters: `tableName` (string): The name of the table to query. `columns` (string): The columns to retrieve. `whereExpression` (string, optional): The WHERE clause for filtering results. `parameters` (params tuple): The parameters for the query. Returns: A `DataTable` containing the queried data. `DataTable GetData(string tableName, string columns, string whereExpression = null, params (string name, object value)[] parameters);`
3	GetData (With QueryOptions)	Retrieves data from the specified table using custom query options. Parameters: `tableName` (string): The name of the table to query. `columns` (string): The columns to retrieve. `queryOptions` (QueryOptions): Options for customizing the query. Returns: A `DataTable` containing the queried data. `DataTable GetData(string tableName, string columns, QueryOptions queryOptions)`
4	GetData<T>	Retrieves data from the specified table and maps it to an array of type T. Parameters: `tableName` (string): The name of the table to query. `columns` (string): The columns to retrieve. `whereExpression` (string): The WHERE clause for filtering results. `func` (Func<DataRow, T>): A function to map each `DataRow` to type T. `parameters` (params tuple, optional): The parameters for the query. Returns: An array of type T containing the mapped data. `T[] GetData<T>(string tableName, string columns, string whereExpression, Func<DataRow, T> func, params (string name, object value)[] parameters)`
5	GetData<T> (With QueryOptions)	Retrieves data from the specified table using custom query options and maps it to an array of type T. Parameters: `tableName` (string): The name of the table to query. `columns` (string): The columns to retrieve. `queryOptions` (QueryOptions): Options for customizing the query. `func` (Func<DataRow, T>): A function to map each `DataRow` to type T. Returns: An array of type T containing the mapped data. `T[] GetData<T>(string tableName, string columns, QueryOptions queryOptions, Func<DataRow, T> func)`
6	GetUnsecureData	Retrieves unsecured data from the specified table with optional filtering. Parameters: `tableName` (string): The name of the table to query. `columns` (string): The columns to retrieve. `whereExpression` (string, optional): The WHERE clause for filtering results. Returns: A `DataTable` containing the queried data. `DataTable GetUnsecureData(string tableName, string columns, string whereExpression = null)`
7	GetUnsecureData (With Parameters)	Retrieves unsecured data from the specified table with optional filtering and parametrized queries. Parameters: `tableName` (string): The name of the table to query. `columns` (string): The columns to retrieve. `whereExpression` (string, optional): The WHERE clause for filtering results. `parameters` (params tuple): The parameters for the query. Returns: A `DataTable` containing the queried data. `DataTable GetUnsecureData(string tableName, string columns, string whereExpression = null, params (string name, object value)[] parameters)`
8	GetUnsecureData<T>	Retrieves unsecured data from the specified table and maps it to an array of type T. Parameters: `tableName` (string): The name of the table to query. `columns` (string): The columns to retrieve. `whereExpression` (string): The WHERE clause for filtering results. `func` (Func<DataRow, T>): A function to map each `DataRow` to type T. Returns: An array of type T containing the mapped data. `T[] GetUnsecureData<T>(string tableName, string columns, string whereExpression, Func<DataRow, T> func)`
9	GetUnsecureData<T> (With Parameters)	Retrieves unsecured data from the specified table with parameters and maps it to an array of type T. Parameters: `tableName` (string): The name of the table to query. `columns` (string): The columns to retrieve. `whereExpression` (string): The WHERE clause for filtering results. `func` (Func<DataRow, T>): A function to map each DataRow to type T. `parameters` (params tuple): The parameters for the query. Returns: An array of type T containing the mapped data. `T[] GetUnsecureData<T>(string tableName, string columns, string whereExpression, Func<DataRow, T> func, params (string name, object value)[] parameters)`
10	GetRecordCount	Retrieves the record count from the specified table with optional filtering. Parameters: `tableName` (string): The name of the table to query. `whereExpression` (string, optional): The WHERE clause for filtering results. `allowedTypes` (Guid[], optional): A list of allowed types for filtering. `isSecured` (bool, optional): Indicates whether the query is secured. Returns: The count of records that match the query. `int GetRecordCount(string tableName, string whereExpression = null, Guid[] allowedTypes = null, bool isSecured = true)`
11	Update	Updates data in the specified table. Parameters: `tableName` (string): The name of the table to update. `columns` (string): The columns to update. `sourceColumns` (string): The source columns for the update. `where` (string): The WHERE clause for filtering the update. `void Update(string tableName, string columns, string sourceColumns, string where);`
12	Delete	Deletes records from the specified table using a WHERE clause. Parameters: `table` (string): The name of the table to delete from. `whereExpression` (string): The WHERE clause for filtering the records to delete. `void Delete(string table, string whereExpression);`
13	GetValue	Retrieves a specific value from the table based on the given object ID and column. Parameters: `tableName` (string): The name of the table to query. `objectId` (Guid): The ID of the object to retrieve. `column` (string): The column to retrieve the value from. `where` (string, optional): The WHERE clause for filtering results. Returns: The retrieved value. `object GetValue(string tableName, Guid objectId, string column, string where = null)`

Log Provider

The Matrix42.Common.ILog interface provides a structured approach to logging at various levels, ensuring flexible and effective logging capabilities to files which could be found in AppFolder/Logs

Parameters

The following parameters are common for all methods:

message: The message to log.
exception: The exception to log.
arguments: Optional arguments to format the message.

Methods


Trace(string message, params object[] arguments)
Trace(string message, Exception exception, params object[] arguments)
Debug(string message, params object[] arguments)
Debug(string message, Exception exception, params object[] arguments)
Info(string message, params object[] arguments)
Warning(string message, params object[] arguments)
Error(string message, params object[] arguments)
Error(string message, Exception exception, params object[] arguments)
Fatal(string message, params object[] arguments)
Fatal(string message, Exception exception, params object[] arguments)

#	Method	Description
1	Trace (message)	Logs a trace-level message. `Trace(string message, params object[] arguments)`
2	Trace (message with exception)	Logs a trace-level message along with an exception. `Trace(string message, Exception exception, params object[] arguments)`
3	Debug (message)	Logs a debug-level message. `Debug(string message, params object[] arguments)`
4	Debug (message with exception)	Logs a debug-level message along with an exception. `Debug(string message, Exception exception, params object[] arguments)`
5	Info (message)	Logs an info-level message. `Info(string message, params object[] arguments)`
6	Warning (message)	Logs a warning-level message. `Warning(string message, params object[] arguments)`
7	Error (message)	Logs an error-level message. `Error(string message, params object[] arguments)`
8	Error (message with exception)	Logs an error-level message along with an exception. `Error(string message, Exception exception, params object[] arguments)`
9	Fatal (message)	Logs a fatal-level message. `Fatal(string message, params object[] arguments)`
10	Fatal (message with exception)	Logs a fatal-level message along with an exception. `Fatal(string message, Exception exception, params object[] arguments)`

Examples:

Writing logs in PowerShell

$M42_Log.Info("Amount of active Scripted Diagnostic Rules: {0}", $dbData.Rows.Count)

Web API Client

Defines a Web API client interface for making requests to a service operation registered in Service Repository addressing them by Operation Id.
Interface: Matrix42.Http.Client.Contracts.IWebApiClient

Parameters

The following parameters are common for all methods:

operationId: Object ID of the Web Operation in Service Repository (PLSLWebServiceOperation.ID)

Methods


Run(Guid operationId, Argument[] arguments = null, object data = null, int? lcid = null)
RunWithStream(Guid operationId, Argument[] arguments = null, object data = null, int? lcid = null)
Run(Guid operationId, Argument[] arguments = null, object data = null, int? lcid = null
Call(Guid operationId, Argument[] arguments = null, object data = null)
RunOperation(Guid operationId, Func<string, object> argFunc, object data = null, int? lcid = null)
RunOperation(Guid operationId, Guid serviceConnectionId, Func<string, object> argFunc, object data = null, int? lcid = null)
GetOperationDescriptor(Guid operationId)

#	Method	Description
1	Run	Executes a request and returns a typed response. Parameters: `operationId`: The operation ID. `arguments`: Request arguments (ignored if data is specified). `data`: Request body. `lcid`: The LCID (locale identifier) for the culture. Returns: The typed response data. `Run(Guid operationId, Argument[] arguments = null, object data = null, int? lcid = null)`
2	RunWithStream	Executes a request and returns a stream response. Parameters: `operationId`: The operation ID. `arguments`: Request arguments (ignored if data is specified). `data`: Request body. `lcid`: The LCID for the culture. Returns: A response data stream. `RunWithStream(Guid operationId, Argument[] arguments = null, object data = null, int? lcid = null)`
3	Run (JSON response)	Executes a request and returns a JSON response. Parameters: `operationId`: The operation ID. `arguments`: Request arguments (ignored if data is specified). `data`: Request body. `lcid`: The LCID for the culture. Returns: The JSON response data. `Run(Guid operationId, Argument[] arguments = null, object data = null, int? lcid = null`
4	Call	Calls an operation without expecting a response. Parameters: `operationId`: The operation ID. `arguments`: Request arguments (ignored if data is specified). `data`: Request body. `Call(Guid operationId, Argument[] arguments = null, object data = null)`
5	RunOperation	Runs an operation and returns a JSON response. Parameters: `operationId`: The operation ID. `argFunc`: Function to get argument values by name (ignored if data is specified). `data`: Request body. `lcid`: The LCID for the culture. Returns: The JSON response data. `RunOperation(Guid operationId, Func<string, object> argFunc, object data = null, int? lcid = null)`
6	RunOperation (using Service Connection)	Runs an operation using a specific service connection and returns a JSON response. Parameters: `operationId`: The operation ID. `serviceConnectionId`: The service connection ID. `argFunc`: Function to get argument values by name (ignored if data is specified). `data`: Request body. `lcid`: The LCID for the culture. Returns: The JSON response data. `RunOperation(Guid operationId, Guid serviceConnectionId, Func<string, object> argFunc, object data = null, int? lcid = null)`
7	GetOperationDescriptor	Retrieves the operation descriptor. Parameters: `operationId`: The operation ID. Returns: The operation descriptor. `GetOperationDescriptor(Guid operationId)`

Service Connection Manager

Manages service connections, enabling seamless communication with external and internal services.
Interface: Matrix42.Http.Client.Contracts.IWebApiClient
Powershell global variable: $M42_ServiceConnection

Methods

# Method Description

#	Method	Description
1	GetAuthData	Retrieves authentication data for a specified service connection. Parameters: `connectionId` (Guid): The unique identifier of the service connection. Returns: `ServiceConnectionAuthData`: Authentication details for the connection `ServiceConnectionAuthData GetAuthData(Guid connectionId)`
2	GetAccessToken	Retrieves an access token for a specified service connection.. Parameters: `connectionId` (Guid): The unique identifier of the service connection. `getNew` (bool, default = `false`): Whether to force retrieval of a new token. `doNotUpdate` (bool, default = `false`): Whether to prevent updating the stored token. Returns: `AuthTokenInfo`: Access token details. `AuthTokenInfo GetAccessToken(Guid connectionId, bool getNew = false, bool doNotUpdate = false)`

GetAuthData

Retrieves authentication data for a specified service connection.
Parameters:

connectionId (Guid): The unique identifier of the service connection.

Returns: ServiceConnectionAuthData: Authentication details for the connection

ServiceConnectionAuthData GetAuthData(Guid connectionId)

GetAccessToken

Retrieves an access token for a specified service connection..

Parameters:

connectionId (Guid): The unique identifier of the service connection.

getNew (bool, default = false): Whether to force retrieval of a new token.

doNotUpdate (bool, default = false): Whether to prevent updating the stored token.

Returns: AuthTokenInfo: Access token details.

AuthTokenInfo GetAccessToken(Guid connectionId, bool getNew = false, bool doNotUpdate = false)

Examples

Get password from Username/Password Service connection

$authInfo = $M42_ServiceConnection.GetAccessToken([System.guid]::New("932a2baf-b3cd-c94b-12f9-08dd6ab79223"))
$apiKey = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($authInfo.Token)).Split(':')[1]

Private SDK API

Contact Us

Overview

Usage

Use in code

PowerShell Integration

Example

Business Components

Data Provider

Methods

Log Provider

Parameters

Methods

Examples:

Web API Client

Parameters

Methods

Service Connection Manager

Methods

Related Articles