×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

   

This documentation supports an earlier version of BMC Helix Operations Management.

To view the documentation for the latest version, select 23.2 from the Product version picker.
BMC Helix Operations Management 22.3 Managing policies, event data, and metric data with REST APIs

Managing global variables with REST APIs

The following section provides a list of supported endpoints and an overview about running these endpoints. Before you run an endpoint, you must authenticate yourself. For more information, see  Access and authentication for the REST API Open link

Related topic

Information sharing between enrichment policies with global variables


Managing global variables for event enrichment policies

You can create, update, delete, and retrieve global variables by running APIs. You can also modify attributes of global variables by running APIs.

POST /global_variables

Important

Make sure that you specify the request body only in the English locale.

Request URL 
 https://<BMC Helix Portal URL>/events-service/api/v1.0/global_variables
Example request URL 
 https://HostA.bmc.com/events-service/api/v1.0/global_variables
Request Header 
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API. Open link

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringBodyYesUnique name of the global variable that you want to create.
descriptionStringBodyYesDescription of the global variable.
attributesObject (List)BodyYes

List of attributes for the global variable. The attributes have the following parameters:

  • name (Type: String): Name of the attribute
  • dataType: Data type of the attribute
    Supported data type:
    • STRING
  • defaultValue: Default value of the attribute. This value can be set to blank.
  • value: Value of the attribute

Request body

{
  "name": "String",
  "description": "String",
  "attributes": [
    {
      "name": "String",
      "dataType": "String",
      "defaultValue": "String",
      "value": "String"
    }
  ]
}

Example request body

{
  "name": "mom_records",
  "description": "MOMInformation",
  "attributes": [
    {
      "name": "timeframe_heartbeats",
      "dataType": "STRING",
      "defaultValue": "",
      "value": "86400"
    },
    {
      "name": "amount_heartbeats",
      "dataType": "STRING",
      "defaultValue": "6",
      "value": ""
    }
  ]
}


Successful response

{
  "message": "[Successfully created Global Variable.]",
  "object": {
    "name": "[mom_records]"
  }
}

Unsuccessful responses

Scenario 1: You specify a duplicate global variable name

{
  "message": "[Failed to create global variable entry, entry with same id already exists for tenant 936425861 and name mom_records.]",
  "errorCode": "GLOBAL_VARIABLE_ALREADY_EXIST"
}

Scenario 2: You specify an empty or null value in the global variable name

{
  "message": "Global Variable Name Passed as empty/null",
  "errorCode": "EMPTY_NULL_GLOBAL_VARIABLE_NAME"
}

Scenario 3: You specify an empty or null value for an attribute name in the global variable

{
  "message": "Attribute Name seems to be empty/null",
  "errorCode": "EMPTY_GLOBAL_VARIABLE_ATTRIBUTE_NAME"
}

Scenario 4: You specify an invalid global variable name

{
  "message": "Invalid Naming Convention : record$$$_1",
  "errorCode": "NAMING_CONVENTION_NOT_PROPER"
}


Back to top

PUT /global_variables/?updateOption=<Update Option>

Important

Make sure that you specify the request body only in the English locale.

When you update a global variable, you can partially or completely override attributes in the global variable. To add or remove values from the enumeration, send the entire enumeration request payload with the required values. To learn more about the request payload, see Example request body.

Request URL 
https://<BMC Helix Portal URL>/events-service/api/v1.0/global_variables?updateOption=<Update Option>
Example request URL 
 https://HostA.bmc.com/events-service/api/v1.0/global_variables?updateOption=OVERRIDE
Request Header 
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API. Open link

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringBodyYesName of the global variable that you want to update.
descriptionStringBodyYesDescription of the global variable.
attributesArrayBodyYes

List of attributes for the global variable. The attributes have the following parameters:

  • name (Type: String): Name of the attribute
  • dataType: Data type of the attribute
    Supported data type:
    • STRING
  • defaultValue: Default value of the attribute
  • value: Value of the attribute
updateOptionStringPathYes

The Type of update that you want to apply to a global variable.

Possible values:

  • OVERRIDE
  • PARTIAL_UPDATE
    Specify the value in uppercase as it is case sensitive.

Request body

{
  "name": "String",
  "description": "String",
  "attributes": [
    {
      "name": "String",
      "dataType": "String",
      "defaultValue": "String",
      "value": "String"
    }
  ]
}

Example request body

In this example, a new attribute heartbeat_threshold_count is added to the mom_records global variable. To add this new attribute, send the entire variable request payload with the required values.

{
  "name": "mom_records",
  "description": "MOMInformation",
  "attributes": [
    {
      "name": "timeframe_heartbeats",
      "dataType": "STRING",
      "defaultValue": "",
      "value": "86400"
    },
    {
      "name": "amount_heartbeats",
      "dataType": "STRING",
      "defaultValue": "6",
      "value": ""
    },
    {
      "name": "heartbeat_threshold_count",
      "dataType": "STRING",
      "defaultValue": "100",
      "value": "300"
    }
  ]
}

Overriding an existing attribute replaces the entire attribute definition similar to overwriting the changes in a file. To override an existing attribute, send the entire variable request payload with the required values.

{
  "name": "mom_records",
  "description": "MOMInformation",
  "attributes": [
    {
      "name": "ping_heartbeats",
      "dataType": "STRING",
      "defaultValue": "",
      "value": "103200"
    }
  ]
}

Successful response

{
  "message": "[Successfully updated Global Variable.]",
  "object": {
    "name": "[mom_records]"
  }
}

Unsuccessful responses

Scenario 1: You do not specify the mandatory parameter updateOption in the API request URL

[
  {
    "key": "validation.request.parameter.query.missing",
    "level": "ERROR",
    "message": "Query parameter 'updateOption' is required on path '/v1.0/global_variables' but not found in request.",
    "additionalInfo": []
  }
]

Scenario 2: You attempt to change the data type of an existing attribute in the global variable

{
  "message": "[Data type of timeframe_heartbeatsv3 cannot be changed for tenant 936425861 and global variable name Scomrecords5.]",
  "errorCode": "DATA_TYPE_CANNOT_BE_CHANGED"
}

Back to top

GET  /global_variables/{name}/values
Request URL 
 https://<BMC Helix Portal URL>/events-service/api/v1.0/global_variables/{name}/values
Example request URL 
https://HostA.bmc.com/events-service/api/v1.0/global_variables/mom_records/values
Request Header 
Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringPathYesName of the global variable that you want to retrieve.
Successful response

{
  "message": "[Global Variable entry found successfully for specified name.]",
  "object": [
    {
      "name": "timeframe_heartbeats",
      "dataType": "STRING",
      "value": "86400"
    },
    {
      "name": "amount_heartbeats",
      "dataType": "STRING",
      "value": "6"
    }
  ]
}

Unsuccessful response

Scenario: You specify a variable name that does not exist

{
  "message": "[No Global Variable entry for matching input request.]",
  "errorCode": "400"
}

Back to top

GET  /global_variables
Request URL 
https://<BMC Helix Portal URL>/events-service/api/v1.0/global_variables
Example URL 
https://HostA.bmc.com/events-service/api/v1.0/global_variables
Request Header 
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API. Open link

Successful response

{
  "message": "[Global Variables found.]",
  "object": [
    {
      "name": "mom_records",
      "description": "MOM Information",
      "attributes": [
        {
          "name": "invdata_last_run",
          "dataType": "STRING",
          "defaultValue": "",
          "value": "1644844433"
        }
      ]
    },
    {
      "name": "scom_records",
      "description": "SCOM Information",
      "attributes": [
        {
          "name": "amount_heartbeats",
          "dataType": "STRING",
          "defaultValue": "",
          "value": "10"
        }
      ]
    }
  ]
}

Back to top

DELETE  /global_variables/{name}
Request URL 
 https://<BMC Helix Portal URL>/events-service/api/v1.0/global_variables/{name}
Example request URL 
https://HostA.bmc.com/events-service/api/v1.0/global_variables/mom_records
Request Header 
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API. Open link

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringPathYesName of the global variable that you want to delete.
Successful responses

{
  "message": "[Successfully deleted Global Variable.]",
  "object": {
    "name": "[mom_records]"
  }
}

Unsuccessful response

Scenario: You specify a variable name that already exists or is deleted

{
  "message": "[Requested Global variable does not exist or already deleted]",
  "errorCode": "400"
}

Back to top

PUT  /global_variables/{name}/values


Request URL 
https://<BMC Helix Portal URL>/events-service/api/v1.0/global_variables/{name}/values
Example request URL 
 https://HostA.bmc.com/events-service/api/v1.0/global_variables/mom_records/values
Request Header 
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API. Open link

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringPathYesName of the global variable whose attribute you want to update.
nameStringBodyYesName of the global variable attribute.
valueStringBodyYesNew attribute value that you want to set in the global variable.

Request body

[
  {
    "name": "String",
    "value": "String"
  }
]

Example request body

[
  {
    "name": "timeframe_heartbeats",
    "value": "86700"
  },
  {
    "name": "amount_heartbeats",
    "value": "15"
  }
]

Successful response

{
  "message": "[Successfully updated Global Variable.]",
  "object": {
    "name": "[mom_records]"
  }
}

Unsuccessful responses

Scenario 1: You specify a variable name that does not exist

{
  "message": "[Failed to get existing global variable entry for tenant 1980396036 and name record_11.]",
  "errorCode": "GLOBAL_VARIABLE_NOT_EXIST"
}

Back to top

Was this page helpful? Yes No Submitting... Thank you
Last modified by Shreya Gurukiran on Jun 21, 2022
swagger developing api reference development

Comments

Log in or register to comment.

Managing dynamic monitor type registration with REST APIs
Managing the Agent Query Tool PSL commands with REST APIs
© Copyright 2020-2022 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.