Using the Adapter Configurator and Map Configurator
When a Managed Adapter is used in a process, you must define the mapping from input dataslots in your process to the adapter inputs in an external application and from the adapter outputs to your output dataslots. The MapConfigurator is the GUI-based component used to define this mapping.
Progress Developer Studio for OpenEdge (or Business Process Modeler) provide a default MapConfigurator that can be used for all out-of-the-box adapters. However, the MapConfigurator can also be defined separately for each adapter.
The MapConfigurator is started , when a Managed Adapter is used as the workstep performer.
In the following example, the Email Adapter is used to illustrate mapping. The following procedure assumes you have already created a preconfigured instance of this adapter.
1. Create a Managed Adapter workstep and assign Email Adapter as its performer. Double-click the workstep to open the workstep’s Properties dialog box.
2. From the Properties view of this workstep, open the Configuration tab.
You can specify other properties in the rest of tabs in the Properties view, same as that for custom adapters. For information regarding configuring properties for custom adapter workstep, refer to the "Defining Properties of Adapter Worksteps" section of the OpenEdge Getting Started: Developing BPM Applications with Developer Studio.
3. To configure the Managed Adapter, click Configure..., to open the AdapterConfigurator for the Email Managed Adapter.
Note: You can also open the Email Adapter Configurator using the new Managed Adapter Browser (available only from Progress Developer Studio for OpenEdge) functionality. In addition to configuring, you can use the Managed Adapter Browser to perform functions like creating a copy, renaming, deleting, as well as importing and exporting the configuration information. For more information, refer to the "Using the Managed Adapter Browser" section of the OpenEdge Getting Started: Developing BPM Applications with Developer Studio.
a. In the Adapter Configurator, you can enter new, or modify existing, information that are implemented only for the adapter instance. Open the Message tab and enter information in the From field and the Subject field. We leave the To field blank for now because it is mapped to a dataslot in Step 4.
b. Open the Message Body tab and enter information. Note that we use the $ symbol to create variables that are mapped to dataslots. Click Extract Variables to display the variables in the text area below.
c. Open the Configuration tab to configure the Mail Host and enter the notation "${oebps.smtp.host}" to tell the adapter to read the Mail Host name from the oebps.smtp.host property in the oebps.conf configuration file.
d. Enter the Username and Password details and select the language from the Language dropdown.
e. When you have finished configuring the Email Adapter, click OK, to open the Dataslot Mapping dialog box (or the Map Configurator). You can also open the Map Configurator by clicking the Change mapping button.
4. To modify the dataslot mapping, click Change mapping from the Configuration tab of the workstep’s Properties view, to open the Dataslot Mapping dialog box of the map configurator for the adapter. This example demonstrates how to send a message to all employees on a mailing list stored in a property file.
Note: The dataslot mapping dialog box are different for each adapter and each adapter configuration.
a. In the Message tab of the Dataslot Mapping dialog box, you can define the mapping between the input/output dataslots and the adapter inputs/outputs by either:
Selecting one from the drop-down list.
Using the "GroupMapper" feature by entering a notation that refers to email addresses, such as an employee mailing list, that are stored in a property file. This notation instructs the adapter to get the "empMailingList" property from the "mail.prop" file and use the property value as the email destination.
b. Open the Velocity Template tab to map dataslots to each of the variables we used in the message body. Map the "meetingRoom" dataslot to the "roomNumber" variable to substitute the value of this dataslot for the $roomNumber field in the message text; and similarly map the "schedTime" dataslot to the "time" variable.
c. Click OK to return to the Configuration tab of the workstep’s Properties view.
5. To edit the mapping.prop file to change the settings for mapping (for example, log level), click Advanced properties from the Configuration tab of the workstep’s Properties view, to open the Advanced Adapter Properties dialog box.
a. Edit the mapping.prop file displayed in the Advanced Adapter Properties dialog box appropriately as per your requirement.
b. Click OK to return to the Configuration tab of the workstep’s Properties view.
c. Click OK to save the changes.
The Dataslot Mapping dialog box lists all input and output dataslots for the workstep, and lists all the visible adapter parameters, grouped according to the config.xml. You can enter or select the value of the given dataslot or parameter. Simple syntax distinguishes constant values from values to be copied from dataslots or from adapter parameters. The following table explains the syntax in detail.
Table 9. Mapping syntax
Value
Description
@<dataslot>
The value of the corresponding adapter input comes from:
The given dataslot.
OR
The value of the output dataslot is transferred from the given adapter output.
Usually you select the dataslot from the drop-down list, making it unnecessary to manually enter the @ symbol. Once a valid dataslot is selected, the @ symbol is not displayed, but an icon representing the dataslot type is shown.
Begins with any other character
Any character other than "@" at the beginning of a string signals that the value is a constant. In case the constant itself begins with "@", precede the "@" with "\"; or if the constant begins with a "\", use "\\". The "\" and "@" symbols are significant only at the beginning of the string, and have no special meaning anywhere else in the string.
${propertyFile: propertyName}
If an adapter input is mapped to a constant (see the previous row in this table), you can use this "GroupMapper" notation to extract values from property files on the server. The "propertyFile:" prefix is optional — if no property file is defined, "oebps.conf" are read. For example, "${oebps.home}" is substituted with the value of the "oebps.home" property from the "oebps.conf" file. If you use your own property files, make sure they are located in the server classpath (EJB Server or Portal Server, depending on where your application is running).
Custom property files may contain references to another file by including "alias=fileName" property. For example, if "file1.prop" includes "alias=file2.prop", the property values from "file2.prop" are read too. In case a property is present in both files, higher precedence are given to the value in the "file2.prop" file.
Note: Even when the input and output have exactly same format, copying a value from an input dataslot directly to an output dataslot is not allowed.
Note that some of the adapter parameters have read-only combo boxes when:
The parameter is output-only.
The parameter is a constant.
When map configuration is completed, the MapConfigurator creates the input and output map files in the OpenEdge\workspace directory under <Process_Name>\maps\<Workstep_Name>.
Selecting one from the drop-down list.
