Overview

About the Adapter

IBM webMethods Adapter for Remedy (Adapter for Remedy) is an add-on to IBM webMethods Integration Server that enables you to exchange data with Remedy Action Request System (AR System), which is the base for all Remedy applications. The adapter provides seamless and real-time communication with the AR System Server. You can create integrations that initiate actions from IBM webMethods Integration Server that are performed in the AR System, and you can detect changes in the AR System and send notification to Integration Server:

Initiating action from Integration Server.
You can issue requests to the AR System to create, get, update, find, retrieve details, execute one of several adapter ARS Server operators, or delete entries in the AR System. Adapter for Remedy provides user interfaces in the Integration Server Administrator that enable you to configure and manage adapter connections to the AR System Server. Adapter for Remedy also provides user interfaces in IBM webMethods Designer that you use to create adapter services. The adapter services use the connections you define to perform an action (create, get, update, find, retrieve details, execute one of several adapter ARS Server operators, or delete entries). To perform the action, Adapter for Remedy uses the AR System Java APIs.
Detecting changes in the AR System.
You can set up filters in the AR System that detect specific changes that occur in the AR System. When a change is detected, the AR System Server sends the information defined in the filter. To notify Integration Server of a change, you can set up the filter to send an e-mail message to Integration Server, or you can invoke a Web service.

Architecture and Components

Adapter for Remedy provides a set of user interfaces, services, and templates that enable you to create integrations that interact with the AR System. The adapter is provided as a single package that must be installed on Integration Server. For detailed installation instructions, see Installing IBM webMethods Adapter for Remedy. For software requirements, see the IBM webMethods Adapters System Requirements.

The following diagram shows, at a high level, how the adapter components connect to an AR System Server:

Integration Server
Adapter for Remedy is installed and runs on Integration Server.
Adapter Runtime (WmART Package)
The Adapter Runtime, which is provided in the WmART package, provides a common framework for webMethods 7 and later adapters to use the Integration Server's functionality, making Integration Server the run-time environment for Adapter for Remedy. The WmART package is installed with Integration Server and provides logging, transaction management, and error handling for the adapter and its connections and services.
Adapter for Remedy
Adapter for Remedy is delivered as a single package called WmRemedyAdapter. The adapter provides administrative screens that enable you to configure and manage adapter connections. You access these administrative screens via Integration Server Administrator. Adapter for Remedy also provides Designer user interfaces that enable you to configure and manage adapter services. Adapter for Remedy installation includes templates from which all Adapter for Remedy services can be created.
Adapter Connections
An adapter connection enables Integration Server to connect to the AR System Server at run time. You must configure an adapter connection before you can create adapter services. For a detailed description of adapter connections and usage information, see Adapter Connections.
Adapter Service Templates
Use adapter services for transactions where Integration Server initiates a request in the AR System. An adapter service enables Integration Server to interact with the AR System Server to create, get, update, find, retrieve details, execute one of several adapter ARS Server operators, or delete entries in the AR System database.

Each entry in the AR System database uses a specific form. When you create an adapter service, you select an existing form to provide the schema for the entry upon which the adapter service is to act.

These adapter services act as a client to the AR System Server and use the AR System Java APIs to perform the requested actions. Adapter for Remedy provides adapter service templates in Designer. For more information about adapter service templates and how the services interact, see Requests Initiated on Integration Server, Adapter Services.
AR System Server
Adapter for Remedy connections and services interact with the AR System Server. The AR System Server performs access control to the AR System and controls the flow of data into and out of the AR System database. For example, if you invoke an adapter service to create a new entry in the AR System, the AR System Server performs the action to update the database with the new entry.
AR System database
The data (entries) that the AR System maintains is stored in the AR System database.
Filters
Use filters to have the AR System notify Integration Server of actions that occurs in the AR System. Filters are a feature of the AR System and are not provided by Adapter for Remedy. You define filters in the AR System, and they are executed in the AR System Server. When you define a filter, you specify the condition that the filter is to detect and the action to take when that condition is met. For integrations with Integration Server, the action you specify is to notify Integration Server either by sending an e-mail message or by invoking a Web service. For more information, see the Adapter for Remedy documentation.

Requests Initiated on Integration Server

The following diagram illustrates the use of Adapter for Remedy and Integration Server in a typical business-process integration to initiate a request from Integration Server that is performed in the AR System. See the table below the diagram for additional information.

Step	Description
1	To request that an action be performed in the AR System, your back-end systems invoke services that you create and that reside in Integration Server. When invoking the service, Integration Server client sends data that provides more information about the request. For example, if the Integration Server client wants to create an entry in the AR System, the data would be the values to use in the entry to create.
2	The service that the Integration Server client invokes is executed on Integration Server. The service invokes adapter services to interact with the AR System.
3	The adapter services use an adapter connection to connect to the AR System Server. The adapter service interacts with the AR System via the AR System Java APIs.
4	The AR System Server receives the request and performs the request that the Integration Server client initiated.

Notifications Sent from the AR Systems

This section describes how Integration Server can receive notifications when an action occurs in the AR System. The AR System can send notifications either using an e-mail message or by invoking a Web service.

Receiving an E-mail Notification

The following diagram illustrates how Integration Server can receive a notification in an e-mail message when an action occurs within the AR System. See the table below the diagram for additional information.

Step	Action
1	An action occurs in the AR System, and a filter that you created in the AR System detects this condition. The action defined in the filter is to notify via an e-mail message. As a result, the AR System Server sends an e-mail notification to the outgoing mailbox identified in the filter.
2	The outgoing mailbox sends the e-mail message to the e-mail account specified when the outgoing mailbox was configured.
3	The e-mail message is sent to a mail server that receives e-mail messages from AR System Server. The Integration Server Email Listener periodically checks the e-mail account on the mail server and polls for e-mail messages.
4	The Email Listener receives the e-mail message.
5	The Email Listener invokes the service that you defined to handle the notification. Adapter for Remedy provides a sample service, wm.adapter.wmremedy.outbound.emailNotification:receiveEmail service, which illustrates how to obtain the content from the e-mail message.

Handling Notifications via a Web Service

The following diagram illustrates how the AR System can invoke a Web service to notify Integration Server when an action occurs within the AR System. See the table below the diagram for additional information.

Step	Action
1	An action occurs in the AR System, and a filter that you created in the AR System detects this condition. The action defined in the filter is to invoke a Web service. As a result, the AR System Server invokes the Web service and passes an XML document that contains the notification.
2	The Web service that the AR System Server invokes resides on the Integration Server that handles the notification. Adapter for Remedy provides a sample Web service that you can use to model your own Web service. The sample Web service is wm.adapter.wmremedy.outbound.webService:receiveWSDL_SOAP_RPC.

Adapter Package Management

Adapter for Remedy is provided as a package called WmRemedyAdapter that you manage like any package on Integration Server.

There are several considerations regarding how you set up and effectively manage your packages on Integration Server, such as those described in the following list.

Configure user-defined packages for your adapter connections and adapter services. See Managing the Adapter Package for details.
Understand how package dependencies work so you make the best decisions regarding how you manage your adapter services. See Package Dependency Requirements and Guidelines for details.
Control which development groups have access to which adapter services. See Controlling Group Access for details.
Understand how clustering, an advanced feature of IBM webMethods Integration Server, works to effectively manage your adapter services. See Using Adapter for Remedy in a Clustered Environment for details.
Enable and disable packages. See Enabling Packages and Disabling Packages for details.
Load, reload, and unload packages. See Loading, Reloading, and Unloading Packages.

Adapter Connections

An adapter connection enables a Adapter for Remedy service to connect to the AR System Server to create, update, find, get, retrieve details, execute one of several adapter ARS Server operators, and delete entries that are stored in the AR System database.

You can configure one or more adapter connections at design time to use in integrations. You configure one adapter connection for each AR System Server with which you want to integrate. When you define the adapter connection, you specify parameters, such as:

Name for the connection
AR System Server host name
User name and password of a user defined on the AR System Server that Integration Server uses to establish the connection and to obtain information about forms, fields, etc.

You configure adapter connections using the Integration Server Administrator. You must have webMethods administrator privileges to access the Adapter for Remedy's administrative screens.

For instructions for configuring, viewing, editing, enabling, disabling, and deleting Adapter for Remedy connections, see Adapter Connections. For information about setting user privileges, see the IBM webMethods Integration Server Administrator’s Guide for your release.

For a list of tasks that you must do before you can create your connections, see Before Configuring or Managing Adapter Connections.

Connection Pools

Integration Server includes a connection management service that dynamically manages connections and connection pools based on configuration settings that you specify for the connection. All adapter services use connection pooling.

A connection pool is a collection of connections with the same set of attributes. Integration Server maintains connection pools in memory. Connection pools improve performance by enabling adapter services to reuse open connections instead of opening new connections.

Run-Time Behavior of Connection Pools

When you enable a connection, Integration Server initializes the connection pool, creating the number of connection instances you specified in the connection's Minimum Pool Size parameter. Whenever an adapter service needs a connection, Integration Server provides a connection from the pool. If no connections are available in the pool, and the maximum pool size has not been reached, the server creates one or more new connections (according to the number specified in Pool Increment Size) and adds them to the connection pool. If the pool is full (as specified in Maximum Pool Size), the requesting service will wait for Integration Server to obtain a connection, up to the length of time specified in the Block Timeout parameter, until a connection becomes available. Periodically, Integration Server inspects the pool and removes inactive connections that have exceeded the expiration period that you specified in Expire Timeout. You can enable the system to retry the initialization any number of times, at specified intervals.

For information about configuring connections, see Adapter Connections.

Built-In Services For Connections

Integration Server provides built-in services that enable you to programmatically control connections. You can use them to enable and disable a connection, and to return usage statistics and the current state (Enabled or Disabled) and error status for a connection. These services are located in the WmART package, in the pub.art.connection folder.

The built-in service setAdapterServiceNodeConnection enables you to change the connection associated with an adapter service. For more information, see the sections below.

For details about the built-in services, see the IBM webMethods Integration Server Built-In Services Reference for your release.

Changing the Connection Associated with an Adapter Service at Design Time

Integration Server provides a built-in service that you can use at design time to change the connection associated with an adapter service. This built-in service is named setAdapterServiceNodeConnection and is provided in the WmART package's pub.art.service folder. Using this function, you can change the specific connection associated with an adapter service at design time so that you do not need to create and maintain multiple adapter services.

Note: This built-in service can be run at design time only; do not use it within an Integration Server flow or Java service. You must run this service directly from Designer by selecting the service and running it.

For details, see the IBM webMethods Integration Server Built-In Services Reference for your release.

Other built-in services enable you to control connections; for more information, see Built-In Services For Connections.

Changing the Connection Associated with an Adapter Service at Run Time

Integration Server enables you to dynamically select the connection a service uses to interact with the adapter's resource. This feature enables one service to interact with multiple, similar back-end resources.

For example, you can configure an adapter service to use a default connection that interacts with your company's production AR System Server. However, at run time you can override the default connection and instead use another connection to interact with the company's AR System Server.

For more information about overriding a service's default connection at run time, see Dynamically Changing a Service's Connection at Run Time.

Adapter Services

Adapter services allow you to connect to the AR System Server and initiate an operation on the AR System from Integration Server. Integration Server uses adapter connections that you defined earlier to execute the adapter services. You invoke adapter services from flow or Java services to interact with the AR System Server to create, get, update, find, retrieve details, execute one of several adapter ARS Server operators, or delete entries in the AR System database. The adapter services perform these operations (for example, create, get, update, find, or delete) using the AR System Java APIs. Adapter for Remedy makes synchronous calls to the AR System Server using the AR System Java APIs.

Entries in the AR System database are associated with specific AR System forms. A form defines the fields associated with an entry. At design time you configure an adapter service using templates provided with Adapter for Remedy. When you configure an adapter service, you provide the form name. An adapter service template contains all the code necessary for accessing forms and obtaining fields. Each template represents a specific operation for doing work on an AR System Server, such as using the Get template to retrieve an entry from the AR System database.

You use Designer to configure the adapter service. For more information, see the IBM webMethods Service Development Help for your release.

The input and output signatures for an adapter service are defined for you when you configure the adapter service. The input and output signatures depend on the function of the adapter service (for example, create, get, update, find, or delete) and the specific form that the adapter service is to use. For example, if you use the Create template, the input signature includes the fields from the form that you select when you configure a Create service. Similarly, if you use the Get template, the output signature includes the fields from the form that you select when you configure a Get service.

Adapter Service Templates

The following table lists the adapter service templates:

Adapter Service Template	Description
Create	Creates an entry in the AR System database based on a selected AR System form.
Delete	Deletes an entry with a specified entry ID number from the AR System database.
Find	Locates one or more entries that are stored in the AR System database and that match the specified search criteria.
Get	Retrieves the details for an existing entry in the AR System database that uses a specified form and has a specified entry ID.
Batch Get	Finds and retrieves the details for all existing entries in the AR System database that use a specified form and have the specified list of entry IDs.
Update	Updates fields for an existing entry in the AR System database.
ARS Server Operations	Executes one of the following ARS Server operations: Execute Process Get Operation Time Begin Bulk Entry Transaction End Bulk Entry Transaction

Adapter Service Operation

The run time actions that occur in Integration Server and the AR System when an adapter service is invoked are basically the same for all types of Adapter for Remedy services. The only difference is the operation performed in the AR System.

At run time, an Integration Server client invokes a flow or Java service on Integration Server. This flow or Java service, in turn, invokes the adapter service. The adapter service uses AR System Java APIs to interact with the AR System Server. The diagram and table below illustrate the run-time processing for an adapter service.

Step	Description
1	An Integration Server client invokes a flow service or Java service on Integration Server.
2	The flow or Java service invokes the adapter service, which you configured earlier using Designer.
3	The adapter service gets a connection from the service's connection pool, which you created and enabled earlier using Integration Server Administrator.
4	Through its connection, the adapter service interacts with the AR System Server using the AR System Java APIs to perform the operation requested by the adapter service.
5	The AR System Server performs the requested operation, interacting with the AR System database as necessary. For more information about a specific operation, see one of the following sections: Create Adapter Service Delete Adapter Service Find Adapter Service Get Adapter Service Batch Get Adapter Service Update Adapter Service ARS Server Operations Adapter Service
6	The AR System Server returns the result of the operation. See the appropriate section below for information about the outcome for a specific operation.
7	The adapter service updates results of the operation in the pipeline.

Create Adapter Service

Services configured with the Create template create entries in the AR System database.

At design time, you identify the AR System form that the Create adapter service is to use. Based on the form you select, Adapter for Remedy loads the appropriate fields into the adapter service template. You select the fields that are needed for the entries that the service will create. The input signature of the Create adapter service is based on the form fields that you select. The output signature of the Create adapter service is the entry ID of the newly created entry; you cannot modify the output signature.

At run time, the Create adapter service uses the AR System Java APIs to create a new entry in the AR System database. The new entry has the format that is defined by an AR System form, which you identified when you configured the Create adapter service. The form identifies the fields that make up the entry. The Create adapter service retrieves the values for the fields from the pipeline.

If the Create operation is successful, the adapter service returns a String that contains the entry ID for the newly created entry. If the operation is unsuccessful, the adapter service throws an AdapterException or AdapterConnectionException. For more information about how the adapter handles exceptions, see Adapter Logging and Exception Handling.

Delete Adapter Service

Services configured with the Delete template delete an entry from the AR System database. The entry to delete is identified by the name of the AR System form for the entry along with the entry ID for the entry.

At design time, you identify the AR System form that the Delete adapter service is to use. You can also optionally supply the entry ID of the entry to delete. Alternatively, the entry ID can be supplied at run time. The output signature of the Delete adapter service contains a String that holds the status (or outcome) of the delete operation (Success or Failure); you cannot modify the output signature.

At run time, the Delete adapter service uses the AR System Java APIs to delete the entry specified by the form name and entry ID.

If the Delete operation is successful, the adapter service returns a String. If the operation is unsuccessful, the adapter service throws an AdapterException or AdapterConnectionException. For more information about how the adapter handles exceptions, see Adapter Logging and Exception Handling.

Find Adapter Service

Services configured with the Find template locate one or more existing entries in the AR System database. The search criteria for locating entries are the name of the form used for the entries and a query string.

At design time, you identify the AR System form that the Find adapter service is to use. You can also optionally supply a query string that the Find adapters service applies to select a subset of the entries that use the specified form. The input signature of the Find adapter service includes this query string, allowing you to pre-define the query string at design time or supply the query string at run time. The output signature of the Find adapter service contains String values that hold the entry ID and description for each matching entry; you cannot modify the output signature.

At run time the Find adapter service uses the AR System Java APIs to locate entries. It locates entries that match the form name and query string you specify. The AR System Server returns the list of matching entries.

Get Adapter Service

Services configured with the Get template obtain the details about an entry in the AR System database. The entry obtained is identified by the name of the AR System form along with the entry ID.

At design time, you identify the AR System form that the Get adapter service is to use. You can also optionally supply the entry ID that the Get Adapter service uses to retrieve the entry details. Alternatively, the entry ID can be supplied at run time. You can configure the output signature of the Get adapter service to contain the field values that you select. The Get adapter service returns the selected field values from the entry.

At run time, the Get adapter service uses the AR System Java APIs to obtain the selected field values of the specified entry. The AR System Server returns the field values from the entry.

Batch Get Adapter Service

Services configured with the Batch Get template retrieve details about multiple form entries from the Remedy ARS Server. The entries obtained are identified by the name of the AR System form along with the entry IDs.

At design time, you identify the AR System form associated with the Batch Get adapter service and the entry form fields retrieved by this service. As input to the service, you provide the list of entry IDs for the Remedy form that should be retrieved. The Batch Get service returns a document list. The document list takes the name of the Remedy form whose entries are being retrieved. Each document in the list contains the entry data for all entry fields that you selected during design time.

At run time, the Batch Get adapter service uses the AR System Java APIs to obtain the selected field values of the specified entries. The AR System Server returns the field values from the entries.

Update Adapter Service

Services configured with the Update template update fields for an entry in the AR System database. The entry that the Update adapter service updates is identified by the name of the AR System form for the entry along with the entry ID for the entry.

At design time, you identify the AR System form that the Update adapter service is to use. You can also optionally supply the entry ID of the entry that the Update Adapter service uses to update the details. Alternatively, the entry ID can be supplied at run time.

You configure the input signature of the Update adapter service to contain the fields that you select. The output signature of the Update adapter service contains a String that holds the status (or outcome) of the update operation (Success or Failure); you cannot modify the output signature.

At run time, the Update adapter service uses the AR System Java APIs to supply new field values for the selected fields. The adapter service retrieves the new values for the fields from the pipeline. The AR System Server returns the result of the update operation, which indicates the status of the update operation.

ARS Server Operations Adapter Service

Services configured with the ARS Server Operations template execute one of the following ARS Server operations:

Operation	Description
Execute Process	Executes the input command on the AR System server and returns the result if the service has been configured to wait for the process to complete. For more information about the commands that can be executed on the AR System server, see the BMC Remedy Action Request System documentation.
Get Operation Time	Gets the operation time stamp set by the AR System server after each API call.
Begin Bulk Entry Transaction	Marks the beginning of a bulk entry transaction for the associated service connection object.
End Bulk Entry Transaction	Marks the ending of a bulk entry transaction for the associated service connection object.

Note: The Bulk Entry Transaction operations supported in Adapter for Remedy are different that any other WmART-based adapter transactions. The Adapter for Remedy Bulk Entry Transaction operations are not handled by the WmART-based (Integration Server) transaction manager.

When you select one of the above operations in the service template, the input and output parameters of the adapter service change based on the operation selected.

Using Adapter Services

The following table lists the tasks required to use adapter services:

Task		Use this tool...
1	Create and enable an adapter connection. See Adapter Connections for details.	Integration Server Administrator
2	Select the appropriate adapter service template and configure the necessary adapter services. Depending on the type of adapter service, you specify the: Adapter connection Form name for the entry in the AR System with which the adapter service is to interact Optionally, the entry ID for an entry if you are getting information about an entry or deleting an entry See Adapter Services for more information about configuring each of the adapter services.	Designer
3	If you plan to use an Integration Server flow service or Java service to invoke the adapter service, design the flow service to use Adapter for Remedy services you configure. For information about using Designer, see the IBM webMethods Service Development Help for your release.	Designer
4	Manage the adapter services. See Adapter Package Management and Adapter Logging and Exception Handling for details.	Designer and Integration Server Administrator

Using Version Control Systems to Manage Adapter Elements

The adapter supports the Version Control System (VCS) Integration feature provided by Designer. When you enable the feature in Integration Server, you can check adapter packages or elements into and out of your version control system from Designer. For more information about the VCS Integration feature, see the Configuring the VCS Integration Feature.

Beginning with Integration Server 8.2 SP3, the adapter supports the local service development feature in Designer. This feature extends the functionality of the VCS Integration feature to check package elements and their supporting files into and out of a VCS directly from Designer. For more information about local service development and how it compares to the VCS Integration feature, see the IBM webMethods Service Development Help.

Optimize Infrastructure Data Collector Support for the Adapter

Optimize Infrastructure Data Collector monitors the system and operational data associated with webMethods run-time components such as Integration Servers, Broker Servers, Brokers, and adapters, and reports the status of these components on Optimize for Infrastructure or other external tools. When you start monitoring an Integration Server, Infrastructure Data Collector automatically starts monitoring all ART-based adapters that are installed on the Integration Server.

For information about monitored key performance indicators (KPIs) collected for the monitored adapter components, see the IBM webMethods Optimize User’s Guide for your release.

Viewing the Adapter's Update Level

With Integration Server 7.1 or later, you can view the list of updates that have been applied to the adapter. The list of updates appears in the Updates field on the adapter's About page in the Integration Server Administrator.

Controlling Pagination

About this task

When using the adapter on Integration Server 8.0 and later, you can control the number of items that are displayed on the adapter Connections screen and Notifications screen. By default, 10 items are displayed per page. Click Next and Previous to move through the pages, or click a page number to go directly to a page.

To change the number of items displayed per page, set the watt.art.page.size property and specify a different number of items.

To set the number of items per page

Procedure

From Integration Server Administrator, click Settings > Extended.
Click Edit Extended Settings. In the Extended Settings editor, add or update the watt.art.page.size property to specify the preferred number of items to display per page. For example, to display 50 items per page, specify:
```
watt.art.page.size=50
```
Click Save Changes. The property appears in the Extended Settings list.
For more information about working with extended configuration settings, see the IBM webMethods Integration Server Administrator’s Guide for your release.