Editing a BPL Business Process
This topic describes how to use the Business Process Designer, which enables you to create a BPL business process as a visual diagram. When you save a diagram from the Business Process Designer, it generates a class description—that is, a text document—in correct BPL syntax. The BPL diagram and the BPL document are equally valid descriptions of the same BPL business process class.
When you open a BPL business process in the Management Portal or Studio, or when you create a new BPL business process using a wizard, its BPL diagram displays in the Business Process Designer. To the right of the diagram is a pane containing a set of property tabs; you can expand and collapse this right pane as desired using the double arrow icons.
After a period of inactivity, the InterSystems Management Portal may log you out and discard any unsaved changes. Inactivity is the time between calls to the InterSystems IRIS server. Not all actions constitute a call to the server. For example, clicking Save constitutes a call to the server, but typing in a text field does not. Consequently, if you are editing a business process, but have not clicked Save for longer than Session Timeout threshold, your session will expire and your unsaved changes will be discarded. After a logout, the login page appears or the current page is refreshed. For more information, see Automatic Logout Behavior in the Management Portal.
BPL Designer Toolbar
The ribbon bar of the Business Process Designer page contains the options and commands that form the BPL designer toolbar:
Commands that are not valid at the focus of the diagram appear dimmed. The following table describes the action you initiate for each command and, if applicable, provides a link to a detailed description of the process.
Command | Description |
---|---|
New | Launch the Business Process Wizard to create a new BPL business process. |
Open | Launch the Finder Dialog to choose an existing BPL business process class to load and begin editing using the Business Process Designer. |
Save | Save any changes you have made to the business process diagram. |
Save As | Save your changes as a new BPL business process class. |
Compile | Compile the BPL business process class. |
100% | Choose from a list of percentage values to shrink or enlarge the size of the BPL diagram. Choose a large factor to view details, a small factor to gain an overview. |
Add Activity | Choose a BPL element from the list of activities to add to your BPL diagram as described in Adding Activities to BPL. |
Group Items | Group the selected items to form a group diagram, into which you can drill down for details; the group is represented as one shape on the higher level diagram. You can select whether to group the selected elements as a <sequence>, as a specific type of loop: <foreach>, <while>, or <until>, or as a <scope> or <flow> element. |
Undo your most recent action, such as adding, moving, or editing an activity. | |
Remove the selected item from the diagram. You can select one activity at a time by clicking on it. The selected activity changes color to yellow. | |
Cut the selected items and places them on the BPL clipboard. | |
Copy the selected items to the BPL clipboard. | |
Paste items from the BPL clipboard at the selected location. | |
Display the BPL diagram of the activity details that you have grouped together. This drills down into a nested diagram. Only available for a shape representing a group (you can also click the plus sign in at the bottom of the shape). | |
Display the current group as a single shape in the higher level diagram. This drills up the nested diagram. Only available if you have previously drilled down into a group. | |
Arrange the layout of items in the diagram; this aligns shapes in the diagram without changing the underlying BPL document. | |
Display a printer friendly version of the diagram in a new browser page. |
BPL Diagram
The left pane below the ribbon bar displays the BPL diagram which consists of shapes that correspond to activities in a BPL file, with additional shapes and connections that correspond to logic in the BPL file. The following is a sample BPL diagram.
The following topics provide details about the diagram and how it represents the different elements of BPL.
Editing Tips
When using the Business Process Designer to work with a BPL diagram, you can:
-
Select a shape by clicking it.
-
Select multiple shapes by holding down the Ctrl key while selecting.
-
Connect one element to another by clicking on its input or output connection point and dragging to the desired element. The Business Process Designer does not allow you to make an illegal connection.
-
Display or edit the properties of an element by selecting it and viewing its properties in the Activity tab to the right. You can also select a connector to see its properties; click the other property tabs to see the properties of the process itself.
-
Insert and connect a new shape in one operation: select the connector between the two elements where the new shape should go, then add an activity. The new shape appears between the existing elements with connections automatically in place.
-
Automatically validate activities as you add them to the diagram. If InterSystems IRIS® detects an element with a logical error, it displays a red warning on the Activity tab for the element along with the reason for the error.
BPL Diagram Shapes
A BPL diagram uses certain shapes to indicate that a BPL element is present in the code.
BPL Shape | Meaning | Example |
---|---|---|
Activity * | <assign>, <call>, <sync>, and most others. | |
Loop | <foreach>, <while>, or <until>. Reveal the loop details by clicking on the arrow at the bottom of the shape, or by clicking | |
Sequence | <catch>, <catchall>, or <sequence>. Reveal the sequence by clicking on the plus sign at the bottom of the shape, or by selecting the shape, or by clicking | |
Scope | The start of a BPL <scope> for error handling purposes. A shaded rectangular background encloses all the BPL elements that fall within this <scope>. If the <scope> includes a <faulthandlers> element, the rectangle includes a horizontal dashed line across the middle; the area below this line displays the contents of the <faulthandlers>. For examples, see the topic Handling Errors in BPL. | |
Decision | The start of an <if>, <switch>, or <branch>. | |
Special | <alert>, <reply>, or <label>. | |
Split | The start of a BPL <flow> element, where various logical paths diverge from a single point | |
Join | The end of any branching element—<if>, <flow>, <branch>, <scope>, or <switch>—where all possible paths come together. | |
Start/End | The start or end of a BPL diagram. |
* Many activity shapes display an icon, as shown in the right portion of the <call> activity box. The following table lists and describes the meaning of these icons.
Icon | BPL Element | Icon | BPL Element | Icon | BPL Element | ||
---|---|---|---|---|---|---|---|
<assign> | <code> | <sql> | |||||
Asynchronous <call> | <delay> | <sync> | |||||
Synchronous <call> | <milestone> | <trace> | |||||
<catch> | <rule> |
In general the interior color of a BPL diagram shape is white, with a blue outline. If the shape is in error, its outline is red. If the shape is disabled, its interior color is gray, with a gray outline.
When you click a shape in a BPL diagram, it becomes selected. Its attributes display in the Activity tab, where you can edit their values. Its interior color changes to yellow. If it is in error, its outline remains red; if not, its outline changes to a bolder blue. When you select a disabled shape it shows a dotted outline.
You can select multiple shapes by holding down the Ctrl key while clicking on shapes. To clear the selection of a shape, click on it while it is selected.
When a shape represents a complex activity such as <if> or <switch> that has multiple branches, joins, or other types of related shapes elsewhere in the BPL diagram, clicking on one of these shapes highlights the related shapes in green with a purple outline. Clicking on a <sync> element highlights the <call> elements that it synchronizes. Clicking on an <if> shape highlights the Join where the <true> and <false> branches come together, and so on. For example:
BPL Diagram Connections
In a BPL diagram, the lines between shapes specify logical relationships and sequencing among the elements. These lines are called connections. The start of each line is a circular nub and the end is a triangular point. One triangular input nub and one circular output nub are built into each shape that you add to the BPL diagram.
You can connect one shape to another by clicking on its input or output nub and dragging the cursor to the desired shape. When you release the mouse, a connection appears. Another way to connect shapes is to insert and auto-connect a new shape in one step. Select the two elements on either side of where the new shape should go. You can select multiple elements by holding down the Ctrl key while clicking on the shapes. If two elements are selected with no existing connection between them, you can add a new shape and it appears between the existing elements, with connections automatically in place. To add a new shape between two connected elements, click on the connection to highlight it, then add the new element. The new shape appears between the existing elements, with connections automatically in place.
Once two shapes are connected, the connection is preserved no matter where you drag the respective shapes. You can drag shapes to any layout position you wish, within the same diagram. Connections reroute automatically, and the underlying BPL document is not changed. On the other hand, if you change the logic of the connections, for example to reorder calls, create loops, or cut and paste, then the underlying BPL document does change to reflect your actions in the Business Process Designer.
Within a <switch> activity, each possible path is automatically labeled with the corresponding <switch> value. All of the possible paths from a <switch> activity converge at a Join shape before a single arrow connects from the Join shape to the next activity in the BPL diagram.
The Business Process Designer provides many types of validation of your diagram as you work on it. One useful validation feature is that the editor detects if the output branches of an <if>, <flow>, or <switch> element are connected to the wrong Join shape in the diagram. If so, the connector that is in error displays in red until you correct the diagram.
BPL Diagram Layout
After you add shapes or create new connections, you can tidy the diagram by clicking the arrange icon on the tool bar.
For example, if you do not have the auto arrange feature set in your preferences, when you add a shape to a BPL diagram it looks something like the following figure.
When you click the auto arrange tool the shapes are aligned as shown in the following figure.
If you want your diagrams to always use this type of structured layout, select the Auto arrange check box on the Preferences tab.
By default, when you open a BPL diagram in the Business Process Designer for the first time, the auto arrange feature is enabled. This choice may or may not be appropriate for a particular drawing. You can disable automatic arrangement to ensure that your diagram always displays with exactly the layout you want by clearing the Auto arrange check box on the Preferences tab. This way, when the diagram is displayed in the Business Process Designer, it does not take on any layout characteristics except what you have specified.
Drilling Down into a BPL Diagram
A loop activity displays a cyclic arrow to indicate that it provides drill-down details. The following is an example of the <foreach> loop activity. Others include <while> and <until>. For example:
If you select the loop activity and then click the tool or click the in the loop shape, a BPL diagram of the loop displays. This is a full BPL diagram showing all the logic between the start and end of the loop. For example:
To return to the higher logical level, where one shape represents the entire loop, click the tool.
A sequence displays a plus sign to indicate that it, too, can provide drill-down details. For example:
When you drill down into a sequence, the resulting BPL diagram shows all the logic between the start and end of the sequence. To return to the higher logical level, where one shape represents the entire sequence, click the tool. For example:
If there is an error anywhere in a lower-level diagram, the Business Process Designer highlights the group shape (<foreach>, <sequence>, <while>, or <until>) in red. To fix the error, you must drill down into the group shape to see the activity that has the error highlighted in red in the lower-level diagram.
Adding Activities to a BPL Diagram
The Add Activity list is available in the Business Process Designer toolbar whenever you have a BPL diagram open in the Management Portal or Studio. When you click on an item in this list, you add its shape to the BPL diagram. The list is divided into the following categories:
-
Activities
Adds this Activity View documentation for this element Alert <alert> Assign <assign> Break <break> Call <call> Code <code> Continue <continue> Delay <delay> Empty <empty> Reply <reply> Rule <rule> SQL <sql> Sync <sync> Trace <trace> Transform <transform> XPATH <xpath> XSLT <xslt> -
Decisions and Placeholders
Adds this Decision View documentation for this element If <if> Switch <switch> Branch <branch> Label <label> Milestone <milestone> -
Logic
Adds this Logic View documentation for this element Flow <flow> Join (required for the diagram, no corresponding BPL element) Scope <scope> Sequence <sequence> -
Loops
Adds this Loop View documentation for this element ForEach <foreach> While <while> Until <until> -
Error Handling
Adds this Loop View documentation for this element Throw <throw> Catch <catch> Catch All <catchall> Compensate <compensate> Compensation Handler <compensationhandlers>
When you add an element to the diagram, the Activity tab displays with the properties applicable to the element. At the top of the tab is the corresponding BPL element and a description along with an active link to the BPL reference entry for that element. This is the most accurate place to get information about the settings that follow.
Except for the <start> and <end> shapes, the following settings are common to all elements:
Enter a name for the caption inside the shape.
The x axis coordinate for the location of the selected shape in the diagram.
The y axis coordinate for the location of the selected shape in the diagram.
Select this check box to disable the activity; clear it to enable. The default is enabled.
Enter text to appear as comments next to the shape in the diagram.
The <start> and <end> shapes only have the x and y coordinates, so you can move them manually if you wish.
Adding a Call Activity
A common task in a BPL business process is to add a Call activity. The following information is necessary to properly create a new <call> to one of the available business processes or business operations in the production:
-
Input
-
Output
-
Name
-
Target
-
Request
BPL Designer Property Tabs
To the right of the BPL diagram is a pane containing a set of property tabs; you can expand and collapse this right pane as desired using the double arrow icons. Three of the tabs relate to the BPL business process itself and one relates to the selected shape:
-
General—contains settings for the overall definition of the BPL business process. See Setting General Properties of the BPL Business Process.
-
Context—provides the interface for defining the context object for this BPL business process.
-
Activity—contains settings for the selected item in the BPL diagram; see Adding Activities to a BPL Diagram.
-
Preferences—contains settings pertaining to the appearance of the BPL diagram. See Setting BPL Diagram Preferences.
Setting General Properties of the BPL Business Process
The General tab contains the following settings that apply to the BPL business process:
-
Language—Can be Python, ObjectScript, or Basic.
-
Layout—Select either Automatic or Manual for the size of the diagram. If you select Manual you can enter a Width and Height.
-
Annotation—Enter text to include in the class description.
-
Includes—An optional comma-delimited list of ObjectScript include file names, so that you can use macros in your <code> segments.
-
Python From / Import statements—An optional list of Python from / import statements, one per line. Use this so that Python code within this business process can refer to these modules.
-
Version—Enter an optional version number of the BPL diagram
-
Is component—If true, include this process in the component library where it can be called by other processes.
See <process> for details on these properties.
Defining the context Object
You can define the context object of a BPL business process from the Context tab of the Business Process Designer. You can click the magnifying glass to launch the Finder Dialog for each of the following fields:
-
Request Class—Choose the class of the incoming request for this process.
-
Response Class—Choose the class of the response returned by this process.
-
Context Superclass—Use this option to provide custom context properties, in a different way than adding to the Context properties list, described next. To use Context Superclass, create a custom subclass of Ens.BP.ContextOpens in a new tab. In this subclass, define class properties to use as context properties. Use the name of this class as the value of Context Superclass in the business process. Then when you create <assign> actions, for example, you can choose these custom properties in addition to the standard properties of the context object.
You can add to the list of Context properties by clicking the plus sign to launch the Business Process Context Property wizard. Then enter values in the following fields:
-
Property Name—Must be a valid identifier.
-
Choose if the property data is one of the following: Single Value, List Collection, or Array Collection
-
Property Type—Type of this property including parameters.
Enter a data type class name in the Type field or click the magnifying glass to browse for a class you want to use as a data type.
-
Default Value (ignored for collections)—Enter an initial expression for a single value data type.
-
Instantiate—Select this check box for object-valued properties if you want the object to be instantiated when it is created.
-
Description—Enter an optional description of the context property.
Click OK to save your changes, Cancel to discard them. The Business Process Designer generates the necessary <context> and <property> elements in the BPL code.
To set property parameters such as MINVAL, MAXVAL, MINLEN, MAXLEN, or others in the Business Process Designer, add data type parameters to a context property when you first add the property, or at any subsequent time, by inserting a comma-separated list of parameters enclosed in parentheses after the data type class name. That is, rather than simply entering %StringOpens in a new tab or %IntegerOpens in a new tab, you can enter data types such as:
%String(MAXLEN=256) %Integer(MINVAL=0,MAXVAL=100) %String(VALUELIST=",Buy,Sell,Hold")
The Business Process Designer generates the necessary <parameters> element in the BPL code.
Once you have defined properties on the context object, you can refer to them anywhere in BPL using ordinary dot syntax and the property name, as in: context.MyData
For reference details, see the following resources:
-
Typically you choose the property type from the system library of data types described in Data Types. These include %StringOpens in a new tab, %IntegerOpens in a new tab, %BooleanOpens in a new tab, etc.
-
System data types have optional parameters. For details, see Parameters. These include the MINLEN and MAXLEN parameters that set the minimum and maximum allowed lengths of a %StringOpens in a new tab property. The default maximum %StringOpens in a new tab length is 50 characters; you can reset this by setting the MAXLEN for that %StringOpens in a new tab property to another value.
By default, the ruleContext passed to the rule is the business process execution context. If you specify a different object as a context, there are some restrictions on this object: It must have a property called %Process of type Ens.BusinessProcessOpens in a new tab; this is used to pass the business process calling context to the rules engine. You do not need to set the value of this property, but it must be present. Also, the object must match what is expected by the rule itself. No checking is done to ensure this; it is up to the developer to set this up correctly.
Setting BPL Diagram Preferences
The Preferences tab contains the following settings that apply to the appearance of the BPL diagram:
-
Gridlines—Select one of the following choices for the appearance of the grid lines on the diagram: None, Light, Medium, or Dark.
-
Show annotations—Reveal or conceal the text notes that explain each shape. When you reveal annotations, they appear to the upper right of each shape that has an <annotation> element in the BPL document.
-
Auto arrange—Cause each new shapes in the diagram to automatically conform to a structured arrangement without needing to select after adding each shape.
Changing the position of shapes does not change the underlying BPL code. Only a change to the connecting lines changes the code.
Notes on Creating BPL in Studio
When you save a diagram from the Business Process Designer, it generates a class description—that is, a text document—in correct BPL syntax. The BPL diagram and the BPL document are equally valid descriptions of the same BPL business process class. Studio recognizes each format interchangeably. A change to one automatically generates a change to the other. Therefore, while viewing the class in Studio, you can switch between diagram and text views of the BPL document by clicking View Other Code or pressing Ctrl-Shift-V.
When switching from the text view to the graphical view, sometimes it is necessary to close and reopen the class to see the graphical view again.
Some of the tools in the Management Portal do not appear with the others; existing Studio commands provide the same functions.
Command | Studio Equivalent |
---|---|
New | On the File menu, click New and then click Business Process on the Production tab. |
Open | On the File menu, click Open to launch the finder dialog to choose an existing BPL business process class to load and begin editing using the Business Process Designer. |
Save | On the File menu, click Save to save any changes you have made to the business process diagram. |
Save As | On the File menu, click Save As to save your changes as a new BPL business process class. |
Compile | On the Build menu, click Compile to compile the BPL business process class. |
On the File menu, click Print to open the Print dialog. |
You can export a BPL diagram to an XML file which can later be imported back into another InterSystems IRIS installation. The rules for doing this are the same as for importing or exporting any other class to a file: In Studio, use the Tools Export and Tools Import commands.
There are tasks you can do in the BPL code when defining the context object:
In BPL code, insert <property> elements inside the <context> element, one for each property, as described in Business Process and Data Transformation Language Reference.
To set property parameters such as MINVAL, MAXVAL, MINLEN, MAXLEN, or others in BPL code, you must allow the <property> element to specify the data type with its type attribute (class name only!) and include a <parameters> element inside the <property> element to describe any data type parameters that you want to include, as described in Business Process and Data Transformation Language Reference. For example:
<context>
<property name='Test' type='%Integer' initialexpression='342' >
<parameters>
<parameter name='MAXVAL' value='1000' />
</parameters>
</property>
<property name='Another' type='%String' initialexpression='Yo' >
<parameters>
<parameter name='MAXLEN' value='2' />
<parameter name='MINLEN' value='1' />
</parameters>
</property>
</context>