Private SDK API

Daniel White
2025-08-26T20:33:00Z

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:

"Invoke PowerShell" Workflow Activity

User-defined System Diagnostic Rules

Scripted Web Operations

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.
$M42_GlobalCache | Global Cache is a singleton service for storing shared data across the whole application.

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

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

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

# | 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.ServiceConnection.Contracts.IExternalAuthService
Powershell global variable: $M42_ServiceConnection

Methods

# | 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)

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]

Global Cache

The Global Cache provides functionality for storing custom data that can be shared across the entire Web Application process lifecycle. Cached data can be stored either:

for the full lifetime of the Web Application process, or

for a defined duration when an explicit expiration time is specified for the cache entry.

Only a single instance of the Global Cache exists. This ensures access to the same cached data regardless of the process or component requesting it.

Supported starting from version: 26.1
Interface: Matrix42.Contracts.Common.Caching.IGlobalCache
Powershell global variable: $M42_GlobalCache

Methods

# | Method | Description

1

Get

Retrieves a value from the cache by its key .
Parameters:

key(string): Unique identifier of the cache entry.

defaultValue(string): Value to return if the cache entry does not exist or has expired .

Returns: string: The value in the cache instance for the specified key, if the entry exists; otherwise, defaultValue

string Get(string key, string defaultValue);

2

Set

Adds or updates a cache entry.

Parameters:

key(Guid): The unique identifier for the cache item.

value(string): Data stored in cache. Complex data types must be serialized to a string (e.g. JSON) before storing

expiration(Timespan, optional): Defines how long the cache entry remains valid. If not specified, the entry persists for the lifetime of the application process..

void Set(string key, string value);
void Set(string key, string value, TimeSpan expiration);

| |

Examples

Get password from Username/Password Service connection

$ts = [Timespan]::FromMinutes(1)
$M42_GlobalCache.Set("k1", "a", $ts)

return $M42_GlobalCache.Get("k1", "not found")