Actor adapter requests

Actor adapters use requests to obtain data from external systems and, in some cases, affect data in those systems. These requests are configured in BMC Atrium Orchestrator Development Studio in either a Call Adapter activity or an Assign activity.

In a Call Adapter activity, the adapter request is defined by the following ways in the Properties tab of the Activity Property window:

Static value: specifies the XML text of the request that you enter in the adapter's Data field, exactly as shown in the templates and the samples provided in the respective adapter sections.
Context key: specifies that an Assign activity is used to create an XML document for the adapter request and assigns that document to a context item. The context item is referenced in the Properties tab of the Call Adapter activity. This XML document must be contained in <request-data> tags. These tags are not included in the XML templates and the samples provided in the respective adapter sections. You must add them to create a request that executes successfully.

Some adapters can perform more than one type of action, so you must specify the action in the Action field of the Properties tab.

For each adapter, the wiki help for Base adapters includes the available actions, a table outlining XML request elements, an XML template of the request, and a sample of XML adapter request. The Call Adapter activity and Creating and configuring the Call Adapter activity contain detailed steps about using the Call Adapter and Assign activities.

The following table describes the fields associated with each available option in the Properties tab for a Call Adapter activity.

Call Adapter activity properties with static value as the adapter input

Fields	Description
Adapter Name	Specifies the adapter to use to service the request It must be an adapter that has been configured in Grid Manager.
Peer Location	Specifies the location of the peer that services the adapter request The adapter must be enabled on the peer that services the request. This can be a different peer from the one that is executing the process. Following are the options: any: Specifies that the adapter request can be serviced by any peer on the grid. The master job processor distributes the process to the next available peer. The adapter must be enabled on at least one peer on the grid. this: Specifies that the adapter request is serviced by the selected peer and contains the master job processor. With this option, The adapter must be enabled on the configuration distribution peers (CDPs) and all the activity peers (APs) on the grid because any one of them can be the master job processor at any time. Lightweight activity peers (LAPs) cannot become the master job processor. best: Allows the grid to determine the best peer to service the request. The adapter must be enabled on at least one peer on the grid. peer: Enables you to specify the peer to service the adapter request. The adapter must be enabled on the peer specified in the Peer Name field.
Peer Name	Specifies the peer on the grid on which the adapter is enabled This element is required when the value of `<Peer Location>` is peer.
Action	Specifies the type of action to be performed by the adapter request Not all adapters use an adapter action. If an adapter does not have an associated action, leave this field blank.
Adapter Data	Specifies an XML document that defines the adapter request The samples and the templates for each adapter can be referenced in this document. You can enter the templates provided in this document into the Adapter Data field exactly as shown.
Adapter Input	Specifies, for the Context key option, a context item that contains an XML document with a root element, `<request-data>`, for the adapter request Click the browse icon to launch the Context Browser and select a context item, the value of which must contain the `<request-data>` element and all required elements for the adapter request. The specific XML required for each adapter can be referenced in this document. If you select a global context item, the globe icon is displayed.
Adapter Output	Specifies the context item to which the adapter response is assigned Not all adapter requests produce an adapter response. If an adapter output is assigned for an adapter request that does not produce a response, the activity fails and a compensation is executed.

Each adapter request consists of the elements shown in the Elements of an actor adapter request.

The complete adapter request is formed by the Call Adapter activity, which uses information provided in its Activity Property panel. The only XML content that you must provide is contained in the <request-data> element shown in the following figure.

XML sample of an adapter request

<adapter-request>
  <target-adapter>target_adapter_name</target-adapter>
  <peer-location>
  <location> this | any | best | peer </location>
  <peer-name>peer_name</peer-name>
  </peer-location>
  <request-action>adapter-specific request action text</request-action>
  <request-data>adapter-specific request XML data</request-data>
</adapter-request>

The following table describes the elements of an actor adapter request.

Elements of an actor adapter request

Request element	Description	Required
`<target-adapter>`	Specifies the adapter name as defined in Grid Manager	Yes
`<peer-location>`	Contains information about which peer to use to execute the adapter request	Yes
`<location>`	Specifies the type of peer from which the adapter request executes: this, any, best, peer For description of these values, see the Call Adapter activity properties with static value as the adapter input. An adapter request can be executed on a peer different from the one that executes the process that initiates the adapter request.	Yes
`<peer-name>`	Specifies the peer name This element is used only when the value of `<location>` is peer.	Yes
`<request-action>`	Specifies the action that the request executes	No
`<request-data>`	Specifies an XML document that provides the adapter with specific instructions and parameters to facilitate an action	No

Actor adapter requests

Comments