Python 3 Matrix42 SDK for Enterprise Service Management (ESM) tool

"ERP for Software Asset Management"

The background story

As of July 2020, Matrix42 AG, a German company is offering a Configuration Management Database (CMBD) - basically a competing product to ServiceNOW and many others like Microsoft Intune.

Their Angular based product can be installed on-prem and used as ITIL supporting tool for the company.

It provides a REST API which this Python3+ SDK tries to cover. Unfortunately, Swagger support is currently not available which has led me to write this client package myself - becoming my first python3 client SDK.

It shows - also due to learning Python OOP principles.

Documentation of Rest API

• https://help.matrix42.com/030_DWP/030_INT Intro
• https://help.matrix42.com/030_DWP/030_INT/Business_Processes_and_API_Integrations How to use the API
• https://help.matrix42.com/030_DWP/030_INT/Business_Processes_and_API_Integrations/Matrix42_Web_Services_API Matrix42 Approach to the API
• https://help.matrix42.com/030_DWP/030_INT/Business_Processes_and_API_Integrations/Web_Services%3A_Authentication_types Example of AuthN
• https://help.matrix42.com/030_DWP/030_INT/Business_Processes_and_API_Integrations/Web_Services_tokens%3A_Generate_API_Token Generate API Token

Setting up the Sphinx auto-generate documentation:

• https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/

What works and what does not?

Works:

• get and put (i.e. update) fragment

Use Cases:

• updating CI version numbers

Semi/or not working:

• creating fragment was not tested, but is implemented as a Rest API call
• get and put object -> here not tested extensively and one must expect bugs

Testing

Without having a Matrix42 ESM portal which allows API access and is publicly available for unlimited use, the only option how to test this library is to use your own ESM portal installation (be it in public cloud or on prem). Hence the need to use your own API keys, etc.

From this follows that this library cannot - as of now - include more python tests, at least not publicly available. It is my recommendation to write your own, private tests and report issues here.

Sorry for inconvenience!

Usage

Python 3 - Simple Testing

Using requests you can call

import requests

url = "https://xxxx/m42Services/api/ApiToken/GenerateAccessTokenFromApiToken/"

payload = {}
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer the 'short' version of bearer token generated from Administration Panel in the GUI'
}

response = requests.request("POST", url, headers=headers, data = payload, verify = False)

print(response.text.encode('utf8'))

# only then start using proper API requests
import requests

url = "https://xxxx/m42Services/api/data/fragments/Ud_SoftwareproduktVersionClassBase/775c82cf-d243-4bfb-a1b2-f3edad93c826"

payload = {}
headers = {
  'Authorization': 'Bearer "output of the previous requests "RawToken" '
}

response = requests.request("GET", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

Matrix42 SDK for Python

To use Matrix42 SDK, first decide which authN approach you are going to use.

For a basic, create a Matrix42RestClient object by using your (or any other matrix42 CMBD) account:

import matrix42sdk
from matrix42sdk import Matrix42RestClient
from matrix42sdk.api_endpoints import *

For using Access/API Tokens, you can set your MATRIX42SDK_API_TOKEN via a shell (higher priority):

export MATRIX42_URL="xxx"
export MATRIX42SDK_API_TOKEN="xxx"

and then:

mat = api_endpoints.fragments.FragmentsDataService()

Then to get a fragment for a specific CI, insert correct parameters according to the documentation:

JUPYTERLAB_ID_FRAG = "8c51cfff-bf16-452e-8d2c-527cc25518c3"
SYS_ENTITY = "SPSSoftwareType"
full_ci_frg = mat.get_fragement(SYS_FRAGEMENT, JUPYTERLAB_ID_FRAG)

Documentation

We use https://sphinx-rtd-theme.readthedocs.io/ and https://www.sphinx-doc.org/en/master/

cd docs
sphinx-apidoc -o source ../matrix42sdk
make html

Building this package yourself

This package is being build on Azure DevOps services:

https://dev.azure.com/johnmalc/Matrix42SDK/_build

and further uses SonarCloud:

https://sonarcloud.io/dashboard?id=dmpe_matrix42sdk

Use to install package from non-PyPI feed (the azure one):

pip3 install --index https://pkgs.dev.azure.com/johnmalc/Matrix42SDK/_packaging/my-feed/pypi/simple/ matrix42sdk

PyPI

poetry build