API integration

The StackState SCOM API integration sends requests to the SCOM API to retrieve topology data and events.

• Agent V2 connects to the configured SCOM API.

• Topology data and events for the configured criteria are retrieved from SCOM.

• Agent V2 pushes retrieved data to StackState.

• StackState translates incoming SCOM topology data into components and relations. Incoming events are used to determine component health state and publish SCOM alerts in StackState.

When to choose API integration

The SCOM API integration produces a clean topology in StackState by allowing you to specify the topology to collect. You can run the SCOM check from any StackState Agent V2 as long as it can connect to both the SCOM API and StackState.

Retrieving a large topology can require a high number of API requests, this can take time and may place some stress on your SCOM system. The size of topology you can retrieve may also be limited by the number of requests possible. To avoid this, use the SCOM PowerShell integration.

To set up the StackState SCOM API integration, you need to have:

• ​StackState Agent V2 must be installed on any machine that can connect to both SCOM and StackState.

• A running SCOM instance (version 1806 or 2019).

• A SCOM user with the role Operations Manager Read-Only Operators.

To enable the SCOM check and begin collecting data from SCOM, add the following configuration to StackState Agent V2:

1. Edit the Agent integration configuration file /etc/sts-agent/conf.d/scom.d/conf.yaml to include details of your SCOM instance:

   • hostip - SCOM IP.

   • domain - active directory domain where the SCOM is located.

   • username

   • password - use secrets management to store passwords outside of the configuration file.

   • auth_mode - Network or Windows (Default is Network).

   • integration mode - to use the API integration, set to api.

   • max_number_of_requests - The maximum number of requests that should be sent to the SCOM API. See how to determine the required number of API requests, default 10000.

   • criteria - A query to specify the components to retrieve data for.

     init_config:
       # run every minute
       min_collection_interval: 60
     instances:
     - hostip: localhost
       domain: stackstate
       username: <username>
       password: <password>
       auth_mode: Network
       integration_mode: api    # can be api or powershell, default api
       max_number_of_requests: 10000   # default 10000
       criteria : "(FullName LIKE 'Microsoft.Windows.Computer:%')" # an Operations Manager Data Query

2. ​Restart the StackState Agent(s) to apply the configuration changes.

Specify the components to retrieve data for

The components to retrieve data for can be defined using an Operations Manager Data Query (docs.microsoft.com). For example, to retrieve data for all Microsoft Windows computers:

criteria : “(FullName LIKE ‘Microsoft.Windows.Computer:%’)”

Errors in the configured criteria query will be reported in the StackState Agent log file.

2020-11-05 09:19:31 GMT | ERROR | ... | (scom2.py:114) | Invalid criteria :The property FullNsame is not valid for the given criteria.

Determine the required number of API requests

Use the script below to determine the number of components that match a criteria query and the number of dependencies. Add these numbers together and multiply by 2 to find the required number of API requests to retrieve topology data from SCOM. Two API requests are required to retrieve data for each component and each dependency.

$components = (Get-SCOMManagementGroup).GetMonitoringObjects("FullName LIKE 'Microsoft.Windows.Computer:%'")
"total number of components that match criteria: "+$components.count 
$deps= ($components.GetRelatedMonitoringObjects('Recursive')).count
"Total number of dependencies: "+ $deps

As two API requests are required to retrieve data for each component and each dependency, the configured max_number_of_requests must be higher than the returned total number of components that match criteria AND total number of dependencies multiplied by 2.