Software Development Kit (SDK) Release Notes

Overview

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:

Any 64-bit Windows operating system that supports at least Windows PowerShell 3.0.
http://www.microsoft.com/en-us/download/details.aspx?id=34595
The SDK client must be able to communicate with the Empirum-API over the configured port (e.g. port 9200).

New features and changes

SDK Version 1.3.14 contains the following changes and new functionalities:

Feature Enhancements
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 'InventoryDate' 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.

Feature Enhancements

PRB37127: Workflows using "Empirum Disconnection" Activity fail when running on Monitoring Level "Troubleshooting".
PRB37497: The Empirum Computer Property 'InventoryDate' 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 'ScheduleString' support to Set-EmpirumDistributionCommands. Requires Empirum 23.0 or higher.

SDK Version 1.3.11 contains the following changes and new functionalities:

Feature Enhancements
New cmdlet Remove-EmpirumPackage has been added to remove a package from the database and the file share completely. Requires Empirum 23.0 or higher. Added 'ReadyToInstall' support to Set-EmpirumProperty. 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

Start Empirum DBUtil and setup the Empirum-API service.
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.
Apply all settings and restart the Empirum-API service to run with the new settings.
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
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

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

Supported PowerShell Cmdlets (Empirum Version)

PowerShell Cmdlets	>= 21.0.3
Add-EmpirumComputerToGroup
Add-EmpirumPackageToGroup
Close-Matrix42ServiceConnection
Export-EmpirumPackage
Find-EmpirumComputer
Find-EmpirumGroup
Find-EmpirumPackage
Get-EmpirumBackendTaskStatus
Get-EmpirumBootConfiguration
Get-EmpirumBootConfiguration
Get-EmpirumDistributioncommands
Get-EmpirumPackageState
Get-EmpirumProperty
Import-EmpirumPackage
Invoke-EmpirumComputerActivation
Invoke-EmpirumComputerDeactivation
Invoke-EmpirumComputerEndOfLife
Invoke-EmpirumGroupActivation
Invoke-EmpirumGroupDeactivation
Invoke-EmpirumPackageReinstallation
New-EmpirumBootConfiguration
New-EmpirumBootConfiguration
New-EmpirumComputer
New-EmpirumGroup
Remove-EmpirumPackage (Supports Software packages, Agent Templates, Boot Configurations and Variable Configurations)	>= 23.0
Open-Matrix42ServiceConnection
Remove-EmpirumComputer
Remove-EmpirumComputerFromGroup
Remove-EmpirumGroup
Remove-EmpirumPackageFromGroup
Set-EmpirumBootConfiguration
Set-EmpirumDistributioncommands
Set-EmpirumProperty	(ReadyToInstall >= 23.0)
Start-HashGeneration

= Functionality available
= Functionality not available

Supported Audit Functionality (Empirum Version)

	>= 21.0.3
Audit

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