Configuring the BMC Remedy AR System actor adapter

You configure an adapter in Grid Manager. The configuration provides information about how the adapter interacts with the BMC Remedy Action Request System application (BMC Remedy AR System). While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties.

The form view provides an easy-to-use interface for configuring adapters. The form view prevents human errors that might occur as a result of copying the configuration XML from the XML sample into the UI when configuring an adapter. You can switch to the XML view to configure those elements and attributes that are not available as fields on the form view or to configure all the elements and attributes using XML only. However, after you switch to the XML view and save the configuration in the XML from that view, you cannot thereafter use the form view for modifying that configuration.

To  configure the actor adapter

  1. Log on to the BMC Atrium Orchestrator Grid Manager.
  2. Access the adapters page by clicking the Manage tab; then click the Adapters tab.
  3. In the Adapters in Repository list select the ro-adapter-remedy-actor check box to configure an actor adapter.
  4. Click Add to Grid to include the adapter in the Adapters on Grid list.
  5. Click Configure corresponding to the newly added adapter.
  6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or jump to step 7to configure the adapter using the XML view:
    1. Enter a name for the adapter.

      Note

      The default name for the BMC Remedy AR System actor adapter is ARSAdapter.

    2. Enter a description for the adapter.
    3. Under Properties, enter or select values for the configuration elements. 
      Include all required elements indicated with an asterisk (*).
  7. (Optional) Configure the adapter in the XML view using the following substeps:
    1. Enter a name and a description for the adapter.
    2. Click Switch to XML View to specify elements and attributes that are not in the form view, starting with step.
    3. On the Warning message that appears, click Switch View.
    4. Copy the configuration elements and attributes into the Properties text box, and then click OK.

      Note

      If the default value for an optional element is acceptable, omit the element. Do not include empty elements.

    5. On the Warning message that appears, click Save.

      This action saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list. 

The following table describes the elements of an actor adapter configuration that you can specify using the form view, XML view, or both. You cannot use the form view to configure elements and attributes that do not have an entry in the "UI label" column. To configure such elements and attributes, you have to switch to XML view.

Configuration node elements for the actor adapter

UI label

Element

Description

Required

None

<configs>

Contains the configuration and peer mapping nodes for an adapter configuration

Conditional; required, if the<peer-config-mappings>element is used to define peer mapping for configurations

None

<config>

Contains the configuration elements to connect to a specific server, along with log on credentials 

This element can contain an optional <name>attribute to be used as a reference when multiple configurations are defined. The name attribute is required when using the peer mapping feature.

Yes

Target

<target>

Specifies the host name or IP address of the BMC Remedy AR System server

Yes

Schemas

<schemas>

Contains the <schema> elements

No

Schema

<schema>

Specifies the BMC Remedy AR System schema to be cached upon adapter attachment to peer, restart of peer, or immediately following a reset-cache action

In the absence of this element, the schema is cached the first time after it is called by an adapter request.

No

Port

<port>

Specifies the remote connection port number 

In the absence of this element, a default value of 0will be assigned. This default will cause the BMC Remedy AR System to use its default TCP/IP port number.

No

User Name

<user-name>

Specifies the user name to be used to connect to the BMC Remedy AR System server

Yes

Password

<password>

Specifies the password that corresponds to the<user-name> specified

No

Rpc Number

<rpc-number>

Specifies the RPC port number 

In the absence of this element, a default value of 0will be assigned. The default will cause the BMC Remedy AR System to use its default RPC port number.

No

Auto Reset Cache

<auto-reset-cache>

Schedules the resetting of cache for repeated execution if true 

Valid values: true (default), false

No

Delay

<delay>

Specifies the successive resetting of cache that takes place at approximately regular intervals, separated by the specified delay 

The delay is specified in minutes. The default value is 120.

No

Use Connection Pooling

<use-connection-pooling>

Enables the connection pooling provided by the Java™ API of the BMC Remedy AR System 7.5 

Specify true if you are going to use the adapter for more than one request at a time.

Valid values: true, false (default)

No

Max Connections

<max-connections>

Configures the proxy pool sizes per server when the value for <use-connection-pooling> is true 

The default value is 100.

Conditional; specify only if the <use-connection-pooling> element is set to true.

Max Request Queue Size

<max-request-queue-size>

Specifies the maximum size of the queue maintained by the actor adapter to handle concurrent requests if the value of <use-connection-pooling> is false or not specified 

The default value is 2147483647.

Conditional

Attachment Destination Dir

<attachment-destination-dir>

Specifies the directory in which the actor adapter stores the attachments retrieved from the BMC Remedy AR System server 

The default value is the Java Virtual Machine (JVM) value for java.io.tmpdir.

  • For Microsoft Windows, the default value is: 
    C:\DOCUME~1\user\LOCALS~1\Temp\.
  • For Oracle Solaris, the default value is: var/tmp/
  • For Linux, the default value is: /tmp

No

Download Attachments

<download-attachments>

Specifies whether the attachments needs to be downloaded with details or only with details in response 

Valid values: true, false 

With a value of true the attachments are downloaded on the configured destination location (configurable through adapter configuration) on disk and the attachment details are returned in the response. 

With a value of false, the attachment details are returned in the response without downloading the attachment to the specified directory.

No

Retrieve Attachment In Response

<retrieve- attachment-in-response>

Specifies whether the attachment to be sent in adapter response is a Base 64 encoded string 

Valid values: true, false (default) 

With a value of true, the download attachments process input is not considered. This states that the attachment sent in the adapter response is a Base64 encoded string. If this element is set to false and the download attachmentselement is set to false, the attachment details are shown only in the response.

Conditional

Monitor Server Up Down

<monitor-server-up-down>

Reflects the connectivity state of the BMC Remedy AR System server 

Valid values: true, false (default) 

If the value is set to true, the actor adapter monitors the connection to the BMC Remedy AR System server. If the BMC Remedy AR System server is down, it sets the adapter state to Fault. When the BMC Remedy AR System server comes back online, the adapter returns to the running state. 

This feature enables the same actor adapters to connect to more than one BMC Remedy AR System server (using peer configuration maps). When the BMC Remedy AR System server is down, all requests are routed to the adapter that is not in the fault state. If the value is set to false, the adapter would not monitor the connectivity state of the BMC Remedy AR System server.

No

Monitor Server Frequency Secs

<monitor-server-frequency-secs>

Specifies the frequency at which the adapter should monitor the connectivity state of the BMC Remedy AR System server 

The default value is 30 seconds.

No

Monitor Server Retry Count

<monitor-server-retry-count>

Specifies the number of times the adapter tries to reconnect to the BMC AR System server before going into a fault state 

Default value: 3 

The adapter tries to reconnect only if one of the BMC Remedy AR System errors 90 through 95 occurs. For details about errors 90 through 95, see the BMC Remedy Action Request System 7.6.04 Error Messages Guide. For any other error, the adapter goes into a fault state immediately.

No

Server Timeout Normal

<server-timeout-normal>

Specified to increase the normal timeout value in order to execute the adapter request successfully 

<server-timeout-normal> is used with simple get operations. 

The timeout value for this parameter should be increased if network latency or Remedy AR Server's slow performance is noticed.

Note

If the value specified for this parameter is less than or equal to default value, the specified value is ignored and the default value is considered.



Default value: 120 seconds

No

Server Timeout Long

<server-timeout-long>

Specified to increase the long timeout value in order to execute the adapter request successfully 

<server-timeout-long> is used with get operations for a list of objects. 

The timeout value for this parameter should be increased if network latency or Remedy AR Server's slow performance is noticed.

Note

If the value specified for this parameter is less than or equal to default value, the specified value is ignored and default value is considered.



Default value: 300 seconds

No

Server Timeout Extra Long

<server-timeout-extra-long>

Specified to increase the extra long timeout value in order to execute the adapter request successfully 

<server-timeout--extra-long> is used with createupdate, or delete operations. 

The timeout value for this parameter should be increased if network latency or Remedy AR Server's slow performance is noticed.

Note

If you specify a value for this parameter that is less than or equal to default value, the specified value is ignored and default value is considered.



Default value: 1800 seconds

No

Client Locale

<client-locale>

Provides the user the ability to set the locale of the Remedy adapter 

The default value is the computer's default locale.

No

Query Response Contains Id Or Name

<query-response-contains-id-or-name>

Specifies whether the value of the name attribute in the adapter response to a query is a field ID or a field name 

Valid values: ID (or id), name

Note

If you do not specify a value while configuring the adapter, the response contains the value that you specify for the <field> element in the adapter request.

No

Max Retrieve

<max-retrieve>

Specifies the maximum number of records to be retrieved per request for the query and get actions 

If you do not specify <max-retrieve> or if its value is set to zero, all the matching records are retrieved. 

Records are retrieved by using the default sorted order, which is ascending, based on the created date or entry ID. The adapter uses the default order that is used by the BMC Remedy AR System application.

No

None

<peer-config-maps>

Contains the mapping nodes for each peer

Conditional; required to define peer mapping for configurations

None

<peer-config-map>

Contains the peer and configuration mapping elements 

This feature facilitates peer-specific configuration files, allowing users to assign specific user name and password credentials to each peer.

Conditional; required to define peer mapping for configurations

None

<peer-name>

Specifies the name of the peer, as defined in Grid Manager, for which a specific configuration will be assigned

Conditional; required to define peer mapping for configurations

None

<config-name>

Specifies the value of the name attribute for the desired configuration to be used by the peer

Conditional; required to define peer mapping for configurations

 XML template for configuring the actor adapter
<configs>
  <config name=' '>
   <target></target>
   <schemas>
     <schema></schema>
     <schema></schema>
   </schemas>
   <port></port>
   <user-name></user-name>
   <password></password>
   <client-locale></client-locale>
   <server-timeout-normal></server-timeout-normal>
   <server-timeout-long></server-timeout-long>
   <server-timeout-extra-long></server-timeout-extra-long>
   <rpc-number></rpc-number>
   <auto-reset-cache></auto-reset-cache>
   <delay></delay>
   <use-connection-pooling>true</use-connection-pooling>
   <max-connections>50</max-connections>
   <attachment-destination-dir></attachment-destination-dir>
   <download-attachments></download-attachments>
   <retrieve-attachment-in-response></retrieve-attachment-in-response>
   <max-request-queue-size></max-request-queue-size>
   <monitor-server-up-down>false</monitor-server-up-down>
   <monitor-server-frequency-secs></monitor-server-frequency-secs>
   <monitor-server-retry-count></monitor-server-retry-count>
   <query-response-contains-id-or-name></query-response-contains-id-or-name>
   <max-retrieve></max-retrieve>
  </config>
  <peer-config-maps>
    <peer-config-map>
      <peer-name></peer-name>
      <config-name></config-name>
    </peer-config-map>
  </peer-config-maps>
</configs>
 XML sample for configuring the actor adapter
<config>
  <target>vm-test123</target>
  <user-name>Demo</user-name>
  <password>Demo</password>
  <schemas>
     <schema>Alert Events</schema>
   </schemas>
   <use-connection-pooling>true</use-connection-pooling>
   <max-connections>30</max-connections>
   <monitor-server-up-down>true</monitor-server-up-down>
   <monitor-server-frequency-secs>5</monitor-server-frequency-secs>
   <server-timeout-normal>180</server-timeout-normal>
   <server-timeout-long>500</server-timeout-long>
   <server-timeout-extra-long>2500</server-timeout-extra-long>
   <client-locale>Shift-JIS</client-locale>
   <max-retrieve>100</max-retrieve>
</config>
 XML sample for configuring the actor adapter using the <auto-reset-cache> element that resets the cache automatically after 120 minutes
<config>
  <target>vm-w23-rds24</target>
  <user-name>appadmin</user-name>
  <password>Admin</password>
  <auto-reset-cache>true</auto-reset-cache>
  <delay>120</delay>
</config>
 XML sample for configuring the actor adapter using the <attachment-destination-dir> element
<config>
  <target>vm-w23-rds24</target>
  <user-name>Demo</user-name>
  <password />
  <auto-reset-cache>true</auto-reset-cache>
  <delay>120</delay>
  <attachment-destination-dir>C:\ARS Testing\Download</attachment-destination-dir>
  <download-attachments>false</download-attachments>
  <retrieve-attachment-in-response>true</retrieve-attachment-in-response>
</config>
 XML sample for configuring the actor adapter using the <monitor-server-up-down>, <monitor-server-frequency-secs>, and <monitor-server-retry-count> elements
<config>
  <target>arserver-1</target>
  <user-name>aruser</user-name>
  <password>arpasswd</password>
  <monitor-server-up-down>true</monitor-server-up-down>
  <monitor-server-frequency-secs>10</monitor-server-frequency-secs>
  <monitor-server-retry-count>2</monitor-server-retry-count>
   ....
   ....
</config>
 XML sample for configuring the actor adapter when <query-response-contains-id-or-name> is set to ID
<config>
  <target>vm-w23-rds24</target>
  <user-name>appadmin</user-name>
  <password>Admin</password>
  <query-response-contains-id-or-name>ID</query-response-contains-id-or-name>
</config>
 XML sample for configuring the actor adapter using the peer configuration mapping
<configs>
  <peer-config-maps>
  <peer-config-map>
    <peer-name>CDP</peer-name>
    <config-name>C1</config-name>
  </peer-config-map>
  <peer-config-map>
    <peer-name>AP</peer-name>
    <config-name>C2</config-name>
  </peer-config-map>
  </peer-config-maps>
  <config name="C1">
    <target>ARServer1</target>
    <user-name>U1</user-name>
    <password>P1</password>
    <monitor-server-up-down>true</monitor-server-up-down>
    <monitor-server-frequency-secs>10</monitor-server-frequency-secs>
  </config>
    <config name="C2">
    <target>ARServer2</target>
    <user-name>U2</user-name>
    <password>P2</password>
    <monitor-server-up-down>true</monitor-server-up-down>
    <monitor-server-frequency-secs>10</monitor-server-frequency-secs>
  </config>
</configs>

Enabling custom logging

To enable custom logging for the adapter, you must specify a log file name. You can also provide additional parameters for logging.

Note

You must be using BMC Atrium Orchestrator Platform version 7.8 or later to use the custom logging feature. These parameters will be ignored in earlier versions of BMC Atrium Orchestrator Platform.

These parameters are available with supported adapter versions. See your adapter documentation for details.

  • Log File Name: Provide a name for the log file.
    This file will be stored in the AO_HOME/tomcat/logs directory. If Log File Max Backup Index value is greater than 0, the log file name is suffixed with the backup index. For example, if the parameter value is a.log, backup log files will have names, such as a.log.1, a.log.2.
  • Log File Size: Specify a size limit for the log file. 
    If the value specified for Log File Max Backup Index is greater than 0, when the specified size is reached, the current file is renamed with the suffix .1. Otherwise, the log file will be reset and over-written. The default value is 10MB. The available units are KiloBytes (KB), MegaBytes (MB) or GigaBytes (GB).
  • Log File Max Backup Index: Enter the maximum number of backup files allowed. The default value is 10.
  • Log File Append: Select this option to append new log information to the existing information in the file. If unselected, the file will be overwritten with new log information.
  • Log Level: Enter the logging level using one of the following choices:

    Logging level

    Description

    DEBUG

    The most detailed logging level; logs low-level messages, normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions

    INFO

    (default)

    Logs normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions

    WARN

    Logs recoverable erroneous conditions and unrecoverable erroneous conditions

    ERROR

    The least detailed logging level; logs only error conditions that are not usually recoverable

Peer mapping feature

Within the adapter configuration, the user can establish multiple configuration nodes, each referenced by a specific name. These configurations can be mapped to specific peers, allowing each peer to have a specific set of credentials to connect to BMC Remedy Action Request System (BMC Remedy AR System). 

Peer mapping is an optional feature and elements pertaining to peer mapping should be omitted from the adapter configuration if this function is not implemented. 

When using this feature, each peer can be mapped to a specific configuration that will be used for all adapter interaction with BMC Remedy AR System. For peers on which the adapter has been enabled, but a specific mapping has not been established in the adapter configuration, the default configuration (the first configuration node listed in the XML document) is used.

Was this page helpful? Yes No Submitting... Thank you

Comments