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

Important

   

This documentation supports the releases of BMC Helix Intelligent Integrations and BMC Helix Developer Tools 22.2.00 and their patches. To view the documentation for earlier releases, see BMC Helix AIOps.

BMC Helix Intelligent Integrations 22.2 Getting started

Use case: Building a custom third-party integration with BMC TrueSight Impact Manager

Configure an integration with TrueSight Impact Manager by using BMC Helix Developer Tools to get the TrueSight Impact Manager cell events into BMC Helix Operations Management for monitoring.

This use case explains how to build an integration with TrueSight Impact Manager by using the Custom Integration template in BMC Helix Developer Tools.  

Configuring an integration with TrueSight Impact Manager involves the following high-level tasks:

Task 1: Set up the environment

Setting up the environment involves the following tasks:

  1. Download a Docker connector.

  2. Update the communication ports.

  3. (Optional) Configure the connector to use an HTTP Proxy.
  4. Install the Docker connector.

To download a Docker connector

In BMC Helix Developer Tools, download the Docker connector required for the integration. Enter a name for the connector, for example, CellGateway while downloading. For the Docker requirements and download instructions, see Step 1 to Step 3 on Downloading and installing Docker connectors.

If you have entered the connector name as CellGateway, the connector shell script will be downloaded as install-connector-CellGateway.sh.

To allow communication between the container and the Docker host

To allow communication between the container and Docker host, add the container port and the corresponding port on the Docker host by using the -p option. 

  1. Open the install-connector-CellGateway.sh file that you downloaded with a text editor.

  2. Search for the following command in the file:

    docker create --name $NEW_CONNECTOR_NAME --restart=unless-stopped --env-file $ENV_VARIABLE_FILE_PATH -h $CONNECTOR_NAME -v $DATA_FOLDER_PATH/:/fluentd/etc/data/ -v $CUSTOM_FOLDER_PATH/:/fluentd/etc/custom/ -v $LOG_FOLDER_PATH/:/fluentd/log/ -it $NEW_DOCKER_IMAGE_ID > /dev/null

  3. Add the port numbers by using the -p option:

    docker create --name $NEW_CONNECTOR_NAME --restart=unless-stopped --env-file $ENV_VARIABLE_FILE_PATH -h $CONNECTOR_NAME -v
$DATA_FOLDER_PATH/:/fluentd/etc/data/ -v $CUSTOM_FOLDER_PATH/:/fluentd/etc/custom/ -v $LOG_FOLDER_PATH/:/fluentd/log/ -p 1850:1850 -it $NEW_DOCKER_IMAGE_ID > /dev/null

    In this example, both the container port and the corresponding port on the Docker host are 1850. 

To configure the connector to use an HTTP Proxy

  1. Create a config.json file with the following contents in the ~/.docker directory of the user who will be running the Docker container:

    {
 "proxies":
 {
   "default":
   {
     "httpProxy": "http://<proxy_hostname_or_IPAddress>:<proxy_port>",
     "httpsProxy": "http://proxy_hostname_or_IPAddress>:proxy_port>"
   }
 }
}
  2. Update the values for the proxy_hostName_or_IPAddress and proxy_port parameters in the file.
    You can add more parameters to this file. For details, see the Docker documentation. Open link .

To install the connector and verify its status

  1. Install the connector that you have downloaded in a previous step. For instructions, see Step 4 on Downloading and installing dockerized connectors.

  2. To verify the connector status, run the following command:

    tail -f /opt/bmc/connectors/CellGateway/logs/fluent.log

    The following output indicates that the connector is running and logging the heartbeat periodically.

Task 2: Create and deploy the integration

Creating and deploying the integration involves the following tasks:

  1. Create a sandbox integration environment by using the Custom Integration template.

  2. Create the pipeline configuration files.

  3. To create a deployable package and deploy the integration.

To create a sandbox integration environment by using the Custom Integration template

  1. In BMC Helix Developer Tools, click the Available integrations tab.

  2. On the Custom Integration tile, click Configure.

  3. Enter a unique name for the integration, for example, CellGateway.

  4. From the Connector list, select the connector that you have installed, for example, CellGateway.

  5. Click Configure.
    The added integration is available on the Configured Integrations tab. The integration environment contains few out-of-the-box directories and example pipeline configuration files.
     

To create the pipeline configuration files

Create the cellgateway_event_pipeline.conf and cellgateway_mapping.json files.

Before you begin

Before you create the pipeline configuration files, identify the sandbox integration ID and get familiar with the default sandbox directory structure. For information, see Exploring the default sandbox directory structure and configuration files.

Do the following steps to create the pipeline configuration files 

  1. Create a CONF file named cellgateway_event_pipeline.conf with the following contents. In the file, tag stores the integration name that can be referred by other elements such as filter and match to filter and match the incoming events.

    cellgateway_event_pipeline.conf 
    <source>
  @type tcp
  tag CellGateway_GENERICEVENTS
  port 1850
  bind 0.0.0.0
  <parse>
  @type none
  </parse>
</source>

<filter CellGateway_GENERICEVENTS>
  @type record_transformer
  enable_ruby
  <record>
    message ${record["message"].gsub('\'', '')} 
  </record>
</filter>

<filter CellGateway_GENERICEVENTS>
@type parser
key_name message
<parse>
  @type csv
  delimiter "|EIF_EIF|"
  parser_type fast
 keys cell_garbage,cell_class,cell_action,cell_ueid,cell_severity,cell_status,cell_repeat_count,cell_priority,cell_object,cell_host,cell_location,cell_host_address,cell_object_class,cell_parameter,cell_parameter_value,cell_parameter_unit,cell_msg 
</parse>
</filter>

<filter CellGateway_GENERICEVENTS>
  @type record_transformer
  remove_keys cell_garbage
</filter>

<filter CellGateway_GENERICEVENTS>
        @type bmc_ade_transformer
        result_in_array true
        mapping_file /fluentd/etc/data/config/cellgateway_mapping.json
        mapping_json_key EventMappingDetails
        ignore_blank_values false
</filter>

<filter CellGateway_GENERICEVENTS>
@type stdout
</filter>

<match CellGateway_GENERICEVENTS>
	@type bmc_ade_http
    endpoint_url    			${{CONNECTOR_ENV.ADE_BASE_URL}}/events-service/api/v1.0/events
    ssl_no_verify   			true  # default: false
    use_ssl         			true
    http_method     			post    # default: post
    serializer      			json   # default: form
    rate_limit_msec 			0    # default: 0 = no rate limiting
    raise_on_error  			true  # default: true
    recoverable_status_codes	503 # default: 503
    config_json_file_path 		/fluentd/etc/data/config/ade_config.json
    format           			json
    audit_payload  {"labels":{"metricName":"Events","hostname":"${{CONNECTOR_ENV.HOST_NAME}}","entityId":"${{CONNECTOR_ENV.AGENT_ID}}","entityType":"Connector","entityName":"${{CONNECTOR_ENV.AGENT_NAME}}","IntegrationID":"<integrationID>","IntegrationName":"CellGateway_GENERICEVENTS","unit":"Nos.","source":"CELL"},"samples":[{"value":0,"timestamp":0}]}
</match>
  2. In the file, specify the value of the IntegrationID parameter for the integration that you have created. 
  3. Copy the cellgateway_event_pipeline.conf file to the /opt/bmc/connectors/CellGateway/data/integrationID/pipeline directory.

  4. Add the following line to the /opt/bmc/connectors/CellGateway/data/integrationID/generic_pipeline.conf file:
    @include ./pipeline/cellgateway_event_pipeline.conf

  5. Create a JSON file named cellgateway_mapping.json and add the mapping details as shown in the following example:

    {
  "EventMappingDetails": [
  {
    "inputkey": "MonitorEvent",
    "outputkey": "class",
    "type": "constant"
  },
       {
    "inputkey": "cell_action",
    "outputkey": "source_port",
    "type": "assignment"
  },
   {
    "inputkey": "cell_ueid",
    "outputkey": "object_id",
    "type": "assignment"
  },
    {
    "inputkey": "cell_severity",
    "outputkey": "severity",
    "type": "assignment"
  },
    {
    "inputkey": "cell_status",
    "outputkey": "status",
    "type": "assignment"
  },
    {
    "inputkey": "cell_repeat_count",
    "outputkey": "_repeat_count",
    "type": "assignment"
  },
  {
    "inputkey": "cell_priority",
    "outputkey": "priority",
    "type": "assignment"
  },
  {
    "inputkey": "cell_object",
    "outputkey": "object",
    "type": "assignment"
  },
   {
    "inputkey": "cell_host",
    "outputkey": "source_hostname",
    "type": "assignment"
  },
    {
    "inputkey": "cell_location",
    "outputkey": "location",
    "type": "assignment"
  },
   {
    "inputkey": "cell_host_address",
    "outputkey": "source_address",
    "type": "assignment"
  },
  {
    "inputkey": "cell_object_class",
    "outputkey": "object_class",
    "type": "assignment"
  },
    {
    "inputkey": "cell_class",
    "outputkey": "source_identifier",
    "type": "assignment"
  },
    {
    "inputkey": "cell_parameter",
    "outputkey": "metric_name",
    "type": "assignment"
  },
    {
    "inputkey": "cell_parameter_value",
    "outputkey": "metric_value",
    "type": "assignment"
  },
    {
    "inputkey": "cell_parameter_unit",
    "outputkey": "metric_unit",
    "type": "assignment"
  },
  {
    "inputkey": "cell_msg",
    "outputkey": "msg",
    "type": "assignment"
  }]
}
  6. Copy the cellgateway_mapping.json file to the /opt/bmc/connectors/CellGateway/data/config directory.

  7. Restart the integration by running the following commands:

    cd /opt/bmc/connectors/CellGateway
sh ./restart.sh

The /opt/bmc/connectors/CellGateway directory now contains the following directories and configuration files:



To create a deployable package and deploy the integration   

  1. Navigate to the /opt/bmc/connectors/CellGateway/data/<integrationID> directory.

  2. Run the following command to create a deployable package: 

    tar -cvf /opt/bmc/connectors/CellGateway/custom/download/cellgateway.tar.gz config pipeline generic_pipeline.conf

    The cellgateway.tar.gz file is created in the /opt/bmc/connectors/CellGateway/custom/download directory.

  3. Run the following command to verify the status of the connector: 

    tail -f /opt/bmc/connectors/CellGateway/logs/fluent.log

    The following output indicates that connector is running and logging the heartbeat periodically:

  4. In BMC Helix Developer Tools, on the Available integrations tab, click the action menu of the CellGateway integration, and select Copy ID to copy the integration ID of the sandbox integration, and make a note of this integration ID. 
  5. Click the info icon(below the Connector Status) on the integration tile, and note the connector name and host name on which the connector is running. 

  6. In BMC Helix Developer Tools, on the Available integrations tab, click the action menu of the CellGateway sandbox integration, and select Edit.

  7. Enter the following information:

    1. From the entity list, select Events.
    2. Enter cellgateway_event_pipeline.conf as the entity configuration file name.
    3. Leave the Name and Value fields blank.
    4. Ensure that the Encrypt option is not selected.
    5. Enter cellgateway.tar.gz as the deployable package file name and click Update.
  8. On the Configured Integrations tab, verify that the integration is updated and connected.

Task 3: Enable and test the integration 

Enabling and testing the integration involves the following tasks:

  1. Enable the BMC TrueSight Impact Manager cells to propagate events to the CellGateway integration.

  2. Test the connector for messages.

  3. Test the CellGateway integration.

To enable the BMC TrueSight Impact Manager cells to propagate events to the CellGateway integration

Before you begin

  • Ensure that the TrueSight Impact Manager server and cell are up and running.
  • Ensure that the BMC Helix Operations Management service is up and running.

To enable the BMC TrueSight Impact Manager cells to propagate events to the CellGateway integration, do the following steps:

  1. Log on to the computer where the BMC TrueSight Infrastructure Management Server is installed.
  2. Navigate to the installationDirectory/server/etc directory.

  3. Create the gateway.bhom file with the following contents:

    protocol=EIF
cond.new=always
cond.mod=always

#drop.mod=[]
#drop.new=[]

#add.mod=[]
#add.new=[]

slots.new=[mc_ueid,severity,status,repeat_count,mc_priority,mc_object,mc_host,mc_location,mc_host_address,mc_object_class,mc_parameter,mc_parameter_value,mc_parameter_unit,msg]
slots.mod=[mc_ueid,severity,status,repeat_count,mc_priority,mc_object,mc_host,mc_location,mc_host_address,mc_object_class,mc_parameter,mc_parameter_value,mc_parameter_unit,msg]

#modify.mod=[]

#---------------------------------------------------------------
# Format parameters 
#---------------------------------------------------------------
init.new=|EIF_EIF|$CLASS|EIF_EIF|200
body.new=|EIF_EIF|$VALUE
term.new=\n

init.mod=|EIF_EIF|$CLASS|EIF_EIF|204
body.mod=|EIF_EIF|$VALUE
term.mod=\n

#separator=|EIF_EIF|
#quoatable=
#openquote=
#closequote=
#escapequote=

  4. Add the entry for the gateway.bhom file to the mcell.dir file.

    The following code snippet shows a sample mcell.dir configuration of a cell with the gateway.bhom entry.

    Type	          <Name>	      <EncryptionKey>      <IPAddress>:<Port>
gateway.bhom 	   bhom	       	   mc              	   <hostNameorIPAddress>:1850
cell           	  <CELL_NAME>      mc                  <hostNameorIPAddress>:1828
  5. Navigate to the <MCELL_HOME>/etc/<CELL_NAME>/kb/rules directory.

  6. Create the bhom_propagate.mrl file with the following contents:

    refine gw_event : EVENT ($EV) 
where [$EV.status != BLACKOUT] 
{ 

# Message - Remove tricky chars to allow REST call to BHOM
	$NL=char(10);
	$CR=char(13);
	$EV.msg=strip($EV.msg,7,$CR);
	$EV.msg=strip($EV.msg,7,$NL);
	$EV.msg = strreplace($EV.msg,',',' '); 
	$EV.msg = strreplace($EV.msg,'"',''); 
	$EV.msg=substring($EV.msg, 0, 300); 

# Message - Add default message if empty to allow REST call to BHOM
    if($EV.msg == '') then 
    { 
		$EV.msg = "default message: " || 'CLASS=' || $EV.CLASS || ' ObjectClass=' || $EV.mc_object_class || ' Object=' || $EV.mc_object;
    }; 

}         
END
  7. Add the Propagate rule to the file.

    The following code snippet shows the contents of the file with the rule added to the end of the file.

    refine gw_event : EVENT ($EV) 
where [$EV.status != BLACKOUT] 
{ 

# Message - Remove tricky chars to allow REST call to BHOM
	$NL=char(10);
	$CR=char(13);
	$EV.msg=strip($EV.msg,7,$CR);
	$EV.msg=strip($EV.msg,7,$NL);
	$EV.msg = strreplace($EV.msg,',',' '); 
	$EV.msg = strreplace($EV.msg,'"',''); 
	$EV.msg=substring($EV.msg, 0, 300); 

# Message - Add default message if empty to allow REST call to BHOM
    if($EV.msg == '') then 
    { 
		$EV.msg = "default message: " || 'CLASS=' || $EV.CLASS || ' ObjectClass=' || $EV.mc_object_class || ' Object=' || $EV.mc_object;
    }; 

}         
END

# Propagate event to CellGateway
propagate bhom_propagate : EVENT($EV)
  where [ $EV.status == OPEN ]
   to bhom
END

  8. Add the file name (bhom_propagate.mrl) for the new rule to the compiler load list in the .load file, as shown in the following example:

    #
# File name: .load
# Version: 7.4.00
# Copyright 1998-2022 BMC Software, Inc. All Rights Reserved
#
kbversem
kbverssim
mc_startup
.........
bhom_propagate

     

  9. Compile and restart the cell by using the following commands:

    mccomp -n <CELL_NAME>
mcontrol -n <CELL_NAME> restart

To test the connector for messages

  1. Send a test message to your container by running the following command:

    curl -X POST -d 'json={"json":"test event"}' http://<host>:<port>/testing.event

  2. Verify the messages in the /logs/fluent.log file.
    The following code snippet shows the sample message received by the connector.

    2021-09-16 18:48:52 +0000 [info]: Heartbeat call sent successfully. No Command to process.
2021-09-16 18:48:56.999026864 +0000 testing.event: {"json":"test event"}
2021-09-16 18:48:57 +0000 [info]: Heartbeat call sent successfully. No Command to process.

To test the CellGateway integration

  1. Log on to TrueSight Impact Manager.

  2. Send a sample event to the cell by using the following command:

    msend -n <CELL_NAME> -a EVENT -r MINOR -m ‘This is a test event’;

  3. Verify the event in the CellGateway log by running the following command:

    tail -f /opt/bmc/connectors/CellGateway/logs/fluent.log


  4. Verify the increased count of events on the CellGateway integration. 

  5. From BMC Helix Operations Management, select Monitoring > Events to view the ingested events.

Task 4: Extend the integration

Extending the integration involves the following tasks:

  1. Enable automatic synching of events and dropping of duplicate events.
  2. Add more slots.
  3. Manage event buffers.

To enable automatic synching of events and dropping of duplicate events

Enable automatic synching of events between TrueSight Impact Manager and BMC Helix Operations Management and dropping of the duplicate events by creating the following policies in BMC Helix Operations Management:

  • Sync Events policy: This policy synchs events between TrueSight Impact Manager and BMC Helix Operations Management, as follows:  
    • If an event is closed in TrueSight Impact Manager, it is also closed in BMC Helix Operations Management.
    • When a new event is received, the policy looks for a previous event from the same host, with the same Object value. If the severity, priority, or message of the event has changed, same is updated for the existing event in BMC Helix Operations Management and the repeat count for the event is incremented in BMC Helix Operations Management. The new incoming event is dropped in this case.
  • Detect Duplicate Events policy: This policy detects the duplicate events and keeps the events updated in BMC Helix Operations Management, as follows:
    When a new event is received, the policy looks for a previous event from the same host, with the same Object value, but which is not an OK event. If the incoming new event has the OK status, the old event, if found, is closed. For example, for an OK event, a matching Critical event is closed. If the incoming event is not an OK event, the severity, priority, and message is updated for the old event and repeat count is incremented for the old event. Also. the incoming new event is dropped.

Consider the following while creating these policies:

  • New events are ingested into BMC Helix Operations Management with code 200.
  • Updated events are ingested into BMC Helix Operations Management with code 204.
  • The code is stored in slot, source_code, and the cell mc_ueid is stored in the slot, object_id to be used as identifier for updates.
  • Updated events in the cell are automatically ingested into BMC Helix Operations Management in the following slots:
    mc_ueid, severity, status, repeat_count, mc_priority, mc_object, mc_host, mc_location, mc_host_address, mc_object_class, mc_parameter, mc_parameter_value, mc_parameter_unit, msg

To create a policy to enable automatic synching of events

  1. In BMC Helix Operations Management, go to Configuration > Event Policies, and click Create.

  2. Specify a unique name for the policy (for example, Sync Events). 

  3. Specify an optional description and precedence number for the policy.

  4. Define a condition to select events of the class Monitor Event with the source port equal to 204. 
    The following image illustrates how the event selection criteria should look.

  5. Build the policy workflow by adding actions.
    1. Add the Lookup action.
      1. Click Add Configuration and select Advance Enrichment.
      2. Click Lookup.
      3. In the Lookup Settings panel, enter Latest equal ID as the label.
      4. Select the With custom criteria option and add the following condition to the existing criteria:
        $OLD.Object ID Equals $NEW.Object ID
        The following image illustrates how the event lookup criteria should look.

      5. Click Apply.
    2. From Add Below, select Update old events.
    3. Add an If action.
      1. In the If Settings panel, enter If Status Closed as the label.
      2. Add the following condition: $New.Status Equals Closed
      3. Click Apply.
    4. Select the Then box.
    5. Add an Enrich action to close the existing events:
      1. In the Enrichment Settings panel, enter Close Old Events as the label.
      2. Select $OLD.Status as the slot.
      3. Select Closed as the slot value.
  6. Click the Else box.
  7. Add an Enrich action to update the severity of an old event.
    1. From Add Below, select Enrich.
    2. In the Enrichment Settings panel, enter Update Severity as the label.
    3. Select $OLD.Severity as the slot.
    4. Select $NEW.Severity as the value.
    5. Click Apply.
  8. Add an Enrich action to update the priority of an old event.
    1. From Add Below, select Enrich.
    2. In the Enrichment Settings panel, enter Update Priority as the label.
    3. Select $OLD.Priority as the slot.
    4. Select $NEW.Priority as the value.
    5. Click Apply.
  9. Add an Enrich action to update the message of an old event.
    1. From Add Below, select Enrich.
    2. In the Enrichment Settings panel, enter Update Message as the label.
    3. Select $OLD.Message as the slot.
    4. Select $NEW.Message as the value.
    5. Click Apply.
  10. Add an Enrich action to update the repeat count of an old event. 
    1. From Add Below, select Enrich.
    2. In the Enrichment Settings panel, enter Increase Repeated as the label.
    3. Select $OLD.Repeated as the slot.
    4. Click the Function option.
    5. Select Math as the function.
    6. Select Plus as the operator.
    7. Select $OLD.Repeated as number 1.
    8. Enter 1 as number 2.
    9. Click Apply.
  11. Select the End-If box.
  12. Add a Function to drop new events:
    1. From Add Below, select Function.
    2. Add Drop New Events as the label.
    3. Select DropNewEvent as the function.
    4. Click Apply and then click Save.

The resulting policy workflow automatically syncs the events between TrueSight Impact Manager and BMC Helix Operations Management as shown in the following image:

To create a policy to enable automatic detection of duplicate events and drop them

  1. In BMC Helix Operations Management, go to Configuration > Event Policies, and click Create.

  2. Specify a unique name for the policy (for example, Drop Duplicate Events). 

  3. Specify an optional description and precedence number for the policy.

  4. Define a condition to select events of the class Monitor Event with the source port equal to 200. 
    The following image illustrates how the event selection criteria should look.

  5. Build the policy workflow by adding actions.
    1. Add the Lookup action.
      1. Click Add Configuration and select Advance Enrichment.
      2. Click Lookup.
      3. In the Lookup Settings panel, enter Detect Duplicate as the label.
      4. Select the With custom criteria option and add the following conditions to the existing criteria:

        $OLD.Object ID Equals $NEW.Object ID

        The following image illustrates how the event lookup criteria should look.

      5. Click Apply.
    2. From Add Below, select Update old events.
    3. Add an If action.
      1. In the If Settings panel, enter If Status Closed as the label.
      2. Add the following condition: $New.Status Equals Closed
      3. Click Apply.
    4. Select the Then box.
    5. Add an Enrich action to close the existing events:
      1. In the Enrichment Settings panel, enter Close Old Events as the label.
      2. Select $OLD.Status as the slot.
      3. Select Closed as the slot value.
  6. Click the Else box.
  7. Add an Enrich action to update the severity of an old event.
    1. From Add Below, select Enrich.
    2. In the Enrichment Settings panel, enter Update Severity as the label.
    3. Select $OLD.Severity as the slot.
    4. Select $NEW.Severity as the value.
    5. Click Apply.
  8. Add an Enrich action to update the priority of an old event.
    1. From Add Below, select Enrich.
    2. In the Enrichment Settings panel, enter Update Priority as the label.
    3. Select $OLD.Priority as the slot.
    4. Select $NEW.Priority as the value.
    5. Click Apply.
  9. Add an Enrich action to update the message of an old event.
    1. From Add Below, select Enrich.
    2. In the Enrichment Settings panel, enter Update Message as the label.
    3. Select $OLD.Message as the slot.
    4. Select $NEW.Message as the value.
    5. Click Apply.
  10. Add an Enrich action to update the repeat count of an old event. 
    1. From Add Below, select Enrich.
    2. In the Enrichment Settings panel, enter Increase Repeated as the label.
    3. Select $OLD.Repeated as the slot.
    4. Click the Function option.
    5. Select Math as the function.
    6. Select Plus as the operator.
    7. Select $OLD.Repeated as number 1.
    8. Enter 1 as number 2.
    9. Click Apply.
  11. Select the End-If box.
  12. Add a Function to drop new events:
    1. From Add Below, select Function.
    2. Add Drop New Events as the label.
    3. Select DropNewEvent as the function.
    4. Click Apply and then click Save.

The resulting policy workflow automatically detects the duplicate events from TrueSight Impact Manager and drops them as shown in the following image:

To extend the integration with additional slots in BMC Helix Operations Management

The CellGateway integration with TrueSight Impact Manager is by default created to map standard slots and classes in the BMC Helix Operations Management event class, Monitor Event.

The Cell event class is mapped to the source_identifier slot to allow source specific event policies in BMC Helix Operations Management or create tags and event groups based on event classes.

  1. Create the new slot, for example, bmc_info, in BMC Helix Operations Management. For instructions to add a slot by using REST API, see  Managing events with REST APIs Open link .

    Click here to see the sample body request with the new slort. 
    {
      "attributes":[
                          {
                    "name": "bmc_info",
                    "dataType": "STRING",
                    "allFacet": [
                        {
                            "name": "read_only",
                            "value": "false"
                        }
                    ],
                    "enumElements": [],
                    "enum": false
        }
            ]
}

  2. Add the new slots to the Cell Gateway file.

    slots.new=[mc_ueid,severity,status,repeat_count,mc_priority,mc_object,mc_host,mc_location,mc_host_address,mc_object_class,mc_parameter,mc_parameter_value,mc_parameter_unit,msg,bmc_info]
slots.mod=[mc_ueid,severity,status,repeat_count,mc_priority,mc_object,mc_host,mc_location,mc_host_address,mc_object_class,mc_parameter,mc_parameter_value,mc_parameter_unit,msg,bmc_info]

  3. Add the new slot to integration configuration file, cellgateway_event_pipeline.conf.

    <filter CellGateway_GENERICEVENTS>
@type parser
key_name message
<parse>
@type csv
delimiter "|EIF_EIF|"
parser_type fast
keys cell_garbage,cell_class,cell_action,cell_ueid,cell_severity,cell_status,cell_repeat_count,cell_priority,cell_object,cell_host,cell_location,cell_host_address,cell_object_class,cell_parameter,cell_parameter_value,cell_parameter_unit,cell_msg,cell_info
</parse>
</filter>

  4. Add the new slot to the integration mapping file, cellgateway_mapping.json.

    {
  "EventMappingDetails": [
  {
    "inputkey": "MonitorEvent",
    "outputkey": "class",
    "type": "constant"
  },
       {
    "inputkey": "cell_action",
    "outputkey": "source_port",
    "type": "assignment"
  },
   {
    "inputkey": "cell_ueid",
    "outputkey": "object_id",
    "type": "assignment"
  },
    {
    "inputkey": "cell_severity",
    "outputkey": "severity",
    "type": "assignment"
  },
    {
    "inputkey": "cell_status",
    "outputkey": "status",
    "type": "assignment"
  },
    {
    "inputkey": "cell_repeat_count",
    "outputkey": "_repeat_count",
    "type": "assignment"
  },
  {
    "inputkey": "cell_priority",
    "outputkey": "priority",
    "type": "assignment"
  },
  {
    "inputkey": "cell_object",
    "outputkey": "object",
    "type": "assignment"
  },
   {
    "inputkey": "cell_host",
    "outputkey": "source_hostname",
    "type": "assignment"
  },
    {
    "inputkey": "cell_location",
    "outputkey": "location",
    "type": "assignment"
  },
   {
    "inputkey": "cell_host_address",
    "outputkey": "source_address",
    "type": "assignment"
  },
  {
    "inputkey": "cell_object_class",
    "outputkey": "object_class",
    "type": "assignment"
  },
    {
    "inputkey": "cell_class",
    "outputkey": "source_identifier",
    "type": "assignment"
  },
    {
    "inputkey": "cell_parameter",
    "outputkey": "metric_name",
    "type": "assignment"
  },
    {
    "inputkey": "cell_parameter_value",
    "outputkey": "metric_value",
    "type": "assignment"
  },
    {
    "inputkey": "cell_parameter_unit",
    "outputkey": "metric_unit",
    "type": "assignment"
  },
  {
    "inputkey": "cell_msg",
    "outputkey": "msg",
    "type": "assignment"
  },
  {
    "inputkey": "cell_info",
    "outputkey": "bmc_info",
    "type": "assignment"
  }]
}

  5. Compile and restart the cell by using the following command:

    mccomp -n <CELL_NAME>
mcontrol -n <CELL_NAME> restart

  6. Restart the integration by running the following commands:

    cd /opt/bmc/connectors/CellGateway
sh ./restart.sh

To manage event buffers

Event buffering is possible from:

  • TrueSight Impact Manager cell to the CellGateway integration by using propagate rules. This type of buffering is enabled by default.
  • CellGateway integration to TrueSight Impact Manager. This type of buffering is disabled by default.

Buffering from BMC TrueSight Impact Manager cells to the CellGateway integration

When the TrueSight Impact Manager cell is started, the event buffers are set to a minimum workable size. The default size is 5000 events for each destination buffer and 5000 requests for the propagation buffer.

If the cell cannot propagate events, it stores the events to be propagated to the destination buffers and the requests for the propagation of those events in the propagation buffer. When the buffers become full, the cell automatically expands the buffer size by a specified percentage (10 percent, by default), unless the buffer has exceeded a maximum size. By default, the maximum buffer size is unlimited, although the practical limit of the buffer size is the amount of available memory. After the maximum defined buffer size is reached, additional requests for expansion fail.

When an automatic expansion of a buffer occurs, an MC_CELL_RESOURCE_EXPANSION event is generated. An expanded buffer contains free space after propagation has resumed. To free memory resources, the buffer is reduced when it contains more than the specified amount of free space. Reduction leaves enough free space to avoid the need for an immediate expansion. The buffer is never reduced below the specified minimum size. When the buffer is reduced, an MC_CELL_RESOURCE_REDUCTION event is generated.

You can control the buffer size by configuring various parameters in the mcell.conf file as listed in the following table:

ParameterTypeDescription
DestinationBufferBaseSizeNumberThe initial number of messages or events retained in the buffer.
DestinationBufferExpandPercentageNumberPercentage of the actual buffer size that the buffer expands when events continue to be propagated after the buffer is full.
DestinationBufferSizeLimitNumberMaximum allowed buffer size.
The default value of 0 means the buffer size is unlimited. In practice, the size is limited to 2^32-1, or to the available amount of memory.
If the limit is set to a value lower than DestinationBufferBaseSize, the buffer does not expand beyond DestinationBufferBaseSize.
DestinationBufferReducePercentageNumberMinimum percentage of free buffer size required to perform a reduction.
DestinationBufferKeepSentNumberAmount of time, in seconds, to keep the sent events buffered while waiting for an answer.
DestinationBufferKeepWaitNumberAmount of time, in seconds, for which events are retained in the buffer until they can be sent.
After the specified time elapses, the retained events are removed from the buffer.
DestinationBufferReconnectIntervalNumberTime interval, in seconds, during which the cell attempts to reconnect to a destination if the original connection fails.
The cell continues to reestablish a connection as long as there are events in the buffer.
DestinationBufferResendCountNumberNumber of times to resend the unanswered events.
PropagateBufferBaseSizeNumberNumber of requests for propagation to retain in the propagation buffer.
Such a request corresponds to executing a Propagate rule. There is one propagate buffer per cell with as many places for requests as set by the parameter.
PropagateBufferExpandPercentageNumberPercentage of the actual buffer size that the buffer expands when events continue to be propagated after the buffer is full.
PropagateBufferSizeLimitNumberMaximum allowed buffer size.
The default value of 0 means the buffer size is unlimited. In practice, the size is limited to 2^32-1, or to the available amount of memory.
If the limit is set to a value lower than PropagateBufferBaseSize, the buffer does not expand beyond PropagateBufferBaseSize.
PropagateBufferReducePercentageNumberMinimum percentage of free buffer size required to perform a reduction.
PropagateConfigFileNamePathName of the propagation configuration file.

Buffering from the CellGateway integration to BMC Helix Operations Management

The buffering from the CellGateway integration to BMC Helix Operations Management is disabled by default. You can use buffered parameter available in the bmc-ade-http plug-in to enable or disable the buffeting. For more information about the plug-in, see bmc-ade-http-pull plug-in.

Was this page helpful? Yes No Submitting... Thank you
Last modified by Sulekha Gulati on Aug 09, 2022
custom_integration_template custom_integration truesight impact manager developer_tools unrestored-unknown-attachment

Comments

Log in or register to comment.

Supported out-of-the-box integrations for BMC Helix Developer Tools
Onboarding and implementing
© Copyright 2021-2022 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2023 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.