How to Create a Connector 290310

7/27/2019 How to Create a Connector 290310

http://slidepdf.com/reader/full/how-to-create-a-connector-290310 1/24

Bonita Open SolutionVersion 5.1

How to… Create a Connector

Version1.0



Bonita Open Solution 5.1 How to

BOS V5.1 – How To Create a Connector – 25 Mar 10 www.bonitasoft.com | © BonitaSoft S.A. page 2

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 ......................................................................................................... 7Figure 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 ......................................................................................................... 14Figure 17. Add a text variable for the Connector Input ....................................................................... 15

Figure 18. Add a java object variable for the Connector output ......................................................... 16



Figure 19. Global Data Added .............................................................................................................. 16

Figure 20. Configure Connector ........................................................................................................... 17

Figure 21. Select ${url} to take input .............................................................................................. 17

Figure 22. Map the output of the Connector to the rssResult Data variable ............................... 17

Figure 23. New Connector defined for RSS Feed Step ......................................................................... 18

Figure 24. Skip initial forms at process start ........................................................................................ 18Figure 25. Create an initial Form .......................................................................................................... 19

Figure 26. Create Form in Form Builder ............................................................................................... 19

Figure 27. RSS Feed Step now has a Form ........................................................................................... 20

Figure 28. Create a form to display returned data .............................................................................. 20

Figure 29. Add a field to the form to take the returned output .......................................................... 21

Figure 30. Select field for Expression ................................................................................................... 21

Figure 31. Add Groovy script to read list output ................................................................................. 21

Figure 33. Output defined .................................................................................................................... 22

Figure 34. Increase the width of the output field ................................................................................ 22

Figure 35. RSS Feed form appears in Bonita User Experience ............................................................. 23

Figure 36. Enter a URL for an RSS feed ................................................................................................ 23Figure 37. 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

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.

Part 2 Design the Connector

2.1 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:

http://www.bonitasoft.com/products/downloads.php




http://www.bonitasoft.org/exchange/extension_view.php?eid=2


http://wiki.java.net/bin/view/Javawsxml/Rome









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 The ID by which BOS recognizes this Connector; for this example use

RSSReader

Description what the Connector does

Category 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



Connector. If you want to use an icon, browse to where it is located

and upload it. (Recommended size: 60x 60 pixels).

Class name The java class name; this is automatically completed to be the same

as the Connector ID. For this example, leave it as is.

Package 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 the ID by which BOS recognizes this Connector wizard page (for this

example use EnterURL)

Page Title this will appear at the top of the wizard (Retrieve an RSS or

Atom feed)

Description (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 the name of the input data field (url)

Mandatory select “mandatory” for this field

Widget select the type of widget for this field to appear in (Text)

Data Type 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 the name of the output data field (for this example, use

itemsList)

Data Type 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 com.sun.syndication.feed.synd.SyndEntryImpl;import com.sun.syndication.feed.synd.SyndFeed;import com.sun.syndication.io.SyndFeedInput;import 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 FIELDprivate String url;private List<SyndEntryImpl> itemsList;

@SuppressWarnings("unchecked")@Overrideprotected 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();

}

@Overrideprotected List<ConnectorError> validateValues() {

List<ConnectorError> errorsList = newArrayList<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 Design the Process

3.1 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.



Name enter the name of the Connector (Fetch RSS)

Description 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)

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 resultsfrom 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

Documents

How to Create a Connector 290310