Skip to main content

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.

Important:

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 icon
Undo your most recent action, such as adding, moving, or editing an activity.
Delete icon
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 icon
Cut the selected items and places them on the BPL clipboard.
Copy icon
Copy the selected items to the BPL clipboard.
Paste icon
Paste items from the BPL clipboard at the selected location.
Drill into the Current Group Activity icon
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).
Drill Out of the Current Group Activity icon
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 icon
Arrange the layout of items in the diagram; this aligns shapes in the diagram without changing the underlying BPL document.
Print icon
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.

BPL diagram showing the process for obtaining weather data for a given store location and then performing other actions

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
BPL call activity, which appears as a rectangle with rounded corners
Activity * <assign>, <call>, <sync>, and most others.
BPL foreach loop, which has a clockwise arrow icon
Loop <foreach>, <while>, or <until>. Reveal the loop details by clicking on the arrow at the bottom of the shape, or by clicking rectangle with green circle
BPL sequence, which includes a plus icon
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 rectangle with green circle
BPL scope, which is a semicircle
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.
BPL decision, which is a diamond
Decision The start of an <if>, <switch>, or <branch>.
BPL alert, which is a circle with an exclamation point in the center
Special <alert>, <reply>, or <label>.
BPL split, which is a triangle
Split The start of a BPL <flow> element, where various logical paths diverge from a single point
BPL join, which is an inverted triangle
Join The end of any branching element—<if>, <flow>, <branch>, <scope>, or <switch>—where all possible paths come together.
BPL start, which is a circle
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
BPL assign icon, which is an equals sign
<assign>  
BPL code icon, which looks like a paper
<code>  
BPL sql icon, which looks like a paper
<sql>
BPL asynchronous call icon, which looks like a right arrow meeting a vertical line
Asynchronous <call>  
BPL delay icon, which looks like a clock
<delay>  
BPL sync icon, which looks like a left arrow leaving a line
<sync>
BPL synchronous call icon, which looks like two arrows in opposite directions meeting and starting from a vertical line
Synchronous <call>  
BPL milestone icon, which is a diamond
<milestone>  
BPL trace icon, which is a pencil
<trace>
BPL catch icon, which looks like a funnel
<catch>  
BPL rule icon, which is the function indicator, f(x)
<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 with if shape selected and inverted triangle that represents a join highlighted

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.

BPL switch shape connected to multiple call shapes, which converge at a join shape

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 Two intertwining green arrows 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.

BPL start and end shape connected in an untidy fashion to a trace shape

When you click the auto arrange tool Two intertwining green arrows the shapes are aligned as shown in the following figure.

Trace shape tidily connected to a start and end point in a BPL diagram

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:

BPL foreach shape selected

If you select the loop activity and then click the rectangle with green circle tool or click the blue curved arrow 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:

BPL diagram of a loop that includes nested if shapes

To return to the higher logical level, where one shape represents the entire loop, click the rectangle with green circle tool.

A sequence displays a plus sign to indicate that it, too, can provide drill-down details. For example:

BPL sequence shape selected

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 rectangle with green circle tool. For example:

BPL diagram with three sequential call shapes

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:

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:

Name

Enter a name for the caption inside the shape.

x

The x axis coordinate for the location of the selected shape in the diagram.

y

The y axis coordinate for the location of the selected shape in the diagram.

Disabled

Select this check box to disable the activity; clear it to enable. The default is enabled.

Annotation

Enter text to appear as comments next to the shape in the diagram.

Note:

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:

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:

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 Two intertwining green arrows 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 rectangle with red dot View Other Code or pressing Ctrl-Shift-V.

Note:

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.
Print icon
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.

Defining the context Object

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>

See Also

FeedbackOpens in a new tab