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

Log on to the BMC Atrium Orchestrator Grid Manager.
Access the adapters page by clicking the Manage tab; then click the Adapters tab.
In the Adapters in Repository list select the ro-adapter-remedy-actor check box to configure an actor adapter.
Click Add to Grid to include the adapter in the Adapters on Grid list.
Click Configure corresponding to the newly added adapter.
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 (*).
(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 attachments`element 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 create, update, 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.

Configuring the BMC Remedy AR System actor adapter

To configure the actor adapter

Enabling custom logging

Peer mapping feature

Comments