Copyright © 2002-2012, Agent Oriented Software Pty. Ltd.

JACK Intelligent Agents® Graphical Plan Editor Manual

Release 5.5
2 September 2010

Table of Contents

Publisher Information

 Agent Oriented Software Pty. Ltd.  
 P.O. Box 639,  
 Carlton South, Victoria, 3053  
 AUSTRALIA  
   
Phone: +61 3 9349 5055
Fax: +61 3 9349 5088
Web:  http://www.agent-software.com

If you find any errors in this document or would like to suggest improvements, please let us know.

The JACK™ documentation set includes the following manuals and practicals:

Document Description
Agent Manual Describes the JACK programming language and infrastructure. JACK can be used to develop applications involving BDI agents.
Teams Manual Describes the JACK Teams programming language extensions. JACK Teams can be used to develop applications that involve coordinated activity among teams of agents.
Development Environment Manual Describes how to use the JACK Development Environment (JDE). The JDE is a graphical development environment that can be used to develop JACK agent and team-based applications.
JACOB Manual Describes how to use JACOB. JACOB is an object modelling language that can be used for inter-process transport and object initialisation.
WebBot Manual Describes how to use the JACK WebBot to develop JACK enabled web applications.
Design Tool Manual Describes how to use the Design Tool to design and build an application within the JACK Development Environment.
Graphical Plan Editor Manual Describes how to use the Graphical Plan Editor to develop graphical plans within the JACK Development Environment.
JACK Sim Manual Describes how to use the JACK Sim framework for building and running repeatable agent simulations.
Tracing and Logging Manual Describes the tracing and logging tools available with JACK.
Agent Practicals A set of practicals designed to introduce the basic concepts involved in JACK programming.
Teams Practicals A set of practicals designed to introduce the basic concepts involved in Teams programming.

1 Introduction

The Graphical Plan Editor (GPE) is designed for graphically viewing and editing JACK Intelligent Agents® (JACK) plans. The GPE is integrated with the Development Environment (JDE). Plans edited with the GPE may be compiled with the JACK Compiler Utility and traced with the JACK Plan Tracing Tool.

The GPE allows users to view and edit all the details of a plan in separate panels. The panels of the GPE can be displayed or hidden, depending on what a user needs to view while editing each plan. The window that contains these panels is called the Graphical Plan Editor window.

The GPE emphasizes the use of documentation in plans. Plan documentation assists users when creating and understanding plans. Separate documentation sections are included in the GPE for each relevant detail. Plan documentation, resources, variables, conditions and graphs may be edited in the GPE. The reasoning methods of a plan can be represented graphically in the GPE as directed graphs – the Plan Graph Editor is provided for this purpose. However, textual reasoning methods as well as graphical reasoning methods are allowed in plans developed using the JDE. Experience has shown that plans created with the GPE are easier to present to, and are more easily understood by, non-programmers and subject-matter experts because of their graphical nature.

This document describes the GPE and the Plan Graph Editor. These descriptions are applicable to both plans and teamplans.

When a plan is edited using the GPE, the title bar will display Plan: followed by the name of the plan that is currently being edited. When a plan reasoning method is opened using the Plan Graph Editor, the title bar will display Graphs: followed by the name of the plan.

When a teamplan is edited using the GPE, the title bar of the GPE will display Team Plan: followed by the name of the teamplan that is currently being edited. When a teamplan reasoning method is opened using the Plan Graph Editor, the title bar of the Plan Graph window will display Team Graphs: followed by the name of the plan.

Note that a teamplan cannot be opened with the GPE in Agent Mode, as teamplans are not visible within the JDE browser unless Teams Mode is active. Teams Mode can be toggled on or off by clicking the Teams Mode option in the View menu of the JDE.

1.1 Operating System notes

The instructions in this document are written with the expectation that the reader will be a PC user, but they are generally applicable to both Macintosh and Unix users. However, in some cases the instructions will be slightly different for Macintosh users.

Macintosh users should note the following:

Unix users should note:

The screenshots used in the document were generated from a Macintosh; this was for readability purposes only.

2 Overview

This manual provides instructions for using the GPE to edit components of Graphical Plans and Graphical Reasoning Methods. It begins with a brief description of Graphical Plans and their features. Creating and opening graphical plans within the JDE is also described.

Instructions for editing graphical reasoning methods are outlined and include details of the types, categories and editors of nodes required for defining graphical plan logic. Management of Graphical Plans, including printing and exporting is also covered. The manual concludes with a description of the graphical plan and font preferences that affect the GPE.

3 Graphical plans

Graphical plans have the same components as regular JACK plans with the addition of graphical reasoning methods. Graphical reasoning methods allow the user to construct the logic of a plan graphically. Reasoning method statements are represented with nodes, which are created from the node types provided in the Plan Editor Palette. The nodes are connected with links to designate control flow.

Graphical plans have body, pass and fail reasoning methods by default. Plan execution starts and finishes in the body method. Pass and fail methods are used if any actions are required after plan success or failure. Other graphical reasoning methods may be added, and they may be renamed to replace default graphical reasoning methods.

Note: It is possible to have a plan with non-graphical and graphical reasoning methods.

3.1 Creating graphical plans

A new plan can be created in the JDE from either the Plan Types folder or a design within the current project. Refer to the Design Tool Manual for more information on designs. Once a plan has been created, a GPE window can be opened for the plan.

4 Opening graphical plans

The GPE is used to edit plans that have already been created from within the JDE. A separate GPE window is shown for each plan that is edited. Likewise, the Plan Graph Editor is used to edit graphical reasoning methods that have already been created for a plan from within the GPE. The Plan Graph Editor window provides access to all the graphical reasoning methods of the associated plan.

To open the GPE, follow the steps below.

  1. Open the JDE.
  2. Load a project into the JDE, or create a new project by following the steps given in the Development Environment Manual.
  3. Open the Agent Model folder in the JDE browser by clicking on the + symbol to the left of the Agent Model icon. The Agent Model will expand.
  4. Open the Plan Types folder in the Agent Model by clicking on the + symbol to the left of the Plan Types folder icon. The Plan Types folder will expand, and the various plans will become viewable.
  5. Right-click on the plan type to be edited. A pop-up dialog box will open, providing (among other options) the option to Edit Graphically.
  6. Click with either mouse button on the Edit Graphically option. The GPE will open.

Figure 4-1: An open Graphical Plan Editor window

4.1 Opening graphical reasoning methods

The Plan Graph Editor can either be opened from the GPE or directly from the Reasoning Methods folder of the JDE. In the former case, open the GPE according to the instructions above. Then select/create the reasoning method to be edited from the Graphs List and right-click the Edit Graph button.

To open the Plan Graph Editor directly from the JDE:

  1. In the JDE browser, expand the current plan by clicking the icon to the right of the plan name.
  2. Expand the Reasoning Methods folder of the plan by clicking the icon to the right of the folder. Graphical reasoning methods are distinguished from textual reasoning methods by the icon to the left of the reasoning method name; a text or pencil icon indicates a textual reasoning method, whereas a graph icon indicates a graphical reasoning method. Textual reasoning methods can not be edited graphically.
  3. Double-click a graphical reasoning method name. Alternatively, right-click a graphical reasoning method name and select the Edit option from the pop-up menu.
  4. A Plan Graph Editor window displaying the selected graph will open. If not already open, a GPE window will also open for this plan.

In either case a window like the following will be displayed. In the example below, the Plan Graph canvas is empty, as we are dealing with a newly created reasoning method.

Figure 4-2: Plan Graph Editor window

4.2 Editing graphical plans with both the JDE and the GPE

The documentation, resources and conditions (excluding conditions documentation) of a plan can be edited in both the JDE and the GPE. When one of these components is edited in the JDE or GPE, it is automatically updated in the other window. For example, if a new sentence was added to the plan documentation in the GPE, it would also appear in the plan documentation in the JDE browser.

Once a plan has been edited in the GPE, it may still be edited in the JDE. However, not all components of graphically edited plans can be edited in the JDE. For example, the variables and graphical reasoning methods (including documentation, variables and parameters) of plans must be edited in the GPE. Plan conditions may be edited in the JDE, although conditions documentation is not visible.

If a plan has existing body, pass or fail textual reasoning methods, and is opened in the GPE, a Subgraph/textual method conflict will occur. The user can choose to rename an existing textual reasoning method and create a new graphical reasoning method, or leave the original name as is.

Note: It is possible for a plan to have both graphical reasoning methods and textual reasoning methods.

Plans created and/or edited using the GPE cannot be edited with the JDE alone. They require editing with the GPE because they have graphical reasoning methods.

5 Editing graphical plans

Graphical plans are edited in GPE windows. A GPE window contains buttons for printing and exporting plans as well as the following panels for editing plan attributes:

When a GPE window first appears, only the Documentation and Graphs List panels are displayed.

The toolbar of a GPE window has checkboxes with names corresponding to the above plan attributes which can be used to display or hide the panels. Panels are displayed or hidden by clicking on the checkbox or panel name. The GPE window grows and shrinks according to the panels that are displayed.

Note that the GPE only maintains a list of the graphical reasoning methods required by the plan. The actual content of these reasoning methods is specified and edited in the Plan Graph Editor.

5.1 Editing plan documentation

The Documentation panel of the GPE displays plan documentation as editable text. This panel is displayed by default. Documentation panel text may be edited in:

Figure 5-1: Documentation panel

When a new plan is created, the documentation text section in the Add Plan Type dialog window allows plan documentation to be added.

To add, edit or delete plan documentation:

  1. Select the Documentation checkbox with the left mouse button if it is not already selected. Alternatively, click the Documentation name to display the Documentation panel. The Documentation panel will open below the GPE tool bar.
  2. Documentation in text form can now be added, edited or deleted within the Documentation panel. Text may be cut, copied and pasted using the JDE Edit menu or keyboard shortcuts.

5.2 Editing plan resources

The Resources panel of the GPE displays the resources used by a plan. These resources are the same as those shown under the plan name in the JDE Browser. The Resources panel can be used to add, edit and delete plan resources in the same way as the JDE browser. The Resources panel is, in effect, a way that the user can see which JACK elements the plan is associated with, without needing to look at the JDE browser.

Figure 5-2: Resources panel

To display the plan resources, click the Resources checkbox.

To add a resource:

  1. Holding the mouse button down over the required resource, drag the required resource from the JDE browser into the appropriate section in the Resources panel.
  2. Release the mouse button once the cursor becomes an arrow. This will drop the required resource into the appropriate section in the Resources panel.

To edit a plan resource name:

  1. Right-click the resource name with the mouse.
  2. Select the Edit option in the pop-up dialog window.
  3. Edit the current name and press ENTER. Alternatively, select another resource to finish editing.

To edit a plan resource:

  1. Right click the resource name and select Edit from the pop-up dialog options. Alternatively, double-click on the resource name.
  2. Edit the resource text as required and click the Done button to close.

5.3 Editing plan variables

The Variables panel of the GPE displays a sortable list of plan variables. Variables declared in the Variables panel of the GPE window are global to the plan. Each variable has the following fields:

As well as a list of plan variables, the Variables panel also has Delete and Add buttons for adding and deleting variables. Variables may be sorted by clicking on a field heading. Variables must have a name and type, but the Value and Documentation fields are optional. Note that the GPE does not validate variable names, types or values.

Figure 5-3: Variables panel

To add a variable with plan scope:

  1. Open the Variables panel in the GPE window by clicking the Variables checkbox in the Plan Graph tool bar, or by clicking the Variables name in the Plan Graph tool bar. The Variables panel will open.
  2. Click the Add button in the Variables panel.
  3. A new variable with name newVariable will be added.

Note: A newly added variable has no type, value or documentation.

To edit the Type, Name, Value or Documentation fields of a variable:

  1. Using the left button of the mouse, click the Type, Name, Value or Documentation field of the variable requiring editing with the mouse. The field name will become editable.
  2. Type in the required changes.
  3. Click another field, or press ENTER to finish editing.

To delete a variable:

  1. Select the variable to be deleted by clicking any of the variable's fields.
  2. Click the Delete button in the Variables panel.

Note that variables can only be deleted one at a time.

To sort the list of plan variables by a field, click a field heading using the mouse. The list of variables will be sorted according to that field.

Note: If plan variables are sorted during editing of the variable, any changes will be lost.

5.4 Editing plan conditions

The Conditions panel of the GPE displays the conditions for plan execution.

The following sections are displayed as editable text:

Figure 5-4: Conditions panel

An Available Variables list is also displayed. This is a list of alphabetically sorted variable names and types. These variables may be inserted into text areas in the Conditions panel by clicking on one of the arrows to the left of the list. The Available Variables list in the Conditions panel includes plan variables, events, interfaces and belief data.

Once a variable name is inserted into an editable text area, the name will not be automatically updated if changed in the GPE. A variable name is inserted as text, so if the variable changes, the name is updated in the Available Variables list, but not in any text areas into which it has been inserted.

To edit a plan condition, first display the Conditions panel by selecting the Conditions checkbox in the tool bar or by clicking the Conditions name. The relevance and context conditions for the plan and their documentation can now be edited. Text in each of the corresponding text boxes can be cut, copied and pasted using the JDE Edit menu or keyboard shortcuts.

5.4.1 Relevance

The relevance condition component is a text box that contains the plan's relevance condition. The relevance condition is a static boolean method that is applied to an event instance for the purpose of determining whether or not the plan type is relevant for that event instance. The relevance condition text box should contain the definition of that method or be left empty. Documentation for the relevance condition is added to the relevance documentation text box.

5.4.2 Context

The context condition component is a text box that contains the plan's context condition. When a plan is relevant for handling an event, the context condition is used to determine the ways, if any, in which a plan type is applicable. The context condition text box should either contain a logical expression or be left empty. Documentation for the context condition is added to the context documentation text box.

The conditions panel of the GPE has an Available Variables list. This list contains the names of plan variables, events and beliefsets. If appropriate, variable names from the list can be copied into the context condition and context conditions documentation text box.

To copy a variable name :

  1. Select the variable name.
  2. Move the insertion point to the desired place in the documentation or conditions text box.
  3. Click the left arrow button next to the relevant text box.
  4. The variable name is inserted after the current cursor position.

Note: Once a variable name has been inserted, it is not automatically updated. This means that if a variable name is changed in the Variables panel, the old variable name will still be in the Conditions panel.

5.5 Editing the Graphs List

The Graphs List panel of the GPE displays a sortable list of graphical reasoning methods (graphs). This section contains instructions for creating, renaming and deleting graphs.

Note: The body, pass and fail methods may be renamed or deleted; however, the user must ensure that a plan has a body method before it is compiled and run.

Each graphical reasoning method has a Name and Documentation column. Below the list of graphical reasoning methods are the following buttons:

Note: Spaces are not allowed in graphical reasoning method names. Where a space is required, using an underscore ( _ ) is a good alternative.

Figure 5-5: Graphs List panel

5.5.1 Deleting graphs

To delete a graphical reasoning method:

  1. Select the method name from the list.
  2. Click the Delete button. A Confirm Deletion of Graph dialog window will appear.
  3. Click the Delete Graph button to confirm the deletion of the graphical reasoning method, or Cancel to cancel the deletion.
  4. The method will be deleted from the list.

Note: Graphical reasoning methods must be deleted individually from the Graphs List.

Figure 5-6: Confirm Deletion of Graph dialog window

5.5.2 Renaming graphs

To rename a graphical reasoning method:

  1. Click the Rename button. A Rename Subgraph dialog window with the current method name will appear.
  2. Edit the method name as required. The dialog window does not allow spaces.
  3. Click Apply Changes to confirm the renaming of the method or Cancel to cancel the action.
  4. The graphical reasoning method will be shown with the new name.

Figure 5-7: Rename Subgraph dialog window

5.5.3 Editing graphs

To edit a graphical reasoning method:

  1. Select the name of the method to be edited from the Graphs List.
  2. Click on the Edit Graph button. The Plan Graph Editor window will open, displaying the selected graphical reasoning method.
  3. Edit the method using the Plan Graph Editor.

Alternatively, double-click the method name in the Graphs List. The Plan Graph Editor window will open, displaying the selected method.

See the Editing Graphical Reasoning Methods chapter of this manual for instructions for the Plan Graph Editor.

5.5.4 Creating graphs

To create a graphical reasoning method:

  1. Click the Create Subgraph button. A Create New Subgraph dialog window will appear.
  2. Type the new graphical reasoning method name in the Create New Subgraph dialog window.
  3. Click the Create New button to create a new graphical reasoning method or click Cancel to cancel the operation.
  4. A new graphical reasoning method will be added under the currently selected method, or at the bottom of the Graphs List if no method is currently selected.

Note: The GPE does not allow duplicate graphical reasoning method names. The dialog window does not allow spaces in graphical reasoning method names. Also, like Java methods, reasoning methods cannot have spaces in method names.

Figure 5-8: Create new graphical reasoning method

5.5.5 Sorting graphs

To sort the Graphs List, click the Name or the Documentation heading of the Graphs List in the Graphs List panel. The Graphs List will be sorted alphabetically according to the selected heading.

6 Editing graphical reasoning methods

Editing of the graphical reasoning methods (also known as graphs or plan graphs) for a plan is performed in a Plan Graph Editor window. The title bar of the Plan Graph Editor displays the name of the particular plan whose graphical reasoning methods are currently being edited. The name of the graphical reasoning method that is currently being edited is displayed in a drop-down list next to the Plan Graph: option at the top of the Plan Graph Editor window. Clicking on the drop-down list displays a list of all the graphical reasoning methods for the plan. This allows the user to switch between the various graphical reasoning methods of a plan without needing to open and close each method separately.

The Plan Graph Editor window contains a tool bar with a Show Plan button and buttons to print and export graphical reasoning methods. The tool bar also provides access to the following panels:

When the window first appears, only the Plan Graphs panel is displayed.

Figure 6-1: Plan Graph Editor window

6.1 Selecting graphs

To change the current graphical reasoning method being edited:

  1. Click the name of the current graphical reasoning method at the top of the Plan Graph Editor. A list of all methods is displayed.
  2. Click on the name of the method to be edited.
  3. The newly selected graphical reasoning method is displayed in the Plan Graph Editor.

Figure 6-2: Current graphical reasoning method

6.2 Editing graph documentation

This panel displays documentation for the current method as editable text. Graphical reasoning method documentation should give a description of the method. For example, documentation can include the actions in the method, names of other reasoning methods called in the method, and what the method does.

Figure 6-3: Documentation panel

Documentation for graphical reasoning methods can only be added and edited in the Plan Graph Editor.

The contents of the graphical reasoning method documentation may be added, edited or deleted in the Documentation panel. Text may be cut, copied and pasted using the JDE Edit menu or keyboard shortcuts.

6.3 Editing graph variables

The Variables panel of the Plan Graph Editor displays a sortable list of reasoning method variables. Variables declared in the Variables panel of the Plan Graph Editor window are local to the reasoning method.

Figure 6-4: Variables panel

To add, edit, delete or sort graphical reasoning method variables first open the Variables panel in the Plan Graph Editor by clicking on the Variables checkbox or Variables name in the tool bar. Then follow the steps relevant to each feature listed below.

6.3.1 Adding variables

To add a graphical reasoning method variable:

  1. Click the Add button in the Variables panel. A new variable option will appear, entitled newVariable.
  2. The newVariable can now be edited as required.

6.3.2 Editing variables

To edit the Type, Name, Value and Documentation fields of a graphical reasoning method variable:

  1. Click the relevant field. Type in the required changes.
  2. Click another field, or press ENTER to finish editing.

6.3.3 Deleting variables

To delete a graphical reasoning method variable click the Delete button.

6.3.4 Sorting variables

To sort the list of graphical reasoning method variables by field, click the heading of the field to sort by. The list of graphical reasoning methods variables will be sorted in ascending order according to the field clicked.

Note: If graphical reasoning method variables are sorted during editing of a variable, any changes will be lost.

6.4 Editing graph parameters

The Parameters panel displays parameters. Parameters allow calling reasoning methods to pass arguments to the current reasoning method. The features of this panel are similar to the Variables panel in the Plan Graph Editor window, except that the Parameters panel does not have a Value column.

Note: body, pass and fail do not have parameters. The Parameters panel is not shown for these methods.

Figure 6-5: Parameters panel

To add, edit, delete or sort parameters, first select the Parameters checkbox or click the Parameters name to display the Parameters panel.

6.4.1 Adding parameters

To add a parameter to a graphical reasoning method, click the Add button. A new parameter with name newVariable will be added. The new parameter has no type or documentation. If a parameter is previously selected, the new parameter is added below it.

6.4.2 Editing parameters

To edit the Type, Name and Documentation fields of a parameter, click the relevant field. Type in the required changes, and click another field or press ENTER to finish editing.

6.4.3 Deleting parameters

To delete a parameter, select the parameter to be deleted. Click on the Delete button, and repeat the process with any further parameters to be deleted, as parameters can only be deleted one at a time.

6.4.4 Sorting parameters

To sort the list of parameters by a field, click a field heading. The list of parameters will be sorted in ascending order according to the field selected.

Note: If graphical reasoning method parameters are sorted during editing of a parameter, any changes will be lost.

6.5 Editing graph exceptions

Each Plan Graph Editor window has an exceptions panel. This panel allows the user to type in any catch / finally statements as they would appear in Java code. The statements of the entire graph are then enclosed in a try statement, with the text in this box handling any exceptions.

The exceptions panel contains essentially all the exception handling code a user would write in normal textual code, except for the initial try block. Note that depending on the type of exception the user is trying to catch, the body of the reasoning method may require code that actually throws that exception.

Figure 6-6: Exceptions panel

6.6 Editing graph logic

The Plan Graph panel of the Plan Graph Editor has a tool bar and a canvas on which the structure of a graphical reasoning method may be drawn. A graphical reasoning method is drawn as a directed graph. The nodes of the graph are created from the node type provided in the Plan Editor Palette. Links are then created between these nodes to indicate control flow.

Figure 6-7: Plan Graph panel

Nodes may be added to a graphical reasoning method diagram in any order. When linking nodes, it is recommended that the flow of a graphical reasoning method be from top to bottom, to aid the viewer or designer of the method. Graphical reasoning methods must begin with one, and only one, Start node. It is also recommended that End nodes are added to show where the method finishes.

The font of graph component text can be changed in the Fonts preferences of the JDE. See the Font preferences section of the Editor preferences chapter of this manual for further information.

Graph components can be edited or removed by right-clicking on the required node or link and selecting the required option. For example, after right-clicking on a node the options are Edit Node... and Remove Node.

6.6.1 Plan Graph Editor tool bar

The Plan Graph Editor tool bar contains tools for editing and viewing a graphical reasoning method. To select a tool in the tool bar, choose the desired tool and click on the tool button. Certain tools cannot be selected at the same time: the Selection Mode tool and the Link Mode tool are examples of this. The Plan Graph Editor must be in either one mode or the other: it cannot be in both. Moving the mouse cursor over a particular tool on the tool bar elicits tool tips, which are floating text boxes providing descriptions of the relevant tool.

The following tools and buttons are located on the tool bar:

6.6.2 Plan Editor Palette

The Plan Editor Palette contains node types that can be dragged and dropped onto the Graph canvas. It may be opened either with the Open Plan Editor Palette button or by clicking on the Plan Editor Palette option in the Tools menu of the JDE.

The Plan Editor Palette for both Agent Mode and Teams Mode is illustrated below. Note that in Teams Mode, the Plan Editor Palette has four additional nodes:

These nodes can only be used in teamplans.

Figure 6-8: Plan Editor Palette in Agent Mode (left) and Teams Mode (right)

Apart from the Start, End and Fail nodes in the palette, a node editor is opened automatically when a node is added to a graphical reasoning method. A node editor can also be opened by double-clicking on a node.

A node editor has a short description of the node type and editable text areas for node documentation and each node argument. The number and types of arguments depend on the type of node being edited. An Available Variables list is displayed if there are any plan or graphical reasoning method variables.

Each node type has a different node editor. The text fields in a node editor change according to the arguments required by the node type. If a node type can represent two or more reasoning statements or if a reasoning statement has optional arguments, the node editor displays a drop-down Node Type: options menu. This allows the user to select the required statement and/or combination of arguments.

Each of the node editors consists of several text boxes into which relevant arguments and documentation etc. can be added and changed. The figure below displays the Begin Parallel node editor.

Figure 6-9: Begin Parallel node editor

The Available Variables list is a list of alphabetically sorted variable names and types. These variables may be inserted into text areas in the node editor by clicking on one of the arrows to the left of the list. The Available Variables list in the node editor includes plan variables, events, interfaces, belief data, graphical reasoning method variables and parameters.

Once a variable name is inserted into an editable text area, the name will not be automatically updated if changed in the GPE. A variable name is inserted as text, so if the variable changes, the name is updated in the Available Variables list, but not in any text areas into which it has been inserted.

6.6.3 Nodes

Each of the node types in the Plan Editor Palette (with the exception of the Note node) defines a step in a graphical reasoning method. The Note node is used to add documentation to a node or group of nodes. The other node types may contain documentation and JACK / Java code. Some node types represent reasoning method statements.

A node can reference variables that appear in the Variables panel of the GPE window (which have plan scope) or in the Variables panel of the reasoning method graph (which have reasoning method scope). If a variable is defined within a node (such as a Code node) that variable has node scope and is not visible outside the node.

6.6.3.1 Node types

The node types that are supported by the Plan Graph Editor and are accessible via the Plan Editor Palette are listed below. Note that some nodes represent one or two kinds of reasoning method statements. Also, each node type contains documentation, but the documentation for Start, End and Fail nodes is not displayed in Descriptive mode, and is only accessible by opening the node editor.

The mapping between reasoning method statements and nodes is straightforward, except for @parallel statements. Implementation of an @parallel statement in a graphical reasoning method requires a combination of Begin Parallel, End Parallel, Parallel Task nodes together with the nodes required to implement the parallel tasks. As an example, consider the following @parallel statement:

  @parallel(ParallelFSM.ANY,false,null,p) {
    watch: @teamAchieve(crew,crew.wm.watch());
    fly: fly(p);
  };

The corresponding subgraph is shown below:

Figure 6-10: Subgraph in Descriptive mode

Figure 6-11: Subgraph in Non-descriptive mode

Note: In graphical reasoning methods, parallel tasks should only be referred to by label and not by index.

6.6.3.2 Node categories

Nodes can be categorised according to the maximum number of outgoing links (0, 1 or 2). The following three categories are defined for reference purposes:

Links Category Nodes
0 terminal End, Fail
1 action Post/Send, Reply
1 none Start, Note, Parallel Task
2 action Code, Subgraph, Subtask, Wait For, Maintain, Achieve/Insist, Test/Determine, End Parallel, Team Achieve
2 decision Decision
many none Begin Parallel

Table 6-1: Graphical Plan Editor Nodes

6.6.3.3 Node editors

Each node type has a different node editor. The text fields in a node editor change according to the arguments required by the node type. If a node type can represent either of two or more reasoning method statements, the node editor gives a choice between the two statements.

The Available Variables list in the node editor contains the names of plan variables, events, beliefsets, graphical reasoning method variables and parameters. Available variable names may be inserted into the documentation and arguments of a node.

To insert a variable:

  1. Select the variable name from the list.
  2. Move the mouse cursor to the desired place in the documentation or argument text.
  3. Left-click the left arrow button next to the relevant text box. The variable name is inserted after the current cursor position.
  4. Once a variable name has been inserted, it is not automatically updated, and will need to be updated manually. This means that if a variable name is changed, the old variable name will remain in the text into which it was inserted.

Figure 6-12: Node editor

6.6.3.4 Node operations

Within the Plan Graph Editor, one can add, edit, delete and move nodes.

To add a node:

  1. Open the Plan Editor Palette by selecting the Open plan editor palette button on the tool bar, or selecting the Plan Editor Palette option from the Tools menu of the JDE menu bar.
  2. Select a node from the Plan Editor Palette by clicking on the new node type to be added.
  3. Drag-and-drop the node from the Plan Editor Palette to the Graph canvas.
  4. For nodes other than Start, End and Fail, a node editor window will open. In the node editor window, edit the node details (documentation and any arguments) and click the Add New button to add the new node, or click the Cancel button to close the node editor and cancel the operation.

Note: The node editor must be closed before continuing with further editing.

To edit a node after it has been added to a graphical reasoning method, double-click on the node using the left mouse button. Edit the node details (documentation and any arguments) in the node editor. Click the Apply Changes or Cancel button to close the node editor.

To delete a node from a graphical reasoning method, click on the node to be deleted while in Selection mode. The node will become highlighted. Now click on the Delete button on the tool bar or press the DELETE key on the computer keyboard. Note that when a node is deleted, any associated links are also deleted. This behaviour is different to that of the Design Tool.

Note: Nodes can also be edited or deleted by right-clicking on the link and choosing from the context menu.

To move a node, click the Selection mode tool in the tool bar, and then click the node. The node will become highlighted, and can thenceforth be moved by dragging with the mouse.

6.6.4 Links

Links are represented by single lines between two nodes. Some have an arrow at one end to indicate the direction of flow. Documentation may be added to all links in a graphical reasoning method diagram. Any link documentation appears as text on the link in Descriptive mode. Link documentation may be added, edited and deleted. The outgoing links of some node types may also be given a label.

6.6.4.1 Link types

Depending on the type of the node and the number of outgoing links, the outgoing links for a node are labelled with a link type. The possibilities are as follows:

All remaining node types which have outgoing links (Post/Send, Reply, Start, Note, Begin Parallel and Parallel Task) have no labels associated with the outgoing links.

An example of the use of both pass/fail and yes/no links is shown below:

Figure 6-13: Subgraph pass/fail and yes/no links

6.6.4.2 Link categories

Two categories of links are supported within the Plan Graph Editor – floating links and fixed links. Floating links are created by targeting the mouse cursor anywhere on a component. To create a floating link, it is not necessary to be accurate. Targeting anywhere within the component icon enables a floating link to be formed. The GPE will automatically form the link from an appropriate link point (enlarged point on the perimeter of a component). Floating links can move from link point to link point and, should a component be moved on the canvas, the link between it and its associated component also moves. Fixed links are created by building a link from a link point on one component directly to a link point on another. To create a fixed link, it is necessary to be accurate with the mouse cursor, and create the link directly from link point to link point.

6.6.4.3 Link operations

Links can be added, edited and deleted.

The link tool is used to add a link between two nodes. When the mouse cursor is placed over a node while in Link mode it is highlighted, and attachment points are shown. These attachment points are used to link nodes together.

Figure 6-14: : A floating link connecting a Start node to a Decision node

The attachment point of a link can be changed by dragging a link from one link point to another. This can be done at both ends of a link. Links can also be reattached to another node: either end of the link can be reattached.

Loop constructs are implemented as cycles within the plan graph:

Figure 6-15: Subgraph pass/fail and yes/no links

Note: The order in which nodes are linked determines the direction of the arrow on the link.

6.6.4.4 Editing links

Links can be edited at any stage during the development process, and documentation can be added to links or edited at any stage. To edit the documentation for a link or to change its link type:

  1. Double-click with the left mouse button on the link to be edited.
  2. The Edit Link pop-up dialog will open. Depending on the nodes being linked, the editor may offer an option to change the link type. A text box for documentation is also provided.
  3. Enter the necessary documentation and make any changes to the link type that are required.
  4. Click the Apply Changes when finished, or Cancel to cancel the operation.

Figure 6-16: The link editor

Links can be deleted while in either Selection mode or in Link mode. To delete a link from a graphical reasoning method diagram:

  1. Click on the link to highlight it.
  2. Click on the Delete button on the tool bar, or press the DELETE key on the computer keyboard.
  3. The link and any associated documentation will be deleted.

Note: Links can also be edited or deleted by right-clicking on the link and choosing from the context menu.

7 Graphical plan management

7.1 Saving plans

A graphically edited plan is saved when the current project is saved in the JDE. Any unsaved components of a project, including plans, are highlighted in the JDE browser until they are saved. Refer to the Development Environment Manual for details.

7.2 Deleting plans

Deleting a graphically edited plan is completed in the same way as deleting a plan edited in the JDE. Refer to the Development Environment Manual for details.

7.3 Compiling plans

The JDE automatically generates gcode for graphical plans so compilation for a project containing graphical plans is the same as for a project containing non-graphical plans. Refer to the Development Environment Manual for details.

Graphically edited plans may be generated as traceable plans, which allows them to be traced during execution by the graphical Plan Tracing Tool (see the Plan Tracing Tool chapter of the JACK Tracing and Logging manual for further details). To generate traceable plans, the Generate traceable plans option must be selected in the Graphical Plans tab of the Preferences option in the JDE Tools menu.

7.4 Printing plans

Plans and their graphical reasoning methods are printed from the Print Plan window. To open the Print Plan window, click the Print button in the GPE window or Plan Graph Editor window.

Figure 7-1: Print Plan window

The following options are available for printing plans:

7.4.1 Print Plan Details (Separate Page Only)

To print the details of the current plan, select the Print Plan Details (Separate Page Only) option name or checkbox. This option will print the following plan details:

7.4.2 Select Graphs to Print

To print graphical reasoning methods, select one or more graphical reasoning method names from the list of methods in the Print Plan window.

Note: The Select All and Clear All buttons can be used when selecting graphical reasoning methods to print. Multiple methods can be selected by holding down the CTRL or SHIFT key, and clicking method names.

7.4.3 Print Graph Details on Separate Pages

To print the details of a graphical reasoning method on a separate page to the diagram, select the Print Graph Details on Separate Pages option.

To print the nodes of a graphical reasoning method with documentation, select the Print Graphs in Descriptive Mode option.

The following graphical reasoning method details may be selected and printed:

Graphs may be centred horizonally or vertically and can be expanded to fit the page.

7.4.4 Print

Click on the Print button to print the required diagrams.

7.5 Exporting graphical reasoning methods

Plan Graphs can be exported as an image to a JPG or PNG file. To export a plan graph, click the Export plan graphs button on the GPE window or a Plan Graph Editor window. An Export Plan Graphs window similar to the figure below will open.

Figure 7-2: Export Plan Graphs window

Select the required graph, image dimensions and graph details to be exported. Then click the Export to File... button. An Export selected to the following file dialog will open and the file name and path of the exported image can be specified.

Note: When exporting multiple graphs, only the file path should be specified. The exported files will have names corresponding to the exported graph name.

8 Editor preferences

8.1 Graphical plan preferences

The Preferences option in the Tools menu of the JDE has a Graphical Plans tab with the options listed below. Note that when the options are changed, they are not applied to windows that are already open.

Figure 8-1: Graphical Plans tab in the Preferences option of the JDE Tools menu

8.2 Font preferences

The Preferences option in the Tools menu of the JDE has a Fonts tab with the options listed below. Three options are given in this tab to change the font of nodes, links and text in graphical reasoning methods. Note that when the options are changed and applied, Plan Graph Editor windows that are already open must be closed and then reopened for font changes to take effect.

Each preference has an Edit button, which opens a Font Chooser window. The Font Chooser window contains a list of fonts available on the system being used, and from this list the Family, Typeface and Size of the font can be chosen.

Figure 8-2: Fonts tab in the Preferences option of the JDE Tools menu

The three options relevant to Graphical Plans are:

Copyright © 2002-2012, Agent Oriented Software Pty. Ltd.

US Government Restricted Rights

The JACK™ Modules and relevant Software Material have been developed entirely at private expense and are accordingly provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013 or subparagraph (c)(1) and (2) of the Commercial Computer Software Restricted Rights and 48 CFR 52.2270-19, as applicable.