TrueSight Web Services REST API

TRUESIGHT WEB SERVICES
REST API
Bhuvaneswaran Ekanathan
TrueSight Web Services REST API
TABLE OF CONTENTS
Introduction .................................................................................................................................................................. 3
TrueSight Web Services – REST API ........................................................................................................................................ 3
Assumptions ............................................................................................................................................................................... 3
Web Services Architecture ........................................................................................................................................................ 3
Web Services Authorization ...................................................................................................................................................... 5
Setting Up Postman for Web Services Testing ......................................................................................................... 6
Web Browser Extension ............................................................................................................................................................ 6
Postman for Windows ................................................................................................................................................................ 6
TrueSight Presentation Server Web Services ........................................................................................................... 8
Web Services Authentication .................................................................................................................................................... 9
Input Parameters using JSON Format ....................................................................................................................................................... 9
Input Parameters using x-www-form-urlencoded Format ..................................................................................................................... 10
Retrieving Configuration Data ................................................................................................................................................. 11
Retrieving Performance Data .................................................................................................................................................. 12
Retrieving List of Devices........................................................................................................................................................ 13
Retrieving List of Monitor Instances ...................................................................................................................................... 14
Retrieving List of Monitor Types ............................................................................................................................................. 15
Retrieving List of Tenants ....................................................................................................................................................... 16
Managing Integration Service ................................................................................................................................................. 17
Create Integration Service ........................................................................................................................................................................ 17
Update Integration Service ....................................................................................................................................................................... 18
List Integration Service - GET ................................................................................................................................................................... 19
List Integration Service - POST ................................................................................................................................................................ 20
Delete Integration Service ......................................................................................................................................................................... 21
Create Integration Service Cluster ........................................................................................................................................................... 22
Update Integration Service Cluster .......................................................................................................................................................... 23
List Integration Service Cluster - GET ..................................................................................................................................................... 24
List Integration Service Cluster - POST ................................................................................................................................................... 25
Delete Integration Service Cluster ........................................................................................................................................................... 26
Managing Policies .................................................................................................................................................................... 27
Create Policy .............................................................................................................................................................................................. 27
Monitoring Policy.............................................................................................................................................................................................................. 28
Configuring Filters ......................................................................................................................................................................................................................................... 28
Configuring Agent Thresholds ..................................................................................................................................................................................................................... 30
Configuring Intelligent Thresholds .............................................................................................................................................................................................................. 32
Configuring Rulesets ..................................................................................................................................................................................................................................... 34
Configuring Agent Communication with Infrastructure Management .................................................................................................................................................... 36
Blackout Policy ................................................................................................................................................................................................................. 38
Staging Policy ................................................................................................................................................................................................................... 40
Update Policy ............................................................................................................................................................................................. 42
List Policy – GET Method .......................................................................................................................................................................... 43
List Policy – POST Method ....................................................................................................................................................................... 44
Delete Policy ............................................................................................................................................................................................... 45
Create Timeframe ....................................................................................................................................................................................... 46
Update Timeframe ...................................................................................................................................................................................... 47
List Timeframe – GET Method .................................................................................................................................................................. 49
List Timeframe – POST Method ................................................................................................................................................................ 50
Delete Time frame ...................................................................................................................................................................................... 51
TrueSight Infrastructure Management Server Web Services ................................................................................. 52

Retrieving Data from Infrastructure Management ................................................................................................................. 53
Managing Configuration Items ................................................................................................................................................ 55
Search Usage ............................................................................................................................................................................................. 55
Search API – GET ....................................................................................................................................................................................... 56
Search API – POST .................................................................................................................................................................................... 57
Search for a Specific CI ............................................................................................................................................................................. 58
Retrieve Infrastructure Details of CI......................................................................................................................................................... 59
Create a CI or Relationship ....................................................................................................................................................................... 60
Update a CI ................................................................................................................................................................................................. 63
Delete a CI or Relationship ....................................................................................................................................................................... 64
Get Events for a CI ..................................................................................................................................................................................... 65
1
Related CI.................................................................................................................................................................................................... 67
Managing Events ...................................................................................................................................................................... 68
Create Events ............................................................................................................................................................................................. 68
Modify an Event.......................................................................................................................................................................................... 70
Listing Events............................................................................................................................................................................................. 72
Event Subscription .................................................................................................................................................................................... 74
Create Event Subscription............................................................................................................................................................................................... 74
List Event Subscription - GET......................................................................................................................................................................................... 75
List Event Subscription - POST ...................................................................................................................................................................................... 76
Delete Event Subscription ............................................................................................................................................................................................... 77
Managing Service Level Objectives........................................................................................................................................ 78
Create SLO.................................................................................................................................................................................................. 78
Retrieve Metadata Information of SLO..................................................................................................................................................... 79
Update SLO................................................................................................................................................................................................. 80
Retrieving the Current Status of SLO ...................................................................................................................................................... 81
Delete SLO .................................................................................................................................................................................................. 82
Delete SLO based on SLO Type ............................................................................................................................................................... 83
2
Introduction
TrueSight Web Services – REST API
TrueSight Presentation Server & TrueSight Infrastructure Management Server includes web
services that can be extended to perform various day-to-day operations. For example, web
services can be used to retrieve performance data from TSIM, create or update or list events in
TSIM cell or remote cell, manage Configuration Items, manage SLO information, manage
Integration Services and perform Infrastructure Monitoring functions [policies & timeframes]
TrueSight Web Services [tsws] are based on Representational State Transfer [REST] style
architecture and uses HTTP or HTTPS to send requests and JavaScript Object Notation [JSON]
standards to receive response
Assumptions
TrueSight Presentation Server [TSPS] is installed and integrated with Atrium SSO for
Single Sign On authentication
TrueSight Infrastructure Management [TSIM] is installed and configured
Utility to test Web Services are configured. Web browser extensions [Google Chrome has
Advanced REST Client, Postman, RestMan] and many other apps can be used for testing.
I prefer using ‘Postman for Windows’ since it is portable and easy to use
Web Services test utility has necessary ports open between client and TrueSight
components
SSO user credentials part of ‘BPPM WS Full Access’ group is created and available for
testing
TSPS and TSIM version 10.5.00 are used in this document for testing. Some of the
functionalities might not be applicable for lower version
Web Services Architecture

Web Service client sends HTTP or HTTPS request for authentication using TrueSight
Presentation server API. If authentication is successful, an authentication token is created and
sent back to Web Service client. This token is used in subsequent API calls to TSPS or TSIM
Web Services.
By default, authentication token is valid up to 24 hours and is configurable.
For settings, go to TSIM Server pw\pronto\conf\bppmws.properties and look for property
loginExpiryInterval_hrs
3
High Level flow for a single TSIM Server installation is below,
High level flow for a multiple TSIM Server installation is below,
In a multiple TSIM Server installation, Central Server acts as a router for web service requests. It
receives web service requests from client and sends it to corresponding Child Servers and also
collects response from Child Servers and sends them to web service client.
https://docs.bmc.com/docs/display/public/PN90/BMC+ProactiveNet+Web+Services+overview
4
Web Services flow architecture and functions carried out in TrueSight Presentation Server and
TrueSight Infrastructure Management Server are outlined below,
Web Services Authorization
User must have necessary permissions to access TrueSight Web Service APIs. To perform all
web service related functions, user must be part of ‘BPPM WS Full Access’ group. More details
of roles and permissions are available in below link,
https://docs.bmc.com/docs/display/public/tsim105/Web+services+authorization
5
Setting Up Postman for Web Services Testing
Web Browser Extension
Launch chrome web store and search for ‘Postman’ app and add to chrome
Go to Chrome  Settings  Advanced Settings  HTTPS/SSL Manage Certificates  Import

TrueSight certificate
For more details,
http://blog.getpostman.com/2014/01/28/using-self-signed-certificates-with-postman/
Postman for Windows

Download Postman for Windows setup,
https://www.getpostman.com/apps
Launch Setup  Settings  Certificates  Import Client Certificates

If there are issues with self-signed certificates and you prefer to test without SSL certificates, go
to Settings  General  Turn OFF ‘SSL certificate verification’
6
7
TrueSight Presentation Server Web Services
TrueSight Presentation Server web services are used for below functions,
Web Services Authentication
Retrieving Configuration Data
Retrieving Performance Data
Retrieving List of Devices
Retrieving List of Monitor Instances
Retrieving List of Monitor Types
Retrieving List of Tenants
Managing Integration Services
Managing Infrastructure Monitoring [policies & time frames]
8
Web Services Authentication
Web Service client sends request to TrueSight Presentation Server for authentication. User
credentials are passed through HTTP header. Login API uses POST method to authenticate user
credentials
Input parameters can be passed using JSON or x-www-form-urlencoded method,
Input Parameters using JSON Format
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/authenticate/login
Method POST
Query Parameters
username <username>, default admin
password <password>, default admin12345
tenantName tenant name, default BmcRealm
A successful authentication will be returned with statusCode ‘200’
Authtoken value returned in Web Services authentication request can be used in subsequent
requests to TSPS or TSIM Web Service APIs
9
Input Parameters using x-www-form-urlencoded Format
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/authenticate/login
Method POST
Select request type as POST and provide Login API URL. In the body, select ‘x-www-form-
urlencoded’ and provide ‘key’ and ‘value’ pairs as below
Query Parameters
username <username>, default admin
password <password>, default admin12345
tenantName tenant name, default BmcRealm
‘responseTimeStamp’ and ‘expires’ time displays same information but authentication token
expiry is derived from bppmws.properties and by default valid up to 24 hours. If user credentials
are validated using BMC Atrium SSO, set maximum session time in SSO configuration [by default
120 minutes]
10
Retrieving Configuration Data
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/omprovider/configdata
Method POST
Authorization authtoken <tokenvalue>
Query Parameters
tenantId tenant name, default BmcRealm
monUniqName Unique Monitor Name
instKeyList serverId, monTypeId and monInstId of the monitor
Using Monitor Unique Name option,
Using Monitor Instance Key List,
11
Retrieving Performance Data
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/omprovider/perfdata
Method POST
Query Parameters
startTime Start time in epoch format
endTime End time in epoch format
type rate
computation avg
attribUniqNameList One or more attributes of the same monitor type
monUniqName Unique Monitor Name
instKeyList serverId, monTypeId and monInstId of the monitor
Note: Use Devices, Monitor Instances & Monitor Types query to get the required details. Actual
Name of Attributes might not be same as Display Name. Refer Parameter Reference Database
to get attribute names for PATROL Knowledge Modules
https://docs.bmc.com/docs/display/PRD/Home
12
Retrieving List of Devices
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/omprovider/devices
Method GET
Query Parameters
deviceEntityType Valid device entity types, to get all devices set value as ‘all’
parentDeviceId  ‘-1’ ignores the parent device and displays all devices
 ‘0’ displays all devices that do not have a parent device
13
Retrieving List of Monitor Instances
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/omprovider/instances
Method GET
Query Parameters
deviceId ID of the device belonging to the tenant
monUniqName Unique name of the monitor
serverId ID of the server
monTypeId ID of the monitor type
monInstId ID of the monitor instance
14
Retrieving List of Monitor Types
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/omprovider/monitortypes
Method GET
Query Parameters
monitorCategory  instance
 group
 all
15
Retrieving List of Tenants
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/omprovider/tenants
Method GET
16
Managing Integration Service
Create Integration Service
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationService/create
Method POST
Query Parameters
hostname Name of the computer that hosts Integration Service
isClusterName Name of the Integration Service cluster to which Integration Service belongs
to
bppmserver Details of TSIM server to add Integration Service to
connectionModeToServer Communication protocol between Integration Service and TSIM,
 TCP_IP_DIRECT
 TCP_IP_SSL
serviceType Specifies whether Integration Service is ‘STAGING’
eventDestination Destination to send the events
destinationDetails Details of the cell name to send events
cellName Name of the cell to send events
destination Type of destination to send the events,
 CURRENT_INTEGRATION_SERVICE
 CHILD_SERVER
 REMOTE_CELL
name Name of the Integration Service
port Port number through which communication is established
17
Update Integration Service
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationService/<identifier>/update
Method PUT
Request Parameters
identifier URI of the Integration Service, <servername>|<hostname>~<port>
<servername> - Name of TSIM Server
<hostname> - host name of Integration Services
<port> - Port number of Integration Services, default 12124
Query Parameters
hostname Name of the computer that hosts Integration Service
isClusterName Name of the Integration Service cluster to which Integration Service belongs
to
bppmserver Details of TSIM server to add Integration Service to
connectionModeToServer Communication protocol between Integration Service and TSIM,
 TCP_IP_DIRECT
 TCP_IP_SSL
serviceType Specifies whether Integration Service is ‘STAGING’
eventDestination Destination to send the events
destinationDetails Details of the cell name to send events
cellName Name of the cell to send events
destination Type of destination to send the events,
 CURRENT_INTEGRATION_SERVICE
 CHILD_SERVER
 REMOTE_CELL
name Name of the Integration Service
18
List Integration Service - GET
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationService/<identifier>/list
Method GET
Request Parameters
19
List Integration Service - POST
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationService/list
Method POST
Query Parameters
responseType basic
Query Parameters
Provide blank JSON body { }
20
Delete Integration Service
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationService/<identifier>/delete
Method DELETE
Request Parameters
21
Create Integration Service Cluster
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationServiceCluster/create
Method POST
Query Parameters
bppmserver Details of TSIM server to add Integration Service Cluster to
name Name of the Infrastructure Management Server
id Identifier of the Infrastructure Management Server
integrationServices List of Integration Services that are part of the cluster
host Name of the computer that hosts Integration Service
name Name of the Integration Service cluster
description Brief description of the Integration Service Cluster
22
Update Integration Service Cluster
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationServiceCluster/
<identifier1>,<identifier2>,...<identifierN>/update
Method PUT
Request Parameters
identifier1,identifier2,… Identifiers of the Integration Service clusters,
identifierN  Name of the Integration Service Cluster
 Identifier of the Integration Service Cluster
Query Parameters
idType Identifier type of the Integration Service,
 name
 id
Query Parameters
integrationServices List of Integration Services that needs to be updated
action Type of update to perform,
 addTop – Move the Integration Service to top of the list
 addBottom – Move the Integration Service to bottom of the list
 remove – Remove the specified Integration Service from Cluster
host Name of the Integration Service that is part of the cluster
name Name of the Integration Service Cluster that needs update
description Description of the Integration Service cluster
23
List Integration Service Cluster - GET
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationService/
<identifier1>,<identifier2>,…<identifierN>/list
Method GET
Request Parameters
Query Parameters
 name
 id
24
List Integration Service Cluster - POST
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationServiceCluster/list
Method POST
Query Parameters
responseType basic
Query Parameters
25
Delete Integration Service Cluster
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/IntegrationServiceCluster/
<identifier1>,<identifier2>,…<identifierN>/delete
Method DELETE
Request Parameters
Query Parameters
 name
 id
26
Managing Policies
Create Policy
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/<policyType>/create
Method POST
Request Parameters
policyType Type of policy to create,
 MonitoringPolicy
 BlackoutPolicy
 StagingPolicy
Note: JSON body Syntax for Monitoring Policy creation is wrong [brackets open, close & wrong
usage] for many categories in TrueSight document. Easier way to get the syntax right is to create
a sample policy in TSPS and use ‘List Policy – GET’ method to get details. Template the new
policy using Web Services based on the syntax from ‘List Policy’
27
Monitoring Policy
Configuring Filters
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/MonitoringPolicy/create
Method POST
Query Parameters
filteringConfiguration List of attributes to configure filters for data or events
configurations Filters to identify monitors and solutions to create the policy
solutionName Name of the monitoring solution
solutionVersion Version of the specified monitoring solution
monitors Details of the monitors
monitorType Type of the monitor
filter Filter type,
 none – sends both data & events
 data – sends only events, not data
 events – sends only data, not events
precedence Priority of the policy
tenant Details of the tenant who owns the policy
name Name of the tenant who owns the policy
 <nameOfTenant>
 GLOBAL
 PROVIDER
enabled Indicates whether policy is enabled
 true
 false
name Name of the policy
type Type of policy,
 blackout
 monitoring
 staging
description Brief description of the policy
shared  true – policy is shared among specific user group
 false – policy is not shared with others
associatedUserGroup Name of the user group to associate the policy
28
29
Configuring Agent Thresholds
Method POST
Query Parameters
agentThresholdConfiguration Lists the threshold definitions for the agent
solutionThresholds Lists the threshold definitions grouped by solutions
attributes Threshold definitions for the monitor attribute
attributeName Name of the monitor attribute
scope Scope for the threshold,
 monitorType
 Instances
agentThresholds Threshold definitions grouped by instances of the monitor attribute
instanceName Name of the monitor instance
thresholds Threshold definitions grouped by specified instance
type Type of the threshold
 border
 alarm1
 alarm2
details Details of the threshold
triggerAlarmWhen Specifies condition to trigger the alarm,
 ImmediatelyOnAlarm
 afterAlarmCount
 afterAllRecoveryActionsFail
minimum Minimum threshold value
maximum Maximum threshold value
enable Specifies whether threshold is enabled or not.
 true
 false
severity Severity of the threshold
 OK
 WARN
 ALARM
alarmCount Alarm count for the threshold
agentSelectionCriteria Set of conditions based on which policy is applied to the agents.
Syntax is “agentIdentifier operator\”value\””

 <nameOfTenant>
 GLOBAL
30
 PROVIDER
 true
 false
 blackout
 monitoring
 staging
31
Configuring Intelligent Thresholds
Method POST
Query Parameters
serverThresholdConfiguration Lists the threshold definitions for the server
solutionThresholds Lists the threshold definitions grouped by solutions
attributes Threshold definitions for the monitor attribute
attributeName Name of the monitor attribute
thresholds Threshold definitions for the specified monitor attribute
matchDeviceName Specifies whether to include associate device and entire string for
pattern matching
 true
 false
instanceName Name of the monitor instance
thresholds Threshold definitions grouped by specified instance
type Type of the threshold
 absolute
 signature
 abnormality
details Details of the threshold
severity Severity of the threshold
 MINOR
 MAJOR
 CRITICAL
durationInMins Duration (in minutes) of delay when threshold is violated to when an
event is generated
comparison  smaller_than
 greater_than
 smaller_or_equals
 greater_or_equals
 above
 below
outsideBaseline  notEnabled
 auto
 hourly
 daily
 weekly
 hourlyAndDaily
 all
predict Specifies whether to generate predictive events,
 true
 false
32
autoClose  true
 false
threshold Range of values for which events are triggered
minimumSamplingWindow Minimum window to keep raw data points for intelligent threshold
computation
absoluteDeviation Tolerance for the baseline values, default 5 units
percentDeviation Tolerance for the baseline values, default 5%

 <nameOfTenant>
 GLOBAL
 PROVIDER
 true
 false
 blackout
 monitoring
 staging
33
Configuring Rulesets
Method POST
Query Parameters
rulesetConfiguration List of rules for the PCONFIG variables to apply on the agent
rulesets List of rules for each PCONFIG variable
variable PCONFIG variable to define the rule
operation Operation to perform on the agent,
 REPLACE
 DELETE
 DELVAR
value Value to set for the variable
 <nameOfTenant>
 GLOBAL
 PROVIDER

 true
 false
 blackout
 monitoring
 staging
34
35
Configuring Agent Communication with Infrastructure Management
Method POST
Query Parameters
agentConfiguration List the details for the agent
agentDefaultAccountCredentials Default account details for the agent
integrationService Integration Service through which agent communicates with
Infrastructure Management
name Name of the integration service
type Type of the integration service,
 IS
 IS cluster
eventConfiguration List of attributes to configure event for the agent
eventsFormatContainer String to be appended to the name of the events from the agents
forwardEvents Specifies whether event must be forwarded to the destination,
 true
 false
destinationType Type of destination to forward the event,
 INTEGRATIONSERVICE
 CELL
destinationCells Cells to which events to be forwarded
destinationCellsSharedKey Shared key for communication with destination cell
restartAgent Specifies whether to restart the agent after applying the configuration
 true
 false
pollConfiguration Configuration details for the polling interval
solutions Details of the monitoring solution
parameters List of parameters to configure the polling interval
pollInterval Polling interval duration in hh:mm:ss
name Name of the parameter to configure polling interval
tag Details of the agent tag
agentTag Tag name for the agent

 <nameOfTenant>
 GLOBAL
36
 PROVIDER
 true
 false
 blackout
 monitoring
 staging
37
Blackout Policy
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/BlackoutPolicy/create
Method POST
Query Parameters

tenant Details of tenant who owns the policy,
 Name
 ID
 <nameOfTenant>
 GLOBAL
 PROVIDER
 true
 false
 blackout
 monitoring
 staging
timeframe Details of the time frame
name Name of the time frame
scope Scope of the blackout policy,
 completeAgent
 monitorTypesAndInstances
blackoutTypes Type of blackout policy
 data
 events
 recoveryActions
monitorConfigList List of monitors to create the blackout policy
monitorTypeSpecification Details of the monitor
solutionName Name of monitoring solutions
scope Scope of policy based on the monitoring type,
 type
 instances
monitorInstances Details of the monitor instances to create the policy
monitorInstance Details of monitor instance
38
39
Staging Policy
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/StagingPolicy/create
Method POST
Query Parameters

tenant Details of tenant who owns the policy,
 Name
 ID
 <nameOfTenant>
 GLOBAL
 PROVIDER
 true
 false
 blackout
 monitoring
 staging
integrationService Display name of Integration Service through which Agent communicates with
Infrastructure Management
type Type of Integration Service
name Name of the Integration Service or Integration Service Cluster
40
41
Update Policy
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/<policyType>/<id>/update
Method PUT
Request Parameters
policyType Type of policy to update,
 MonitoringPolicy
 BlackoutPolicy
 StagingPolicy
id Identifier of the policy,
 Name of the policy
 ID of the policy
Query Parameters
 name
 id
Query Parameters
Same parameters as Create Policy viz., MonitoringPolicy, BlackoutPolicy and StagingPolicy. Values that
needs to be updated should be passed in body in JSON format
42
List Policy – GET Method
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/Policy/<id>/list
Method GET
Request Parameters
Query Parameters
 name
 id
43
List Policy – POST Method
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/Policy/list
Method POST
Query Parameters
responseType Retrieve basic information of the policies
 basic
Query Parameters
44
Delete Policy
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/Policy/<id>/delete
Method DELETE
Request Parameters
Query Parameters
 name
 id
45
Create Timeframe
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/Timeframe/create
Method POST
Query Parameters
recurrence Time frame recurrence,
 once
 daily
 weekly
 monthly
date Date for the timeframe to be active
endHour End time for the time frame
type Type of end time for the time frame,
 time – Actual time in hh:mm
 timeDuration – Time duration, 00:05,00:10,…12:00,18:00,24:00
startTime Start time for the time frame
days Days the time frame to be active,
 all
 excludeWeekends
daysOfWeek Specific days the time frame should be active,
 1 – Monday
 2 – Tuesday
 3 – Wednesday
 4 – Thursday
 5 – Friday
 6 – Saturday
 7 – Sunday
dates Specifies the date in a month for which time frame should be active. For
example 10-15 or 3,7,15,26
name Name of the timeframe
description Brief description of the time frame
46
Update Timeframe
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/Timeframe/<id>/update
Method PUT
Request Parameters
id Identifier of the time frame,
 Name of the time frame
 ID of the time frame
Query Parameters
idType Identifier type of the time frame,
 name
 id
Query Parameters
recurrence Time frame recurrence,
 once
 daily
 weekly
 monthly
date Date for the timeframe to be active
endHour End time for the time frame
type Type of end time for the time frame,
 time – Actual time in hh:mm
 timeDuration – Time duration, 00:05,00:10,…12:00,18:00,24:00
startTime Start time for the time frame
days Days the time frame to be active,
 all
 excludeWeekends
daysOfWeek Specific days the time frame should be active
 1 – Monday
 2 – Tuesday
 3 – Wednesday
 4 – Thursday
 5 – Friday
 6 – Saturday
 7 – Sunday
dates Specifies the date in a month for which time frame should be active. For
example 10-15 or 3,7,15,26
name Name of the timeframe
description Brief description of the time frame
47
48
List Timeframe – GET Method
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/Timeframe/
<identifier1>,<identifier2>…<identifierN>/list
Method GET
Request Parameters
identifier1,identifier2… Identifiers of the time frame,
identifierN  Name of the time frame
Query Parameters
 name
 id
49
List Timeframe – POST Method
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/Timeframe/list
Method POST
Query Parameters
responseType Retrieve basic information of the policies,
 basic
Query Parameters
50
Delete Time frame
Syntax https://<TSPShostname>:<port>/tsws/10.0/api/unifiedadmin/Timeframe/<id>/delete
Method DELETE
Request Parameters
identifier1,identifier2… Identifiers of the time frame,
identifierN  Name of the time frame
Query Parameters
 name
 id
51
TrueSight Infrastructure Management Server Web Services
Infrastructure Management web services are used for below functions,
Retrieving Data from Infrastructure Management
Managing Configuration Items
Managing Events
Managing Service Level Objectives
Each Web Service has various options or parameters that can be passed to perform Operations
in TSIM Server. For more details, refer TrueSight Infrastructure Management guide
https://docs.bmc.com/docs/display/public/tsim105/Developing
52
Retrieving Data from Infrastructure Management
Syntax https://<TSIMhostname>:<port>/bppmws/api/<resourceType>/<resourceID>/<action>
Method GET
Request Parameters
resourceType  Device
 MonitorInstance
 CI
resourceID  Name of Resource
 IP Address of Resource
 Unique Resource Identifier of Resource
 Unique Identifier of CI
 Token Identifier of CI
action  metadata
 configdata
 stats
Query Parameters
starttime Start time to retrieve data in YYYY-MM-DDTHH:MM:SS, UTC 24 hour format
endtime End time to retrieve data in YYYY-MM-DDTHH:MM:SS, UTC 24 hour format
idType  Name
 IPAddress
 URI [default]
 RECON_ID/CI_ID
monitor Name of the monitor type & attributes to retrieve data,
monitor=monitorType:attribute
page Page number to retrieve data
subtype Sub type of the specified resource
infotype Used when subtype of the resource is cluster
statstype  raw – to get raw data of the resource
 aggregate – to get aggregated data of the resource
attributetype  kpi – to pull data only for KPI attributes of the resource
 all – to pull data for all attributes of the resource
tenantName Name of the tenant
53
54
Managing Configuration Items
Search Usage
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/search/usage
Method GET
55
Search API – GET
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/<searchstring>/search
Method GET
Request Parameters
searchstring String to be searched
Query Parameters
idType  Type of Identifier
 Name
 RECON_ID [default]
 URI
Subtype Sub type of the specified resource
slot=slotName:slotValue Search based on a CI slot and value
resultSize  default – retrieves partial details of CI defined in pronet.conf
 full – retrieves complete details of CI
56
Search API – POST
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/search
Method POST
Query Parameters
resultSize  default – retrieves partial details of CI defined in pronet.conf
 full – retrieves complete details of CI
Query Parameters
sortCriteria Conditions based on which search is sorted
sortOrder  1 – ascending
 2 – descending
attributeName slot name based on which results are sorted
criteria Conditions to search
groupingOperator  OR
 AND
leftExpression One of the conditions based on which CIs are searched
value String to search
identifier Slot name of CI
operator Condition relating identifier and value parameters
rightExpression One of the conditions based on which CIs are searched
57
Search for a Specific CI
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/<id>/details
Method GET
Request Parameters
id Identifier of the CI
Query Parameters
idType  CI_ID
 RECON_ID
filter Retrieves only specified slot details
58
Retrieve Infrastructure Details of CI
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/<identifier>/graph
Method GET
Request Parameters
identifier Identifier of the CI
Query Parameters
idType  CI_ID
 RECON_ID
 CI Name
 TOKEN_ID [default]
Subtype Sub type of the resource
relationshipType  INFRASTRUCTURE [default]
 IMPACT
 TOPOLOGY
sourceLevel Number of Level to go down to identify source devices
targetLevel Number of Level to go down to identify target devices
routingTargets Name of the cell for target devices [used if cell is different than TSIM cell]
slot CIs are filtered matched on condition slot:slotName=slotValue
59
Create a CI or Relationship
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/create
Method POST
Query Parameters
routingIdType Type of routing,
 CACHE_KEY
 SERVER_NAME
routingId Identifier of cell on which CI must be created
routingIdKeyParam Cache Key through which routingId parameter value is searched,
 NAME [default]
 RECON_ID
 URI
ciType Type of CI to create,
 CI
 RELATIONSHIP
Query Parameters - CI
id Name of the CI
className Class name of CI
attributeMap Slot names of CI
Query Parameters – Relationship
provider_id Identifier of the CI that provides the relationship
consumer_id Identifier of the CI that consumes the relationship
mc_udid Identifier of the relationship that you want to create between CIs
SourceId mc_udid slot of the provider CI
DestinationId mc_udid slot of the consumer CI
className Class name of CI or relationship
PropagationModel Impact Relationship between Provider & Consumer CI
60
61
62
Update a CI
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/<CI_ID>/update
Method PUT
Request Parameters
CI_ID Identifier of the CI to update
Query Parameters
idType  NAME
 RECON_ID
 URI
id Name of the CI
className Class name of CI
attributeMap Slot names of CI
Query Parameters – Relationship
provider_id Identifier of the CI that provides the relationship
consumer_id Identifier of the CI that consumes the relationship
mc_udid Identifier of the relationship that you want to create between CIs
SourceId mc_udid slot of the provider CI
DestinationId mc_udid slot of the consumer CI
className Class name of CI or relationship
PropagationModel Impact Relationship between Provider & Consumer CI
63
Delete a CI or Relationship
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/<resource_ID>/delete
Method DELETE
Request Parameters - CI
resource_ID  Name of the CI [Name]
 Uniform Resource Identifier of CI [URI]
 Unique Identifier of CI or Relationship [RECON_ID]
 Identifier of the CI that provides the relationship [Provider_ID]
 Identifier of the CI that consumes the relationship [Consumer_ID]
Query Parameters
idType  Name
 RECON_ID
 URI
 Provider_ID
 Consumer_ID
routingId Identifier of the CI that consumes the relationship
routingIdType  NAME
 RECON_ID
 URI
ciType  CI [default]
 RELATIONSHIP
ciSubType  IMPACT
 NON_IMPACT
 ALL
64
Get Events for a CI
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/<CI_ID>/getevents
Method POST
Request Parameters
CI_ID  ID of the CI
 Reconciliation ID of the CI
Query Parameters
idType  CI_ID
 RECON_ID
eventType Type of events to be searched,
 IMPACTING
 ALL
 DIRECT [default]
Query Parameters
totalResultCount Total number of events to be searched
startIndex start index of the list to search from, default is 1
className Class name of the event
slotList List of slots to search
sortCriteria Condition based on which search results are sorted
attributeName Slot name based on which search results are sorted
criteria Conditions based on which events are searched
groupingOperator  AND
 OR
65
66
Related CI
Syntax https://<TSIMhostname>:<port>/bppmws/api/CI/<CI_Identifier>/related
Method GET
Request Parameters
CI_Identifier CI for which related CIs are to be searched
idType  NAME
 RECON_ID
 CI_ID
relationshipType  root_causes
 possible_causes
 impacted_consumers
 providers_direct
 consumers_direct
 providers_all
 consumers_all
routingTarget Cell name used to search consumers for a distributed service model
filter Filter provider to search CI results, filter=class:className
67
Managing Events
Create Events
Syntax https://<TSIMhostname>:<port>/bppmws/api/Event/create
Method POST
Query Parameters
routingId  Name of the cell to send events to
 Name of the server to send events to
routingType  CELL_NAME
 SERVER_NAME
Query Parameters
applicationtype  CHANGE_MANAGEMENT
 CAPACITY_MANAGEMENT
eventSourceHostName Name of the server from which event is generated
eventSourceIPAddress IP Address of the server from which event is generated
eventId Unique identifier of the event maintained at the source
transactionId Unique identifier for the transaction
correlationId Identifier of the event to which current event is related
routingInfo Name of the Infrastructure Management Cell Name or Server Name
eventType  CM_CHANGE_EVENT
 CM_TASK_EVENT
attributes Event slot attributes and the values to be created, CLASS is mandatory
68
To send events to Remote cell, provide routingId as remote cell cellname or servername and
routingType as CELL_NAME or SERVER_NAME
Make sure remote cell is registered is TSIM Server and is visible in TrueSight Operations
Management console under Other Cells option
69
Modify an Event
Syntax https://<TSIMhostname>:<port>/bppmws/api/Event/update
Method PUT
Query Parameters
 SERVER_NAME
Query Parameters
applicationtype  CHANGE_MANAGEMENT
 CAPACITY_MANAGEMENT
eventSourceHostName Name of the server from which event is generated
eventSourceIPAddress IP Address of the server from which event is generated
eventId Unique identifier of the event maintained at the source
transactionId Unique identifier for the transaction
correlationId Identifier of the event to which current event is related
routingInfo Name of the Infrastructure Management Cell Name or Server Name
eventType  CM_CHANGE_EVENT
 CM_TASK_EVENT
attributes Event slot attributes and the values to be created
CLASS and mc_ueid are mandatory. Provide mc_ueid of the event that needs
to be updated
Provide the slot details and slot value that needs to be modified
Note: Syntax for Event update is not correct in TrueSight document. It is mentioned as same
syntax as ‘Create Event’. But, ‘update’ should be used instead of ‘create’ in syntax and PUT
method should be used. Also, open and close JSON body with square brackets [ ] for event
creation and do not use square brackets in body for event update
70
71
Listing Events
Syntax https://<TSIMhostname>:<port>/bppmws/api/Event/search
Method POST
Query Parameters
 SERVER_NAME
Query Parameters
totalResultCount Total number of events to be searched
Modify the value maxEventsResultCount attribute in bppmws.properties file

if the requirement is to search more events
startIndex start index of the list to search from, default is 1
className Class name of the event
slotList List of slots to search
sortCriteria Condition based on which search results are sorted
attributeName Slot name based on which search results are sorted
criteria Conditions based on which events are searched
groupingOperator  AND
 OR
72
73
Event Subscription
REST API is used to create or list or delete Event subscriptions. API will create new events based
on the criteria provided in the subscription
Create Event Subscription
Syntax https://<TSIMhostname>:<port>/bppmws/api/stream/subscribe
Method POST
Query Parameters
dataType Event
Query Parameters
subscriptionName Unique name of the subscription
destination type: REST
url: URL to be used for REST destination
username: username to be used for REST
password: Base64 encoded password for REST
criteria input criteria to create subscription
criterias one or more criteria to select data
74
List Event Subscription - GET
Syntax https://<TSIMhostname>:<port>/bppmws/api/stream/<subscriptionID>/list
Method GET
Request Parameters
subscriptionID ID of the subscription
75
List Event Subscription - POST
Syntax https://<TSIMhostname>:<port>/bppmws/api/stream/list
Method POST
Query Parameters
76
Delete Event Subscription
Syntax https://<TSIMhostname>:<port>/bppmws/api/stream/<Subscription_ID>/unsubscribe
Method DELETE
Request Parameters
Subscription_ID Subscription ID that needs to be unsubscribed
77
Managing Service Level Objectives
Create SLO
Syntax https://<TSIMhostname>:<port>/bppmws/api/slo/create
Method POST
Query Parameters
filtertype device
filterid  Hostname of the device
 IP Address of the device
filteridtype  name
 IPAddress
Query Parameters
name name of the SLO
owner User who owns the SLO
contactinfo Contact details of the owner
content instances
type  Availability
 Response Time
 System Performance
compliancerangeset Default or customized compliance range
complianceobjective Percentage of compliance or non-compliance that SLO must obtain
schedules  24x7
 Business Hours
78
Retrieve Metadata Information of SLO
Syntax https://<TSIMhostname>:<port>/bppmws/api/slo/<IDforSLO>/metadata
Method POST
Request Parameters
IDforSLO Identifier for the SLO,
 Name of SLO
 URI for the SLO
Query Parameters
idtype  name [default]
 URI
Query Parameters - SLO

type  Availability
 Response Time
content instances
uri Uniform Resource Identifier for the SLO
schedules  24x7
 Business Hours
Query Parameters - SLO Objectives
value SLO value for the instance or attribute
weight Weight associated with the SLO attribute
condition  Greater than or equal to
 Less than or equal to
minimumduration Time period for validating the SLO violation
financialimpact Amount of financial loss caused if the SLO is not met
79
Update SLO
Syntax https://<TSIMhostname>:<port>/bppmws/api/slo/<IDforSLO>/update
Method PUT
Request Parameters
 Name of SLO
 URI for the SLO
Query Parameters
 URI
infotype basic
Query Parameters
uri Uniform Resource Identifier for the SLO
schedules  24x7
 Business Hours
80
Retrieving the Current Status of SLO
Syntax https://<TSIMhostname>:<port>/bppmws/api/slo/<IDforSLO>/status
Method GET
Request Parameters
 Name of SLO
 URI for the SLO
Query Parameters
 URI
81
Delete SLO
Syntax https://<TSIMhostname>:<port>/bppmws/api/slo/<IDforSLO>/delete
Method DELETE
Request Parameters
 Name of SLO
 URI for the SLO
Query Parameters
 URI
82
Delete SLO based on SLO Type
Syntax https://<TSIMhostname>:<port>/bppmws/api/slo/delete
Method DELETE
Query Parameters
slotype SLO type to delete,
 Availability
 Response Time
83

TrueSight Web Services REST API

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TrueSight Web Services REST API

Uploaded by

Copyright:

Available Formats

TRUESIGHT WEB SERVICES

TrueSight Infrastructure Management Server Web Services ................................................................................. 52

TrueSight Infrastructure Management [TSIM] is installed and configured

Web Services Architecture

High Level flow for a single TSIM Server installation is below,

High level flow for a multiple TSIM Server installation is below,

Web Services Authorization

Go to Chrome  Settings  Advanced Settings  HTTPS/SSL Manage Certificates  Import

Postman for Windows

Launch Setup  Settings  Certificates  Import Client Certificates

Input Parameters using JSON Format

A successful authentication will be returned with statusCode ‘200’

Authorization authtoken <tokenvalue>

Using Monitor Unique Name option,

Using Monitor Instance Key List,

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Syntax is “agentIdentifier operator\”value\””

Authorization authtoken <tokenvalue>

Syntax is “agentIdentifier operator\”value\””

Authorization authtoken <tokenvalue>

Syntax is “agentIdentifier operator\”value\””

Authorization authtoken <tokenvalue>

Syntax is “agentIdentifier operator\”value\””

Authorization authtoken <tokenvalue>

Syntax is “agentIdentifier operator\”value\””

Authorization authtoken <tokenvalue>

Syntax is “agentIdentifier operator\”value\””

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>

Authorization authtoken <tokenvalue>