Developing Workspace Workflow

Introduction

This is a practical Getting Started guide of how to create, deploy and run a workspace workflow within Comflow Studio.

Purpose

The purpose of the document is not to fully describe the Comflow. The document provides an introduction and explains some basic working procedures.

Who should read this document?

This document is intended for Comflow users who use Comflow for developing solutions.

Before you start

The following starting conditions must be met:

• Installed Comflow Studio
• Installed related Tomcat
• Installed database or access to remote database

Presentation of content

Introduction to Comflow

Concepts

Tools

Development Process

“Top down” or “Bottom up” development method

When working with Comflow Studio you have a choice whether to use a top-down or a bottom-up design approach. You can either define your views (portlets) first, and then define the flow of the views in the workspace workflow, or you can define the flow first, and then fill it with the views.

The repository (and a database) however is good to have, before starting the development of portlets and workspaces. It is strongly recommended that you have a clear definition of the structure of your data. For demo purposes though, it is possible to create an executable workspace workflow without a repository.

Building a simple Workspace Workflow

We create a simple repository that defines the table “Item” (see below).

We will define a data model from this repository, build a portlet on this data model, and associate the portlet in a workspace workflow that can be executed in ComActivity Enterprise Value Portal.

Create a new Eclipse Project

You can choose between the following categories:

• Component – A generic component that will be used by different customer portal solutions.
• Core – Mainly used by ComActivity when developing CA-Tools & Core.
• Customer – Component collection with customer specific adoptions.
• Frontend – Similar to Customer project type (will probably be merged with the customer project type).
• Repository – Project for a generic repository used by several projects of type Customer, Component or Core.

For the example of this guide we can choose Component project.

The “Item” Project Repository

Create the following simple repository:

Note: In this case we create the repository inside the item project, but a repository can also be defined in a separate repository project. Having a separate project is a good idea if several projects work on the same repository.

Another Note: At the moment, there are two parallel ways of defining a repository. The old “Repository Builder”, shown here, easy to use when creating a small repository, and the new “RepTool” which is the preferred tool when creating a more complex repository.

In later releases, these two will be one.

As an alternative you can, if you have access to a packaged repository like Rep_MOVEXV12R5, try to use that instead of defining a repository of your own.

Create a Data Model & Browse Portlet

The first portlet we create is a browse portlet where all items of a certain category can be presented. (Just to make the example a little more interesting we make a hard coded limitation here that the browse only presents items of category = 403).

Note: At the moment, the data model is only possible to create from within the portlet builder. This will change in later versions. So, to be able to create a data model we need at least an empty portlet.

Create a portlet: Package Explorer – Portlets dir – right click – New Portlet

The Data Model

1. Outline - right click – Add Simple Model
2. Outline – on the simple model – right click – Add Master Table
3. Set meta data ID to “Item”
4. Work with Master Table
5. Set the selection to “multi” – this means we want to have a multi row result set. The ItemNo will not be used in a where criterion, only ItemCategory. I.e. we will get all items (ItemNo:s) inside the specified category (we will hard code category later).
6. Push the Select All button so that all fields get checked (this means that all fields will be presented in the data model.
7. Generate criteria: Outline – right click – Generate Criteria.

Warning: Never use a data model name with underscore (‘_’) since it is used as a delimiter by the system.

Now just mark the generated “where”-criterion and change the Col2 value to fix value=403 instead of the MapData variable. Also change Col2Type to fix instead of var.

Note: The original MapData value in the generated criteria assumes that this variable is present in MapData. MapData is a storage for data (keys for example) that has to live between several activities in a workspace workflow. A data instance (runtime instance of a data model as the one we have created above) only lives inside one activity.

Note about complex/simple model: What we’ve created now is a simple model. The simple model is included in a complex model. This relationship gives a lot of flexibility. In the example we only picked fields from one simple model, but a segment can have fields from any number of simple models. When submitting data (update), a complex model including all simple models from the segment in question, is what is submitted.

In simpler words, this means that one little segment in a portlet can have fields that refer to columns in different tables. These tables can possibly also come from different metadata ID:s.

Finally, one simple model can actually also involve columns from different tables since the master table can have imported tables.

Creating the fields in the Portlet

Now the data model is created and we can select the fields from the data model that we want to present in the portlet. Some fields in the data model might be there just for other reasons than presentation. We can for example define a virtual field (not shown in this example) and calculate the sum of two fields in the data model. A virtual field is a field not associated with a data model.

Before adding fields we have to add a segment that works as a collection of fields.

If you want tabs you also have to add them to the portlet surface before starting to define your fields. Since this should be a portlet that can present several rows we need to add a browse segment.

1. Select browse segment – drop on portlet surface
2. right click on segment – Add Field – Select All – OK

Now when you have all fields in the segment, you can mark (select) a field and set its properties in the Eclipse property inspector. See the reference manual for additional information about all properties.

Note about Properties: Almost all ComActivity objects (Portlets, Workspaces, fields, constants etc.) have properties that can be modified in the general Eclipse property inspector, so it’s always a good thing to have the ‘Properties’ view active and look at the properties of an object to see what can be done.

Create the Detail Portlet

Do the same as in previous chapter but use a detail segment instead. Also be sure to use ‘single’ (all keys) when building the data model. This will make sure that we always get one and only one row in our result set when the activity associated with this portlet is executed in our workspace.

Refining your Portlet

After portlets are created and initially tested in a workspace there are refinements that can be done to customize the look & feel of the portlet. Examples of such refinements are length of fields, presenting text fields as text areas with several rows, language support etc. We leave this at the moment.

Creating a Workspace Workflow

When all portlets (2 in our simple example) are ready, we want to define the rules for when a certain portlet should be presented for the user of the portal.

1. Package Explorer – Workflows folder – right click – New Workflow
2. When inside the Workspace Builder (Eclipse Plug-in), add a main portlet activity in the same “select & drop” manner as when you added segments for the portlet in previous chapter.

Note: Each main artifact created in CA Tools has a Builder of its own (Portlet, Workspace Workflow, Repository etc.)

1. Connect the main portlet activity with the entry point by a transition.
2. right click on main portlet activity – Associate Portlet – choose ItemBrowse.pml (if that is what you called it)

Note about Process vs. Workspace Workflows: What we are building in this example can be viewed as a “single user” Workflow for a user to be able to solve a certain task. Several such tasks can within another ComActivity Tool - “Process Builder” (see CA - Process Development User Guide) be tied together into a Process (or Process Workflow). A Process defines a workflow within an organization involving several persons.

About the names: The Processes are situated in a folder called Processes, but the Workspaces are in a folder called Workflows (even though both processes and workspaces are different forms of workflows). This name will change to “Workspaces” in a later version.

To be able to navigate further on in the workspace from the browse view, we have to add some navigation buttons:

1. Right click on main portlet activity – Add Action – choose the segment – Add

Set properties as in pictures below.

The purpose of the properties in this dialog is very important to understand to be able to create a workspace that navigates a user in a correct way.

The Data Instance Event is defining what action should be taken with the data instance when this action is invoked.

The Data Model Event is a parameter that is used by the “next” activity in the flow (in our case the next activity will be our Item Detail Portlet). The actions in the next activity can check this parameter in which case it is decided whether they will be shown or not). As an example if we choose _model_view, then we can hide an update button or update right click action by letting that action (in the next portlet) have Action Condition set to _model_view. In case of _model_view all fields will also be presented in a read only mode.

Dialog Event: If doDefault, then the transition conditions on the outgoing transitions from current activity will decide where the flow is going. doPrevious and doClose on the other hand are overriding the default behavior of the flow and do what their names are indicating (previous goes to previous activity and close closes the task (the workspace).

Event type: button or right click menu item. RowData and RowKey means left click on key or data part of a row.

Also see reference manual for these properties.

After the step above, we do the same but for the detail portlet and we connect the browse portlet with the detail portlet. In the detail portlet it can be nice to add for example a button that has the dialog event doPrevious which will let the flow go back to the browse activity.

Before the workspace workflow can execute, we need to define the action condition on the transition between the browse and the detail. At the moment we could execute the workspace, browse the items in the browse portlet, but when we left click on a row nothing will happen. This is because no transition has a condition that checks the transitions event of the left click that we defined (trans_select).

1. Activate the Associate Action tab.

2.Check the action to add and click OK.

This step will generate a condition on the transition. You can manually define much more complex conditions if necessary, but since checking transition events sent by actions are such a common condition, there is a generator for them.

Note that the transitions are selected in the top to bottom order. A transition without associated actions will always be considered correct if not another has been already been selected prior to the first one.

Deploy and Run

What is left before we are able to run this small workspace workflow inside the portal is to create a task, put the task in a navigator tree, and configure our sitedef.xml so that the navigator tree is visible when we start our web server.

Note: Under Eclipse – Window – Preferences – ComActivity – Deploy, you can see what sitedef it is that is the default sitedef for all projects.

What is a sitedef? A sitedef is a configuration file for all types of configuration that has to be made to be able to deploy and run a portal. For example DB connections, security etc. Typically you have your own personal sitedef when developing your projects, and another production specific sitedef for the production portal.

1. Copy an existing task into the task dir under the item project.
2. Open the task in an XML-editor (XMLBuddy for example), and change the ID and the workspace workflow reference.
3. Copy an existing navigator tree to the configuration dir under your project and change it to include the task you just created.
4. Insert a reference to the navigator tree in your sitedef.
5. Deploy your sitedef.
6. Deploy the item project.
7. Start (or restart) the web server where you deployed the project.

Note: A sitedef always has to be deployed separately even though under same projects that you just deployed.

Now you should be able to logon to the portal and run the new workspace workflow by starting it from the new task under your new navigator tree. This assumes that you have some test data in your database.

This “Item Browse”-Workspace Workflow could be extended to be a full blown “Item Registration”-Workspace Workflow by adding actions for insert, update and deletion of items.

How to?

This chapter explains how solve classic design problems. Each and every chapter describes briefly how to solve the problem that is stated in the heading.

Browse segment open for update

To control that a browse segment is open for editing, you only set the Type property for the field in the segment to input.

Note that this only works on non-key fields and that the data model in the browse segment must have Data Model Event in ‘_model_update’ mode set for the action in the workflow.

Create a sum of a numeric field in a browse segment

If you want to create a sum of a numeric field in a browse segment, you set the Summarize Column property for the field in the browse segment to Yes.

Then you also have to enable the summary rows on the segment by setting the Summary Row property for the browse segment. By selecting ‘page’, you get a summary row for the records shown in a page. If you select extract, you get a summary row for all the extracted rows, which can span cross multiple pages. When selecting ‘pageandextract’ you get both.

Note that if you use server side rendering, the value of the property doesn’t matter, since a page is the same as an extract.

Create a virtual field in a browse segment that is calculated from other fields

To

Fråga 3

Jag vill skapa ett virtuellt fält i min browse panel som skall beräkan typ följande:

Anta`l*Pris/prisfaktor*valuta konverteringskurs.

Alla fälten ligger i samma fil och skall bara beräkas i som en kolum.

Hur gör man

Controlling description field for a prompt

To control what column that is shown as description field for a prompt, you set a property on the table in the repository. It is the property 05 –Key column description that shall contain the description column in the table.

Select from one model and update or create another in the same portlet

To build a portlet where a selection shall be made from one or several models, and then create or update one or several models you do the following;

For the models that you shall do the select for, you set the DB Access property for the simple model in your portlet to “out”. You thereby control that the model is only used in the Data model process out access (DMProcOut).

For the simple model or models that you want to insert in the data source, you set the same parameter to “in”, and thereby controlling that it is only processed in the Data model processor in (DMProcIn). Note that you also have to have Data Model Event put to ‘_model_create’ on your preceding action in the workflow to actually tell the DMProcIn to generally do a create action against the data source.

For simple models that shall be updated, the DB Access type is the default ‘inout’ and they are executed if the Data Model Event is ‘_model_update’. This limits the actions in a portlet to do either creation or update and not both in the same time.

Note that if the Result type portlet is set to ‘single’ on the simple model that has DB Access Type, you will get an empty data instance after the DMProcOut, which then makes it very easy to insert values into it via rules.

Manage Data model criteria in a portlet

Sometimes you want to change the criteria for the models in order to request a different set of data or to just initialize data in a portlet.

Manage dependencies between data models in a portlet

If you want to manage dependencies between two or more data models in a portlet, like that you want one model to do the select based on the resulting fields in other models, you do the following.

First you must have defined the two models and generated the criteria for them. Then the dependant model must be below the model it is dependant of, though not necessary directly below in the Data model builder/Portlet builder. You create the dependency by right click on the dependant model and chose Add Dependency. Then you chose the model that it shall be dependant of.

Then you mark the criteria in the dependant model and change the property Default criteria to Override. Note the red color on the criteria icon.

Then you click on the Identifier Right property. You chose Scope to Instance in the pop-up window and then you select the model, table and column that you want the dependency on.

If the model that want to have dependency on, already have a dependency you will see that model also. Thereby you can chose dependency fields from the model, the dependency model and it’s dependency model.

Now you are finished with the dependency and you can continue to add more dependencies for other criteria. You can also add totally new criteria that have dependencies. See “Manage Data model criteria in a portlet”.

Controlling prompt fields

If you want to control what field that is shown at the side of the key in a prompt against a data source, like a description field, you control that via a table property

By setting the 05 Keycolumndescr to any field in the table, but not a primary key column, that field will be shown to the left of the key in the generic prompt.

Control data in one segment from another

Sometimes you want to control the data in one segment from another segment, like if you want to have a selection of warehouse controlling a list of inventory on that warehouse like the example below.

To do that control you define your models and segments, then you create a dependency from the second model to the first, controlling, model and change the where conditions in the second model so it relates to the first model.

In the example the Inventory table (MITLOC) has a dependency to the Warehouse table (MITWHL) via the first model. The Warehouse ID (WHLO), which is key in Inventory table, is then controlled by the chosen Warehouse ID in the Warehouse table.

The where statement is thereby changed to be controlled by the data instance value from the controlling model. If you change a default criterion (a generated one), you shall always change the Default criterion property to Override. See the chapter for Manage dependencies between data models in a portlet for more information.

Then you have to enable a control of refreshing the second segment from the first. You then create an action, like a button, that do a _postselect as Data Instance Event. This then controls that you do a refresh of the portlet, controlled by the selection that you have made in the first segment.

Managing rule execution points in a portlet

Rules can be executed via execution or exit points at several states in the rule processing for a portlet, when it transits from another portlet or to another portlet. They are generally divided into the ones that executes before displaying the portlet, the “out-processing” or the one after the portlet has been displayed, the “in-processing”.

The picture below shows the flow for a single portlet in a transition flow, and all the possible exit points.

PreDMProcOut is an execution point for managing data before you access the data source, like managing keys for a data request.

PostDMProcOut is an execution point for managing data directly after receiving the data result set.

Sametime is an execution point for managing data before starting a sametime portlet.

PreDialogOut is an execution point for managing data before the data is processed for creating the user dialog. In this point you should do UI changes such as setting segments and/or fields visible or hidden.

PostDialogOut is an execution point for managing the data after the user dialog has been created, but before the portlet is rendered. In this point you should do UI changes associated with styling such as setting fonts, background colors or text colors.

PreDialogIn is an execution point for managing the data in the dialog, before the system starts processing it.

PreDMProcIn is an execution point for managing data before the data is processed against the data sources.

PostDMProcIn is an execution point for managing the data after it has been processed against the data sources, but before the processing of the next portlet starts.

Stack is an execution point for managing the portlet stack.

PreDocumentOut is an execution point for managing UI changes such as setting segments and/or fields visible or hidden.

Flex tree

The flex tree is a component to display hierarchical data (ie. Product structures or file/folder structures).

How to create a flex tree segment

1. In the portlet designer choose a Graphical Component segment and place it in the desired spot in your portlet.
2. In Designer Properties choose the Advanced tab.
3. Set the Component property to “Tree (flex)”.
4. Choose your data provider (the rule to populate the tree).

How to create a data provider (populate the tree from a rule)

1. Create a java class extending the net.comactivity.core.cag.rule.AbstractCAGTreeRule.
2. The “execute” method which is called upon when interacting with the tree takes the clicked node’s ID as an argument and shall return a list of children of type net.comactivity.core.cag.tree.CAGTreeNode.

For example rule see  net.comactivity.cagtest2.BuildTree.java in the CAVerify project.

Related documents