Skip to main content
Matrix42 Self-Service Help Center

Software Development Kit (SDK) Release Notes

Overview

Matrix42_SDK.png

The Matrix42 Software Development Kit (SDK) provides powerful tools (PowerShell libraries and .NET libraries) to communicate with Empirum.
Customers, partners, and software vendors can integrate Empirum into existing processes and products or extend its enormous capabilities to perfectly fit into their enterprises.
The Matrix42 Software Development Kit (SDK) for Client Management includes everything needed to access the power of the platform from other systems:

  • PowerShell CmdLets offer easy to use access to Empirum via scripting
  • .NET based API (Application Programming Interface) DLL’s allows powerful programming with all .NET compatible programming languages

System Requirements

In general, the SDK can be used with all currently supported Empirum versions.
Client:

New features and changes

SDK Version 1.39 contains the following changes and new functionalities:

Security Enhancements
PRB36804: Vulnerability in OData Library can be exploited for Denial-of-Service attack. In the fix, the OData library has been updated to latest available version.
Feature Enhancements
Optional packages can be assigned using a new distribution parameter in the same way Empirum supports it using one of the consoles.

Installation

  1. Start Empirum DBUtil and setup the Empirum-API service.
  2. Activate your preferred protocol HTTP (e.g. port 9200) or TCP (e.g. port 9100) and set the security (Encrypted/Not encrypted) for the communication channel.
  3. Apply all settings and restart the Empirum-API service to run with the new settings.
  4. Install the Empirum SDK Windows Installer package on the computer you want to run the SDK.
  5. You can install the SDK manually or you can use the provided Empirum package (ready to import) from the Matrix42 Marketplace.

The installation of the SDK on the Empirum Master Server is not necessary.

After the installation, you will find the following folder structures:

Description Path
PowerShell module \Windows\system32\WindowsPowerShell\v1.0\Modules\Matrix42.SDK.Empirum.PowerShell
.NET library .\Program Files\Matrix42\SDK\Empirum
Documentation .\Program Files\Matrix42\SDK\Empirum\Documentation
PowerShell sample scripts .\Program Files\Matrix42\SDK\Empirum\Samples


All activities are available in any PowerShell host on the machine because the installer extends the module path. When uninstalling these changes will be reverted as well.
You can either use the Empirum PowerShell SDK console that will be created by the installation process in the start menu. It is also possible to use any other PowerShell console or PowerShell editor.
To see how it works you can try the sample script - GettingStarted.ps1.
To run this script in your environment just add/replace the credentials in the header of the script and let it run.

Please be sure, that you run all scripts with elevated rights, if UAC is activated.

All sample scripts are using unencrypted passwords. In a productive environment, we strongly recommend encrypted AES256 passwords. Please use the tool EmpCrypt.exe which will be shipped as a part of Empirum. You can find it on your Empirum Master Server in the folder \Empirum\AddOns\Encrypter. Please use the /AES256 parameter for the password.
To connect to the Empirum-API use an Empirum user (SQL or Windows user) which is member of the role EMP_SERVICES.

Available Commandlets

You can get the list of all available cmdlets by typing:
Get-Command -Module Matrix42.SDK.Empirum.PowerShell
You can get the help for each cmdlet by typing:
Get-Help <Cmdlet> -Full
For a complete cmdlet overview, see also the HTML documentation
Start > All Programs > Matrix42 SDK > Empirum PowerShell SDK Documentation

Audit

All actions except the Get- and Find- functions will be audited.
You can view the audit entries in the EMC > Management > Audit > Services > Empirum API/SDK.

Troubleshooting

  1. Please be sure the Empirum-API service is running (Empirum Interface Hosting Service).
  2. Check the Empirum-API log file ehost.log in C:\Program Files\Empirum\Empirum API on your Empirum Master Server for errors.
  3. Check the port availability from the client to the server.

Supported PowerShell Cmdlets (Empirum Version)

PowerShell Cmdlets >= 21.0.3
Add-EmpirumComputerToGroup SDK_Yes.png
Add-EmpirumPackageToGroup SDK_Yes.png
Close-Matrix42ServiceConnection SDK_Yes.png
Export-EmpirumPackage SDK_Yes.png
Find-EmpirumComputer SDK_Yes.png
Find-EmpirumGroup SDK_Yes.png
Find-EmpirumPackage SDK_Yes.png
Get-EmpirumBackendTaskStatus SDK_Yes.png
Get-EmpirumBootConfiguration SDK_Yes.png
Get-EmpirumBootConfiguration SDK_Yes.png
Get-EmpirumDistributioncommands SDK_Yes.png
Get-EmpirumPackageState SDK_Yes.png
Get-EmpirumProperty SDK_Yes.png
Import-EmpirumPackage SDK_Yes.png
Invoke-EmpirumComputerActivation SDK_Yes.png
Invoke-EmpirumComputerDeactivation SDK_Yes.png
Invoke-EmpirumComputerEndOfLife SDK_Yes.png
Invoke-EmpirumGroupActivation SDK_Yes.png
Invoke-EmpirumGroupDeactivation SDK_Yes.png
Invoke-EmpirumPackageReinstallation SDK_Yes.png
New-EmpirumBootConfiguration SDK_Yes.png
New-EmpirumBootConfiguration SDK_Yes.png
New-EmpirumComputer SDK_Yes.png
New-EmpirumGroup SDK_Yes.png
Open-Matrix42ServiceConnection SDK_Yes.png
Remove-EmpirumComputer SDK_Yes.png
Remove-EmpirumComputerFromGroup SDK_Yes.png
Remove-EmpirumGroup SDK_Yes.png
Remove-EmpirumPackageFromGroup SDK_Yes.png
Set-EmpirumBootConfiguration SDK_Yes.png
Set-EmpirumDistributioncommands SDK_Yes.png
Set-EmpirumProperty SDK_Yes.png
Start-HashGeneration SDK_Yes.png

SDK_Yes.png = Functionality available
SDK_No.png = Functionality not available

Supported Audit Functionality (Empirum Version)

  >= 21.0.3
Audit SDK_Yes.png

EAI – PowerShell Cmdlets Mapping

 

EAI Functions PowerShell Cmdlets
ActivateClientInSoftwareGroup Invoke-EmpirumComputerActivation
ActivateClient_OS Invoke-EmpirumComputerActivation
ActivateClient_SW Invoke-EmpirumComputerActivation
ActivateClient_SWOS Invoke-EmpirumComputerActivation
ActivateConfigGroup_OS Invoke-EmpirumGroupActivation
ActivateConfigGroup_SW Invoke-EmpirumGroupActivation
ActivateConfigGroup_SWOS Invoke-EmpirumGroupActivatio
ActivateSoftwareGroup Invoke-EmpirumGroupActivation
ActivateUser  
AssignClientToConfigGroup Add-EmpirumComputerToGroup
AssignClientToConfigGroupAndActivate_OS Add-EmpirumComputerToGroup + Invoke-EmpirumComputerActivation
AssignClientToConfigGroupAndActivate_SW Add-EmpirumComputerToGroup + Invoke-EmpirumComputerActivation
AssignClientToConfigGroupAndActivate_SWOS Add-EmpirumComputerToGroup + Invoke-EmpirumComputerActivation
AssignClientToSoftwareGroup Add-EmpirumComputerToGroup
AssignEmpirumServerToClient Set-EmpirumProperty
AssignEmpirumServerToConfigGroup Set-EmpirumProperty
AssignPatchManagementClassToConfigGroup Add-EmpirumPackageToGroup
AssignPXEToConfigGroup Add-EmpirumPackageToGroup
AssignSoftwareClassToClient Multiple steps neccessary:
- New-EmpirumGroup
- Add-EmpirumComputertoGroup
- Add-EmpirumPackageToGroup
AssignSoftwareClassToClientAndActivate_SW Multiple steps neccessary:
- New-EmpirumGroup
- Add-EmpirumComputertoGroup
- Add-EmpirumPackageToGroup
- Invoke-EmpirumComputerActivation
AssignSoftwareClassToConfigGroup Add-EmpirumPackageToGroup
AssignSoftwareToClient Multiple steps neccessary:
- New-EmpirumGroup
- Add-EmpirumComputertoGroup
- Add-EmpirumPackageToGroup
AssignSoftwareToClientAndActivate_SW Multiple steps neccessary:
- New-EmpirumGroup
- Add-EmpirumComputerToGroup
- Add-EmpirumPackageToGroup
- Invoke-EmpirumComputerActivation
AssignUserToConfigGroup  
CloneClient Please use the script CloneComputer.ps1
CreateClient New-EmpirumComputer
CreateConfigGroup New-EmpirumGroup
CreateUser  
DeactivateClient_OS Invoke-EmpirumComputerDeActivation
DeactivateClient_SW Invoke-EmpirumComputerDeActivation
DeactivateClient_SWOS Invoke-EmpirumComputerDeActivation
DeactivateConfigGroup_OS Invoke-EmpirumGroupDeActivation
DeactivateConfigGroup_SW Invoke-EmpirumGroupDeActivation
DeactivateConfigGroup_SWOS Invoke-EmpirumGroupDeActivation
DeactivateUser  
DeleteAllEmpirumServerFromClient Set-EmpirumProperty
DeleteClientFromConfigGroup Remove-EmpirumComputerFromGroup
DeleteClientFromDB Remove-EmpirumComputer
DeleteClientFromSwGroup Remove-EmpirumComputerFromGroup
DeleteConfigGroup Remove-EmpirumGroup
DeleteEmpirumServerFromClient Set-EmpirumProperty
DeleteEmpirumServerFromConfigGroup Set-EmpirumProperty
DeletePatchManagementGroupFromConfigGroup Remove-EmpirumPackageFromGroup
DeletePXEFromConfigGroup Remove-EmpirumPackageFromGroup
DeleteSoftwareClassFromConfigGroup Remove-EmpirumPackageFromGroup
DeleteSoftwareFromConfigGroup Remove-EmpirumPackageFromGroup
DeleteSoftwareFromDB  
DeleteSoftwareGroupFromDB  
DeleteUserFromConfigGroup  
DeleteUserFromDB  
DeleteVariableValueFromConfigGroup Set-EmpirumProperty
DeleteVariableValueFromUser  
DeleteVariableValueOnClient Set-EmpirumProperty
GeneratePackageHash Start-HashGeneration
ReinstallSoftware Invoke-EmpirumPackageReinstallation
SetConfigGroupDistributionCommands Set-EmpirumDistributionCommands
SetGroupRights  
SetSoftwareClassDistributionCommands Set-EmpirumDistributionCommands
SetSoftwareDistributionCommands Set-EmpirumDistributionCommands
SetSoftwareGroupDistributionCommands Set-EmpirumDistributionCommands
SetVariableValueOnClient Set-EmpirumProperty
SetVariableValueOnConfigGroup Set-EmpirumProperty
SetVariableValueOnUser  
UninstallSoftwareFromClient Set-EmpirumDistributionCommands

 

  • Was this article helpful?