IBM WebSphere Developer Technical Journal : A guided tour of WebSphere Integration Developer -- Part 8

Dynamically invoking a component using selectors

This is the eighth article in a series describing how to build applications based on a service-oriented architecture (SOA). A previous article examined the flexible on-demand nature of business rules. This article examines selectors, another on-demand capability provided by WebSphere® Integration Developer and WebSphere Process Server.


Jane Fung (, Advisory Software Developer, IBM

Photo of Jane Fung Jane Fung is an Advisory Software Developer at IBM Canada Ltd, where she is responsible for developing the Business Process Execution Language (BPEL) and Business Rules debuggers in WebSphere Integration Developer. Prior to that, she was the team lead of the WebSphere Studio Technical Support team.

Greg Adams (, Distinguished Engineer, IBM

Photo of Greg AdamsGreg Adams was the lead architect for the user interface in the award-winning Eclipse platform, and more recently, has been the lead architect and development lead in the core WebSphere Business Integration Tools, including WebSphere Studio Application Developer Integration Edition and WebSphere Integration Developer. Greg led the delivery of IBM's first complete services oriented architecture (SOA) tools stack and the first BPEL4WS standards supporting Business Process Editor; both critical deliverables in support of IBM's On Demand strategy.

Richard Gregory (, Staff Software Developer, IBM

Photo of Richard GregoryRichard Gregory is a software developer at the IBM Toronto Lab on the WebSphere Integration Developer team. His responsibilities include working on the evolution and delivery of test tools for WebSphere Integration Developer.

Randy Giffen (, Senior Software Developer, IBM

Photo of Randy Giffen Randy Giffen is a senior software developer is the usability lead for WebSphere Integration Developer and WebSphere Message Broker Toolkit. He was responsible for WebSphere Integration Developer's business state machine tools and the visual snippet editor. Prior to to this he was a member of user interface teams for WebSphere Studio Application Developer Integration Edition, Eclipse, and VisualAge for Java.

06 December 2006

Also available in Chinese

From the IBM WebSphere Developer Technical Journal.


In the previous articles we looked at each of the service-oriented component types that you can build with WebSphere Integration Developer, including business state machines, business processes, and human tasks. We toured the overall programming model and various supporting tools, such as visual snippets and mapping. We also explored the on-demand capabilities that WebSphere Integration Developer provides, such as how using business rules helps you make your running application dynamic and flexible so that you can handle changing business conditions without having to redeploy the application.

Simply put, you identify your key business decisions, create a business rule for the decision, and ultimately make it configurable at runtime. For example, if the client is one of your best, perhaps you want to give him or her a 20% discount. Maybe, on a particularly grumpy day, you want to lower that discount to 10%. Business rules in WebSphere Integration Developer make it easy to be grumpy, or adjust other, more pressing business needs.

The next piece of the on-demand puzzle is the selector.

What is a selector?

A selector is a dispatch pattern you use to dynamically determine which implementation of a component to invoke at runtime. Like a rule group, a selector has date range entries, selection criteria, and a default destination. You select a destination in a selector the same as your would for a rule group. That is, when a selector is invoked, it selects a destination using the selection criteria and date range entries. A destination could be any service-oriented component.

One major difference between a selector and a rule group is that the destination of a selector can be any service component, while a destination in a rule group can be only a rule set or decision table. In other words, a selector can dynamically re-route a service call to any other component at runtime.

You can call a selector from any of your service-oriented components. The selector’s job is to use dynamic information to determine which component should be called to do the work. The set of destination components is also configurable, allowing you to provide additional destinations at runtime. For example, imagine that at the start of the new year (after all the confetti has been cleaned up) you want to switch your application over to a new subsystem for inventory management. A selector allows you to provide two destinations and indicate that the new one takes effect on January 1.

Let’s take the following business process shown in Figure 1 as an example. This business process is for approving a loan application and has only two steps:

Step 1: Invoke a service to check for the credit rating.

Step 2: Invoke another service to determine if the loan should be approved.

Figure 1: Business process calling a partner service
Business process calling a partner service

The two invoke activities are hard-wired to target implementations in the assembly diagram. Let’s say the business process invokes the low cost credit-checking service that Company A provides. What happens if the service that Company A provides becomes unavailable during a certain period?

Such a situation is where selectors can help. As mentioned, selectors can decide which implementation to invoke. In the next section, you will see how using selectors can let you change the destination of the service call from Company A to another company's service which costs more, but is available 24x7.

Using a selector for simple dispatch

A basic use of a selector is for simple dispatch, which means you can dynamically reroute the destination of a service call from one component or import to another. Let’s make the Invoke Credit Checking Service activity in the business process now call a selector instead of being statically wired to the Company A service. It would look like the following:

Figure 2: Using a selector for simple dispatch
Using a selector for simple dispatch

The Invoke Credit Checking Service activity calls a selector that will decide at runtime which implementation to invoke. The selector uses a selection criterion to choose a destination that is the desired service implementation to invoke. The selection criterion could either be a current date, an XPath expression that gets a date from a business object, or a Java snippet that returns a date. Just like rule groups, each destination has an entry that specifies a range of dates in which this destination would be applicable. If the date returned from the selection criterion is within the boundary of the date range entry, then the selector will use the corresponding destination.

The date range entries are optional. If, in fact, no date range entry is supplied or if no date matches the selection criterion, the default destination will be invoked. Keep in mind that if you do not specify a default destination and no date range entry matches the selection criterion, then an exception will be thrown. Therefore, it is best to provide a default destination.

In Figure 2, the selector chooses the service implementation that Company B provides if the selection criterion is a date in October 2006. The selector will run the service that Company C provides if the selection criterion is a date in November 2006. For all other situations, the selector runs the service that Company A provides.

Figure 3: Using a selector to call a component in the same module or an export in a different module
Using a selector to call a component in the same module or an export in a different module

The destination of a selector can be a component inside the assembly diagram of the same module or an export of another module. For example, Figure 3 shows the LoanProcess component wired to the CreditCheckSelector. The selector can route service calls to either the CreditCheck component in Module A or the Module_B_Export in Module B.

Keep in mind that the interface operations of the selector must match all of the interface operations of the destinations. In other words, you may not select a destination that has an interface with a different operation name, input, or output than the selector itself. If you try to use a selector where the operation name does not match, then you get a ServiceRuntimeException saying the operation name cannot be resolved. If the input or output does not match (for example, if the destination interface has a different input name or a different input type), then you get a SelectorException saying the component does not support the operation.

If you cannot match the interface of the selector with the interfaces of the destinations, you can use a selector with an interface map, which we described in the seventh article in this series, to convert from one interface to another by using the interface map as a destination in the selector. Then the selector can invoke the interface map that, in turn, calls the actual service implementation.

For example, Figure 4 shows a selector that can choose from two Web service imports, each having a different interface. To reconcile the differences between each interface, the selector sets the corresponding interface maps as destinations, rather than setting the imports as destinations. Then the LoanApplicationProcess component can make credit-check service calls using the CreditCheck interface without worrying about which import will be used, or the interface of the import.

Figure 4: Using interface maps with selectors
Using interface maps with selectors

We have covered how you can use a selector in a simple dispatch scenario. What if your company were to terminate the contract with Company A and replace it with a contract with Company B? Selectors can also help in this situation.

Altering existing destinations or adding new destinations

You can update or modify the destinations of a selector and their corresponding date ranges at runtime without redeploying the original application. This means that in the previous example, you would not have to redeploy the business process to modify the components you want to dispatch to through the selector.

Using the WebSphere Process Server administrative console, you can replace an existing service implementation with another one, add a new destination with complete date range information, or remove a destination.

Figure 5 shows an example of the actions that you can perform through the administrative console at runtime, including

  • Replace an existing component (Company Z as the new default)
  • Change the date range (Company B moves to December)
  • Add a new component (Company X in October)
Figure 5: Using a selector to dynamically alter destinations
Using a selector to dynamically alter destinations

After updating the selector in the runtime, you can optionally export the changes back to the development workbench using the export function in the administrative console. The export function exports the module project that contains the selector into a project interchange file, which you can then import into the WebSphere Integration Developer workbench.

Later in the article, you will try this out by creating a selector that performs a simple dispatch. Then you will update the destination of the selector using the administrative console. After that, you will deploy a new module project and use the selector to invoke a service in the new module.

Creating a selector

This section describes the high-level steps involved in creating a selector. In the next section, you will get a chance to actually build one yourself.

Creating a selector is similar to creating any other component in WebSphere Integration Developer. You start by choosing the interface that your selector will support. Often, you choose the interface based on the destinations that the selector dispatches to. Remember, the interface operations of your selector must match exactly the interface operations of the destinations. This includes the parameters, whose types must match exactly.

When you first create a selector, it opens in a graphical editor, as Figure 6 shows, in which you can specify more information.

Figure 6: Creating a selector
Creating a selector

The first thing that you do is decide which of the following three selection criteria to use:

  • Current date
  • XPath expression
  • Visual snippet or Java expression.

If you choose the current date criteria, then the selector selects a destination when the current date falls within the start date and end date of the destination. If you choose the XPath criteria, then you need to further specify the XPath expression that returns a date from the input variable. If you choose the Java expression criteria, you need to provide the Java code, which can be a visual snippet, that returns a Date object from the input variable.

After you decide which selection criteria to use, you can add destinations. Figure 7 shows the selection of a default destination. As previously mentioned, it is a good practice to always supply a default destination. When you click the default destination cell, it displays a list of available destinations to choose from. The list includes the components in the same module or exports from other modules.

Figure 7: Selecting a default destination
Selecting a default destination

The last step is to provide destinations that apply only to a specific date range. Optionally, you can leave this section empty during development and modify it in the administrative console after deployment. You can also alter the default destination at runtime.

After adding a date selection entry, you can select the destination from the list of available destinations, as Figure 8 shows. There is no limit to how many rows you can add to the date selection table.

Figure 8: Adding additional destinations
Adding additional destinations

Unlike other components on the assembly diagram, you don’t wire selectors to other components or imports. Because the destinations in the selector are not statically bound, and because they might have destinations in other modules, there is no need to wire the selector to any component.

Putting it all together

We’ve covered the theory, now it's time to learn how to build a selector. In this section, you add a selector to an existing application. As Figure 9 shows, the application consists of a loan processing module that calls a credit-check service. We provide the skeleton of the application in the download file, complete with the interfaces and business objects you need, so that you can focus on the material covered in this article. The existing application invokes a static service implementation, so you will make the application more flexible by introducing a selector.

After you download and import the application into the workbench, you see four modules and one library. The LoanProcess business process, shown in Figure 9, resides in LoanProcess_Module, which makes a static call to the Company A service. The other modules are destinations for the selector you will create.

Figure 9: The existing LoanProcess module
The existing LoanProcess module

In the first section of the exercise, you remove the static wire, which allows service calls to Company A, and replace it with a selector that will route calls to Company A, B, or C based on an XPath selection criteria, as shown in Figure 10:

Figure 10: The updated LoanProcess module
The updated LoanProcess module

In the second section of the exercise, you explore the selector features in the administrative console. You learn how to replace an existing destination and add a new destination without needing to redeploy the original LoanProcess application.


Before you start the exercise, you need to download and import the project interchange file that contains the sample application.

  1. Download the file from the Downloads section at the end of this article.
  2. In the workbench, select File - Import - Project Interchange, and then click Next.
  3. Browse to the file that you just downloaded, and then click Open.
  4. Check Select All, and then click Finish. The imported modules open in the Business Integration view and, as the modules build, you see a Building workspace message in the lower right corner of the workbench. Wait for the workspace to finish building.

Exercise 1: Simple dispatch using a selector

In exercise 1, you will create a selector that has one default destination and two date range destinations. Then you will change the invoke activity in the LoanProcess business process that originally invoked the CompanyA import to invoke the newly created selector instead. Finally, you will deploy and run the application.

Create a new module for the selector

In this step, you create a new module for the selector. The interface used in the module already exists in the CommonLibrary.

  1. In the Business Integration view, right-click and select New - Module. Name it SelectorModule, and then click Finish.
  2. Double-click the SelectorModule that you just created. The dependency editor opens so that you can specify which libraries you want to include with your module.
  3. Click Add, select CommonLibrary from the list, and then click OK.
  4. Save the dependency editor, and then close it.

Create a selector

The interface that the selector uses is already in the CommonLibrary. The interface has one operation, checkCredit, and an input and output of type LoanData, as Figure 11 shows:

Figure 11: The selector interface
The selector interface
  1. In the Business Integration view, expand SelectorModule. Under Business Logic, right-click Selectors, and then select New - Selector.
  2. For the name of the new selector, enter CreditSelector, and then click Next.
  3. Select SelectorInterface from the interface list.
  4. Click Finish. The selector editor opens.

Now, you can define the selector so that the service call gets routed to the correct component. In the next steps, you specify the selection criteria, which is the value of the applyDate variable:

  1. In the selector editor, select checkCredit in the Interfaces section on the left panel.
  2. In the Selection Criteria cell, click Current date, and then select XPath from the list of available selection criteria.
  3. In the Parameter cell, click Enter Parameter, and then select input1 from the list of available parameters (there is only one in this example).
  4. In the XPath cell, click Enter Parameter, and then select applyDate as the XPath expression.

The selection criteria should now appear as it does in Figure 12. In the following steps, you specify the destinations to be used, depending on the value of the applyDate XPath as specified in the previous steps.

  1. In the Default Destination cell, click Enter SCA Destination and select Company_A_Component_Export from the list of destinations.
  2. To add a date selection entry, click the Add Date Selection Entry button (Add Date Selection Entry button). The destination list displays s new destination.
  3. Change the Start Date of the destination to Oct 1, 2006 and the End Date to Oct 31, 2006. Note that you can type the date or you can click the date selection button (Calendar icon) to the left of the cell to select a date from the calendar.
  4. Click Enter SCA Destination, and select Company_B_ComponentRG_Export.
  5. Following the same steps you just followed, create another destination with a Start Date of Nov 1, 2006 and an End Date of Nov 30, 2006. For the destination, select Company_C_ComponentExport.
  6. Save the file. The final selector should appear as it does in Figure 12.
Figure 12: The selector definition
The selector definition

Add the selector to the assembly diagram

To use the selector you just created, you need to add it to the assembly diagram of the selector module. Then, to make the selector available to other modules, you need to create an export. You give the export an SCA binding because only other modules of your application will invoke it, not external clients.

  1. Open the SelectorModule assembly diagram by expanding SelectorModule and double-clicking SelectorModule in the Business Integration view.
  2. Drag CreditSelector from the BusinessLogic - Selectors category in the Business Integration view to the assembly diagram.
  3. Right-click the CreditSelector component in the assembly diagram, and select Export - SCA Binding.
  4. Save the assembly diagram contents.
Figure 13: The selector module
The selector module

Examine and prepare the existing LoanProcess

When you open the assembly diagram of the LoanProcess_Module in the steps below, you will see that the LoanProcess is wired to an import that connects to Company A’s export through an SCA binding. If you open the LoanProcess business process (double-click it) and select the Invoke Credit Checking Service invoke activity, you see that the invoke activity contains a partner link with Company A’s interface.

In this section, you make the application more flexible by modifying the invoke activity of the business process so that it calls the selector, rather than a specific component.

  1. Open the LoanProcess_Module assembly editor by expanding LoanProcess_Module and double-clicking LoanProcess_module.
  2. Open the LoanProcess business process by double-clicking the LoanProcess component in the LoanProcess_Module assembly diagram.
  3. On the right palette, select Partner, and then switch to the Properties view and select the Details tab.
  4. Click Browse, select SelectorInterface from the list of interfaces, and then click OK.
  5. In the business process editor, select the Invoke Credit Checking Service activity, and then, in the Details tab of the Properties view, select checkCredit for the operation.
  6. Set the input1 and output1 variables to Input1 and Output1, respectively. Your business process should now look like Figure 14:
  7. Save the file.
Figure 14: The updated business process
The updated business process

The property details for the Invoke Credit Checking Service should now appear as they do in Figure 14. Notice that there is a red ‘x’ in the Business Integration view next to the LoanProcess_Module. Because you changed the partner interface in the business process, you need to change the corresponding component reference in the assembly editor by following these steps:

  1. Open the LoanProcess_Module assembly diagram, and then select the component reference of the LoanProcess component.
    (Tip: The component reference will also have a red ‘x’ until you complete these steps.) Figure 15 shows the reference being selected.
    Figure 15: The LoanProcess_Module assembly diagram
    The LoanProcess_Module assembly diagram
  2. In the Details tab of the Properties view, expand References - Partner - CompanyA_Interface.
  3. Next to Interface, click Change and select SelectorInterface from the list of interfaces.
    Tip: The previous interface might be selected as the filter in the Change Interface dialog box, so you might need to clear that from the filter to see the other interfaces in the list.
  4. Delete the wire from the LoanProcess reference to CompanyA_Component_Import.
  5. Right-click LoanProcess and select Wire References to New - Imports. A Partner import is created.
  6. Right-click the Partner import and select Generate Binding - SCA Binding.
  7. In the Binding tab of the Properties view for the Partner import, click Browse and select CreditSelectorExport.
  8. Click OK and the save the assembly diagram.

Because the component reference and the process partner match, the error markers disappear. Your module assembly will appear as it does in Figure 15. Now you are ready to test your new selector.

Testing the selector

In this step, you use the integration test client to invoke the checkCredit operation of the LoanProcess component. The test client starts the server if necessary, and deploys the modules to the server. But first, let’s step back a bit and investigate more features of the test client that are handy here.

Typically, you would test a module by right-clicking the module in the Business Integration view, or by right-clicking the module assembly diagram and selecting Test Module. However, in this case the module we're testing is going to make service calls to other modules,so the other modules must be deployed to the server first.

You can right-click your server in the Servers view and use the Add and remove projects menu to select which modules to deploy. You can also control which modules to deploy using the test client. Use the test client to deploy when you want to emulate or monitor service calls in the other modules. To do so, in the Business Integration view, select each of the modules you want to test (hold down Ctrl as you select each module), then right-click any selected module and select Test - Test Module. Now when you start a test, it deploys each selected module to the server and monitors service calls as other modules are invoked. You also see each module in the Configurations tab of the test client, which means that you can add emulators or enable or disable monitors.

Let’s get on with testing now:

  1. Hold down Ctrl and select Company_A_Module, Company_B_Module, Company_C_Module, LoanProcess_Module, and SelectorModule, as Figure 16 shows.
    Figure 16: Modules to be tested
    Modules to be tested
  2. Right-click a selected module and select Test - Test Module.
  3. In the test client that opens, ensure LoanProcess_Module is selected for the module, and that LoanProcess is selected for the Component, as Figure 17 shows:
    Figure 17: Testing the LoanProcess component
    Testing the LoanProcess component
  4. Enter 2006-10-09 for applyDate, anything for name, and 800000 for amount.
  5. Click Continue, and then in the Deployment Location dialog that opens, click Finish.
  6. Wait for the server to start and for the modules to deploy.

The selector uses applyDate to decide which component to run. Because the date is within the start and end dates that you specified (Oct 1, 2006 and Oct 31, 2006), the Company_B_Component is called.

Figure 18: Testing results
Testing results

Now let’s try a different date. How about 2006-11-9? In this case, the selector calls Company C’s service.

Exercise 2: Altering and adding destinations

Suppose that your business environment has evolved and you need to change the default destination for CreditSelector. In exercise 2, you use the administrative console to alter the default destination of the selector. After you commit the change, you test the LoanProcess again.

Modify the existing destination

  1. You can change selector criteria using the administrative console. In the Servers view, right-click the server and select Run administrative console.
  2. In the Log in page, you have to specify a user name to change anything in the selector, even if you have not enabled security. Type any user name and log in.
  3. In the navigation section, expand Servers, click Application servers, and then click server1.
  4. In the server1 editor page, scroll down to the Business Integration section and click the Selectors link, as shown in Figure 19:
Figure 19: Changing selector properties at runtime
Changing selector properties at runtime
  1. In the Selectors page, you see all the selectors currently in the system. Click CreditSelector, shown in Figure 20, which is the one that you created earlier:
    Figure 20: Selecting CreditSelector
    Selecting CreditSelector
  2. Click the checkCredit link. You see the date entry for this selector, as Figure 21 shows:
    Figure 21: Properties for CreditSelector
    Properties for CreditSelector
  3. To modify the selector, click the default link.
  4. In the Target Components list, select Exported Target: Company_B_Module Company_B_ComponentRG_Export and click OK.
    Figure 22: Changing the default destination for the selector
    Changing the default destination for the selector
  5. To commit the change, select the check box next to the default selector, and then click Commit. You see a message at the top of the administrative console reminding you to select commit to make the changes take effect.

Now let’s run the LoanProcess again. To invoke the default destination, use an applyDate of 2002-01-01. As Figure 23 shows, you will see that the service from Company B is invoked.

Figure 23: Testing the default destination change
Testing the default destination change

Add a new destination

Now let’s suppose that your business environment has evolved further and you need to change the default destination from Company A to Company X. However, you haven’t deployed the module for Company X to the server. In this step, you deploy a new module, Company X, to the server, and then use the administrative console to specify when this new module should be used as the destination. After you commit the change, you will test the LoanProcess again.

  1. Right-click the server and select Add and remove projects.
  2. In the Add and Remove Projects dialog box, select Company_X_ModuleApp from the list of available projects, and then click Add.
  3. Click Finish and wait for the module to deploy.
  4. Following the steps in the previous section, navigate to CreditSelector in the administrative console, and then click checkCredit.
  5. To create a new date selection entry, click New.
  6. Modify the start date to December 1, 2006 and end date to December 31, 2006.
  7. Change the Target Components to Exported Target: Company_X_Module CompanyX_Component_Export.
  8. The form should now look like Figure 24. Click OK.
    Figure 24: Adding a new destination
    Adding a new destination
  9. Select the checkbox beside the first date entry, and click Commit, as Figure 25 shows:
    Figure 25: Committing a new selector destination
    Committing a new selector destination

If you run LoanProcess again, this time using an applyDate of 2006-12-03, you will see the result shown in Figure 26.

Figure 26: Results of a new destination being selected
Results of a new destination being selected


This concludes the Guided Tour of WebSphere Integration Developer series. Throughout the series, we showed you how to get up and running by covering the basic concepts, namely the programming model, business objects, interfaces, components, and references. We also introduced you to each of the various component implementation types that WebSphere Integration Developer provides, namely business state machines, business processes, and human tasks. Plus, we looked at the various supporting tools, such as interface maps and visual snippets. We hope that this series has helped you understand how to use the tooling, and that you are now on your way to developing your own applications to make your business more on-demand.

The authors would like to thank Stephanie Parkin, Laura Gardash, Catherine Hamilton, and Donna Sutarno for their invaluable help with this series.


MappingExample module with artifacts and  ( HTTP | FTP )73 KB
Complete MappingExample  ( HTTP | FTP )85 KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Business process management on developerWorks

Zone=Business process management, WebSphere, SOA and web services
ArticleTitle= IBM WebSphere Developer Technical Journal : A guided tour of WebSphere Integration Developer -- Part 8