In Part 1 of this two-part article, you learned the features and architecture of a social-media search application that leverages Bonita, an open source BPM engine. You began to build the application by:
- In Bonita, configuring the
TwitterSearchConnectorconnector, which allows a business process to connect to Twitter.
- Using Bonita to generate a template for the
TwitterSearchConnectorclass, which wraps the connect-to-Twitter functionality.
- Editing the
TwitterSearchConnectorclass manually to let it use Twitter4J — an open source Java library for working with the Twitter API.
- Testing the
TwitterSearchConnectorclass in stand-alone mode.
If you didn't perform all the configuration steps for
TwitterSearchConnector in Part 1, you can simply import the TwitterSearchConnector.jar file from this article's source-code download into your Bonita installation. From Bonita's Connectors menu, choose the Import connector option. Browse to the TwitterSearchConnector.jar file and click Open to display
TwitterSearchConnector's complete Java code — including the manually edited portion shown in Part 1— in Bonita's editor.
Here in Part 2, you'll learn about all the activities, forms, and variables that the application uses, and you'll configure the application's business process. You'll attach
TwitterSearchConnector to the business process and test the application by running it in Bonita and doing a keyword search for Twitter messages. You'll then enhance the application by configuring it to display the profile of the Twitter user associated with a selected search result, and then to add the profile data to a CRM system.
The search application's business process
This article's source-code download includes a file named SocialMediaSearchApplication_ProcessFormsAndVariables_1.0.proc. It contains all the process definitions, forms, and variables that are required for configuring the search application. (You can refer to "Bonita for business process management" for detailed information on configuring processes, forms, and variables in Bonita.) You just need to import the SocialMediaSearchApplication_ProcessFormsAndVariables_1.0.proc file into your Bonita installation. Click Import from Bonita's main toolbar, then browse to the SocialMediaSearchApplication_ProcessFormsAndVariables_1.0.proc file, as shown in Figure 1:
Figure 1. Importing the application's process definitions
Click Finish. The search application's process opens in the Bonita editor window's whiteboard, as shown in Figure 2:
Figure 2. Process definition for the search application
You can see in Figure 2 that the process definition contains six boxes, each of which is an activity of the search application. If you click on any activity, its properties appear below the whiteboard in the lower-right window with four tabs: General, Application, Appearance, and Simulation.
The left-most box in Figure 2 is labeled Present the search page. This activity displays a simple search page — the Search Tweets form (Figure 1 in Part 1), where the user enters a search keyword. I have configured one process variable, named
searchKeyWord, to hold the search keyword that the user enters. You can see the
searchKeyWord variable (among other variables) by clicking anywhere on the whiteboard outside the six activity boxes, then selecting the General tab from the lower-right window, and finally selecting the Data tab, as shown in Figure 3:
searchKeyWord selected from among the application's process variables
The second box from the left in Figure 2 is labeled Search messages on Twitter. In this article's next section, you'll configure
TwitterSearchConnector to connect with this activity.
TwitterSearchConnector receives the search keyword from the Search Tweets form and sends the keyword to the Twitter web service. A variable named
tweetsFound holds the search results returned by
The third activity in Figure 2 (Display Twitter messages) displays search results (tweets found) to the user, as shown in Figure 2 in Part 1. As you know from Part 1, in the finished application the user will be able to select any message and click a button to see the profile of the Twitter user who sent it.
The next activity (Fetch profile of Twitter user) uses another Bonita connector that you will configure later in this article (
TwitterUserProfileConnector, as shown in Figure 5 in Part 1).
TwitterUserProfileConnector connects to Twitter to fetch the profile of the Twitter user. It takes five inputs: the two pairs of security keys you obtained in Part 1 for logging into the Twitter web service, and a variable named
twitterUserName, which specifies the name of the Twitter user whose profile is to be fetched.
TwitterUserProfileConnector returns seven parameters about the Twitter user: name, location, language, profile image, the user's website URL, number of Twitter followers, and description, each of which you'll map to a process variable.
The fifth activity (Display Twitter user profile) presents the profile of the Twitter user in the User Profile form (Figure 3 in Part 1). The profile contains the seven attributes of the Twitter user. The User Profile form also allows users to click a button to add the Twitter user to SugarCRM as a new account.
The last activity (the right-most box in Figure 2, labeled Add profile to SugarCRM), adds the Twitter user to SugarCRM. To implement this functionality, you will attach a connector called
Create Sugar Account (which comes bundled with Bonita) to the Add profile to SugarCRM activity.
TwitterSearchConnector to the business process
Now you are ready to configure
TwitterSearchConnector to attach to the application's business process. You'll connect it to the Search messages on Twitter activity.
Click on the Search messages on Twitter activity in the process whiteboard to display its properties in the lower-right window. Click on the General tab's Connectors tab, circled in blue in Figure 4:
Figure 4. Connectors tab for the Search messages on Twitter activity
The Connectors tab shows the connectors associated with the activity. Currently, no connectors are associated. Click the Add button (circled red in Figure 4). The Select a connector dialog opens, showing the list of connectors available for you to configure with the activity.
You can see connectors for many popular applications, such as Jasper and SugarCRM, arranged in categories. You specified the Social category for
TwitterSearchConnector when configuring it in Part 1. Expand the Social category and select
TwitterSearchConnector, as shown in Figure 5:
Figure 5. Selecting
TwitterSearchConnector in the Social category
Next, you'll perform the following steps to attach
TwitterSearchConnector to the Search messages on Twitter activity:
- Provide descriptive information
TwitterSearchConnector's role in the
Search messages on Twitteractivity.
- Provide security credentials (the two pairs of keys) to
- Pass the search keyword from the Search Tweets form on to
- Configure the
tweetsFoundvariable to receive search results from
Providing descriptive information
Click the Next button on the Select a connector dialog. A Name the connector dialog appears, as shown in Figure 6:
Figure 6. Name the connector dialog
Fill in the following fields in the Name the connector dialog:
- Name: Enter
Connection of the search application with Twitter.
- Description: Enter
Pass the search keyword to TwitterSearchConnector and fetch Twitter data.
- Select event: In this field, you specify exactly when to invoke
TwitterSearchConnector— that is, at either the start or the end of the activity. Keep the default value. (Because you want to associate only one task with the activity, it doesn't matter whether
TwitterSearchConnectoris invoked at the start or the end.)
- If connector fails: In this field, you specify what the Search messages on Twitter activity should do if
TwitterSearchConnectorfails. This field allows you to build fail-safe applications in Bonita. Failure-safety is beyond this article's scope, so just keep the field's default value.
The Name the connector dialog should now look like Figure 7:
Figure 7. Completed Name the connector dialog
Click Next. The Twitter Search Connector Input Parameters Page now appears.
Providing security keys to
As you can see in Figure 8, you to need to enter the two pairs of keys (consumer key, consumer secret, access token, and access token secret) that you obtained in Part 1:
Figure 8. Configuration dialog for entering security information
Figure 8 also includes a field labeled SearchKeyword.
This article's source code download contains a file named SecurityKeyValues.txt, in which I have copied the keys that I got from Twitter in Part 1. If you did not obtain your own security keys, you can copy the values from that file into the configuration dialog. Leave the SearchKeyword field blank for now. With the security data entered, the dialog should look like Figure 9:
Figure 9. Configuration dialog after security data is entered
In Figure 9, the contents of the security-key fields are obfuscated, and the SearchKeyword field remains blank.
Passing the search keyword to
The search keyword can change every time you run the application, so you can't enter its value directly in the SearchKeyword field. That's why the search keyword is stored in the
searchKeyWord variable (see The search application's business process). Select
searchKeyWord from the drop-down list to pass this variable as the fifth input to
TwitterSearchConnector, as shown in Figure 10:
Figure 10. Selecting
searchKeyWord from the drop-down list
tweetsFound variable to receive the output of
Click the Next button. A new dialog now asks you to map the outputs of the connector to process variables. There you'll tell the process which variable should store the list of messages that
TwitterSearchConnector finds on Twitter for you. Recall from the discussion accompanying Figure 2 that a variable named
tweetsFound will hold the tweets that
TwitterSearchConnector finds for the user.
TwitterSearchConnector has just one output, named
searchResults (as you know from Listing 2 in Part 1). It contains the Twitter messages that
TwitterSearchConnector finds. You can see
searchResults in the Connector output drop-down list in the left side of Figure 11:
Figure 11. Mapping the connector output to a process variable
searchResults selected and assign its value to the
tweetsFound variable in the Destination variable drop-down list. As a result of this mapping, the contents of the
searchResults (messages found on Twitter) will be copied into the
tweetsFound process variable.
Click Finish. The TwitterSearchApplication_CompleteWithTwitterSearchConnector _2.0.proc file in the source code download reflects everything you have done so far.
Displaying messages found on Twitter
You have configured the first two boxes in Figure 2 (Present the search page and Search messages on Twitter). Your next task is to configure the third activity: Display Twitter messages.
The Display Twitter messages activity is just a form in which you use the
tweetsFound process variable to display the messages found on Twitter. The source code download includes a file named
TwitterSearchApplication_CompleteWithTwitterMessageDisplay_3.0.proc, which contains all the configurations for using the
tweetsFound process variable. (You can refer to "Bonita for business process management" for details on designing forms using variables.) Import the TwitterSearchApplication_CompleteWithTwitterMessageDisplay_3.0.proc file into Bonita now.
Running the search application
Now you can try your search application for the first time. Click the Run button in Bonita's main toolbar, as shown in Figure 12:
Figure 12. The Run button in Bonita's toolbar
Wait until the Search Tweets form appears in a browser window, as shown in Figure 13:
Figure 13. The Search Tweets form
Enter a keyword that you want to search for on Twitter and click the Search button. The search application displays messages found on Twitter in its second form, as shown in Figure 14:
Figure 14. Messages found on Twitter
The search application works only this far for the moment, because you haven't yet configured the rest of the activities.
Configuring and attaching
The next task is to configure the fourth activity in Figure 2
(Fetch profile of Twitter user). This activity requires another Twitter connector, named
TwitterUserProfileConnector, which is similar to
TwitterSearchConnector. Referring to the steps you performed for
TwitterSearchConnector, implement and configure
- Use the Connector creation wizard to create
TwitterUserProfileConnectorand provide descriptive information about it.
- Configure five input parameters: two pairs of keys as security credentials for logging
onto the Twitter web service and the
twitterUserNameprocess variable, which contains the name of the Twitter user whose profile is to be fetched.
- Configure seven output parameters: name, location, language, path to profile image, website URL, number of Twitter followers of the user, and description.
- Map the output parameters to the
profileDescriptionprocess variables, respectively.
- Manually edit the source code of the
TwitterUserProfileConnectorJava class using the Twitter4J library.
searchUsers()method of the
Twitter.search()method that you manually used in step 4 of Listing 4 in Part 1. The
searchUsers()method returns detailed profile information about a Twitter user.
TwitterUserProfileConnectorto attach to the Fetch profile of Twitter user activity.
I have already demonstrated and discussed the preceding steps in detail for the
TwitterSearchConnector, so I won't repeat the whole discussion for
TwitterUserProfileConnector. Similarly, I won't demonstrate configuration of the fifth activity (Display Twitter User Profile, which displays the user profile), because it is just a form. The TwitterSearchApplication_CompleteWithProfileConnectorAndDisplay_4.0.proc file in the source code download contains all configurations for the business process's five activities. You can import and run the TwitterSearchApplication_CompleteWithProfileConnectorAndDisplay_4.0.proc file in Bonita to see that all the three forms discussed at the beginning of Part 1 are now fully functional.
Interfacing SugarCRM with Bonita
Only the last activity of Figure 2 (Add profile to SugarCRM) remains to be configured. In this activity, you'll use a Bonita connector named
Create Sugar Account, which talks to SugarCRM through a web service API (just as
TwitterSearchConnector talks to Twitter through Twitter's web service API).
Create Sugar Account connector comes bundled with Bonita and internally handles all communications with SugarCRM. So you just need to attach the
Create Sugar Account connector to your
Add profile to SugarCRM activity.
Before proceeding, you should have SugarCRM installed either on your machine or somewhere over the network. (see Resources for details on installing SugarCRM). SugarCRM Community Edition version 6.1.6 (Build 5860) was installed on my machine when I developed the search application.
Click on the Add profile to SugarCRM activity to display its properties in the lower-right window. Select the General tab, then select the Connectors tab and click the Add button. The Select a connector dialog (see Figure 5) appears. Expand the SugarCRM category and select the
Create Sugar Account connector, as shown in Figure 15:
Figure 15. Selecting the
Create Sugar Account connector
Click the Next button. A Name the connector dialog (see Figure 6) appears. Enter
Twitter to Sugar connection and
Create a new SugarCRM account using the Twitter user as values of the Name and Description fields, respectively. Leave the other fields at their default values. The Name the connector dialog should now look like Figure 16:
Figure 16. The Name the connector dialog for the
Create Sugar Account connector
Click Next. Now Bonita presents the SugarCRM Configuration dialog asking for information about your SugarCRM service, as shown in Figure 17:
Figure 17. Dialog asking information about your SugarCRM installation
You can see from Figure 17 that you need to fill in four fields:
- Sugar SOAP Port: Enter the URL of the SOAP server where SugarCRM is listening. (See Resources to learn more about the SOAP service of SugarCRM.) The SOAP server on my machine was running at http://127.0.0.1:8080/sugarcrm/service/v2/soap.php (the value shown in Figure 17) when I tried the search application with SugarCRM.
- User and Password: Enter the username and password that you use to log on to your SugarCRM installation.
- Application name: Enter
Twitter user accountas the name of the application connecting to SugarCRM.
Click Next. Next you get a Parameters dialog asking for input parameters, as shown in Figure 18:
Figure 18. Input parameters for the
Create Sugar Account connector
You can see from Figure 18 that the
Create Sugar Account connector is asking for three parameters — Account name, Phone number, and Website — through drop-down lists to create an account. The Twitter user profile that you got through
TwitterUserProfileConnector does not contain the phone number of the Twitter user, so you cannot provide this parameter. I have mapped the other two parameters, which are available, to
profileWebSiteURL process variables, respectively. Select these values from the drop-down lists, as shown in Figure 19:
Figure 19. Input parameters for the
Create Sugar Account connector
Click Next. The next dialog asks you to map connector output to a process variable. The search application does nothing with the output of the
Create Sugar Account connector, so leave this dialog unchanged and click Finish. Save your application.
Start your SugarCRM server and then run the completed search application, going through all its three forms. Click the Add to CRM button on the User Profile form. You can see that the Twitter user whose profile is displayed on the User Profile form is added to SugarCRM as a new account.
You have seen how Bonita uses its connector framework to integrate your business process with external applications through web services. You've built your own connectors (
TwitterUserProfileConnector) and used a connector (
Create Sugar Account) that's bundled with Bonita. With the techniques you've learned in this two-part article, you can bring social-networking data into your business process from other popular applications such as Facebook.
- developerWorks BPM zone: IBM business process management provides the tools you need to model, simulate, execute, adapt, monitor, and optimize your business processes.
- Business Process Management from IBM: BPM software and services from IBM help organizations optimize business performance by discovering, documenting, automating, and continuously improving business processes to increase efficiency and reduce costs.
- IBM Business Process Management Journal: Learn more about IBM's comprehensive BPM platform.
- Bonita Open Solution: Visit the Bonita website.
- SugarCRM documentation: Get installation and application guides for SugarCRM.
- SugarCRM web services: Learn the Web services and SOAP features of SugarCRM.
- "Bonita for business process management, Part 1: Configure a simple workflow" (Bilal Siddiqui, developerWorks, October 2010) and "Bonita for business process management, Part 2: Configure forms and variables" (Bilal Siddiqui, developerWorks, November 2010): Read about configuring business processes and designing forms in Bonita.
Get products and technologies
- IBM BPM in action exercise: Model and run business processes in a visual, code-free environment.
- Bonita Open Solution: Download Bonita.
- SugarCRM: Download SugarCRM.
- Twitter4J: Download Twitter4J.
- Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.
- IBM Business Process Manager forum: Join the discussion in the developerWorks community.
- Get involved in the developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.