Skip to main content
Matrix42 Self-Service Help Center

Private SDK API

  1. Last updated
  2. Save as PDF

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

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.

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

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 data (overrides arguments). 

  • 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 data (overrides arguments). 

  • 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 data (overrides arguments). 

  • 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 data (overrides arguments). 

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 data (overrides arguments retrieved via argFunc). 

  • 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 data (overrides arguments retrieved via argFunc). 

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

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Reference
  2. Tags
    This page has no tags.