Software Development Kit (SDK) Release Notes

+ More

Table of Contents

Overview System Requirements New features and changes Installation Available Commandlets Audit Troubleshooting Supported Power Shell Cmdlets (Empirum Version) Supported Audit Functionality (Empirum Version) EAI – Power Shell Cmdlets Mapping

Overview

The Matrix42 Software Development Kit (SDK) provides powerful tools (Power Shell 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:

  • Power Shell Cmd Lets 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:

The usage of the Empirum SDK is only for Empirum Administrators with EMP_ADMIN role or 'db_owner'.

 

New features and changes

SDK Version 1.3.17 contains the following changes and new functionalities:

Feature Enhancements
  • The Cmdlet "Invoke-Empirum Package Reinstallation" has been extended:
    It is now possible to trigger a reinstallation with prior uninstallation. (requires Empirum API in version 25.4.0 or higher)
  • PRB38725: Empirum SDK - computer property does not match with Empirum Property parameter.
    • Renamed IEmpirum Computer properties (left old property names for backward compatibility)
      • Domain Name -> Domain
      • Is Domain Member -> Is Domain
      • Last Invertory -> Inventory Date
    • Renamed New-Empirum Computer Cmdlet parameter (created alias for old parameter names)
      • Domain Name -> Domain
      • Is Domain Member -> Is Domain
  • PRB38453: Empirum SDK using the same Empirum Session token.
    • Added thread ID to log output.
    • Added thread safe session operations to avoid parallel calls to the same session object.

SDK Version 1.3.16 contains the following changes and new functionalities:

Feature Enhancements
  • PRB38794: Empirum SDK Workflows with Invoke Powershell fail after update to 12.1.2.
  • All SDK libraries are now strong named assemblies.

SDK Version 1.3.15 contains the following changes and new functionalities:

Feature Enhancements
  • If the Cmd Let Set-Empirum Distribution Commands is called without the Optional Until parameter, the corresponding Optional Date value in the database is reset.
  • Logging has been extended.
  • Using new package dependency Microsoft.Data.Services.Client version 5.8.5.

SDK Version 1.3.13 contains the following changes and new functionalities:

Feature Enhancements
  • PRB37127: Workflows using "Empirum Disconnection" Activity fail when running on Monitoring Level "Troubleshooting".
  • PRB37497: The Empirum Computer Property 'Inventory Date' returns inventory date/time in UTC format if available in scan data. This requires that the Inventory data was collected by an Inventory scanner with Version 23.0.0 (including all Hotfixes) or higher. Otherwise the property will still return a local date/time.

SDK Version 1.3.12 contains the following changes and new functionalities:

Feature Enhancements
  • Added 'Schedule String' support to Set-Empirum Distribution Commands. Requires Empirum 23.0 or higher.

SDK Version 1.3.11 contains the following changes and new functionalities:

Feature Enhancements
  • New cmdlet Remove-Empirum Package has been added to remove a package from the database and the file share completely. Requires Empirum 23.0 or higher.
  • Added 'Ready To Install' support to Set-Empirum Property. Requires Empirum 23.0 or higher.

SDK Version 1.3.10 contains the following changes and new functionalities:

Feature Enhancements
  • PRB37089: There is a log file created for each Windows user now (inside the log file folder), so that there is no more issue with access permissions.

SDK Version 1.3.9 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.

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
Power Shell module \Windows\system32\Windows Power Shell\v1.0\Modules\Matrix42.SDK.Empirum.Power Shell
.NET library .\Program Files\Matrix42\SDK\Empirum
Documentation .\Program Files\Matrix42\SDK\Empirum\Documentation
Power Shell sample scripts .\Program Files\Matrix42\SDK\Empirum\Samples


All activities are available in any Power Shell 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 Power Shell SDK console that will be created by the installation process in the start menu. It is also possible to use any other Power Shell console or Power Shell editor.
To see how it works you can try the sample script - Getting Started.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 Emp Crypt.exe which will be shipped as a part of Empirum. You can find it on your Empirum Master Server in the folder \Empirum\Add Ons\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.Power Shell
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 Power Shell 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 Data\Matrix42\Logs\Empirum API on your Empirum Master Server for errors.
  3. Check the port availability from the client to the server.

Supported Power Shell Cmdlets (Empirum Version)

Power Shell Cmdlets >= 21.0.3
Add-Empirum Computer To Group
Add-Empirum Package To Group
Close-Matrix42Service Connection
Export-Empirum Package
Find-Empirum Computer
Find-Empirum Group
Find-Empirum Package
Get-Empirum Backend Task Status
Get-Empirum Boot Configuration
Get-Empirum Boot Configuration
Get-Empirum Distributioncommands
Get-Empirum Package State
Get-Empirum Property
Import-Empirum Package
Invoke-Empirum Computer Activation
Invoke-Empirum Computer Deactivation
Invoke-Empirum Computer End Of Life
Invoke-Empirum Group Activation
Invoke-Empirum Group Deactivation
Invoke-Empirum Package Reinstallation (Uninstall before reinstall >= 25.4.0)
New-Empirum Boot Configuration
New-Empirum Boot Configuration
New-Empirum Computer
New-Empirum Group
Remove-Empirum Package (Supports Software packages, Agent Templates, Boot Configurations and Variable Configurations) >= 23.0
Open-Matrix42Service Connection
Remove-Empirum Computer
Remove-Empirum Computer From Group
Remove-Empirum Group
Remove-Empirum Package From Group
Set-Empirum Boot Configuration
Set-Empirum Distributioncommands
Set-Empirum Property (Ready To Install >= 23.0)
Start-Hash Generation

= Functionality available
 

 = Functionality not available

Supported Audit Functionality (Empirum Version)

  >= 21.0.3
Audit

EAI – Power Shell Cmdlets Mapping

EAI Functions Power Shell Cmdlets
Activate Client In Software Group Invoke-Empirum Computer Activation
Activate Client_OS Invoke-Empirum Computer Activation
Activate Client_SW Invoke-Empirum Computer Activation
Activate Client_SWOS Invoke-Empirum Computer Activation
Activate Config Group_OS Invoke-Empirum Group Activation
Activate Config Group_SW Invoke-Empirum Group Activation
Activate Config Group_SWOS Invoke-Empirum Group Activatio
Activate Software Group Invoke-Empirum Group Activation
Activate User  
Assign Client To Config Group Add-Empirum Computer To Group
Assign Client To Config Group And Activate_OS Add-Empirum Computer To Group + Invoke-Empirum Computer Activation
Assign Client To Config Group And Activate_SW Add-Empirum Computer To Group + Invoke-Empirum Computer Activation
Assign Client To Config Group And Activate_SWOS Add-Empirum Computer To Group + Invoke-Empirum Computer Activation
Assign Client To Software Group Add-Empirum Computer To Group
Assign Empirum Server To Client Set-Empirum Property
Assign Empirum Server To Config Group Set-Empirum Property
Assign Patch Management Class To Config Group Add-Empirum Package To Group
Assign PXETo Config Group Add-Empirum Package To Group
Assign Software Class To Client

Multiple steps neccessary:

  • New-Empirum Group
  • Add-Empirum Computerto Group
  • Add-Empirum Package To Group
Assign Software Class To Client And Activate_SW

Multiple steps neccessary:

  • New-Empirum Group
  • Add-Empirum Computerto Group
  • Add-Empirum Package To Group
  • Invoke-Empirum Computer Activation
Assign Software Class To Config Group Add-Empirum Package To Group
Assign Software To Client

Multiple steps neccessary:

  • New-Empirum Group
  • Add-Empirum Computerto Group
  • Add-Empirum Package To Group
Assign Software To Client And Activate_SW

Multiple steps neccessary:

  • New-Empirum Group
  • Add-Empirum Computer To Group
  • Add-Empirum Package To Group
  • Invoke-Empirum Computer Activation
Assign User To Config Group  
Clone Client Please use the script Clone Computer.ps1
Create Client New-Empirum Computer
Create Config Group New-Empirum Group
Create User  
Deactivate Client_OS Invoke-Empirum Computer De Activation
Deactivate Client_SW Invoke-Empirum Computer De Activation
Deactivate Client_SWOS Invoke-Empirum Computer De Activation
Deactivate Config Group_OS Invoke-Empirum Group De Activation
Deactivate Config Group_SW Invoke-Empirum Group De Activation
Deactivate Config Group_SWOS Invoke-Empirum Group De Activation
Deactivate User  
Delete All Empirum Server From Client Set-Empirum Property
Delete Client From Config Group Remove-Empirum Computer From Group
Delete Client From DB Remove-Empirum Computer
Delete Client From Sw Group Remove-Empirum Computer From Group
Delete Config Group Remove-Empirum Group
Delete Empirum Server From Client Set-Empirum Property
Delete Empirum Server From Config Group Set-Empirum Property
Delete Patch Management Group From Config Group Remove-Empirum Package From Group
Delete PXEFrom Config Group Remove-Empirum Package From Group
Delete Software Class From Config Group Remove-Empirum Package From Group
Delete Software From Config Group Remove-Empirum Package From Group
Delete Software From DB  
Delete Software Group From DB  
Delete User From Config Group  
Delete User From DB  
Delete Variable Value From Config Group Set-Empirum Property
Delete Variable Value From User  
Delete Variable Value On Client Set-Empirum Property
Generate Package Hash Start-Hash Generation
Reinstall Software Invoke-Empirum Package Reinstallation
Set Config Group Distribution Commands Set-Empirum Distribution Commands
Set Group Rights  
Set Software Class Distribution Commands Set-Empirum Distribution Commands
Set Software Distribution Commands Set-Empirum Distribution Commands
Set Software Group Distribution Commands Set-Empirum Distribution Commands
Set Variable Value On Client Set-Empirum Property
Set Variable Value On Config Group Set-Empirum Property
Set Variable Value On User  
Uninstall Software From Client Set-Empirum Distribution Commands

Related Articles