MBSE Model Capture Using Popkin

System Architect

©

version 1.3

January 25, 2000

copyright 1999-2000 Pathfinder Solutions, Inc. all right reserved.

Pathfinder Solutions, Inc.

N

S

W

E

web: www.pathfindersol.com

90 Oak Point Wrentham, Massachusetts 02093 U.S.A

voice: +01 508-384-1392

fax: [phone]

MBSE With Popkin System Architect

Pathfinder Solutions, Inc.

N

S

W

E

1

Introduction

This document describes how to use Popkin’s System Architect

©

(version 6.6.2+) to create U ML™

models that can be processed by Pathfinder Solutions’ Springboard translation engine. The semantic
information captured in the models can be translated by Springboard into formatted documentation or
compilable source code.

The following sections take you step by step from installing System Architect with Pathfinder Solutions’
customizations through creating and maintaining a translatable model.

This document assumes that the reader is familiar with "Model-Based Software Engineering - An
Overview o f Rigorous and Effective Software Development using UML



" available from

www.pathfindersol.com.

Product Installation

•

Use the installer program on the Popkin product CD to install System Architect. The installer allows
you to choose the directory you would like to install the product in.

•

Next, copy the Pathfinder Solutions provided usrprops.txt, pfdreadme.txt, pfd_fmt6.bas, usrprops.txt,
and fmtscrpt.bas files into the product directory. These files customize System Architect dialogs and
model semantics to provide Pathfinder Solutions specific diagram content and data entry fields.

•

in a networked installation, install a copy of the license manager and SYSNET utilities on the license
server node, and install the System Architect editor on each analyst/develo per's workstation. Be
sure to copy Pathfinder customization files to each System Architect editor installation

Encyclopedia Creation

System Architect stores all diagram, data dictionary, and description files into a single directory referred
to as an encyclopedia. Before model entry can begin, an encyclopedia must be created:

•

Create: to create a new encyclopedia, select File -> Open Encyclopedia … (or click the Open
Encyclopedia icon from the toolbar). Select the 'New' tab, and specify the desired direct ory path.

•

Property Configuration: when prompted to set the property settings defining the overall
organization of the diagrams that are going to be stored in the encyclopedia, you need only select
UML in the Object Modeling group. Set both Target Databases and Target Language(s) to '(none)'.
No other modeling types need be selected. When deselecting 'Stuctured A/D' choices, do them
bottom-up. Note that none of the 'Other useful diagrams' cannot be deselected until all of the
'Structured A/D' diagrams have been deselected. You may also choose to make these settings the
default for all future created encyclopedias.

•

Encyclopedia subdirectories: during the course of modeling, four subdirectories will be
automatically created under the encyclopedia directory:

•

dom_services – contains domain service action language text files.

•

obj_services – contains object service action language text files.

•

state_actions – contains all state action language text files.

•

types – contains user defined type declaration files.

(NOTE – on some installations, a defect prevents the automatic creation of these directories. Please
create them manually if you encounter an error during action editing, or if the action edit menu item
is not enabled.)

•

Encyclopedia Open: click the toolbar Encycl opedia Open icon to open an existing encyclopedia.
Specify the encyclopedia directory when prompted.

MBSE With Popkin System Architect

Pathfinder Solutions, Inc.

N

S

W

E

2

Encyclopedia Merging and Reorganizing

•

The Encyclopedia Merge and Encyclopedia Extract commands can be used to combine or merge
individual contributions into one master encyclopedia. They differ only in the direction of the merge –
Merge reads data into this encyclopedia, whereas Extract writes data into another encyclopedia.
Even in a networked installation it is recommended that each domain team use a se parate
encyclopedia, and submit their work to Integration via Merge/Extract.

•

Extract: The Tools/Extract command is used to select diagrams and/or data dictionary items from
the current encyclopedia and to merge them into another specified encyclopedia. Th e current
encyclopedia is the default source encyclopedia.

•

Merge: The Tools/Merge command is used to select diagrams and/or data dictionary items from an
encyclopedia other than the current one, and to merge them into the current one.

•

Reorganize: The Tools/Reorganize command restructures/compacts the encyclopedia databases
and improves tool performance. We suggest reorganizing your encyclopedia on a weekly basis.

Global Modifications

There are three kinds of Global modifications that can be made: renam ing a Definition, renaming a
Diagram, and changing free-form text (e.g. description text)

To rename a definition, find the appropriate type of definition by clicking on the '+' in front of Definitions
in the Browse pane. Click on the '+' in front of that definition type to see definitions of that type. Open the
definition, and modify the name.

To rename a diagram, open the diagram, select Edit -> Diagram, and modify the name.

Finally, to change free -form text, select Tools -> Global Change -> Free Form Text. Ensure that the
Definition Type is '(any)'. Indicate the appropriate From and To. Also check 'Confirm', and you can
decide for each potential change whether to proceed or skip. Afterwards you have a record of the
process.

PLEASE NOTE - these global changes do not update the Action Model files in the dom_services,
obj_services, and state_action subdirectories.

Diagram Documentation Blocks

All diagrams should have documentation blocks to record for example author and version information.
The method is the same for all System Architect diagrams you will be working with.

•

Select Doc Block from the tool palette and click on the class diagram. Right click on the doc block
and choose Edit. Enter descriptive text (e.g. author, version info) in the Modify Sym bol dialog. Click
Ok. Note that the current date and time is automatically reflected in the document block
corresponding to the last time the diagram file was saved.

General Popkin Storage Mechanics

System Architects stores 3 basic classes of items:

-

diagram: these contain symbols and their graphics, are stored in a.DGX file and can be made
available via a .WMF file.

-

symbol: a symbol appears on a diagram, and is associated with its definition via it's name.
(Note: symbols without names cannot have a defi nition). All symbols have a "graphic comment"

MBSE With Popkin System Architect

Pathfinder Solutions, Inc.

N

S

W

E

3

-

definition: some definitions are associated with diagram symbols (like a Analysis Class) and
some are not (like an Analysis Attribute). Typically Design properties are associated with a
definition.

MBSE With Popkin System Architect

Pathfinder Solutions, Inc.

N

S

W

E

4

Domain Model

•

Create: Select File -> New Diagram, or click the New Diagram toolbar icon. From the New Diagram
dialog select diagram type UML Class, enter the system name and click Ok.

•

Add Domain: Domains are represented on the Domain Model as Analysis Domains.

•

Click the tool palette Analysis Domain icon and click on the UML Class diagram to place the
Analysis Domain where desired.

•

Enter the domain name and click Ok.

•

Hit the Esc key and double click on the package symbol. Enter a domain definition and prefix on
the Introduction tab. Select the Domain Coloring tab to choose Domain properties.

•

If using a single encyclopedia for an entire system then set Location to “system
encyclopedia” (default). Otherwise, set the Location to “subdirectory ”, which assumes the
domain is in a separate encyclopedia, located in a direct subdirectory of this encyclopedia
with the same name as the domain PREFIX under the directory containing the system
encyclopedia or
type the full directory path to the domain if it is in a separa te encyclopedia located elsewhere
(possibly on a remote disk).

•

Click the IE Enabled checkbox if you’d like to use Instrumented Execution to later
dynamically test your analysis. This is equivalent to instructing a compiler to create a debug
version of a program.

•

Click Ok.

•

Add Bridges: Bridges are represented as dependencies between Analysis Domains.

•

Click the tool palette Dependency icon.

•

Click on the client Domain symbol.

•

Click on the server Domain symbol.

•

Press enter to leave the name of the Dependancy blank.

•

Click OK on the dialog shown.

•

If the dependency lines are not being drawn diagonally you can adjust the line style by selecting
Format/Symbol Style/Line and choosing “Straight – any orientation”.

•

Add Domain Service: Services can be added on the Services tab of the domain’s definition dialog.

•

Double click on the package symbol.

•

Select the Services tab.

•

Enter the service name next to the Add button then click Add and then Define.

•

Enter a service description in the Description text box.

•

Enter the service return value data type as appropriate

•

To add service parameters: Enter a parameter name next to the Add button then click Add and
then Define.

•

On the parameter definition dialog enter a description, a data type, and select a parameter
mode (input, output, input/output). Click Ok. Type the name of the next parameter if
appropriate.

•

Click Ok on each open dialog when done defining services.

MBSE With Popkin System Architect

Pathfinder Solutions, Inc.

N

S

W

E

5

Scenario Model

Scenario Modeling is a powerful mechanism, either at the system level (where you document the
interactions among domains), or at the domain level (where you document the interactions among the
classes in this domain).

Scenario models are represented in UML™ by either sequence or collaboration diagrams. Unlike the
other diagrams you will create, the scenario diagrams are only linked by name to the system or domain,
and are not utilized by Springboard when translating a UML model to source code. As a result, scenario
diagrams are not affected by global updates and must be manually maintained by the m odeler.

System Architect automatically creates both a sequence diagram and a collaboration diagram for you
when you create either one. However th collaboration diagram must be manually laid out for readability
after you create the corresponding sequence diagram.

•

Creating a Sequence Diagram: Click on the New Diagram toolbar icon, select UML Sequence and
enter a diagram name. Typically, these are named <System name>.<Scenario name> or <Domain
name Click Ok.

•

Describe the Scenario: Add a Note to capture the detailed Preconditions for the scenario,
another Note for expected Postconditions, and a third note for a general Description.

•

Add Domain Entity: To add a domain select “Object” from the tool palette and click on the
diagram. Enter the domain prefix as t he object name and click Ok. In the follow -on dialog, enter
“domain” for the “Instance of (Class)”.

•

Add Analysis Class Entity: To add a Class select “Object” from the tool palette and click on the
diagram. Enter the class name as the object name and clic k Ok. In the follow -on dialog, enter
“class” for the “Instance of (Class)”.

•

Add Interaction: To add an interaction between entities, select Analysis Interaction from the tool
palette and click on the sending entity’s vertical line symbol, move the mouse t o the receiving
entity’s vertical line symbol and click. Enter the appropriate interaction name and click Ok, Ok.

•

Modifying Entity and Interaction Names: Right click on the symbol and select Edit. Edit the
Name and click Ok.

•

Creating a Collaboration Diagram: Click on the New Diagram toolbar icon, select UML
Collaboration and enter a diagram name. Click Ok.

•

Add Domain Entity: To add a domain select “object” from the tool palette and click on the
diagram. Enter the domain prefix as the object name and cl ick Ok. In the follow -on dialog, enter
“domain” for the “Instance of (Class)”.

•

Add Analysis Class Entity: To add an Analysis Class select “object” from the tool palette and
click on the diagram. Enter the class name as the object name and click Ok. In t he follow-on
dialog, enter “class” for the “Instance of (Class)”.

•

Add Interaction (no link): To add an interaction between entities with no existing link, select
Link from the tool palette and click on the sending entity’s symbol, move the mouse to the
receiving entity’s symbol and click. Enter a sequence number, an Event/Operation, and click
Add. To add additional interactions on this link, click new and enter the new sequence and
Event/Operation information.

•

Add Interaction (existing link) : Right click on the link symbol and choose Associative. Enter
interaction(s) as described in the previous bullet.

MBSE With Popkin System Architect

Pathfinder Solutions, Inc.

N

S

W

E

6

Information Model

•

Create: With the Domain Chart open, right click on the domain to be developed and select “Child
Create”. Ensure that diagram type selected is “UML Class” and the domain name is displayed in the
Child Create dialog. Click Ok.

•

Add Class: Select AnalysisClass from the tool palette and click on the class diagram. Enter the
class name. Click Ok. To add a class description, keyletters, and attributes hit the Esc key and
double click on the just added class symbol.

•

Enter class description in the Description text box.

•

Enter class keyletters in the prefix text box.

•

To add class attributes: enter the attribute name next to the Add button th en click Add and then
Define.

•

On the attribute definition dialog enter a description and a data type. If you would like to
specify Design properties to this attribute, select the Attribute Coloring tab. Otherwise click
Ok.

•

Use the attribute properties dialog as outlined in your Design Analyst's Guide.

•

Any non-built-in data type referenced must be defined as a user -defined type at the system
or domain level, or put in the file <System>,typ.

•

Modifying Existing Class: To modify any information associated wi th a class just double click on
the class symbol that you would like to modify. Enter the new information in the dialogs as described
above in adding a new class.

•

Add Binary Association: Select Analysis Association from the tool palette and click on one of the
participating classes. Move mouse to other participating class and click. Enter a name (“An” where
n is a unique-withinthis-domain integer) and click Ok. In the Association dialog enter:

•

multiplicity: select the appropriate multiplicity from th e selection box next to each participating
class name.

•

roles: enter the optional role names as appropriate to this association. Click Ok.

•

description: Hit the Esc key and double click on the association symbol. Enter a description in
the Description text box.

•

relationship coloring: specify Design-specific properties on the Relationship Coloring tab.

•

Modifying Binary Associations: To modify multiplicity or role phrases, right click on the association
symbol and choose Associative. To modify the description or properties double click on the
association symbol as described above in Add Binary Association.

•

Add Sub/Super Association: Select Analysis Inherits From from the tool palette and click on one of
the sub-type classes. Move mouse to the supertype class and click. This must be done for each
subtype in the hierarchy. To enter a name and description hit the Esc key and:

•

Name: choose a subtype “leg” and right click and select Edit. Enter a name (“Sn” where n is a
unique-within-this-domain integer) and click Ok.

•

Description: double-click on one of the “legs” and enter a description in the Description text
box. Click Ok.

•

Modifying Sub/Super Associations: Additional subtypes can be added anytime. Add all additional
subtypes and then select a named subtype "leg". Double-click on it, and press control-c to copy the
sub/super description. Expanding Definitions, find Analysis Inherits From, and expand that. Right
click the sub/super association, and choose Delete. Press Yes on the following dialog. Follow the
instructions in the above Add Sub/Super Association section. Double-click on any "leg", and type the
name ("Sn") again, and with the cursor in Description, press control-v to paste in the sub/super
description. Names and descriptions can be changed anytime also by following the above
instructions.

•

Associative Associations: Once the two participating classes, the associative class, and the binary
association between the participants have been created the connection between the associative
class and the association can be created as follows:

•

Simultaneously select the associative class and binary association symbols.

•

Then from the Draw menu choose Link with Association.

MBSE With Popkin System Architect

Pathfinder Solutions, Inc.

N

S

W

E

7

Information Model, cont.

•

Adding Class Services: Services can be added on the Services tab of the class definition dialog.

•

Double click on the class symbol.

•

Select the Services tab of the class definition dialog.

•

For each service, enter the service name next to the Add button then click Add and then Define.

•

Enter a service description in the Description text box.

•

To add service parameters: enter a parameter name next to the Add button then click Add and
then Define.

•

On the parameter definition dialog enter a description and data type, and select an
appropriate parameter mode (input, output, input/output).

•

If the service is instance -based, select the Coloring tab and mark it so. Click Ok.

•

Click Ok on each open dialog when done defining services.

State Modeling

•

Create: With the Information Model open, right click on the class to b e state modeled and select
“Child Create”. Ensure that diagram type selected is “UML State” and the class name is displayed in
the Child Create dialog. Click Ok. When the dialog showing Class Name as 'state model shadow'
and the correct Analysis Class Name displays, click Ok.

•

Add state: Select Initial State, Analysis State, or Final State as appropriate from the tool palette and
click on the state diagram. Enter the state name (frequently a gerund) and click Ok in the Add
Symbol dialog. Note: for initi al and final states leave the name field blank and just click Ok.

•

Add/modify action summary

: Hit the Esc key and double click on the state symbol in the diagram.

Enter the action summary text in the action summary text box. Click Ok.

•

Layout NOTE: The state symbols grow to accommodate the action summary text so do not add
transitions before entering the action summaries or alternatively, leave enough room between the
state symbols to account for potentially large state action summaries.

•

Modify State Name: Right click the state symbol and select Edit to access the state name.

•

Listing Ignored Events: Double click on the state symbol. Add the events to ignore as appropriate
to the Ignore events list box. Click Ok when done adding ignored events.

•

Adding Transitions : Select Transition from the tool palette and click on the state transitioning from.
Move the mouse to the state transitioning to and click. Enter the associated event name or click
Choices and drag an existing event name to the Name entry fie ld and click Ok, Ok and hit the Esc
key.

•

Define Event : To define the event and optionally add event parameters double click on the transition
line and enter the event description in the event description text box.

•

To add each event parameter: enter a par ameter name next to the Add button then click Add
and then Definition.

•

On the parameter definition dialog enter a description and data type and click OkEnter the next
parameter if appropriate.

MBSE With Popkin System Architect

Pathfinder Solutions, Inc.

N

S

W

E

8

Action Modeling

Action modeling (for states and services) cr eates text files in subdirectories of the encyclopedia directory
as described in the Encyclopedia Creation section of this document. You may choose your favorite
editor to associate with the .pal action language text files.

•

Choosing editor for .pal files: In Windows Explorer, choose View/Options/File Types.

•

Click on New Type.

•

In the New Type dialog, enter the file extension PAL and under the action box click New.

•

In the New Action dialog enter the action “open” and specify the full path name of the edito r
program you would like to use for editing action text files.

•

Click Ok to close each open Explorer dialog.

•

Creating/editing action language files: The mechanism to both create and edit action language
files is via the Tools/Action Edit menu choice. Depe nding on which type of diagram is currently
open, whether or not the files are already in existence, and whether or not you have selected a
particular symbol or not defines what the tool does when this selection is made.

•

Domain Chart: Selecting Tool/Service Action Edit with a Domain Chart open will cause the tool
to pop up the dom_services subdirectory window with a file created for each domain -level
service you have defined. If a particular domain is selected and the service action files have not
been created yet then the tool will create action language files for the selected domain only.

•

Information Model: Selecting Tool/Service Action Edit with an Information Model open will
cause the tool to pop up the obj_services subdirectory window with a file c reated for each object-
level service you have defined. If a particular class is selected and the service action files have
not been created yet then the tool will create action language files for the selected class only.

•

State Model: Selecting Tool/State Action Edit with a State Model open will cause the tool to pop
up the state_actions subdirectory window with a file created for each state you have defined. If a
particular state is selected when the menu selection is made the action language file for the
selected state will be created if it doesn’t exist, and it is opened in your selected editor. Refer to
Pathfinder Solutions Waypoint 6 and/or our Action Language Reference Guide for specifics on
Action Language syntax.

•

NOTE 1: If the tool does not creat e files as described above (some NT installations may be
missing a system DLL), first manually create empty dom_services, obj_services, and
state_actions subdirectories and use Explorer to select files to edit.

•

NOTE 2: If there is no Tools -> Action Edit, then the feature has not been repaired yet.

MBSE With Popkin System Architect

Pathfinder Solutions, Inc.

N

S

W

E

9

REFERENCES

For additional technical support, please call Pathfinder Solutions at 888 -OOA-PATH (888-662-7248) or
+01-508-384-1392, email us at [e-mail], or visit us at www.pathfindersol.com.

You may wish to refer to the following sources:

on the UML



:

"The Unified Modeling Language User Guide", Grady Booch, James Rumbaugh, Ivar Jacobson,

Addison Wesley, 1999; ISBN 0-201-57168-4

"UML Distilled", Martin Fowler, Addison Wesley, 1997; ISBN 0 -201-32563-2

"UML Summary Version 1.1", Object Management Group, Inc. 1997 (this paper is available from

www.omg.org)

on MBSE:

"Model-Based Software Engineering - An Overview of Rigorous and Effective Software
Development using UML



" version 1.3, Pathfinder Solutions, December 3, 1999 (this document is

downloadable from www.pathfindersol.com)

on Popkin System Architect:
Refer to the online help Quick Start as well as the context sensitive help provided throughout the tool.

on Springboard:

“Springboard User’s Guide Version 3.07”, Pathfinder Solutions, June 2, 1999 (this document is
downloadable from www.pathfindersol.com)

UML



is a trademark of Object Management Group, Inc in the U.S. and other countries.