This document explains how to use the OpenCloud Scenario Editor to create scenario definitions, for use with the OpenCloud Scenario Simulator.

Topics

Getting Started

explains how to start the editor, and reviews the components of the main Scenario Editor interface.

Editing Scenarios

describes how to create and edit a scenario, its roles, dialogs, and messages.

Using the Tools

explains how to use tools included with the Scenario Editor for reviewing protocol and scenario information.

Appendix A — Troubleshooting

documents common problems you may find using the Scenario Editor, and how to resolve them.

Other documentation for the Scenario Simulator, including the changelog and links to downloads, can be found on the Scenario Simulator product page.

Getting Started

Below are basic instructions and command-line options for starting the Scenario Editor.

Basic usage

To start the Scenario Editor, double-click the scenario-editor.bat start script (Windows):

scenario-editor.bat

or by running the following from the command line (Linux/Solaris):

./scenario-editor.sh

The main Scenario Editor window opens and displays an introductory page.

main 1
Note

  • The Scenario Editor automatically loads all available schema libraries from the schemas/ directory.

  • For details on components of the Scenario Editor main interface, please see the Main Interface topic.

  • You can see what a completed scenario looks like, by loading examples from the Help menu.
Tip
…or open scenario-editor.jar

You can also open the Scenario Editor by double-clicking scenario-editor.jar (in Windows or OSX), or by running the following command:

java -jar lib/scenario-editor.jar

Command-line options

From the command line, you can include options with the Scenario Editor, like this:

java -jar scenario-editor.jar [options] [scenarios]

for example

java -jar scenario-editor.jar -m MyScenario1.scen MyScenario2.scen

The Editor opens scenarios specified on the command line when it starts.

Three options are available:

Option Abbreviation What it does 
--help

-h

Displays help on command-line options.

 
--dirty

-d

Marks scenarios loaded from the command line as 'dirty'.

Note Scenarios flagged as 'dirty' can be saved again immediately after being opened. 
--migrate

-m

Tries to migrate scenarios specified to the latest schema version. For example, with Linux, to migrate all scenarios in a directory to CGIN v1.4:

 java -jar scenario-editor.jar -m `find scenarios -iname \*.scen`
Note The migration option opens, updates and saves each specified scenario, without confirmation.
Warning This option was added with v1.4, for batch migration of CGIN v1.3 scenarios to v1.4. It may behave unexpectedly against v1.2 and earlier scenarios.
Important This migration doesn’t detect validation errors it can cause — and it can break your scenarios. Back up your scenarios before using this option!

Main Interface

The main Scenario Editor interface consists of the menubar, toolbar, scenario list, dialog list, message flows, and status panel, as follows:

Menubar

Includes these menus:

  • File — operations such as adding, saving, and printing scenarios

  • Edit — operations such as adding new roles, dialogs, messages, and editing scenario properties

  • Tools — tools such as the Schema Browser and Alias Browser

  • Plugins — plugins supplied by OpenCloud to provide additional formats for scenario creation and export.

  • Help — documentation, build information, and sample scenarios.

1-menu

Toolbar

Buttons for the same functions as the Edit menu.

Can be undocked from the main interface.

2-toolbar

Scenario list

Tabs listing open scenarios.

2a-tabs

Dialog list

The first part of the Call Flow Editor, a list of dialogs in the loaded scenario (this example shows one called SSP-SCP which uses the INAP protocol).

3-dialogs

Message flows

The second part of the Call Flow Editor, for the loaded scenario, shows:

  • roles — named boxes (in this example, SSP-Loadgen and SCP-Rhino)

  • messages — named arrows between the roles (direction indicates direction sent).

Tip Click to select components, double-click to edit, drag to re-arrange, or press Delete to delete — see Editing Scenarios.

The currently selected messages are highlighted with a blue border.

4-flows

Status panel

Shows any problems with the currently edited scenario (in this example the scenario has none).

Errors are marked in red, and warnings are marked in brown.

A scenario with errors cannot be simulated, while a scenario with only warnings can still be simulated.

5-status

Editing Scenarios

To add and edit scenarios, see the following topics:

Creating a Scenario

To create a new scenario:

1

Select New from the File menu, or press Ctrl+N.

A NewScenario<#> tab (numbered sequentially) displays with a new (empty) scenario.

blank_scenario

Warning The warning message in the status panel indicates that the scenario must have 2 or more roles — see Adding and Editing Roles.

2

To name the scenario, select Scenario Properties from the Edit menu, or click Scenario Properties on the toolbar, or double-click the scenario’s name on the tab.

The Editing scenario <scenario name> dialog box displays.

scenario_properties

3

Type over the name (and optionally add a description) for the scenario, and click Apply.

The name displays on the scenario tab.
Tip Next, create roles, dialogs, and messages for the scenario.

Adding and Editing Roles

To create a role:

1

Select Add Role from the Edit menu, or click Add Role on the toolbar.

The Adding New Role…​ dialog box displays.

role_editor

2

Type a name and description for the role, and click Create.

The roles display in the Scenario Editor.

roles_created

Warning The status panel indicates that this scenario needs a dialog — see Adding and Editing Dialogs.
Tip
Editing, re-ordering, and deleting roles

  • To change a role’s name or description, double-click it.

  • To re-order roles, drag them to different positions in the Scenario Editor.

  • To delete a role, click to select it and press Delete, or right click on the role and select Delete from the context menu.

Adding and Editing Dialogs

Warning Dialogs can only be created between existing roles (so before you can create a dialog, you must create at least two roles).

To create a dialog:

1

Select Add Dialog from the Edit menu, or click Add Dialog on the toolbar, or drag between roles lines.

The Adding a New Dialog…​ dialog box displays.

dialog_editor

Tip The dialog color can be used to differentiate between dialogs if you need to create multiple dialogs between the same two roles.

2

Select roles and a protocol from the drop-down lists, type a name and description for the dialog, and click Create.

The dialog displays in the dialog list at the top of the Scenario Editor.

dialog_created
Tip
Editing and deleting dialogs

  • To edit a dialog, double-click it in the dialog list.
    New dialogs automatically populate with a default message based on the protocol
    (in the example, OpenRequest).

See also Adding and Editing Messages.

  • To delete a dialog, click to select it and press Delete, or right click on the role and select Delete from the context menu.

Adding and Editing Messages

Warning Messages can only be created on an existing dialog (so before you can create a message, you must create at least one dialog).

To create a message:

1

Select Add Message from the Edit menu, or click Add Message on the toolbar, or drag between roles lines where a dialog already exists.

The Adding a New Message…​ dialog box displays.

message_editor_interface

Note See Message Editor Interface for descriptions of each part of the interface.

2

Select a Dialog and a Message Type (application context) from the drop-down lists, optionally fill out message content.

Tip See Tips & Tricks to quickly select multiple message elements, drag to create new messages, undo and redo changes, and copy and paste message data.

3

To specify message field values (for fields that take values):

  • double-click the field label, or click the field value in the message tree (at right) and type the value
    argument

  • or (for fields with predefined values) select from the drop-down list.+ argumentdropdown

Tip You can also add and delete some fields, and specify settings for optional and translatable fields.

4

To specify message attributes:

  • click to select an element in the message tree
    field_selection

  • double-click the attribute field in the attributes table (at lower left) and enter a new value.
    attribute_editing

Tip For the exact meaning of each attribute, see the Scenario Simulator documentation. See also Message Display Attributes.
Note Each entry in the attribute table has a tooltip which briefly describes its purpose.
Warning Not all fields support all attribute values.

5

Click Create.

The message displays in the body of the Scenario Editor.

Note All valid messages for the selected dialog display at the top of the Message Type drop-down list.
Warning Message types in red have an invalid application context for the selected dialog.
Tip After creating a message, you can move it between dialogs with the same protocol schema, by editing the value in the dialog dropdown box.
Important Changing the type of a message after creation will destroy all message contents.
(If you need to preserve data after changing the message type, copy and paste it.)
Tip
Editing and deleting messages

  • To edit a message, double-click on it in the message flow list.

  • To delete a message, single click to select it and press Delete.

Message Editor Interface

As shown in Adding and Editing Messages, the Scenario Editor uses a Message Editor interface for adding and editing messages. It consists of information about a message’s dialog and type, a tree of its elements, description and attributes of the selected element, and status of all elements.

Dialog

Dropdown menu of available dialogs.

Note Roles display for the selected dialog, with an arrow showing the direction messages travel (which you can click to change).

dialog

Type

Dropdown menu of available Message Types.

type

Tree

Hierarchy of message elements.

Red fields have validation errors.
Brown fields have validation warnings.
Pink fields have children which have validation errors or warnings.
Grey fields are not present in the scenario.
Black fields are present in the scenario.

tree

Description

Description of the element selected in the message tree.

description

Attributes

Table of attributes for the element selected in the message tree.

Tip Each attribute has a tooltip describing its function.

description

Status

Warnings about any problems with the message definition.

Errors are marked in red, and warnings are marked in brown.

A scenario with errors cannot be simulated, while a scenario with only warnings can still be simulated.

status

Optional and Translatable Fields

Optional fields

Message fields may be optional, which means they can be present or absent in a sent or received message. Standard optional fields have a square checkbox icon to the left of their field name: absent_c

Choice fields

Some optional fields, known as choice fields, allow at most one mandatory choice from any set of choices. These fields have round (instead of square) icons: absent_r

Field states

The state of an optional field determines its COUNT in the scenario definition, whether to include it when sending messages, and how it affects whether to match a scenario in received messages. The following table shows icon settings and their field’s corresponding COUNT in the scenario definition, whether the Simulator will include the field in that state when sending messages, and whether the Simulator will match the scenario for the field in that state when receiving messages.

Icons Setting Count Send Receive

mandatory_c mandatory_r

Mandatory

 
1

Include.

Only match if present.

prohibited_c prohibited_r

Prohibited

 
0

Do not include.

Only match if not present.

optional_c optional_r

Optional

 
0..1

Do not include.

Match if present; otherwise ignore.

(x..y)

Non-standard COUNT
Warning May be valid, but usually causes a validation error in the scenario.
Note For an accurate description of the usage semantics of the COUNT attribute in different circumstances, see the Scenario Simulator documentation.

absent_c absent_r

Absent

Empty icons represent fields which are not present in the scenario definition at all.
Note Mandatory is the default state for new fields.
Tip Click the icon to change between states.

Translatable fields

Translatable fields provide different views of the same raw data. Selecting them will translate the data into the selected view. For a scenario to be valid, one (and one only) of the available translatable fields must be selected, by clicking the diamond icon to the left of the field name: absent_a

Note Usually a translatable field has an 'encoded' form and one or more 'structured' forms.
Tip The selected translatable field for a scenario definition has a filled icon​: mandatory_a

Message Display Attributes

Two message attributes, SHOW MESSAGE and SHOW FIELD, are specific to the Scenario Editor. They are for display only, and do not in any way affect how the Scenario Simulator interprets a scenario.

Attribute

SHOW MESSAGE

SHOW FIELD

Where it appears

On the root message element (such as InitialDP) only.

On non-root message elements only.

What it does if set

Displays all message fields set in the Call Flow Editor.

Displays the selected message element in the Call Flow Editor.

Example
(INAP InitialDP operations)

showmessage

Tip

Certain structural fields (argument and structured) don’t show by default, but can be explicitly displayed with the SHOW FIELD attribute.

You can also also quickly toggle the SHOW MESSAGE attribute from the Call Flow Editor, through the right-click context menu.

showmessagerightclick

showfield

Tip This attribute is useful if you are only interested in showing specific information at the call-flow level (for example, only the CallingPartyNumber address field).

Adding and Deleting Fields

Below are instructions for adding fields, and deleting fields or just field data.

Adding fields

Multiple copies of the same field can exist in some messages. Such fields (for example, array field entries) have the +Add "fieldname" label associated with their parent elements.

Tip

To add copies of a field, click its +Add node.

adding_fields

Like all other greyed out fields, these newly created copies just exist for display and editing — the Scenario Editor does not make them part of an edited scenario until you select or enter data in them.

Deleting field elements

To delete one or more field nodes, select them and press the Delete key.

delete_field1

nav_right_red

delete_field2

The Scenario Editor removes those fields — and all of their child fields — and any data they contain. For example, selecting the root node of a message and then pressing Delete will delete all data contained in the entire message.

Tip

  • You can also delete a field from its right-click context menu:
        right_delete

  • You can delete unwanted copies of a field that supports dynamically added copies (see above).
Note The editor will always display at least one copy of a field, even if it contains no data. This is to allow exploration of the message structure without requiring new fields to be added manually.

Deleting field data

To delete the content of a field (as opposed to the field itself), select a field, right click, and select Delete Field Data from the context menu:

right_delete2

nav_right_red

right_delete3

In the above example, the ISDN value is deleted while leaving all attributes and other properties of the field untouched.

Note Deleting field content can cause validation errors due to missing data, because most fields do not support 'no value'. But deleting field data can be useful for fields populated by the alias or select attributes.

Tips & Tricks

While adding or editing scenarios, you can:

Tip copy and paste callflow and message data
Tip drag between roles to quickly create new dialogs or messages
Tip export dialogs to image files
Tip zoom and scroll around the Callflow Editor
Tip quickly select multiple callflow or message elements
Tip undo and redo changes
Tip use right-click shortcuts.

Copying and Pasting

The Scenario Editor supports copy (Ctrl+C) and paste (Ctrl+V) at both the callflow and message-editing levels.

Tip You can also copy and paste using the right-click context menu in the Message Editor.

Below are instructions for copying and pasting callflows, messages, message field data, and message field location.

Callflows

While editing a scenario callflow, you can copy and paste elements such as roles, dialogs, and messages. What gets pasted depends on what’s selected:

With this selected…​ This gets pasted.. Notes

a single dialog

messages only, into that dialog.
Tip This is useful to quickly copy a large number of messages from one dialog to another.
Warning It is possible to paste messages into a dialog with a different protocol --- which can result in an invalid scenario.

no dialog selected

all copied scenario elements, into the currently selected scenario.
Note If there is a naming conflict between the copied data and existing data (for example, if you try to paste "RoleA" into a scenario which already has a "RoleA"), the Scenario Editor renames the copied data before pasting.
Tip If you copy a message or dialog without selecting associated roles, the Scenario Editor automatically includes them in the copy (to keep the copied data consistent).

Messages

While editing a message, you can copy and paste individual tree nodes --- and their children. For example, selecting a CallingPartyNumber and pressing Ctrl+C copies the entire CallingPartyNumber to the clipboard. You can then paste this data into another message (or the same message elsewhere), by selecting a destination CallingPartyNumber and pressing Ctrl+V.

Warning Pasting overrides the target data. In the example above, if the target had any CallingPartyNumber data, the Scenario Editor would replace it with the data from the clipboard.
Warning Paste operations can result in illegal message structure. It is possible to paste the CallingPartyNumber in a place where it is inappropriate (such as pasting an ETSI INAP LocationNumber into a CallingPartyNumber. This can create illegal field elements that prevent the scenario from validating.

To fix situations like this, either undo the change (Ctrl-Z) or manually delete any illegal field elements.

Tip You can also copy a field element using the right-click context menu: copy-element

Message field data

To copy the field data (contents) instead of the field itself, right-click a field node and select Copy Field Data:

copy-field-data

Copying message field location

To copy a description of the location of a field into the clipboard, right-click a field node and select Copy element location:

element-location

The example above copies this to the clipboard:

[InitialDPRequest -> [1] argument -> [2] callingPartyNumber -> [0] structured -> [4] screening{noformat[

Dragging New Dialogs

When editing the message callflows, you can quickly create dialogs — between roles without an existing dialog — by dragging an arrow from one to the other:

  1. Click and hold the mouse button on the line representing one role.

  2. Drag and release the mouse button on the target role.

drag_creation1

nav_right_green

drag_creation2

The Adding new dialog…​ dialog box displays for you to select the protocol and application context.

drag_creation3

nav_right_green

drag_creation4

The example above shows the creation of a new dialog between RoleA and RoleB.

Tip This method of dialog creation has the added benefit of not requiring you to manually fill out the roles or dialog name — the Scenario Editor automatically names them to match the roles you drag between.
Note If a dialog already exists between those two roles, a New Message dialog box displays instead.

Dragging New Messages

When editing message callflows, you can quickly create messages — between roles which have an existing dialog — by dragging an arrow from one to the other:

  1. Click and hold the mouse button on the line representing one role.

  2. Drag and release the mouse button on the target role.

drag_creation5

nav_right_green

drag_creation6

The Adding new message…​ dialog box displays for you to select the protocol and application context.

drag_creation7

nav_right_green

drag_creation8

The example above shows the creation of a new OpenAccept on an already existing dialog.

Tip This method of message creation has the added benefit of not requiring you to manually select the dialog or send direction — the Scenario Editor automatically determines them by the roles you click and the direction you drag.
Note If a dialog does not already exists between those two roles, a New Dialog dialog box displays instead.

Exporting Dialogs to Image Files

You can export the current scenario to an image (.PNG) file, to use elsewhere:

  1. Select Export to PNG from the File menu.

The exported image file looks exactly like the on-screen representation (including any current selection and validation error coloring).

You can navigate the main Callflow Editor by zooming or scrolling.

To zoom in and out of the main Callflow Editor display, use:

  • menu options — Zoom options in the Edit menu

  • shortcut keys — (Ctrl + +) to zoom in, (Ctrl + -) to zoom out

  • mouse movements - Ctrl + mousewheel up or down to zoom in and out.

To reset the zoom level to the default, using the Reset Zoom option from the Edit menu, or press (Ctrl + 0).

zoom-out

nav_right_red

zoom-in

The Callflow Editor supports drag-based navigation using the middle mouse button:

  • hold the middle mouse button down and then move the cursor.

The mouse pointer changes to a movement icon during the drag operation.

Selecting Multiple Elements

You can use the Shift and Ctrl keys, and click and drag, to select multiple callflow and message elements.

Callflow elements

You can hold down the Shift and Ctrl keys while clicking, or click and drag to select multiple callflow elements. The following examples start with just the gsmSSF role selected in this scenario:

select-scenario

To…​ Do this Example

…​add (or remove) an individual role, dialog, or message to (or from) the selection

Ctrl-click.

ctrl-click-flow

…​select a role, dialog, or message — and all elements associated with it

Shift-click.

shift-click-flow

…​add a role, dialog, or message — and all elements associated with it — to the selection

Ctrl-Shift-click.

ctrl-shift-click-flow

…​select multiple elements

drag a selection lasso around them.

lasso

Message elements

You can hold down the Shift and Ctrl keys while clicking to select multiple message elements:

To…​ Do this

…​select more than one message element

Ctrl-click each.

…​select a range of message elements

click the first element, then Shift-click the last.

shift1

nav_right_green

shift2

Undoing and Redoing Changes

The Scenario Editor supports the undo (Ctrl+Z) and redo (Ctrl+R) edit operations. Each scenario and message edit have separate undo histories.

Warning

When editing messages, only changes to the message elements are undoable — so changes to the message dialog or send direction cannot be undone.

Also, making any changes to the scenario after performing one or more undo operations will discard any redo history that exists.

Using the Callflow Context Menu

The Callflow Editor has right-click context menu support to copy and delete all components. You can also create messages, roles, and dialogs by right-clicking outside any component:

callflow-rightclick

Using the Tools

The Scenario Editor comes with a few tools (available from the Tools menu) for reviewing protocol and scenario information. See:

Using the Schema Browser

The Schema Browser lets you review protocol schemas currently loaded in the Scenario Editor.

1

To open the Schema Browser, select Schema Browser from the Tools menu.

The Schema Browser displays.

schema_browser1

Note

The Schema Browser has three columns:

  • Schemas — loaded schema protocols

  • Application Contexts — application contexts from the selected protocol

  • Messages — operations and responses from the selected protocol.

When you first open the Schema Browser, only the first column is populated (until you select a schema).

2

Click to select a schema.

The Application Contexts and Messages for that schema display.

schema_browser2

3

To view messages for one or more application contexts, click to select the application contexts.

The Schema Browser highlights all messages that can be sent on those application contexts.

schema_browser3

Tip
Shift-click and Ctrl-click to select multiple entries

You can select additional application contexts or operation/responses (see below) by holding Ctrl and clicking (to add individual entries) or Shift and clicking (to add a range of entries).

4

To view application contexts for one or more operations, click to select the operations.

The Schema Browser highlights all application context that can be used for those operations.

Using the Alias Browser

The Alias Browser lets you view all aliases in the currently open scenario.

1

To open the Alias Browser, select Alias Browser from the Tools menu.

The Alias Browser displays.

alias_browser1

Note

The alias browser has two columns:

  • Alias Name — lists aliases in the current scenario

  • Location — shows where to find the selected alias.

2

Click to select an alias.

Message fields associated with that alias display.

alias_browser2

3

To select the message associated with an alias, click the alias in the Location column.

alias_browser3

Tip You can edit messages with aliased fields directly, by double-clicking the alias in the Location column.

Using the Table Editor

Tables are an optional scenario mechanism for storing lists of related information that the Scenario Simulator uses for generation and matching logic.

Tip For more about how to use tables in a scenario (with the SELECT attribute on message fields), see the Scenario Simulator User Guide.

1

To open the Table Editor, select Table Editor from the Tools menu.

The Table Editor displays.

table-editor1

2

To create a new table, click Table.

The Adding new table…​ dialog box displays.

table-editor2

3

Enter a Name and (optionally) a Description for the table, and click Create.

The new table displays in the Table Editor.

table-editor3

Note The asterisk ( * ) after the table name indicates that the table has been modified from the values in the currently loaded scenario.

4

To create a new column for the table, click Column.

The Adding new column…​ dialog box displays.

table-editor4

5

Enter a Name and (optionally) a Description for the column, and click Create.

The new column displays in the Table Editor.

table-editor5

6

Enter table data, and click Apply.

The Table Editor automatically adds new rows when you enter data in a table cell, and removes empty rows at the end of the table.

table-editor6

Note The Table Editor does not apply changes to the tables stored in a scenario, until you click Apply.
Warning

As well as storing table inline (within a scenario), you can import it into the Scenario Simulator from an external CSV at runtime (see the Scenario Simulator User Guide for instructions). Storing table data inline is not recommended for large data sets; and if a table only has header values (and no inline data), table data must be supplied from an external source at runtime.

Appendix A: Troubleshooting

Note

This (hopefully small) section is intended to document common problems you may find using the Scenario Editor, and how to resolve them.

Please use the OpenCloud forums to post any undocumented issues you encounter (or anything else you think belongs in this User Guide!).
Issue Solution

Everything is slow!

High-quality rendering is enabled by default in the Scenario Editor. On some configurations of hardware and software this can result in unacceptably slow performance. The problem can also occur when running the editor over a remote X connection.

To resolve this, uncheck the High-quality rendering option from the Edit menu:

high-quality-rendering