Creating and configuring an undercover agent for a message event

You can create an undercover agent (UCA) that invokes a particular service as the result of an incoming or an outgoing message event.

1. Open the Process Designer desktop editor.
2. In the Designer view, click the plus (+) sign next to Implementation and then select Undercover Agent from the list.
3. In the New Undercover Agent window, enter the following information:
   • Name: Type a name for the new undercover agent.
   • Schedule Type: Select On Event from the drop-down list.
   • Click Finish.
4. In the Common section, you can type a description of the undercover agent in the Documentation text box.
5. In the Scheduler section, you can see the type of schedule for the current undercover agent in the Schedule Type field.
6. Beside the Event Marker area, accept the default event marker Message. If you want, you can later click Select and then select Content. (The Content selection is used to work with content events that originate from ECM servers. By comparison, the Message selection is used to work with message events that originate from business process definitions, JMS listeners, or web services that you have created.)
7. Under Details, click the drop-down list next to Queue Name to select the queue that you want from the following options:

   Table 1. Available queue options

   Option	Description
   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.

   Note: For more information about Event Manager jobs, monitoring those jobs, and creating and maintaining Event Manager execution queues, see Maintaining and monitoring IBM Business Process Manager Event Manager. When you install and run the process on a Process Server in a test or production environment, the queue that you select must exist in that environment in order for the undercover agent to run.
8. Beside the Implementation area, accept the default selection Variable or select Service (if necessary). Use a variable implementation to pass events directly from the undercover agent to the business process definition (BPD). By comparison, use a service implementation to process information about events by adding business logic or decisions.
9. If you selected Variable, the default variable type NameValuePair is already selected. However, you can click Select to choose a different existing variable type or you can click New to create a new variable type.
10. If you selected Service, the default attached service Default BPD Event is already selected. However, you can click Select to choose a different existing service or you can click New to create a new general system service.
11. Ensure that the Enabled check box is selected.
    Note: If this check box is not selected, the Event Manager does not run the undercover agent when the message is received or sent. (The Event Manager monitor might show that the Event Manager has run the undercover agent, but if this check box is not selected, the execution does not occur.)
12. In the Parameter Mapping section, select 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.

13. In the Event section, IBM BPM provides a default ID that is unique in the Event Message field. This ID represents the event message for IBM BPM processing.

    If you are posting a message to IBM BPM 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 IBM Business Process Manager Event Manager for more information about the message structure.

    If you are using a web service to enable an external application to call into IBM BPM, you should not alter this ID. IBM BPM seamlessly uses this ID if you create an inbound integration as described in Building a sample inbound integration.

14. Open the BPD that includes the message event to which you want to attach the undercover agent. For example, if you want a particular process to start when a new customer record is created in an external system, you can associate the start event in the BPD with an undercover agent that handles that incoming event.
    Note: Ensure that the sender and receiver of a message both use the same undercover agent. For example, if the sender of a message is a message end event in another BPD, then select the same undercover agent for both the receiving start event and the sending message end event in the other BPD.
    Tip: If you occasionally use inbound messages, consider using durable subscription events. Durable subscriptions are Java Message Service (JMS) subscriptions that persist and store subscribed messages even when the client is not connected. The durable messages accumulate, even if you select the check box to make them consumable. Periodically use the BPMDeleteDurableMessages command for deleting durable subscription events.
15. Click the message event in the BPD to select it.
16. Click the Implementation option in the properties.
17. In the Message Trigger section, click Select next to Attached UCA and pick the undercover agent created in the previous steps.
18. Click Save and switch back to the undercover agent editor.
19. In the undercover agent editor, you can click Run Now if you want to test the undercover agent and monitor it as described in Maintaining and monitoring IBM Business Process Manager Event Manager.