1. No category

Bonita Open Solution
Version 5.1
How to…
Create a Connector
Version1.0
Bonita Open Solution 5.1 How to
Bonita Open Solution V5.1
How to...Create a Connector
Contents
Part 1.
Overview ................................................................................................................................. 4
Part 2
Design the Connector ............................................................................................................. 4
2.1
What will the Connector do? .................................................................................................. 4
2.2
Connector dependencies ........................................................................................................ 4
2.2
Design the Connector ............................................................................................................. 6
2.2.1
Define the Connector wizard .......................................................................................... 6
2.2.2
Enter the Connector code ............................................................................................. 11
Part 3
Design the Process ................................................................................................................ 14
3.1
Define the Process ................................................................................................................ 14
3.2
Define Data variables ............................................................................................................ 15
3.3
Define the new Connector to work with this Process .......................................................... 16
3.4
Create Forms ......................................................................................................................... 18
3.4.1
Add a Form to the RSS Feed Step.................................................................................. 18
3.4.2
Add a Form to the Read results Step ............................................................................ 20
Part 4.
Run the Process..................................................................................................................... 23
Figures
Figure 1. Open Bonita Studio ................................................................................................................. 5
Figure 2. Select Manage jars to upload dependencies .......................................................................... 5
Figure 3. Add dependency files to your BOS jars ................................................................................... 6
Figure 4. Activate jar files ....................................................................................................................... 6
Figure 5. Create a new Connector ......................................................................................................... 7
Figure 6. Set the description of your Connector .................................................................................... 7
Figure 7. Enter the description and parameters for the Connector ...................................................... 8
Figure 8. Define the fields for your Connector wizard ........................................................................... 9
Figure 9. Define the input fields for the Connector wizard ................................................................... 9
Figure 10. Create the output fields for the Connector wizard ............................................................. 10
Figure 11. Define the output fields for the Connector wizard ............................................................. 10
Figure 12. Java editor for a new Connector ......................................................................................... 11
Figure 13. Connector defined in java editor ........................................................................................ 13
Figure 14. Errors are flagged by java editor ......................................................................................... 13
Figure 15. New Category and Connector appears in the Connectors list ............................................ 14
Figure 16. Draw Tutorial Process ......................................................................................................... 14
Figure 17. Add a text variable for the Connector Input ....................................................................... 15
Figure 18. Add a java object variable for the Connector output ......................................................... 16
BOS V5.1 – How To Create a Connector – 25 Mar 10
www.bonitasoft.com | © BonitaSoft S.A.
page 2
Figure 19.
Figure 20.
Figure 21.
Figure 22.
Figure 23.
Figure 24.
Figure 25.
Figure 26.
Figure 27.
Figure 28.
Figure 29.
Figure 30.
Figure 31.
Figure 33.
Figure 34.
Figure 35.
Figure 36.
Figure 37.
Global Data Added .............................................................................................................. 16
Configure Connector ........................................................................................................... 17
Select ${url} to take input .............................................................................................. 17
Map the output of the Connector to the rssResult Data variable ............................... 17
New Connector defined for RSS Feed Step ......................................................................... 18
Skip initial forms at process start ........................................................................................ 18
Create an initial Form .......................................................................................................... 19
Create Form in Form Builder ............................................................................................... 19
RSS Feed Step now has a Form ........................................................................................... 20
Create a form to display returned data .............................................................................. 20
Add a field to the form to take the returned output .......................................................... 21
Select field for Expression ................................................................................................... 21
Add Groovy script to read list output ................................................................................. 21
Output defined .................................................................................................................... 22
Increase the width of the output field ................................................................................ 22
RSS Feed form appears in Bonita User Experience ............................................................. 23
Enter a URL for an RSS feed ................................................................................................ 23
Feed results are returned.................................................................................................... 24
Bonita Open Solution
How to Create Your Own Connector
You can download this, and the general User & Reference Guide and updates, from the BonitaSoft
web site.
Part 1.
Overview
As you follow this tutorial, you will






Part 2
2.1
design a Connector wizard using java;
design a simple Process;
define global Data variables for inputs and outputs;
use your Connector wizard to add a Connector to the Process;
create input and output Forms in the Process; and
run the Process to see the results.
Design the Connector
What will the Connector do?
In this How-To, the Connector will automatically retrieve and read an RSS feed from a URL
entered by the User.
The connector you will create is the same as one which has already been developed and is
available on the BonitaSoft Community at
www.bonitasoft.org/exchange/extension_view.php?eid=2.
The java code for this connector is given in 2.2.2, Enter the Connector Code.
2.2
Connector dependencies
This connector has 2 dependencies which you will need to fetch and install in Bonita Studio.
Go to http://wiki.java.net/bin/view/Javawsxml/Rome and download to your system:


ROME v1.0+ (binary jar Rome-1.0.jar)
JDOM 1.0 (jdom-1.1.1.zip) (download and unzip to locate jdom.jar)
Open Bonita Studio.
Open a new Process.
The Whiteboard shows a start and a Step:
Figure 1. Open Bonita Studio
Go to the Task Bar and select Extensions -> Add/Remove.
Figure 2. Go to Extensions to upload dependencies
Then select Add jar and browse to where you have downloaded the dependency files.
Upload them into Bonita Studio.
Figure 3. Add dependency files to your BOS jars
To activate these dependencies in this Process, go to MyProcess -> Details -> Dependencies
and tick the checkboxes for the two jar files you have just added. (Note this can also be
done at the Diagram level.)
Figure 4. Activate jar files
2.2
Design the Connector
2.2.1
Define the Connector wizard
Go back to the Whiteboard.
Go to the Task Bar and select Connector -> New Connector.
Figure 5. Create a new Connector
The Set the description of your connector wizard appears.
Figure 6. Set the description of your Connector

Connector ID


Description
Category
The ID by which BOS recognizes this Connector; for this example use
RSSReader
what the Connector does
Select which category this Connector will appear in when you select
Add a Connector to a Step. You can put this connector into an
existing category or create your own. You will be able to add more
new Connectors to this new Category later.
In this example, create a new category called Syndication.

Icon
(Optional) The icon in the Category line will be used for the
Category. The Icon in the next line will be used for this specific

Class name

Package
Connector. If you want to use an icon, browse to where it is located
and upload it. (Recommended size: 60x 60 pixels).
The java class name; this is automatically completed to be the same
as the Connector ID. For this example, leave it as is.
The java package. For this example use:
org.bonitasoft.connectors.rssreader
Figure 7. Enter the description and parameters and upload an icon
Next you’ll specify the inputs and outputs for the Connector wizard. Select Pages -> Create
to bring up the next window.

Page ID

Page Title

Description
the ID by which BOS recognizes this Connector wizard page (for this
example use EnterURL)
this will appear at the top of the wizard (Retrieve an RSS or
Atom feed)
(Optional) this will appear below the Page Title at the top of the
wizard (Enter the destination URL)
Figure 8. Define the fields for your Connector wizard
To define the fields in this wizard, select Create. Information will appear in the widgets
fields that you can modify or keep.




Field name
Mandatory
Widget
Data Type
the name of the input data field (url)
select “mandatory” for this field
select the type of widget for this field to appear in (Text)
select the type of data field for this input (Text)
For this example, choose Text for both the Widget and the Data type. Click OK.
Figure 9. Define the input fields for the Connector wizard
Now define the output for this Connector wizard. Select Outputs -> Create and Information
will appear in the widgets fields that you can modify or keep.
Figure 10. Create the input fields for the Connector wizard

Field name

Data Type
the name of the output data field (for this example, use
itemsList)
select the type of data field for this input (Text).
Figure 11. Create the output fields for the Connector wizard
When you click Finish, the java editor appears.
Figure 12. Java editor for a new Connector
Here is where you will copy and paste existing java code to subscribe to an RSS feed – or,
where you will enter your code whenever you create a new Connector.
2.2.2
Enter the Connector code
Copy and paste the following into the java editor.
/**
* Copyright (C) 2010 BonitaSoft S.A.
* BonitaSoft, 31 rue Gustave Eiffel - 38000 Grenoble
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 2.0 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/**
* Bonita Connector to read RSS and Atom feeds.
* Dependencies :
* -ROME v1.0+ : http://wiki.java.net/bin/view/Javawsxml/Rome
* -JDOM 1.0 : http://www.jdom.org/
*
* To read the RSS feed use the Groovy script below in the edit Form
(with a list for example)
*
* @author [email protected]
*/
/*
res = new ArrayList<String>();
itemsList.each
{
res.add(it.getTitle() + " : " + it.getLink())
}
res
*/
package org.bonitasoft.connectors.rssreader;
import java.util.ArrayList;
import java.util.List;
import java.net.URL;
import
import
import
import
com.sun.syndication.feed.synd.SyndEntryImpl;
com.sun.syndication.feed.synd.SyndFeed;
com.sun.syndication.io.SyndFeedInput;
com.sun.syndication.io.XmlReader;
import org.ow2.bonita.connector.core.ConnectorError;
import org.ow2.bonita.connector.core.ProcessConnector;
public class RSSReader extends ProcessConnector {
// DO NOT REMOVE NOR RENAME THIS FIELD
private String url;
private List<SyndEntryImpl> itemsList;
@SuppressWarnings("unchecked")
@Override
protected void executeConnector() throws Exception {
URL feedUrl = new URL(this.url);
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
this.itemsList = feed.getEntries();
}
@Override
protected List<ConnectorError> validateValues() {
List<ConnectorError> errorsList = new
ArrayList<ConnectorError>();
if("".equals(url.trim())) {
ConnectorError error = new ConnectorError("url", new
IllegalArgumentException("Url is empty"));
errorsList.add(error);
}
return errorsList;
}
/**
* Setter for input argument 'url'
* DO NOT REMOVE NOR RENAME THIS SETTER, unless you also change the
related entry in the XML descriptor file
*/
public void setUrl(String url) {
this.url = url;
}
/**
* Getter for output argument 'itemsList'
* DO NOT RENAME NOR RENAME THIS GETTER, unless you also change the
related entry in the XML descriptor file
*/
public List<SyndEntryImpl> getItemsList() {
return this.itemsList;
}
}
Figure 13. Connector defined in java editor
NOTE that if there is an error in the code structure, warning notations will appear.
Figure 14. Errors are flagged by java editor
Click the X on the RSSReader.java tab to save the Connector, close the java editor and return
to the Whiteboard.
Go to Step1 -> Details -> Connectors -> Add. The list of Connectors to choose from will
appear.
The Category Syndication and the Connector RSSReader will appear in the list.
Figure 15. New Category and Connector appears in the Connectors list
Click Cancel to return to the Process and continue.
Part 3
3.1
Design the Process
Define the Process
This simple tutorial Process will have 2 Steps: Subscribe to RSS Feed and Read
results.





Add a second Step and an end to the Whiteboard.
Rename Step1 to RSS Feed.
Rename Step2 to Read results and change it to Human.
Rename MyProcessDiagram to Tutorial Example–RSS Feed.
Rename MyProcess Pool to RSS Feed.
Figure 16. Draw Tutorial Process

Define Actors to be Process Initiator for both Steps. This will allow you to interact
with each step as it is presented in the User Experience.
3.2
Define Data variables
Define two global Data variables: one to send the requested URL (input) and one to receive
the returned information from the RSS feed (output).
Go to RSSFeed (pool) -> Data -> Add.
Figure 17. Add a text variable for the Connector Input
Figure 18. Add a java object variable for the Connector output
Figure 19. Global Data Added
3.3
Define the new Connector to work with this Process
Add the new Connector to the RSS Feed Step. Go to RSS Feed -> Connectors -> Add. Select
RSSReader from the Syndication category.
Click Next to use the wizard you have created to define a new Connector of this type.




enter the name of the Connector (Fetch RSS)
enter a description for this Connector (Receive RSS from a
blog feed)
Select event when this Connector will activate (on finish)
If connector fails
choose action for failed Connector (Abort process and raise
error)
Name
Description
Figure 20. Configure Connector
Figure 21. Select ${url} to take input
Click Next to define Output.
Figure 22. Map the output of the Connector to the rssResult Data variable
Click Finish.
Figure 23. New Connector defined for RSS Feed Step
3.4
Create Forms
Create customized Forms using the Data input and output from the new Connector in this
Process.
Go to the Pool RSSFeed -> Details -> Forms and select the option Skip the initial forms at
process start.
Figure 24. Skip initial forms at process start
3.4.1
Add a Form to the RSS Feed Step
Go to the Step RSS Feed -> Details -> Forms -> Add.
Figure 25. Create an initial Form



Name
enter the name of Form (Retrieve blog feed)
Description
enter a description for this Form
Add widgets based on As this form will accept a URL as input, leave url -> Text
checked.
Click Finish to continue.
Figure 26. Create Form in Form Builder
Click on the X on the Retrieve blog feed tab to close it. The Form now shows in the Step
Details.
Figure 27. RSS Feed Step now has a Form
3.4.2
Add a Form to the Read results Step
Go to Read results -> Details -> Forms -> Add.



Name
enter the name of Form (Read results from blog feed)
Description
enter a description for this Form (See results of RSS feed)
Add widgets based on You will add the widget for the java object returned in the
next step. Unselect the url –> Text option presented as that is not
needed for the output form.
Figure 28. Create a form to display returned data
There will be no “live” fields in this form, but add a List to take the data returned in the java
object in list form.


Click and drag List into the form.
Click on the List1 cell and go to General. Uncheck Show label.
Figure 29. Add a field to the form to take the returned output

Click on the List cell and go to Data. The Expression field should be filled with
${field_List1. If not, choose it from the list.
Figure 30. Select field for Expression

Add a groovy script to the Available values field. Select Edit expression.
The Groovy editor will appear. Copy and paste the Groovy script below into the Groovy
editor.
res = new ArrayList<String>();
rssResult.each
{
res.add(it.getTitle() + " : " + it.getLink())
}
res
Figure 31. Add Groovy script to read list output
Figure 32. Output defined
Click OK to save the script.
Make the output field larger and easier to read. While still in the Form Read results
from blog feed, click on List1, go to Details -> Appearance -> Field and enter 100% in
Width.
Figure 33. Increase the width of the output field
Click on the X on the Read results from blog feed tab to save and close it. The
Form now shows in the Step Details.
Part 4.
Run the Process
Click Run to run the Process.
The first Form will appear. Click Submit to continue (and to activate the Connector).
Figure 34. RSS Feed form appears in Bonita User Experience
Enter the RSS URL for the BonitaSoft.org blog
http://feeds.feedburner.com/BonitaOpenSourceBpmCommunityBlog
and Submit.
Figure 35. Enter a URL for an RSS feed
The feed results are returned:
Figure 36. Feed results are returned