WebSphere Lombardi Edition 7.2 > Modeling processes > Advanced modeling tasks > Integrate with other systems > Create inbound integrations
Understand and using Undercover Agents
A UCA is started by an event. Events can either be triggered by a message or on a specific schedule. When a UCA is started, it invokes a Lombardi service in response to the event.
Incoming messages can originate from a Web Service that you create or from a message that you post to the JMS Listener. To create Web Services to initiate inbound requests from external systems, see Publish Lombardi Web Services.
To post a message to the JMS Listener, the Event Manager has a defined XML message structure that it must receive from an external system. See Posting a message to Lombardi Event Manager for more information about the required message structure.
The Event Manager is the part of the Process Server that handles event scheduling and queuing. See: About the Event Manager in Lombardi Administration Guide and the online help for the Process Admin Console. The Event Manager needs a UCA to find the service that it should run. So, if you want to invoke a service when an incoming message event is received or if you want to invoke a service as the result of an event that occurs on a regular schedule, you should create a UCA
Create an Undercover Agent for an incoming message event
Follow these steps to create a UCA that invokes a particular service as the result of a incoming message event from an external application:
See
Build a sample inbound integration
to learn how to build a sample integration that includes this type of UCA.
- Start Lombardi Authoring Environment and open the appropriate process application in the Designer view
- In the Designer view, select the plus sign next to Implementation and then select Undercover Agent from the list.
-
In the New Undercover Agent dialog, enter the following information and then click the Finish button.
Name Type a name for the new UCA. Schedule Type Select On Event from the drop-down list. Attached Service Click the Select button to select the service to invoke when the event is received. You can select any type of service except for Human services. - In the Common section, you can type a description of the UCA in the Documentation text box.
- In the Scheduler section, you can see the type of schedule for the current UCA. After you have configured and saved the UCA, you can click the Run Now button if you want to test the UCA and monitor it. See: Maintain Lombardi Event Manager in Lombardi Administration Guide and the online help for the Process Admin Console.
-
Under Details, click the drop-down list next to Queue Name to select the queue that you want from the following options:
Async Queue Allows Event Manager jobs to run at the same time. SYNC_QUEUE_1 Forces one job to finish before the next job can start. By default, three synchronous queues are available. SYNC_QUEUE_2 Forces one job to finish before the next job can start. By default, three synchronous queues are available. SYNC_QUEUE_3 Forces one job to finish before the next job can start. By default, three synchronous queues are available. For more information about Event Manager jobs, monitoring those jobs, and creating and maintaining Event Manager execution queues, see Maintain Lombardi Event Manager in Lombardi Administration Guide or the online help for the Process Admin Console. When you install and run the current process application on a Process Server in a test or production environment, the queue that you select must exist in that environment in order for the UCA to run.
- Ensure the service shown as the Attached Service is the one that you want to invoke when the external message is received. If not, click the Select button to choose a different service.
-
Ensure that the Enabled check box is checked/enabled.
If this check box is not enabled, the Event Manager does not run the UCA when the external message is received. (The Event Manager monitor may show that the Event Manager has executed the UCA, but if this check box is not enabled, the execution does not occur.)
-
In the Parameter Mapping section, click the Use Default check box if you want to use the default value of the input variable in the attached service. If the input variable of the attached service does not have a default value, this check box is disabled.
Type a value in the text box if you want to map a constant value to the input variable of the attached service. For example, you might use a constant for testing purposes.
In most cases, the required values are included in the incoming message event and no action is required here.
-
In the Event section, Lombardi provides a default ID that is unique in the Message Event field. This ID represents the Message Event for Lombardi processing.
If you are posting a message to Lombardi Event Manager from an external system, the ID in this field is the event name that you need to include in the XML message. See Posting a message to Lombardi Event Manager for more information about the message structure.
If you are using a Web Service to enable an external application to call into Lombardi, you should not alter this ID. Lombardi seamlessly uses this ID if you create an inbound integration
- Open the BPD that includes the message event to which you want to attach the UCA. For example, if you want a particular process to start when a new customer record is created in your SAP system, you can associate the Start Message Event in the BPD with a UCA that handles that incoming event.
- Click the message event in the BPD to select it.
- Click the Implementation option in the properties.
- In the Message Trigger section, click the Select button next to the Attached UCA field and pick the UCA created in the previous steps.
Create an Undercover Agent for a scheduled event
Follow these steps to create a UCA that invokes a service as the result of an event that occurs on a regular schedule:
Scheduled UCAs do not run on the Process Center Server except via
the
Run Now button. So, if you are testing a BPD
that includes scheduled UCAs and you want to ensure that the UCAs execute on
time, you should run the BPD on a Process Server in one of your runtime
environments such as your staging or testing environment.
- Start Lombardi Authoring Environment and open the appropriate process application in the Designer view
- In the Designer view, select the plus sign next to Implementation and then select Undercover Agent from the list.
-
In the New Undercover Agent dialog, enter the following information and then click Finish.
Name Type a name for the new UCA. Schedule Type Select Time Elapsed from the drop-down list. Attached Service Click the Select button to select the service to invoke when the event is received. You can select any type of service except for Human services. - In the Common section, you can type a description of the UCA in the Documentation text box.
- In the Scheduler section, you can see the type of schedule for the current UCA. After you have configured and saved the UCA, you can click the Run Now button if you want to test the UCA and monitor it. See: Maintain Lombardi Event Manager in Lombardi Administration Guide or the online help for the Process Admin Console.
-
Under Details, click the drop-down list next to Queue Name to select the queue that you want from the following options:
Async Queue Allows Event Manager jobs to run at the same time. SYNC_QUEUE_1 Forces one job to finish before the next job can start. By default, three synchronous queues are available. SYNC_QUEUE_2 Forces one job to finish before the next job can start. By default, three synchronous queues are available. SYNC_QUEUE_3 Forces one job to finish before the next job can start. By default, three synchronous queues are available. For more information about Event Manager jobs, monitoring those jobs, and creating and maintaining Event Manager execution queues, see Maintain Lombardi Event Manager in Lombardi Administration Guide. When you install and run the current process application on a Process Server in a test or production environment, the queue that you select must exist in that environment in order for the UCA to run.
- Ensure the service shown as the Attached Service is the one that you want to invoke according to the specified schedule. If not, click the Select button to choose a different service.
-
Ensure that the Enabled check box is checked/enabled.
If this check box is not enabled, the UCA will not run.
-
In the Parameter Mapping section, click the Use Default check box if you want to use the default value of the input variable in the attached service. If the input variable of the attached service does not have a default value, this check box is disabled.
Type a value in the text box if you want to manually map a constant value to the input variable of the attached service. For example, you might use a constant for testing purposes.
-
In the Time Schedule section, use the available options to establish a schedule.
For example, if you want to start the attached service every week day at midnight, set the options shown in the following image:
You can select multiple contiguous items by pressing the Shift key, clicking the first in the series, and then clicking the last in the series. To select multiple non-contiguous items, press the Ctrl key each time you click an item.
- Open the BPD that includes the message event to which you want to attach the UCA. For example, if you want a particular process to start at the same time each day, you can associate the Start Message Event in the BPD with a UCA that establishes the required schedule.
- Click the message event in the BPD to select it.
- Click the Implementation option in the properties.
- In the Message Trigger section, click the Select button next to the Attached UCA field and pick the UCA created in the previous steps.
Parent topic: Create inbound integrations