BP-VA Plug-in Development

In this tutorial, we are going to develop a plug-in that reads the BPMN tasks in project, check their names, and list the tasks whose name has more than 50 characters. We will use Eclipse as the Java IDE for implementing the plug-in. Therefore, please get Eclipse ready. You can, however use any other Java IDE you preferred.

Getting the Plug-in JavaDoc

The Plug-in JavaDoc provides Visual Paradigm plug-in developers with definition of classes, attributes, operations and arguments in the plug-in. We recommend users getting the JavaDoc and incorporating it into the Java project that will be created in the next section. To get the plug-in JavaDoc:

1. Visit the web page Plug-in API in Visual Paradigm official site.
2. Click on the link Download JavaDoc of Plug-in API.
   
3. Save the zip file to somewhere in your machine.
4. Extract the zip file.

Implementing the Plug-in

1. Start Eclipse.
2. Create a Java project sample.listbadtasks.
   
3. In the Java Settings page, set src to be the source folder and classes to be the class folder.
   
4. Open the Libraries tab. The jar file openapi.jar in %VP-SUITE-INSTALL-DIR%\lib contains the API for plug-in development. Add it as a library or else your work cannot be compiled.
   
5. Expand the node openapi.jar. Select Javadoc location.
   
6. Click Edit on the right hand side.
7. Click Browse in the popup window. Input the path of the extracted zip of JavaDoc. Click OK.
   
8. Click Finish in the New Java Project window.
9. Create a package sample.listbadtasks.
   
10. In package sample.listbadtasks, create a class ListBadTasks which implements interface VPPlugin. If you do this by Eclipse's code completion feature, two methods loaded() an unloaded() will be added automatically. If not, add it yourself. If the editor cannot identify the interface VPPlugin, make sure you have added the openapi.jar to project build path.
    
11. Create package sample.listbadtasks.actions.
12. In the package sample.listbadtasks.actions, create a class ListBadTasksActionController which implements the interface VPActionController. This class is made for performing certain action. In this case, it implements the logic of listing tasks whose name has more than 50 characters. The action can be triggered from user interface.
    
    Here are some of the points you should be aware of:

    The performAction() method contains the logic of action you want to perform. The update() method is called before showing the action on screen. You can make use of this method to disable the method before it get shown. In this tutorial we just leave it empty.

13. We want to popup a dialog box to list the tasks whose name has more than 50 characters. Before we implement the action in ListBadTasksActionController, let's implement the dialog box. Create package sample.listbadtasks.ui.
14. In the package sample.listbadtasks.ui, create a class TaskDialogHandler which implements the interface IDialogHandler. This class is made for performing certain action.
    
15. Add a static class ModelItem inside TaskDialogHandler. It will be used to form the content of task list in the dialog box.

    private static class ModelItem { public final IBPTask bpTask; public ModelItem(IBPTask model) { this.bpTask = model; } public String toString() { return this.bpTask.getNickname(); } }

    
    As we have incorporated the JavaDoc, we can read the description of class and methods when using code completion.
    
    Here are some of the points you should be aware of:

    IBPTask refers to a BPMN task element. IBPTask.getNickName() is used to get the name of task, with nickname considered.

16. Add a static class RendererImpl inside TaskDialogHandler. It will be used render list items by showing the icon and name of tasks.

    private static class RendererImpl extends DefaultListCellRenderer { private BPMNIconRetriever bpmnIconRetriever; public RendererImpl() { bpmnIconRetriever = ApplicationManager.instance().getViewManager() .createBPMNIconRetriever(); } public Component getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus) { Component component = super.getListCellRendererComponent(list, value, index, isSelected, cellHasFocus); if (component instanceof JLabel && value instanceof ModelItem) { JLabel lLabel = (JLabel) component; ModelItem lItem = (ModelItem) value; Icon lIcon; IModelElement lTaskType = lItem.bpTask.getTaskType(); if (lTaskType != null) { lIcon = bpmnIconRetriever.getIconForTask(lTaskType.getModelType()); } else { lIcon = ApplicationManager.instance().getViewManager().getIconByModelType( lItem.bpTask.getModelType()); } lLabel.setIcon(lIcon); } return component; } }

    
    Here are some of the points you should be aware of:

    BPMNIconRetriever is a utility that lets you to get the icons (javax.swing.Icon) for element types. BPMNIconRetriever can be retrieved from the ViewManager, which can be obtained from the ApplicationManager.

17. Add two global variables. One for the panel where the list is placed and another one for the dialog box itself.

    private Component component; private IDialog dialog;

18. Add a constructor for constructing the list and list content.

    public TaskDialogHandler(IBPTask[] models) { int count = models == null ? 0 : models.length; ModelItem[] items = new ModelItem[count]; for (int i = 0; i < count; i++) { items[i] = new ModelItem(models[i]); } JList list = new JList(items); list.setCellRenderer(new RendererImpl()); JScrollPane scrollPane = new JScrollPane(list); JPanel panel = new JPanel(new BorderLayout()); JPanel buttonPanel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); JButton closeButton = new JButton("Close"); buttonPanel.add(closeButton); panel.add(scrollPane, BorderLayout.CENTER); panel.add(buttonPanel, BorderLayout.SOUTH); component = panel; closeButton.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent aE) { dialog.close(); } }); list.addMouseListener(new MouseListener() { public void mouseReleased(MouseEvent aE) {} public void mousePressed(MouseEvent aE) {} public void mouseExited(MouseEvent aE) {} public void mouseEntered(MouseEvent aE) {} public void mouseClicked(MouseEvent aE) { if (aE.getClickCount() > 1) { JList list = (JList) aE.getComponent(); int lIndex = list.locationToIndex(aE.getPoint()); if (lIndex > -1) { ModelItem item = (ModelItem) list.getModel().getElementAt(lIndex); IDiagramElement diagramElement = item.bpTask.getMasterView(); if (diagramElement == null) { IDiagramElement[] diagramElements = item.bpTask .getDiagramElements(); if (diagramElements != null && diagramElements.length > 0) { diagramElement = diagramElements[0]; } } if (diagramElement != null) { ApplicationManager.instance().getDiagramManager() .highlight(diagramElement); } } } } }); }

    
    Here are some of the points you should be aware of:

    Every model element may have zero or one master view. The method IBPTask.getMasterView() is for getting the master view of task, which is a IDiagramElement. The method ApplicationManager.getDiagramManager().highlight(DiagramElement) enables you to highlight a view with a spotlight effect, same as what you can see when using the 'Jump to' feature.

19. Implement the remaining four inherited methods:

    public boolean canClosed() { return true; } public Component getComponent() { return component; } public void prepare(IDialog dialog) { this.dialog = dialog; dialog.setSize(600, 300); dialog.setTitle("Show Task"); } public void shown() { }

20. Let's go back to the class ListBadTasksActionController. Fill in the method performAction() to read the tasks from project, check their names, and popup the implemented dialog box to list the tasks with long names.

    public void performAction(VPAction action) { List badTaskList = new ArrayList(); // Retrieve all tasks from project ProjectManager projectManager = ApplicationManager.instance().getProjectManager(); IModelElement[] modelElements = projectManager.getProject().toAllLevelModelElementArray( IModelElementFactory.MODEL_TYPE_BP_TASK); // Store the tasks whose name is more than 50 chars for (int i = 0; i < modelElements.length; i++) { IModelElement modelElement = modelElements[i]; IBPTask task = (IBPTask)modelElement; if (task.getName() != null && task.getName().length() > 50){ badTaskList.add(task); } } IBPTask[] tasks = new IBPTask[badTaskList.size()]; badTaskList.toArray(tasks); // Show the dialog that lists out the tasks in badTaskList ApplicationManager.instance().getViewManager().showDialog(new TaskDialogHandler(tasks)); }

    
    Here are some of the points you should be aware of:

    ProjectManager.getProject().toModelElementArray(IModelElementFactory.MODEL_TYPE_BP_TASK) enables you to get an array of specific type of model element, such as task. IModelElementFactory contains constants of element type names IModelElement refers to a model element in project, such as a task, a pool, etc. You may type-cast an IModelElement into a concrete type class, such as IBPTask, IBPPool, etc.

21. The coding part is done. If you find the code cannot be compiled, please make sure you have added openapi.jar into the build path.

Deploying the Plug-in

1. Create an XML file plugin.xml under the project root.
   
2. Fill in the XML file as shown below:

   <plugin id="sample.listbadtasks" name="List Bad Tasks" description="List out any task whose name has more than 50 characters" provider="Visual Paradigm" class="sample.listbadtasks.ListBadTasks"> <actionSets> <actionSet id="sample.listbadtasks.actionset"> <action id="sample.listbadtasks.actions.ListBadTasksActionController" actionType="generalAction" label="List Bad Tasks" tooltip="List Bad Tasks" style="normal" menuPath="Tools/Report"> <actionController class="sample.listbadtasks.actions.ListBadTasksActionController"/> </action> </actionSet> </actionSets> </plugin>

   
   Here is a description of the content of plugin.xml:
   

   No.	Description
   1	A text for identifying this plug-in. You may develop multiple plug-ins. Each plug-in must have a unique id defined.
   2	The name of plug-in.
   3	The description of plug-in.
   4	The person/organization who develop this plug-in.
   5	The fully qualified class name of the plug-in class, which is the class that implements the VPPlugin class, offering the load and unload logic.
   6	Actionsets describe the possible ways of invoking the plug-in. An action can be added into MenuBar and Toolbar, by setting @menuPath=... and @toolbarPath=... If your plugin have actions on menu bar and diagram's popup menu. For menu bar's actions, the actions are defined in <actionSet>; For toolbar's actions the actions are defined in <contextSensitiveActionSet>.
   7	A unique value for identifying the action set.
   8	A unique value for identifying the action.
   9	Define the type of action: [generalAction | shapeAction | connectorAction]. generalAction: The simple action that may be added on menu bar/toolbar/diagram popup menu. You are required to specify the <actionController...> for this action (ref to point 14). shapeAction: The action used to create CustomShape. You are required to specify the <shapeCreatorInfo...> connectorAction: The action used to create CustomConnector. You are required to specify a set of <connectionRule...>
   10	The menu item text.
   11	Tooltip is the text that display when moving mouse pointer over a toolbar button.
   12	Specify the menu item is Normal button or Toggle (Checkbox) button. [normal | toggle]
   13	The position where the menu/toolbar button will be presented. In this case, the menu will be placed under the Tools menu, after the menu Report.
   14	The fully qualified class name of the class that implements VPActionController, for showing what and how to perform the action.

3. It's time to deploy the plug-in into your BP-VA/VP Suite installation, to make it available in BP-VA. Create a folder plug-ins in the installation folder. (E.g. C:\Program Files\Business Process Visual ARCHITECT\plugins)
   
4. Copy the Java project folder sample.listbadtasks into the plugins folder. You should obtain folder structure like this: C:\Program Files\Business Process Visual ARCHITECT\plugins\sample.listbadtasks\classes.
   

Running the Plug-in

1. Start BP-VA in a new workspace. Create a new project by selecting File > New Project from the pop-up menu. Name the project Test Plug-in and click Create Blank Project.
2. Draw a simple business process diagram, like this:
   
3. Let's test our plug-in. Select Tools > List Bad Tasks from the main menu.
   
4. The dialog box is shown. Two tasks are listed there. Let's double-click on any of them. The task is highlighted in diagram.
   

Resources

1. Java Project (folder) of this plug-in

Related Links

1. Visual Paradigm Suite Plug-in User's Guide
2. Visual Paradigm Suite Plug-in Sample