Adding Custom Health Events to Aternity

A health event indicates a device or application encountered a significant error which affects the overall health of the user experience, like a corrupted disk or a system crash. There are three types of health events: application health events, hardware health events, and system health events. A system health event for a device is a significant problem at the level of the operating system which impacts on the device's overall health, like BSODs or other system crashes.

Learn more about out of the box health events that Aternity supplies.

In addition to out of the box health events, you can create and add to Aternity any health event to troubleshoot issues with one device or view common symptoms across multiple devices in your organization.

Aternity detects Windows events in one of the following ways:
Aternity detects events in one of three ways
  • To create new events based on Event Log ID - contact Aternity SaaS Administration and supply the required Event Log ID

  • To create new events with WMI queries (for example, if antivirus is not running) - contact Aternity SaaS Administration and supply the WMI query

  • PowerShell script - see details below in this article

You can detect anything with PowerShell scripts. For example, whether the recycle bin or any other folder on the PC exceeds its allowed size, if there are too many very large messages in Outlook, the BitLocker Status, or anything else you want to detect.

Note

Adding custom health events with PowerShell scrips applies only to end-user devices with Agent 12.0.1 or later and only for customers who participate in the Beta program. Contact Aternity Beta Team.

It is possible to assign newly created events to Service Desk Alerts. Then you can connect the Service Desk Alert to a remediation action in order to automatically execute a remediation action upon the Service Desk Alert (learn more).

You can see all health events in the Device Health dashboard (learn more) or with REST API DEVICE_HEALTH_RAW.

Workflow

See below the workflow of adding custom health events to Aternity:

  1. Create a PowerShell script with the logic that will trigger a required health event.
  2. Validate with the tool that Aternity supplies that the script indeed triggers the event you defined.
  3. Sign the script with the trusted certificate. Lean more.
  4. Contact Aternity SaaS Administration and ask to add the script to Aternity.

Writing Script

Follow the rules for writing PowerShell scripts to create custom health events:

  • First specify the Agent library.
    Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll
  • Decide what issue you want to detect and if to send a health event in case it happens.

  • Add your specific logic when an event should be triggered and when it should not. To trigger an event, you must add SetEventOccurred value.

  • Use PowerShell ActionExtensionsMethods to set values to the desired attributes.

  • It is recommended to fill in optional attributes. This data is displayed in the dashboards and supplies a meaningful information about events.
    Methods Description
    EventOccurred

    Mandatory.

    This value will trigger event in case the defined issue occurs.

    Component

    Optional.

    Displays the name of the part of the software or hardware which caused this health event. For example, a battery, a network interface, a disk drive, printer, or a process name like AcroRd32.exe (or Point of Sale (com.company.app2 for mobile apps).

    ComponentType

    Optional.

    Displays the type of the part of the software or hardware which caused this health event.

    ComponentVersion

    Optional.

    Displays the version of the part of the software or hardware which caused this health event. For example, a process version like 19.10.20069.

    SubComponent

    Optional.

    Displays the name of a sub-component which caused this health event (for example, the DLL of an application crash).
    SubComponentType

    Optional.

    Displays the type of a sub-component which caused this health event.

    SubComponentVersion

    Optional.

    Displays the version of a sub-component which caused this health event (for example, the DLL version).

    Details

    Optional.

    Enter more details about event.

    Error

    Optional.

    ApplicationName

    Optional.

    Enter application name for details.

    In case of application health event, it is recommended to set the application name and to use the process as the Component.

See the template with the above rules:

try
{
    # Set new environment for Action Extensions Methods 
    Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll

    # Add any PowerShell business logic and check whether to raise a health event
    # TODO: Replace this with any customized PowerShell behavior
    [bool]$raiseHealthEvent $false

    # Check whether a custom health event should be created by the Agent
    if ($raiseHealthEvent -eq $true)
    {
       # Use the ActionExtensionsMethods in order to set the event attributes (note – only SetEventOccurred is mandatory)
       [ActionExtensionsMethods.PowershellPluginMethods]::SetEventOccurred()
       [ActionExtensionsMethods.PowershellPluginMethods]::SetComponent(“Name”)
    }
    Else
    {
        # Just do nothing since the service status isn’t stopped
    }
}
catch
{
    [ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed($_.Exception.Message)
}

Output

You can see all health events in the Device Health dashboard (learn more).
See all health events on the Device Health dashboard

Sample

The sample provides the script that checks if the CCMEXEC Windows service has stopped and creates a health event if the service indeed stopped.

try
{
    # Set new environment for Action Extensions Methods 
    Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll

    # Get the CCMEXEC windows service status
    $service = Get-Service -Name 'ccmexec' -ErrorAction SilentlyContinue

    # Create and send a custom health event when this service is stopped
    if ($service.Status -eq 'Stopped')
    {
                                [ActionExtensionsMethods.PowershellPluginMethods]::SetComponent ($service.DisplayName +" (" +  $service.Name + ")")
                                [ActionExtensionsMethods.PowershellPluginMethods]::SetDetails ("Service not running")
                                [ActionExtensionsMethods.PowershellPluginMethods]::SetComponentType($service.StartType + " Service")
                                [ActionExtensionsMethods.PowershellPluginMethods]::SetEventOccurred ()                
    }
    Else
    {
        # Just do nothing since the service status isn’t stopped
    }
}
catch
{
    [ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed($_.Exception.Message)
}

Signing scripts

For security reasons, by default, the Agent runs only scripts that are signed either by Aternity or by certificates listed in the Trusted Publishers store of the device on which you run the script. To open the Certificates dialog-box and to see the certificates included in the Trusted Publishers store of the device, open a Command Prompt window and run the certlm command.
Launch Local Computer Certificates
Tip

If using the default execution policy during Agents mass deployment, which is POWER_SHELL_MONITOR_POLICY=Trusted, make sure to place your certificates in the folder shown in the above figure.

It is possible to change the default parameter of the POWER_SHELL_MONITOR_POLICY in the Agent's batch file only during its installation. There are three possible options to alter:
  • Trusted - The default policy that automatically applies during Aternity Agent mass deployment.

  • Unrestricted - Aternity Agent runs any script, both signed and not signed.

  • Blocked - Aternity Agent blocks any script, either signed or not.

Changing these options is supported only for mass installation batch file by entering one of the following parameters: POWER_SHELL_MONITOR_POLICY=Unrestricted or POWER_SHELL_MONITOR_POLICY=Blocked

If the certificate you use for signing is not listed in the Trusted Publishers store, specify in the Agent's batch file with what certificate to sign scripts. You can define up to two certificates during Agent's mass deployment: TRUSTED_CERTIFICATE_SUBJECT1= and TRUSTED_CERTIFICATE_SUBJECT2=. Enter the value to specify the subject of the certificate.

Script Validation

Prior to sending your scripts to Aternity, check that they properly process. Use the supplied by Aternity tool to process the script without running it and to validate its syntax and output.
  1. Start the validation tool by running PowerShellPluginValidation.exe which is located in the Agent installation folder (for example, /ProgramFiles\Aternity Information Systems\Agent).
    Run validation tool
  2. Click the Select button to browse to your PowerShell script.
  3. Click the Start button and check the results.
    See the sample in case an event was not identified and no health event was generated.
    Script validation fails
    See the sample in case a health event was successfully generated. Once this script is added to Aternity, you will get a health event in the dashboard and REST API query.
    Script validation is successful

Contacting Aternity SaaS Administration

When contacting Aternity SaaS Administration, provide the details for the following:
  • First, supply a short description of a new health event you want to add to Aternity.

  • Specify to what category the new health event belongs. There are three types of health events: application health events, hardware health events, and system health events. To create a new category, provide SaaS administrator with details.

  • Specify the Subcategory for the new health event. Under the main categories of health events: Application, Background Process, Hardware and System, there are sub-categories like Windows Background Process, MobileApp, DotNet, Network, Battery and so on.

  • Decide the Severity level of your new health event. For example, if a background process crashes, its severity is minor , if an application crashes, it is major , while a system crash is critical .

  • Specify Context that can be either user or system.

  • Specify frequency to configure the check interval you desire. For example, the script will run once in 30 minutes to check if there are events. If there is an event, it will be detected and reported. The default frequency is one minute. We recommend running it once a day or once an hour, if required.