MapleMBSE 2024.1 User's
Guide

Copyright © Maplesoft, a division of Waterloo Maple Inc.
2024

MapleMBSE 2024.1 User's Guide
Copyright
Maplesoft, MapleMBSE, and Maple are all trademarks of Waterloo Maple Inc.
© Maplesoft, a division of Waterloo Maple Inc. 2024. All rights reserved.
No part of this book may be reproduced, stored in a retrieval system, or transcribed, in any form or by any means— electronic, mechanical, photocopying, recording, or otherwise. Information in this document is subject to change
without notice and does not represent a commitment on the part of the vendor. The software described in thisdocument is furnished under a license agreement and may be used or copied only in accordance with the agreement.
It is against the law to copy the software on any medium except as specifically allowed in the agreement.
Microsoft, Excel, and Windows are registered trademarks of Microsoft Corporation.
Oracle, Java, and JRE are registered trademarks of Oracle and/or its affiliates.
IBM, Rational, and Rhapsody are trademarks or registered trademarks of International Business Machines Corp.,
registered in many jurisdictions worldwide.
Teamwork Cloud, Cameo Systems Modeler, and MagicDraw are registered trademarks of No Magic, Inc.
Eclipse Capella and Capella are trademarks of The Eclipse Foundation.
All other trademarks are the property of their respective owners.
This document was produced using Maple and DocBook.

Contents
Introduction .................................................................................................. ix
1 Getting Started with MapleMBSE .................................................................... 1
1.1 MapleMBSE Components ........................................................................ 1
Supported Model Formats ........................................................................ 4
1.2 Launching MapleMBSE ........................................................................... 4
Launching from Command Line ................................................................ 6
1.3 Using MapleMBSE Specific Functions ....................................................... 7
Reload/Update Model Spreadsheet ............................................................. 8
Exporting and Importing Excel Files .......................................................... 8
Saving a Copy of the Current Model ........................................................... 9
Merging All Syncviews ............................................................................ 9
Restart MapleMBSE .............................................................................. 10
1.4 Saving the Model .................................................................................. 11
1.5 Refreshing the Model ............................................................................ 12
1.6 Closing MapleMBSE ............................................................................. 12
1.7 MapleMBSE Version Information ............................................................ 13
1.8 Using the No Magic Teamwork Cloud Adaptor ........................................... 13
Launching the No Magic Server in MapleMBSE ......................................... 13
Installing No Magic Libraries .................................................................. 14
Updating the Configuration file to Ensure Library Compatibility .................... 16
Logging in to CATIA No Magic server ...................................................... 16
Setting up SSL Certificates ..................................................................... 20
Caching Model Files .............................................................................. 20
The Commit Number Information in the Workbook Title Bar and Status Bar .... 21
Editing and Saving Changes to Your Model ................................................ 22
Automatically Saving Model Changes ....................................................... 25
Creating a new No Magic Server Branch ................................................... 26
Accessing an Arbitrary Commit of a No Magic Server Project ....................... 26
No Magic Server Notification .................................................................. 28
Reloading Your Model from the No Magic Server ....................................... 29
1.9 Using the Eclipse Capella Adaptor ........................................................... 31
Launching the Capella Model in MapleMBSE ............................................ 31
1.10 Using the Capella Adaptor for Team for a Capella Model ........................... 32
Launching the Team for Capella Model .................................................... 32
Editing and Saving changes to your model ................................................ 33
Validation Error during Commit to Team for Capella ................................... 34
2 Editing the Model Spreadsheet MapleMBSE .................................................... 37
2.1 Workbook and Layout ............................................................................ 37
2.2 Operations Overview ............................................................................. 40
Allowed Operations ............................................................................... 42
Editing Operations That Will Result in a MapleMBSE Error Message ............. 43iii

iv • Contents

Operations That Could Negatively Change the Mapping between MapleMBSE
and the Model Element ........................................................................... 43
2.3 Adding Model Elements ......................................................................... 43
Field Modifiers ..................................................................................... 45
Nested Elements ................................................................................... 47
Alternative Groups ................................................................................ 50
2.4 Sorting Records .................................................................................... 55
2.5 Deleting Model Elements ....................................................................... 58
Deleting Records with References ............................................................ 60
2.6 Modifying Model Elements .................................................................... 60
Field Types .......................................................................................... 60
Record State ......................................................................................... 62
Example of Using Different Fields When Adding Elements ........................... 62
Modifying Attribute Fields in Unbound Records ......................................... 66
Modifying Reference Fields in Unbound Records ........................................ 68
Modifying Attribute Fields in Bound Records ............................................. 69
Data type conversion ............................................................................. 72
Modifying Reference Fields in Bound Records ........................................... 76
Unmapped Fields .................................................................................. 79
2.7 Locking Elements in a Worksheet ............................................................ 81
Acquiring Locks While Editing ................................................................ 82
Failure to Acquire Locks ....................................................................... 82
Committing Changes and Cleaning Up Code .............................................. 83
Working with Other Dependencies ........................................................... 84
2.8 Other Editing Operations in Excel ............................................................ 84
CutCopy Mode ..................................................................................... 84
Cell Formatting .................................................................................... 84
Undo/Redo .......................................................................................... 84
2.9 File Attachments in the SyncView Area of a Worksheet ................................ 85
2.10 Opening a Model Diagram .................................................................... 86
Viewing SVG Files ................................................................................ 86
2.11 Formula Evaluation ............................................................................. 87
The Instance Matrix ............................................................................... 87
Executing Calculations in the Worksheet ................................................... 89
Changing the Value of the Inputs in the Instance Matrix: ............................... 89
Adding Additional Instance Specifications to the Instance Matrix ................... 90
Sharing Instances .................................................................................. 91
3 Default Value Generation in a Column ............................................................. 93
3.1 Introduction ......................................................................................... 93
3.2 Default Value Generation and Requirements IDs ......................................... 93
3.3 Limitations .......................................................................................... 93
A Log Files ................................................................................................... 95
A.1 Description of Log Files ........................................................................ 95

Contents • v

A.2 Using a Log File to Identify a Problem ..................................................... 95
A.3 VBA Logging ...................................................................................... 96
B Error Messages and Troubleshooting .............................................................. 97
B.1 Error Messages When Starting MapleMBSE .............................................. 97
B.2 Error Messages Displayed When Attempting to Alter the SyncView Table ...... 97
B.3 Error Messages Displayed When Editing the Model Spreadsheet ................... 98
B.4 Error Messages When Editing (Unhandled Exception/An Internal Error Occurred) ..................................................................................................... 98
B.5 Warning Messages for Remaining Memory ............................................... 99
B.6 Troubleshooting ................................................................................... 99
Changing the Java Heap Size ................................................................... 99
Index ........................................................................................................ 101

vi • Contents

List of Figures
Figure 1.1: A Visual Summary of How MapleMBSE Works .................................... 2
Figure 1.2: Relationship Between Model, In-Memory Model, and Spreadsheet ............ 3
Figure 1.3: Model Information Inserted ................................................................ 5
Figure 1.4: Error While Attempting to Run More Than One Model at a Time .............. 6
Figure 1.5: MapleMBSE Ribbon Menu ................................................................ 8
Figure 1.6: Reminder to Close Excel Instances Before Restarting MapleMBSE .......... 12
Figure 1.7: Commit Information Displayed in Title Bar ......................................... 21
Figure 1.8: Commit Information Displayed in Status Bar ....................................... 21
Figure 2.1: Vertical Table ................................................................................. 38
Figure 2.2: Horizontal Table ............................................................................. 38
Figure 2.3: Dependency Matrix ......................................................................... 39
Figure 2.4: Data Elements Displayed By MapleMBSE .......................................... 41
Figure 2.5: SyncView Areas Displayed in Name Box ............................................ 41
Figure 2.6: Highlighting SyncView Cell Range .................................................... 42
Figure 2.7: Entering Information in Insertion Area ............................................... 44
Figure 2.8: Inserting a Row in the SyncArea ....................................................... 44
Figure 2.9: Defining a Nested Structure in the NestedElements spreadsheet ............... 47
Figure 2.10: Defining Package1 ........................................................................ 48
Figure 2.11: Defining Class1 ............................................................................ 49
Figure 2.12: Defining Property1 ........................................................................ 50
Figure 2.13: Alternative Groups Example Model .................................................. 51
Figure 2.14: Defining Package1 ........................................................................ 52
Figure 2.15: Defining Class1 ............................................................................ 53
Figure 2.16: Defining Package2 ........................................................................ 54
Figure 2.17: Defining Class2 ............................................................................ 55
Figure 2.18: Deleting the Class1 Element from the Model ...................................... 59
Figure 2.19: Deleting Package1 and Associated Elements ...................................... 59
Figure 2.20: Illustration of Main Types of Fields in SyncView ................................ 61
Figure 2.21: Adding Elements to a SyncView with Different Types of Fields ............. 62
Figure 2.22: Defining Package1 ........................................................................ 63
Figure 2.23: Defining Class1 ............................................................................ 63
Figure 2.24: Defining Class2 ............................................................................ 64
Figure 2.25: Creating New Bound Records ......................................................... 65
Figure 2.26: Defining the Type ......................................................................... 66
Figure 2.27: Modifying Existing Elements in Unbound Records Results in the ManuallyEntered Values Being Overwritten ..................................................................... 67
Figure 2.28: Adding New Elements to a Model .................................................... 68
Figure 2.29: Values Entered in Nonkey Reference Fields and No Key Reference Fields
Defined ........................................................................................................ 69
Figure 2.30: Values Entered in Nonkey Reference Fields with Key Reference Fields
Defined ........................................................................................................ 69

vii

viii • List of Figures

Figure 2.31: Modifying a Key Attribute Field ...................................................... 70
Figure 2.32: Modifying a Nonkey Attribute Field ................................................. 71
Figure 2.33: Deleting the Value of a Key Field Attribute ........................................ 71
Figure 2.34: Deleting the Value of a Nonkey Field Attribute ................................... 72
Figure 2.35: Example of a MapleMBSE Configuration that Accepts Arrays of Elements
in a Single Cell .............................................................................................. 76
Figure 2.36: Changing Value of Reference Key Field, Property Type ....................... 77
Figure 2.37: Changing Value of Reference Nonkey Field, Type Visibility .................. 77
Figure 2.38: Deleting Value of a Reference Key Field ........................................... 78
Figure 2.39: Deleting Value of a Reference Key Field ........................................... 78
Figure 2.40: Unmapped Fields .......................................................................... 79
Figure 2.41: Entering a Value for Package Name Results in Updated Mapped
Fields .......................................................................................................... 79
Figure 2.42: Formulas Must be Updated Manually ............................................... 80
Figure 2.43: With the SyncView Extended, Key Fields Need to be Filled .................. 80
Figure 2.44: Defining Class1 Inside of Package1 ................................................. 80
Figure 2.45: Defining Package2 Inside of Package1 .............................................. 81
Figure 2.46: Defining Class2 Inside of Package2 .................................................. 81
Figure 2.47: MapleMBSE Attempts to Acquire Locks When Element is Being
Changed ....................................................................................................... 82
Figure 2.48: Failure to Lock Model Elements Error Message .................................. 83
Figure 2.49: Manually Releasing Locked Element ................................................ 83
Figure 2.50: CutCopy Mode ............................................................................. 84

Introduction
MapleMBSE Overview
MapleMBSE™ gives an intuitive, spreadsheet based user interface for entering detailed
system design definitions, which include structures, behaviors, requirements, and parametricconstraints.

Related Products
MapleMBSE 2024 requires the following products.
• Excel 2016, Excel 2019 or Excel Office 365 desktop• Oracle® Java® SE Runtime Environment 8.
Note: MapleMBSE looks for a Java Runtime Environment in the following order:
1) If you use the -vm option specified in OSGiBridge.ini (not specified by default),
MapleMBSE will use it.
2) If your environment has a system JRE ( meaning either: JREs specified by the environment
variables JRE_HOME and JAVA_HOME in this order, or a JRE specified by the Windows
Registry (created by JRE installer) ), MapleMBSE will use it.
3) The JRE installed in the MapleMBSE installation directory.
If you are using CATIA No Magic Server with MapleMBSE, the following versions aresupported:• Teamwork CloudTM server 2021.x, 2022.x and 2024.x• Magic Collaboration Studio 2021.x, 2022x and 2024.x
If you are using Eclipse CapellaTM with MapleMBSE, the following version is supported:• 6.0
If you are using EclipseTM, the following version is supported:• 2024-3ix

x • Introduction

Related Resources
Resource

MapleMBSE Installation
Guide

Description
System requirements and installation instructions for
MapleMBSE. The MapleMBSE Installation Guide is available
in the Install.html file located in the folder where you installed
MapleMBSE, or on the website.

https://www.maplesoft.com/documentation_center/
MapleMBSE Applications Applications in this directory provide a hands on demonstrationof how to edit and construct models using MapleMBSE. They,
along with an accompanying guide, are located in the Application
subdirectory of your MapleMBSE installation.
MapleMBSE Configuration This guide provides detailed instructions on working withGuide
configuration files and the configuration file language.
Frequently Asked
You can find MapleMBSE FAQs here:
Questions
https://faq.maplesoft.com
Release Notes
The release notes contain information about new features, known
issues and release history from previous versions. You can findthe release notes in your MapleMBSE installation directory.

For additional resources, visit http://www.maplesoft.com/site_resources.

Getting Help
To request customer support or technical support, visit http://www.maplesoft.com/support.

Customer Feedback
Maplesoft welcomes your feedback. For comments related to the MapleMBSE productdocumentation, contact doc@maplesoft.com.

1 Getting Started with MapleMBSE
In this chapter:• MapleMBSE Components (page 1)• Launching MapleMBSE (page 4)• Using MapleMBSE Specific Functions (page 7)• Saving the Model (page 11)• Closing MapleMBSE (page 12)• Using the No Magic Teamwork Cloud Adaptor (page 13)• Using the Eclipse Capella Adaptor (page 31)

1.1 MapleMBSE Components
MapleMBSE provides a platform that you can use to map model information from diagrambased models into a table form. The diagram-based models may be models defined in UML
or SysML or other formats specific to modeling tools. For the list of supported model formats
see Supported Model Formats (page 4).
The figure below shows the components that MapleMBSE works with and how they relate
to each other.

12 • 1 Getting Started with MapleMBSE

Figure 1.1: A Visual Summary of How MapleMBSE Works• ModelA model in the file system or on the server that you want to display and edit. See Supported
Model Formats (page 4).
• Spreadsheet
An Excel spreadsheet that is used as a user interface for displaying and editing the modeldata.
• In-Memory Model
When MapleMBSE is started it loads the given model into its internal memory. The datain the spreadsheet is synchronized with this in-memory model.

1.1 MapleMBSE Components • 3• MSE Configuration
The configuration file (.MSE) is created by the user. It provides the rules for how themodel is converted and represented in a spreadsheet. The rules specify the following:
1. How the data is to be extracted from the model and how it should be mapped into a tableformat. The table is shown in green in the Figure above.
2. How and where the extracted table is presented on the spreadsheet. The area of the
spreadsheet representing the table SyncView. The SyncView is shown in green in
Figure 1.1.
You can find detailed instructions about the MSE configuration language in the MapleMBSE
Configuration Language Guide.
• Template
An Excel file with the same name as the MSE configuration file located in the same directory as the MSE configuration file. The file defines formatting such as column width,
headers, etc. for the given configuration file. For details see MapleMBSE Configuration
Language Guide.
The relation between the model file, the model loaded in MapleMBSE's memory, and the
spreadsheet is shown in the diagram below.

Figure 1.2: Relationship Between Model, In-Memory Model, and Spreadsheet

1. MapleMBSE loads the model from the given file into its internal memory.
2. The data from the in-memory model is loaded into the SyncView area of the spreadsheet.
3. User input on the SyncView area is converted into the changes to the in-memory model.
4. Any other places of the same SyncView or other SyncViews that are linked to the updated
element get updated.
5. The changes to the in-memory model are applied to the model in the file system or on
the server only when the spreadsheet is saved.
6. If the changes were made to the model in the file system or on the server they can bereloaded into the in-memory model by invoking Reload/Update, see Using MapleMBSE
Specific Functions (page 7).
Notes:• Simultaneous operations on the same model by MapleMBSE and other tools are notsupported.

4 • 1 Getting Started with MapleMBSE• Modifying the model in other tools while being modified by MapleMBSE is not recommended.
• It is possible that the spreadsheet is set as read-only.

Supported Model Formats
MapleMSBE 2024 supports the following version of the UML model format.
• UML® 2.0 http://www.uml.org.
The following models are supported if the corresponding adaptors are installed.
• IBM® Rational® Rhapsody® with MapleMBSE Rhapsody Adapter• Models on CATIA No Magic Server with MapleMBSE Teamwork Cloud Adapter• Eclipse CapellaTM with MapleMBSE Capella Adaptor

1.2 Launching MapleMBSE
Note: For launching with the No Magic Teamwork Cloud Adapter see Using the No Magic
Teamwork Cloud Adaptor (page 13).
To launch MapleMBSE:
1. From the Start menu, select All Programs > MapleMBSE 2024.
2. Click MapleMBSE 2024.
3. Browse to the location of your MapleMBSE configuration file (configuration files have
an .MSE file extension), select the configuration file, and then click Open.
Tip: If you do not have a configuration file, you can open an appropriate sample configuration file in <Install Directory>\Example\, where <Install Directory> is the install
location of MapleMBSE 2024.
4. Browse to the location of your model file, select the model file, and then click Open.
A progress bar is displayed indicating that the model is loading.

Tip: If you do not have a model file, you can open the sample model file, <Install
Directory>\Example\MechSheet\MechSheet-sample1.tritest, where <Install Directory> is the install location of MapleMBSE 2024, or if you are using Capella, you can
use the .melodymodeller file corresponding to the Inflight Entertainment System modelin your Samples subdirectory .

1.2 Launching MapleMBSE • 5

Microsoft Excel opens with the model information inserted into the spreadsheet (seeFigure 1.3). You can edit the models in the spreadsheet by simply modifying cells and inserting rows, unless the spreadsheet is set as read-only. For a detailed description of how
MapleMBSE displays the model information in the spreadsheet and how to edit different
aspects, see Editing the Model Spreadsheet MapleMBSE (page 37).To save your model
you simply save this Excel file. For saving models opened with the No Magic Teamwork
Cloud Adapter see Using the No Magic Teamwork Cloud Adaptor (page 13). For more information about saving, see Saving the Model (page 11).

Figure 1.3: Model Information Inserted

Note: You can also start MapleMBSE by double-clicking a configuration file from yourfile manager. This skips the configuration file selection step and takes you directly to theOpen Model File dialog.

6 • 1 Getting Started with MapleMBSE

Note: You can only run one instance of MapleMBSE at a time. If you try to open a model
while another one is already opened by MapleMBSE you will get the error shown in
Figure 1.4. You must close the open model before opening a new one.

Figure 1.4: Error While Attempting to Run More Than One Model at a Time

Launching from Command Line
MapleMBSE can be launched from the command line by executing the MapleMBSE.exe
command in the installation directory. The command has the following syntax.
MapleMBSE.exe [/R <memsize>] [/L <logfile>] [/E <excel.exe>] [[/I | CONFIG(*.MSE)][MODEL]]• If you specify CONFIG (must be *.MSE) and MODEL files, it launches MapleMBSE
with these files. If you do not specify a MODEL or CONFIG file, you will be asked forthese files in a subsequent dialog.
• If you specify /I, MapleMBSE.exe will always ask for the MSE file in a dialog and regard
the first non-slash argument as a model file.
• MODEL can be a local file or URI. For example, consider a model file on the Teamwork
Cloud server:= "twc://[SERVER:PORT][/PROJECT][?[username=USERNAME][&password=PASSWORD]][&branch=BRANCHNAME][&revision=REVISION][&cache=true][&ssl=ssl_certificate_name]"
Note: If you omit some items, MapleMBSE will ask for them in the dialog• If you do not specify any file arguments, it checks if MapleMBSE.xlsm exists in the
AddIns directory inside the directory with MapleMBSE.exe. If found, MapleMBSE
launches it.
• /R <memsize>: (optional, default=905) Memory address space in MB to be reserved forJava VM in the Excel process.
• /L <logfile>: (optional, default="MapleMBSE_Launcher.log") Log file name, relative
to %USERPROFILE% or in absolute path.

1.3 Using MapleMBSE Specific Functions • 7• /E <excel.exe>: (optional) Path of EXCEL.EXE
If it's not specified, the registry entries will be used:= HKEY_CLASSES_ROOT\CLSID\<CLSID of "Excel.Application">\LocalServer32= HKEY_CLASSES_ROOT\CLSID\<CLSID of "Excel.Application">\LocalServer= HKEY_CLASSES_ROOT\Wow6432Node\CLSID\<CLSID of "Excel.Application">\LocalServer32= HKEY_CLASSES_ROOT\Wow6432Node\CLSID\<CLSID of "Excel.Application">\LocalServer
Notes:• After you have launched MapleMBSE successfully from the command line, if you want
to restart MapleMBSE, use the shortcut key combination CTRL+Shift+G.
• You can launch MapleMBSE from the command line using &cache=true. For example:
MapleMBSE.exe "C:\Program Files\MapleMBSE 2024\Example\TWC202X\TWCSample.MSE" "twc://teamworkcloud:3579/Model?username=***&password=***&cache=true"

1.3 Using MapleMBSE Specific Functions
To access MapleMBSE specific functions, select the Ribbon menu, and then expand
MapleMBSE. Here you will find the following items:• Reload/Update the Model Spreadsheet• Restart MapleMBSE• Save to Model• Export to Excel file
• Import Excel file
• Save copy as• Merge all syncviews• Update merged syncviews• Evaluate Formulas• MapleMBSE UserGuide• About MapleMBSE8 • 1 Getting Started with MapleMBSE

Figure 1.5: MapleMBSE Ribbon Menu

Reload/Update Model Spreadsheet
You can refresh your current model so that it reflects any changes made to the model outsideof MapleMBSE.
To reload your model:
1. Select Add-Ins > MapleMBSE > Reload/Update.
2. In the Reload/Update dialog window, click OK. Note: Reloading the model may discard
any unsaved changes.
3. A progress bar is displayed as the model reloads.

4. The model is reloaded in the Model Spreadsheet.
Notes:• You can also use the shortcut key combination CTRL+Shift+R to reload your model.
• Simultaneous operations on the same model by MapleMBSE and other tools are notsupported. It is recommended not to modify the model in other tools when it is modified
by MapleMBSE.

Exporting and Importing Excel Files
Select Add-Ins > MapleMBSE > Export to Excel file to save the current worksheet to an
Excel file.
Select Add-Ins > MapleMBSE > Import Excel file to load an Excel file into the model
you currently have open.
A progress bar is displayed as the data is loaded into the model.

1.3 Using MapleMBSE Specific Functions • 9

Saving a Copy of the Current ModelIf you are working with Rhapsody or UML models, you can save the current model to another model file and keep the current model file unchanged. This function allows you totake a snapshot of the model. The in-memory model is still associated with the originalmodel file. Any changes you save after creating the snapshot will only be saved to the original model and not to the snapshot.
To save a copy of the current model:
1. Select Add-Ins > MapleMBSE > Save Copy As.
2. Enter a filename and location.
3. Click Save.

Merging All Syncviews
The syncview merging feature removes the redundancy of the SyncView and improves
readability of the table.
Without merging applied a table looks like this:Notice every dimension displayed.

10 • 1 Getting Started with MapleMBSE

With merging applied, the table is recreated in a non-syncview area in a new table and looks
like this:Notes:• You can select to merge one worksheet at a time, by right-clicking in the worksheet.
• The shortcut key combination CTRL+Shift+L can be used to invoke the syncview merging
feature.

Restart MapleMBSE
Opens another MSE file without closing the MapleMBSE.
To Restart MapleMBSE:
1. Select Add-ins > MapleMBSE > Restart MapleMBSE.
2. In the Restart MapleMBSE dialog window, click Yes. Note: Restart MapleMBSE willclose the current workbook. If you have unsaved changes a dialog will be displayed
asking to confirm that you want to save your changes before closing.

1.4 Saving the Model • 11

3. A dialog box appears where you can browse to the location of your MapleMBSE configuration file (configuration files have a .MSE file extension). Select the configuration
file, then click Open.

4. Browse to the location of your model file, select the model file, and then click Open. A
progress bar is displayed indicating the model is being launched.

Note: For launching with the No Magic Teamwork Cloud Adapter, see Using the No Magic
Teamwork Cloud Adaptor (page 13).
Note: You can also use the shortcut key combination, Ctrl+Shift+M to restart MapleMBSE.

1.4 Saving the Model
Note: For saving models opened with the No Magic Teamwork Cloud Adapter see Using
the No Magic Teamwork Cloud Adaptor (page 13).
There are several options for how model data can be saved:• Save the in-memory model into the model file.
The changes done in a spreadsheet are performed on the in-memory model. To save thechanges from the in-memory model to the model file use any of the Excel's usual optionsfor Saving.
- Select File > Save
- Press Ctrl + S- Click Save icon at the top of the window12 • 1 Getting Started with MapleMBSE• Save the in-memory model as another model file.
To save the in-memory model into another model, File > Save As, enter a filename andlocation, click Save. The in-memory model is then linked to this new model file. Any
future save operations will be performed on this file.
• Save a copy of the model.
See Saving a Copy of the Current Model (page 9) to save a copy of the model and tokeep the in-memory model linked with the original file.
• Save the data as an Excel file.
To save the model data to an Excel workbook file, select Add-Ins > MapleMBSE >Export to Excel file.

1.5 Refreshing the Model
You can refresh all syncviews in your model by using the shortcut key combination
CTRL+Shift+F.
A progress bar is displayed as the model refreshes.

1.6 Closing MapleMBSE
When you close a workbook editing the model, MapleMBSE is also closed. If there is noother open workbook, Excel will also quit. The following dialog opens reminding you toclose all running instances of Excel before you can use MapleMBSE again.

Figure 1.6: Reminder to Close Excel Instances Before Restarting MapleMBSE

All MapleMBSE Excel windows must be closed. The rules for closing Excel windows not
related to MapleMBSE are as follows.

1.7 MapleMBSE Version Information • 13

• Excel workbooks opened before MapleMBSE was launched can stay open.
• Excel workbooks opened after MapleMBSE was launched must be closed.

1.7 MapleMBSE Version Information
To find information about your version of MapleMBSE, select Add-Ins > MapleMBSE >About MapleMBSE

1.8 Using the No Magic Teamwork Cloud Adaptor
The Teamwork Cloud (TWCloud) Adaptor in MapleMBSE allows you to save changes you
have made to your model in the Model Spreadsheet to the CATIA No Magic repository.
Note: The TWC Apdator works with both Teamwork Cloud and Magic Collaboration Studio.

Launching the No Magic Server in MapleMBSE
To launch your TWCloud model in MapleMBSE:
1. From Start->All Programs->MapleMBSE 2024 select Open CATIA No Magic
Server Model.
2. Select your TWCloud configuration (.MSE) file.

14 • 1 Getting Started with MapleMBSE

3. Click Open. A progress bar is displayed indicating that the model is being launched.

Installing No Magic Libraries
This step is necessary only when the environment path was not set up during installation.
Before opening your TWCloud model in MapleMBSE, you must install the appropriate
TWCloud 202x libraries. There are two ways to provide the No Magic installation path forthese libraries:
1) Setting an environment variable.
2) Selecting the path from a dialog window.
Setting the Installation Path Using an Environment Variable
Set the MAPLEMBSE_MD_INSTALL_ROOT environment variable for the TWCloud
Adapter to find the correct libraries.

1.8 Using the No Magic Teamwork Cloud Adaptor • 15

When setting the MAPLEMBSE_MD_INSTALL_ROOT environment variable, use yourNo Magic product install path (for example, "C:\Program Files\MagicDraw”) . From thisinstall path, the TWCloud Adapter will find the needed libraries.

Selecting the Installation Path from Dialog Window
To select the installation path from a dialog window:
1) Start MapleMBSE. This will display the Select No Magic Library location dialog
2) The Select No Magic Library location dialog lists the locations of all No Magic products
installed on your machine as well as the pre-installed library provided by MapleMBSE.

3) Select the location of the library you want to use from the list.
4) Click OK.

16 • 1 Getting Started with MapleMBSE

Choosing a Library Not Listed in the Dialog Window
If you want to specify a different location for the library, not listed in the dialog window:
1) Click Select Directory.
2) Browse to, and select, the location of the library you want to add.
3) Click OK.

Updating the Configuration file to Ensure Library Compatibility
After installing the necessary No Magic file, you must ensure that MapleMBSE configuration
file is importing the correct metamodel framework, since this is version specific.
To do this, open your configuration (.MSE) file in a text editor and inspect the import-ecore
statement. Ensure you are using the correct ecore. For example, to inform MapleMBSE thatthe type of model is a Teamwork Cloud 19.0 model, use the statement import-ecore "http://www.nomagic.com/magicdraw/UML/2.5.1" in the configuration file. Similarly, for aTeamwork Cloud 2021.x model, use the statement import-ecore "http://www.nomagic.com/magicdraw/UML/2.5.1.1".

Logging in to CATIA No Magic server
There are two ways to log in to the CATIA No Magic server: using regular login and using
single sign-on.
Logging in to the Teamwork Cloud Server
1. In the Login to Teamwork Cloud dialog window, enter your server, username, password,
project name and the branch the project is stored in. To use an SSL connection between
No Magic Server and MapleMBSE, select Use SSL. For more information, see Setting
up SSL Certificates (page 20). To download your model files launch them from a local
folder, select Caching Model Files (page 20). If you check Save settings, MapleMBSE
saves the successful login information except for a password and they are automaticallyfilled in the next login.

1.8 Using the No Magic Teamwork Cloud Adaptor • 17

2. Click OK.
Note: The version of the No Magic libraries must be compatible with the version ofTeamwork Cloud on the server.
Logging in Using Single Sign-On
1. In the Log in to Teamwork Cloud dialog window, enter your server address then click
Single Sign-On.

18 • 1 Getting Started with MapleMBSE

2. In the Teamwork Cloud browser window, click SAML USER.

3. Sign in with your credentials.

1.8 Using the No Magic Teamwork Cloud Adaptor • 19

4. At the Log in to Teamwork Cloud dialog window, use the Project, Category, Branch andRevision filters to select your model.

5. Click OK.
Note: Similar steps are followed to log in to Magic Collaboration Studio
Using the Category field to filter search results
In No Magic Server you can save each project under different categories. If you don't savea project under a category, by default, it will labeled as uncategorized.
To filter projects belonging to a category, after providing the credentials, select the desired
category. This will filter and display projects belonging to that category first in the Project
field. After selecting the project, select the branch if necessary and click Ok to open the
project.
Selecting a different browser for single sign-on
You can use single sign-on to CATIA No Magic server through the default browser or you
can select a different web browser.

20 • 1 Getting Started with MapleMBSE

To select a different web browser for single sign-on:
1. Go to the $MAPLEMBSE\OSGiBridge\ext\SAML_Browser\ directory, where$MAPLEMBSE is your MapleMBSE 2024.1 install directory.
2. Select the folder for the web browser you want to use for single sign-on.
3. Open the readme.txt file and follow the instructions.

Setting up SSL Certificates
For SSL connections, you need to put JKS and PASS files into <MAPLEMBSE-INSTALLATION-DIRECTORY>\certs. By default, TWC adapter will use cert.jsk and cert.pass.
By specifying the "ssl" parameter in TWC URI, you can configure it. For example, if you
launch MapleMBSE TWCSample.MSE twc://?ssl=cert2, cert2.jks and cert2.pass are used
for SSL connection.

Caching Model Files
Select the Use Cache option to have the MapleMBSE TWC Adapter cache files to a local
folder, where the files will be loaded from in the future.
The default location of the cache folder is <user.home>/.twcloud/<version #>/cache/
MapleMBSE will update the cache automatically whenever a user performs any of the following operations:• Reload or update the model.
• Commit changes to the CATIA No Magic server.
A progress bar is displayed as the model files are cached.

When you close a model, the cache files are deleted from the folder and any associatedmemory resources are released.

1.8 Using the No Magic Teamwork Cloud Adaptor • 21

The Commit Number Information in the Workbook Title Bar and Status
Bar
Once you have launched your No Magic Server Model in MapleMBSE you will notice thatcommit information for the model is displayed in the Excel Workbook title bar, as shownin Figure 1.7.
The format for the uri displayed in the title bar is:
Title Bar:
Twc://teamworkcloud.example.com?username=maplembsetest
Status Bar:
Model=<ProjectName> ,Branch=<BranchName>,Revision=<CommitNumber>

Figure 1.7: Commit Information Displayed in Title Bar

Figure 1.8: Commit Information Displayed in Status Bar

Note:
If the connection URL in the title bar is too long (greater than 255 characters), the informationin the URL will be split between a caption in the title bar and a footer at the bottom of theworksheet.
The caption contains the server address and the username, while the footer contains thebranch name model name and revision number.
When the caption exceeds the limit of 255 characters or the footer string exceeds the limit
95 characters the string is truncated and "..." is added at the end.
Updating the Commit Number
MapleMBSE updates the commit number using either of these methods:• If you make changes to the model and commit those changes to the No Magic Server,
the commit number is updated.
• If someone else updates the model, and commits their changes to the No Magic Server,
then you reload or update the model in MapleMBSE. At this point, MapleMBSE will
retrieve the latest resource and update the commit number.

22 • 1 Getting Started with MapleMBSE

Editing and Saving Changes to Your Model
1. Make changes to the model in MapleMBSE.

2. Single-click Save to save your changes to a (local) snapshot.
3. Double-click on Save to save to the No Magic Server repository. The Commit toTeamwork Cloud dialog appears.

1.8 Using the No Magic Teamwork Cloud Adaptor • 23

4. Enter a commit message, then click OK. The changes will be committed to the No Magic
Server repository, to be shared with other users.
5. The following message is displayed when the commit is successful:

Note: By default, MapleMBSE releases locks on files upon commit. If you would like tokeep these locks, select Keep Locks before clicking OK.
6. Reload/Update the model in MapleMBSE.

24 • 1 Getting Started with MapleMBSE

7. Open the Server Project in MagicDrawTM/Cameo Systems ModelerTM.

8. Update the Project in MagicDraw/Cameo Systems Modeler.

1.8 Using the No Magic Teamwork Cloud Adaptor • 25

Automatically Saving Model Changes
The TWCloud Adapter in MapleMBSE automatically creates a snapshot of model changes
and uses this snapshot to recover after a MapleMBSE crash.
MapleMBSE will check periodically (every ten minutes) for a one minute period of inactivity.
At this time, a snapshot will be automatically created.
Loading Models after a Crash
The model resource that is loaded after a crash depends on the most recent save or sync
operation performed just before the crash.
For example, if the last operation before a crash was committing changes to the Teamwork
Cloud, MapleMBSE will load the snapshot that resides in the Teamwork Cloud.
However, if the last operation was saving to your local drive, MapleMBSE will load thislocal snapshot.
Finally, if the autosave has been initiated just before a MapleMBSE crash, a dialog window
will be displayed after recovering from the crash letting you select which snapshot to load.

26 • 1 Getting Started with MapleMBSE

Creating a new No Magic Server Branch
To create a new No Magic Server branch:

1. Double-click the Save button. The Commit dialog box appears.
2. Enter a commit message.
3. Select Create New Branch.
4. Enter the name for the new TWCloud branch in Branch Name.
5. Enter a description for the new TWCloud branch in Description.
6. Click OK.
7. The new branch is created and the resources changes are now committed to this new
branch. Any further commits will also be made to the new branch.

Accessing an Arbitrary Commit of a No Magic Server Project
Access any revision of a project without creating a new branch

1.8 Using the No Magic Teamwork Cloud Adaptor • 27

To access a particular revision:
1. Enter your login credentials: Server, Username and Password.
2. Next, enter the name of your No Magic Server Project in Project.
3. Enter the name of the branch that contains your file in Branch.
4. Enter the file revision that you want to work with.
5. Click OK.
Accessing a Specific No Magic Server Revision
You can access a particular revision of your model at login by doing the following:
1. Click the revision browser text field from the login window. This will open the Revision
Browser window.

28 • 1 Getting Started with MapleMBSE

2. Use the Version, Branch, Author, Date and Comment fields to filter your results.
3. Click Filter.
4. From the search results, select your revision.
5. Click Select.

No Magic Server Notification
It may happen that as you are working on a model in a specific branch, someone else commitsa change to this model in the branch. Your revision will not be the head revision, and you
will need to either reload your model or commit your changes to a new branch.

1.8 Using the No Magic Teamwork Cloud Adaptor • 29

Reloading Your Model from the No Magic Server
You can refresh your current model so that it reflects any changes made to the model outsideof MapleMBSE. This section discusses the different scenarios you might encounter whenreloading your TWCloud server model.
To reload your model:
1. Select Add-Ins > MapleMBSE > Reload/Update.
2. In the Reload/Update dialog window, click OK. Note: Reloading the model may discard
any unsaved changes.
3. The model is reloaded in the Model Spreadsheet.
Notes:• If you begin at the head revision and there are no other changes to the model (in otherwords, the only changes to the model are your local changes), a dialog window will appear
warning that reloading the model may discard your changes.

• If you begin with the head revision and there is a snapshot available, you have the option
to ignore the snapshot, or add your snapshot to the model. The following dialog window
will appear.

30 • 1 Getting Started with MapleMBSE• If you begin with the head revision and a new revision is committed while you areworking on your revision then the dialog box displayed contains a local save checkbox
and a second checkbox for merging your saved local changes.

• If you begin with an arbitrary revision that is not the head revision, then reload, the only
option offered is to go to the new revision and not merge any changes. This dialog window
is the one that will be displayed.

If Update Model with Snapshot is checked and MapleMBSE detects there is a conflict whentrying to merge the new revision with the snapshot, (for example, because both the new revision and the snapshot add a model element of the same name), you will be alerted withanother dialog window.
After clicking OK, MapleMBSE will update to the new revision, but any local changes(whether saved or not) will be discarded. The result will be equivalent to the case where a
new revision is available; you update to the new revision and discard any local changes(whether saved or unsaved) was originally selected) or the case where a new revision is1.9 Using the Eclipse Capella Adaptor • 31

available and the snapshot for the previous revision is saved but changes are not applied
after switching to the new revision respectively.
If you want to keep the local changes, you have the option to restart MapleMBSE (via the“Restart” button or keyboard shortcut), open the previous revision, apply the snapshot, andthen save the local changes into a new branch.

1.9 Using the Eclipse Capella Adaptor
The Capella Adaptor in MapleMBSE allows you to save changes you have made to yourmodel in the Model Spreadsheet to the Capella model file.

Launching the Capella Model in MapleMBSE
To launch your Capella model in MapleMBSE:
1. From Start->All Programs->MapleMBSE 2024.
2. Select your Capella configuration (.MSE) file.
3. Click Open.
4. In the Open Capella Model dialog box click on Open Local Capella Project
5. Select the Capella Model to Open by selecting the .aird file

6. Edit changes and Click on Save button to add changes to the model.

32 • 1 Getting Started with MapleMBSE

1.10 Using the Capella Adaptor for Team for a Capella
Model
With the Capella Adaptor, you can work with local and sever models in Capella and Teamfor Capella, respectively.

Launching the Team for Capella Model
To Launch your Team for Capella model in MapleMBSE:
1. From Start->All Programs->MapleMBSE 2024.
2. Select your Capella configuration (.MSE) file.
3. Click Open. A progress bar is displayed indicating that the model is being launched
4. In the Login to Team for Capella dialog box, enter your server, repository name, username
and password. Once your credentials are validated, select the project to open in
MapleMBSE. If you check Save settings, MapleMBSE saves the successful login information except for a password, and they are automatically filled in the next login.
5. Click Ok.

The model information is displayed in title bar and status bar. Once you have launched it
you will see the server details and username in the title bar.

1.10 Using the Capella Adaptor for Team for a Capella Model • 33

Editing and Saving changes to your model
1. Make changes to the model in MapleMBSE.
2. Double-click on Save to save to the Server repository. The Commit to Team for Capelladialog appears.
3. Enter a commit message, then click OK. The changes will be committed to the Team for
Capella repository, to be shared with other users.

34 • 1 Getting Started with MapleMBSE

Validation Error during Commit to Team for Capella
When you double-click on the save button and commit to Team for Capella, if there is avalidation error when the model is checked, an error message is shown.
To fix the validation error:
1. Click on View Validation Error dialog box

2. Validation errors are displayed and the respective elements that triggered the issues arelisted
3. Click on an item to display the context in message box on the top.
4. Click the OK button and Cancel in the commit dialog box.

1.10 Using the Capella Adaptor for Team for a Capella Model • 35

5. Resolve the issues and click on Save to Model.
6. Enter a commit message and click OK

36 • 1 Getting Started with MapleMBSE

2 Editing the Model Spreadsheet MapleMBSE
In this chapter:• Workbook and Layout (page 37)• Adding Model Elements (page 43)• Sorting Records (page 55)• Deleting Model Elements (page 58)• Modifying Model Elements (page 60)• Formula Evaluation (page 87)

2.1 Workbook and Layout
The content of a workbook for a model is controlled by the MSE configuration file. The
configuration file specifies the rules for what model data should be displayed in a spreadsheet
and how to display this data. The remainder of this chapter reviews how the data can bedisplayed and what implications it has on user interactions with a spreadsheet. For detailed
instructions about the rules governing what model data should be displayed, see theMapleMBSE Configuration Language Guide.
The configuration file specifies how many spreadsheets a workbook has and where andhow the SyncViews are placed on the spreadsheets. Any user interactions that may change
those specifications will result in an error and the actions will not be performed. In particular,
the following information is specified for a workbook by the MSE configuration.
• The number of spreadsheets• The names of the spreadsheets• The order of the spreadsheets
Adding or deleting, renaming or moving the spreadsheets will result in an error. Note thatthe order of the spreadsheets is also controlled by the template file. See the MapleMBSE
Configuration Language Guide for details.
For a SyncView, the MSE configuration specifies the cell in a spreadsheet where the SyncView area starts, the number of fields (see Operations Overview (page 40)) and the typeof the SyncView placement. Any action that moves the location of the SyncView on the
spreadsheet or interferes with the number of fields will be blocked by MapleMBSE. The
specific actions that interfere with the number of fields depend on the placement type. There
are three types of SyncView placement: a vertical table, a horizontal table, and a matrix.
• Vertical Table
A vertical table is a table where elements are arranged vertically: each row represents amodel element, and each column represents a particular attribute of that element. The

37

38 • 2 Editing the Model Spreadsheet MapleMBSE

example is given in the Figure below. The MSE configuration specifies the cell fromwhich the SyncView starts (B3 in the example). Inserting or deleting columns or rows
in front of that cell (rows above row 3 or columns to the left of the column B) would shift
the SyncView which would contradict the specification and result in an error. The configuration also specifies the number of columns for a vertical table (3 columns startingwith column B). Inserting or deleting columns in that area (from B to D) would result inan error. The number of rows is dictated by the number of elements. Adding or deletingrows results in adding new or deleting existing elements.

Figure 2.1: Vertical Table• Horizontal Table
A horizontal table is a table where elements are arranged horizontally: each column represents a model element, and each row represents a particular attribute of that element.
The example is given in the Figure below. The MSE configuration specifies the cell fromwhich the SyncView starts (C2 in the example). As in the case of the vertical table, inserting or deleting columns or rows in front of that cell (rows above row 2 or columns to theleft of the column C) is forbidden. For a horizontal table the configuration specifies thenumber of rows in the table (3 rows starting with row 2). Inserting or deleting rows inthat area (from row 2 to row 4) would result in an error. The number of columns corresponds to the number of elements. Adding or deleting columns results in adding new ordeleting existing elements.

Figure 2.2: Horizontal Table• Matrix
A matrix combines both a vertical and a horizontal table and also provides a matrix form
to indicate a relationship between the two tables. It is convenient to use to represent dependencies among model elements. In the example,Figure 2.3, the matrix represents thedependency of dependent classes on the supplier classes. The dependent classes are rep-

2.1 Workbook and Layout • 39

resented in the vertical table (outlined in green), and their supplier classes are in the horizontal table (blue). The matrix (red) is used to indicate the dependencies. In the example
Class1 from Package1 depends on Class2 from Package1 and Class3 from Package1.
The MSE configuration specifies the cell where the matrix part starts (D5 in the example).
The placements of the vertical and horizontal tables are determined from there. Insertingor deleting rows or columns before that cell (the rows above row 5 or columns to the leftof the column D) is not allowed. The numbers of columns and rows in the matrix aredetermined by the number of elements represented by the vertical and horizontal tables,
respectively. Inserting or deleting rows or columns in the region that affects the matrix
area (rows between 5 and 7 or columns between D and F) is allowed and results in adding
or deleting elements represented by the vertical or horizontal table, respectively.

Figure 2.3: Dependency Matrix• Matrix with Mulitiple Dependencies
You can have Matrices that display more than one dependency at a time, along with any
attached stereotypes. To add a dependency, type the alias of one of the dependency. For
example, in the Matrix below, click in a cell and type either "VER" or "SAT".
To remove a dependency, select the dependency in the cell, the press the delete key.

40 • 2 Editing the Model Spreadsheet MapleMBSE

2.2 Operations Overview
MapleMBSE allows users to edit the models via tables created inside the SyncView areaby translating insertions, deletions, and updates of table rows into additions, removals andupdates of model elements, respectively.
The basic elements of data that MapleMBSE displays on a spreadsheet are SyncView, records, and fields. The area on a spreadsheet representing model data is called the SyncView,
outlined in red in Figure 2.4. For simplicity, the SyncView is a vertical table in this example(see Vertical Table in Workbook and Layout (page 37)). Only operations in the SyncView
region of a spreadsheet will be transferred to the operations on the model. Operations inother places of a spreadsheet do not affect the model. The empty row (or column) at theend of the vertical (or horizontal) SyncView is used to insert new elements and is called
the insertion area (green dashed line in Figure 2.4). Each SyncView corresponds to a setof model elements. Each element corresponds to a record, represented by a row in a vertical
table (outlined in blue in Figure 2.4). Each record is an array of fields, represented by cells
in the row. Each field represents some property of the model element.

2.2 Operations Overview • 41

Figure 2.4: Data Elements Displayed By MapleMBSE

The SyncView areas for a workbook can be looked up in the Name Box (the box to the leftof the formula bar). See Figure 2.5. Expanding the list in the Name Box gives the list of
all SyncView areas on all spreadsheets in the workbook. The names include the names ofthe spreadsheets and the names of the SyncView areas defined by the MSE configuration.

Figure 2.5: SyncView Areas Displayed in Name Box

Selecting one of the names shows the corresponding range of the cells.

42 • 2 Editing the Model Spreadsheet MapleMBSE

Figure 2.6: Highlighting SyncView Cell Range

In the remainder of this section we give an overview of the Excel operations on the
spreadsheets.

Allowed Operations
The given table assumes that the SyncView is a vertical table. For a horizontal table theoperations apply to columns instead of rows.
Editing Operation
Insert a new row into the SyncView table.
Insert a new row by typing into a cell directly
below the last row of the table.

Insert copied cells as new rows.

Description
Use the Excel context menu to insert a new row
anywhere in the table.
Type content into the cell directly below (andadjacent to) the table and press Enter. This will
add a new row to the table and increase the
SyncView area.

Insert rows in the table area by inserting or pasting
copied cells (using Insert Copied Cells featurefrom Excel context menu).
Update cell content in an existing row of the table. Update table cell contents within the SyncView
area
Delete rows
Delete table rows within the SyncView area.
Sort rows in SyncView
Select then sort the entire table in order to replacerows in the table.

2.3 Adding Model Elements • 43

Editing Operations That Will Result in a MapleMBSE Error Message
The editing operations listed in the table below disrupt the structure of the SyncView table,
as defined in the MapleMBSE configuration file and will result in an error message being
generated and the editing operation being undone:• Inserting a new row at the top of the spreadsheet, above the SyncView table• Inserting a column in the spreadsheet to the left of the leftmost column of the table• Updating across several non-adjacent rectangular areas. That is, copying and attempting
to paste cell content into multiple selected areas in the table.
• Deleting rows or columns in the insertion area
• Moving the SyncView area. Note that you must edit the SyncView table schema in theconfiguration file (.mse) to move the SyncView area.

Operations That Could Negatively Change the Mapping between
MapleMBSE and the Model Element
When making edits to the rows and columns in a table, the following operations do not alter
the SyncView table layout as defined in the MapleMBSE configuration file. However, if
you perform any of these operations there is a risk of breaking the mapping between therows of the table in the model spreadsheet and the model element itself. This could resultin unexpected behavior afterwards.
Editing Operation
Description
Sorting only a portion of the table in the SyncView Sorting only selected rows, cells or columns inarea.
the SyncView area
Inserting content into the table and then shifting Inserting content into the table (for example bycells up.
right-clicking on a table cell, then selecting Insert),
then selecting either: Shift Cells Up or Shift Cells
Down.
Deleting content from selected table cells.
Similar to inserting content into the table, and thenshifting cells up or down.

2.3 Adding Model Elements
Adding elements is done by adding records to the SyncView areas. How the records areadded depends on the SyncView layout. For a vertical table, adding records corresponds toadding rows and for the horizontal table, to adding columns. For simplicity, in the following
instructions, assume the SyncView is a vertical table. Adding records to a vertical table canbe done in the following two ways.

44 • 2 Editing the Model Spreadsheet MapleMBSE

Tip: You can follow the steps in this example using the UserGuide.MSE configuration file,
AddingNewElements.uml model and the Packages spreadsheet. These files can be found in
the <MapleMBSE>/Example/UserGuide directory, where <MapleMBSE> is your
MapleMBSE installation directory.
1. Type the necessary information in the insertion area.
In Figure 2.7, the SyncView is outlined in red and the insertion area in green (cell B4in a). Type Package2 in the insertion area (b) and press Enter. MapleMSBE checks thatno other element with this name exists and adds a new package element with the name
Package2 (c). The model is shown in the bottom of the Figure. The SyncView area isgrown by one row. The insertion area is the cell B5.

Figure 2.7: Entering Information in Insertion Area

2. Insert a row in the SyncView area and enter the necessary information.
In Figure 2.8 the SyncView area is outlined in red (a). For example, select row 4 and in
the context menu choose Insert (b). A row inserted in place of row 4, and the previous
row is shifted below (c). The SyncView area is increased by one row. Enter the name of
the new package, Package3. MapleMBSE creates a new element with the name Package3.

Figure 2.8: Inserting a Row in the SyncArea

The changes are performed on the model in the internal MapleMBSE memory. To makeyour model changes persist, save the workbook. For details, see Saving the Model (page 11).

2.3 Adding Model Elements • 45

MapleMBSE does not sort new elements automatically. The sorting can be done manually;for details see Sorting Records (page 55). Adding records will also be reflected in otherspreadsheets that refer to the same model elements. In other worksheets, additional records
are always added to the last line.

Field Modifiers
Sometimes the end user IS required to input hard-to-remember data or semantically loaded
data. In order to improve this user experience MapleMBSE offers Field Modifiers as string
replacements. For instance, if previously a Very::long::qualified::name was the expected
input, within the MSE file we can configure a mnemonic N that internally will be replaceback to the long format.
Field Modifiers can be used as string replacements, in such cases.
In the following Figure you can see an example of long name being replaced by a shortername . In Figure 3 a), a view of the TurboFan engine parts as they are in the model. Without
the Field Modifier shortcuts, the user would see some very cumbersome names, e.g., High
Pressure Axial Compressor.

46 • 2 Editing the Model Spreadsheet MapleMBSE

By contrast, in Figure 3 b), a view of the TurboFan engine parts, when using Field Modifiers.
Often organizations develop jargon and abbreviations that are handy to use. In this case ,HPA and LPA could be the accepted short forms for High Pressure Axial and Low Pressure2.3 Adding Model Elements • 47

Axial, respectively, meaning that the old High Pressure Axial Compressor is now displayed
as HPA Compressor, and can also be entered as such.

Nested Elements
A model usually has a lot of dependencies which are represented by a tree structure. To reflectthat structure in a table a staircase table is used. Consider the example in Figure 2.9. Assume
we want to define a structure as on the left-hand side of the Figure: Package1 contains
Class1, which contains Property1. Each element is represented by one record in the table.
We define each element in turn, starting with Package1.
Tip: You can follow this example using these files: UserGuide.MSE configuration file,
AddingNewElements.uml model and the NestedElements spreadsheet. These files can befound in the <MapleMBSE>/Example/UserGuide directory, where <MapleMBSE> isyour MapleMBSE installation directory.

Figure 2.9: Defining a Nested Structure in the NestedElements spreadsheet• Define Package1
The steps for defining Package1 are shown in Figure 2.10. In the insertion area in thecolumn corresponding to the package definitions (a) type Package1 (b) and press Enter.
When you press Enter, MapleMBSE checks whether there is an element in the in-memory

48 • 2 Editing the Model Spreadsheet MapleMBSE

model with that name already. It finds that such element does not exist yet, so the row
represents a new element. Since one row corresponds to one element we cannot define
any additional elements inside it in this row. MapleMBSE indicates that by showing
fields corresponding to the nested elements in gray.

Figure 2.10: Defining Package1• Define Class1
The steps for defining Class1 in Package1 are shown in Figure 2.11. To define Class1,
you need to first specify the package it belongs to. Type Package1 in the column corresponding to packages and press the right arrow key (a). MapleMBSE checks whether there
is an element with this name already in the model. It finds that the element exists andshows the "Duplicated key" warning for this field. Other fields are still white so you can
now define nested elements inside Package1. Enter Class1 (b) and press Enter. Again
MapleMBSE verifies if Class1 already exists inside Package1, finds that it does not andcreates a new element. The warning from the package field is cleared (c). Since one record
can correspond only to one element and this record now defines Class1, the same row
cannot be used to define any elements inside Class1. MapleMBSE indicates this byshowing the Property Name column in gray.

2.3 Adding Model Elements • 49

Figure 2.11: Defining Class1• Define Property1
The steps for defining Property1 are shown in .Figure 2.12. To define Property1, youneed to specify the package and the class it belongs to. Type "Package1" in the column
corresponding to packages and press the right arrow key (a). As in the case above,
MapleMBSE identifies that the element, Package1 already exists and adds a warningmark to that cell. Type "Class1" and press the right arrow key (b). This time, Class1
already exists in Package1 so MapleMBSE gives the "Duplicated key" warning for thatcell as well. The property field is white and you can now define an element representing
a property inside Class1. Type Property1 (c) and press Enter. MapleMBSE verifies that
there is no existing property inside Class1 called Property1 and the record represents a
new unique element. All warnings from the other fields are cleared (d).

50 • 2 Editing the Model Spreadsheet MapleMBSE

Figure 2.12: Defining Property1

Alternative Groups
In a model, different types of elements may belong to the same parent. For example, apackage may contain classes or other packages. An MSE configuration specifies what typethe record must have thus specifying the type of the element it defines. In the example in
Nested Elements (page 47), the MSE configuration allowed for 3 types of records: packages
defined at the top level, classes defined inside top-level packages, properties defined insideclasses. It did not allow for defining other packages inside top-level packages or classes
inside other classes, for example. To be able to define different types of elements at thesame nested level, alternative groups must be defined in the MSE configuration, see
MapleMBSE Configuration Language Guide for details. Here we consider when such aconfiguration is used.
Tip: You can follow the steps in this example using the: UserGuide.MSE configuration
file, AddingNewElements.uml model and the AlternativeGroups spreadsheet. These files
can be found in the <MapleMBSE>/Example/UserGuide directory, where <MapleMBSE>
is your MapleMBSE installation directory.
The MSE configuration in this example allows us to define the following 4 types of elements
by defining the corresponding fields in the SyncView.
• Top level packages - Package Name
• Classes inside top level packages - Class Name
• Packages nested inside the top level packages - Nested Package Name
• Classes inside nested packages - Nested Class Name

2.3 Adding Model Elements • 51

The model we are going to define in this example is shown in Figure 2.13. A top-levelpackage (Package1) contains two elements: one of class type (Class1) and one of a package
type (Package2). The nested package (Package2) has one class defined in it (Class2).

Figure 2.13: Alternative Groups Example Model• Define Package1
The process of defining Package1 is the same as in the examples in Adding Model
Elements (page 43) and Nested Elements (page 47). Enter Package1 in the Package
Name column in the insertion area and press Enter.

52 • 2 Editing the Model Spreadsheet MapleMBSE

Figure 2.14: Defining Package1• Define Class1
To define Class1, follow the steps in Figure 2.15. Type Package1 in the Package Namecolumn on the new line (row 4) and press Enter (a). As in the examples in Nested
Elements (page 47), Define Class1, a warning is added to the cell defining Package1 indicating that it is a duplicated key. Unlike in that example, the background of the othercells in this row is changed to dark gray. This color is different from the lighter gray used
to indicate that no more elements can be defined in this row (row 3). The dark gray color
is used to indicate the fields represent alternative fields. Type Class1 in the Class Name(b) and press Enter. A new class called Class1 is added to Package1 (c). The backgroundof the remaining cells in this row in the SyncView area is changed to light gray indicatingthat no more elements can be defined in this row.

2.3 Adding Model Elements • 53

Figure 2.15: Defining Class1• Define Package2
To define Package2 inside Package1, follow the steps in Figure 2.16. First, type Package1
on the new line (row 5) and press Enter (a). Again, a duplicated key warning is added tothe cell with Package1 and the background of other cells in this row inside the SyncView
area is changed to dark gray indicating the rest of the cells represent alternative groups.
Leave the Class Name column empty and type Package2 in the Nested Package Namecolumn (b). Press Enter (c). A new package Package2 is added to the model. The background of the cells representing nested elements inside Package2 (Nested Class Name)is changed to light gray indicating that this record cannot be used to define nested classes
inside Package2. The background of the cell representing the alternative (Class Name)remains dark gray.

54 • 2 Editing the Model Spreadsheet MapleMBSE

Figure 2.16: Defining Package2• Define Class2
The steps defining Class2 inside Package2 are shown in the Figure below. Type Package1
in the Package Name column and press Enter (a). Type Package2 in the Nested Package
Name (b) and press Enter (c). Now a package called Package2 inside Package1 alreadyexists and a duplicated key warning is added to the cell with Package2. The backgroundof the Nested Class Name cell remains dark gray. Type Class2 in the Nested Class Namecell (d) and press Enter (e). A class called Class2 is added to Package2 in the model. The
warnings are cleared. The background of the Class Name cell remains dark gray indicatingthat it represents an alternative type of elements in Package1. Any valued entered there
will be ignored and cleared after Enter is pressed.

2.4 Sorting Records • 55

Figure 2.17: Defining Class2

2.4 Sorting Records
The order for sorting is specified in the MSE configuration file. When a model is opened
all records are sorted according to the these specifications. When new records are added tothe tables they are not sorted automatically. You can sort the records manually. Sorting records has no effect on the model.
• Vertical Table
To sort the records manually in a vertical table, right-click anywhere in the SyncView56 • 2 Editing the Model Spreadsheet MapleMBSE

area, and then select Sort Vertically.

• Horizontal Table
To sort the records in a horizontal table, right-click anywhere in the SyncView area, and2.4 Sorting Records • 57

then select Sort Horizontally.

• Matrix
To sort the records in a matrix, right-click anywhere in the matrix SyncView area, and58 • 2 Editing the Model Spreadsheet MapleMBSE

then select Sort Matrix.

2.5 Deleting Model Elements
Deleting elements is done by deleting the corresponding record in the SyncView area. In a
vertical table it corresponds to deleting a row, in a horizontal table - a column. In a matrix,
deleting a row or a column also deletes the row or the column in the corresponding verticalor horizontal table, correspondingly, and, thus, the element represented by that row orcolumn. In Figure 2.18, the SyncView is a vertical table (a). To delete Class1 in Package1,
you need to delete the row representing this element - row 4 (b). The element is deleted
from the table and the model (c).

2.5 Deleting Model Elements • 59

Figure 2.18: Deleting the Class1 Element from the Model

Deleting an element also deletes all elements belonging to it. For example, deleting Package1
in Figure 2.19 (a) also deletes Class1 and Class2 belonging to it.

Figure 2.19: Deleting Package1 and Associated Elements

60 • 2 Editing the Model Spreadsheet MapleMBSE

Deleting Records with References
Reference fields in a record point to other elements in the model, see Field Types (page 60)
for details. When deleting a record that contains reference fields, the corresponding referenced
element is not deleted.

2.6 Modifying Model Elements
In the examples we considered in Adding Model Elements (page 43) and Sorting
Records (page 55), the SyncViews were used to add new elements but they did not allow
to edit or view any properties of the elements. In this section we define other characteristics
of SyncViews that allow us to work with different properties of the elements.
As discussed in Operations Overview (page 40), model elements are represented in a SyncView by records, and each record consists of one or more fields. The fields represent different properties of the element. By editing the fields in the Excel spreadsheet you modify
the corresponding properties of the model elements. What effect editing a field has on themodel element depends on the type of the field. The types of the fields are set by the MSE
configuration. Here we describe the different types of fields and what effect they have on
editing operations.

Field Types
There are three main types of fields in SyncView:• An attribute field;• A reference field;• An unmapped field.
An attribute field points to the value of a property with a primitive type, such as a string ora number. A reference field represents a property with a nonprimitive type, such as anotherelement in the model. An unmapped field is a field that is not mapped to any property ofthe element. It has no influence on the model but may be useful for comments or performing
Excel operations related to other fields. See Unmapped Fields (page 79) for details.
In addition, fields can be either key or nonkey fields. The key fields are used to uniquely
identify a model element. Therefore, multiple records with the same key fields cannot exist
in the same SyncView. One or more key fields exist in one record. Whether a field is key
or not is set in the MSE configuration. The nonkey fields simply represent the propertiesof the element defined by the key fields.
Note: There is a distinction between record key fields and reference key fields. If there
are reference fields in a record some of them must be reference key fields that determine
which element the reference points to. The record key fields are used to determine the record
uniquely. The reference key fields may also be the record key fields.

2.6 Modifying Model Elements • 61

In Figure 2.20, the SyncView is a vertical table. Each row is a record, and different fields
are represented by different columns. The record key fields are outlined in green: Package
Name, Class Name, and Property Name. They are attribute fields. The record nonkey attribute
fields are outlined in blue: Package Visibility, Class Visibility, Property Visibility, andAggregation Type. Both key and nonkey attribute fields are strings. A property in a classmust have a type which is defined by some other class. In other words, a type of a property
is another element in a model. So, to represent a type of a property, reference fields must
be used. To define a class uniquely in the model, we need to specify the name of the package
it belongs to and its name. The fields Property Type Package and Property Type, outlined
in orange, are reference key fields. In this example, reference key fields are not record key
fields (they are not required to determine the record itself, only the element it refers to).
Providing Property Type Package and Property Type is enough information to define thetype of a property. However, you might be interested in viewing some information about
the type in the same record, for example, the visibility of the type. For that purpose a nonkey
reference field is used. The field Type Visibility, outlined in purple, is a nonkey reference
field representing the visibility of the class used as a type for the property.

Figure 2.20: Illustration of Main Types of Fields in SyncView

In the examples we considered in Adding Model Elements (page 43) and Sorting
Records (page 55),the records of the SyncViews consisted only of key attribute fields. In
the example in Deleting Model Elements (page 58), the SyncView had record key attribute62 • 2 Editing the Model Spreadsheet MapleMBSE

fields (Package Name and Class Name) and nonkey attribute fields (Package Visibility andClass Visibility).

Record State
Another definition important for working with records in SyncViews is the the state of therecord. Each record has two states: bound and unbound, depending on whether it is associated with the model loaded in memory. When a new record is first created it is in an unbound state; it is not associated with the model. Once all record key fields are filled and it
is verified that together they represent a unique element the record changes the state tobound, the record is associated with the model in memory. If it represents an existing element,
the nonkey fields will be populated with the information from the in-memory model. If theelement does not exist it is created in the model. Depending on the modeling tool some of
the attributes are given default values to new elements. If any of those attributes are mapped
to nonkey fields, the fields will be populated with those values.

Example of Using Different Fields When Adding Elements
As an example of adding elements to a SyncView with several different types of fields wecreate the model in Figure 2.21. The MSE configuration for the SyncView specifies thetypes of the fields as in the example in Field Types (page 60).
Tip: You can follow the steps in this example using the: UserGuide.MSE configuration
file, AddingNewElements.uml model and the AllElements spreadsheet. These files can befound in the <MapleMBSE>/Example/UserGuide directory, where <MapleMBSE> isyour MapleMBSE installation directory.

Figure 2.21: Adding Elements to a SyncView with Different Types of Fields• Define Package1
The steps defining Package1 are shown in Figure 2.22. The names of the columns corresponding to the record key fields are shown in green. Type Package1 in the Package
Name column (a). The record is unbound. Press Enter. MapleMBSE verifies that the record
defines a unique element. The record's status is changed to bound. MapleMBSE creates2.6 Modifying Model Elements • 63

a new package in the model with the name Package1. By default, new elements in UML
have visibility assigned to public. Since the record is now bound, the value of the Package
Visibility field is populated automatically (b).

Figure 2.22: Defining Package1• Define Class1
The steps defining Class1 in Package1 are shown in Figure 2.23. To define Class1, you
only need to fill out the key fields: Package Name and Class Name (a). When you enter
Package1 in the Package Name column, MapleMBSE checks that an element with thisname already exists, so the status of the record remains unbound. The Package Visibility
remains unpopulated. Enter Class1 in the Class Name column and press Enter.
MapleMBSE verifies that the record now represents a unique element and binds the record
to the model. It creates a new class inside Package1 called Class1. The visibility is set to
public by default. The nonkey fields for Package and Class Visibility are populated (b).

Figure 2.23: Defining Class1

64 • 2 Editing the Model Spreadsheet MapleMBSE• Define Class2
The first steps defining Class2 in Package1 are the same as defining Class1 (a and b in
Figure 2.24). The last step is to change the default value for the visibility of Class2 toprivate (c).

Figure 2.24: Defining Class2• Define Property1
The steps defining Property1 in Class2 are shown in Figure 2.25 and Figure 2.26. First,
only key fields need to be entered. When you enter the package and the class name therecord remains unbound because a package and a class with those names already exist.
Nonkey fields remain unpopulated. Type Property1 in the Property Name column (a) andpress Enter. Now the record represents a new unique element, so MapleMBSE binds itto the model and creates a new element. The nonkey fields are populated (b). The values
for the visibilities of the existing elements (Package1 and Class2) are taken from thevalues defined for these elements (public and private, respectively). Property1 is assigned
the default visibility--public. The Property Type Package and the Property Type columns
do not have default values. They are defined (in the corresponding configuration file) as
references to existing classes.

2.6 Modifying Model Elements • 65

Figure 2.25: Creating New Bound Records

To define the type, you need to specify the full name of the class that property instantiates.
The full name includes the name of the package the class belongs to and the name of theclass itself (d). Note that just specifying the package name does not resolve the class reference, and so the warnings appear. Only after entering the name of the class and pressing
Enter the reference is resolved and the warnings are cleared (e).
Note: The reference target must exist in the model already. This line cannot be used tocreate the referenced element.
Finally, change the Aggregation Type from its default value (none) to shared (f).

66 • 2 Editing the Model Spreadsheet MapleMBSE

Figure 2.26: Defining the Type

Modifying Attribute Fields in Unbound Records
For definitions of bound and unbound records see Record State (page 62).
• Modifying key attribute field
When a new record is defined before it is bound to a model, entering and modifying
values in the key fields specifies the new model element the record represents. This iswhat we have been doing in the examples of adding elements.
• Modifying nonkey attribute fields
If any values are entered into the nonkey fields when the record is unbound, the result
depends on whether the field represents an existing element or the new element that therecord defines.
- For existing elements
The entered value will be ignored and overwritten with the existing value of the element.
In the example in Figure 2.27, when adding Class1 inside Package1, Package1 alreadyexists and has public visibility. During the definition of the Class1 the visibility of
Package1 is set to private while the record is unbound (a). When the input of the classname is finished and Enter is pressed, the record becomes bound, and the visibility of
Package1 is set to the value defined in the model--public.

2.6 Modifying Model Elements • 67

Figure 2.27: Modifying Existing Elements in Unbound Records Results in the Manually Entered
Values Being Overwritten- For new elements
The entered value will be assigned to the corresponding property of the new element
when the element is created. In the example in Figure 2.28, when adding Class1, thevisibility for it is entered before all key fields define the element uniquely and the record
is unbound (a). The key field for the name of the class is field (b) and entered. The record
becomes bound to the model. The visibility of Package1 is determined from the definitionof Package1. A new class, Class1 is created in Package1 and its visibility is set to private.

68 • 2 Editing the Model Spreadsheet MapleMBSE

Figure 2.28: Adding New Elements to a Model

Modifying Reference Fields in Unbound Records
For definitions of bound and unbound records see Record State (page 62).
• Modifying reference key field
When a new record is being added, the reference key fields must be set to an existingelement. The reference fields cannot be used to create a new element. If there are multiple
keys that define the reference target it is necessary to define all of them and all of themshould be pointing to elements that already exist in the model. See step Define Property1
in Example of Using Different Fields When Adding Elements (page 62),
• Modifying reference nonkey fieldIf the values are entered into nonkey reference fields in an unbound record the result depends on whether the reference keys were defined.
- Reference keys were not defined
When no key reference fields are defined, the values entered in the nonkey reference
fields of an unbound record (a, outlined in purple) are ignored and cleared when the record
becomes bound (b).

2.6 Modifying Model Elements • 69

Figure 2.29: Values Entered in Nonkey Reference Fields and No Key Reference Fields Defined- Reference keys were defined
When reference keys are defined and refer to an existing record (a, outlined in orange),
the values entered into the nonkey reference fields of an unbound record (outlined inpurple in a.) are applied to the element that is being referenced when the record becomesbound. Other fields and SyncViews bound to the same property are also updated (b).

Figure 2.30: Values Entered in Nonkey Reference Fields with Key Reference Fields Defined

Modifying Attribute Fields in Bound Records
For definitions of bound and unbound records see Record State (page 62).
A bound record is linked to an element in the model. Changing the value of an attribute
field in a bound record modifies the corresponding property of the element. If there areother fields in other records or other SyncViews that show the same attribute of that element
they will also be updated.

70 • 2 Editing the Model Spreadsheet MapleMBSE• Modifying key attribute field
When a key attribute is changed, MapleMBSE first performs checks to identify if the
new combination of the key fields for the record is unique. If it is, the new value is assigned
to the property in the model and in the SyncViews.

Figure 2.31: Modifying a Key Attribute Field

Note: MapleMBSE can check only that the combination of the keys for the record in whichchange is performed is unique. For example, if in the example above we changed Class1 toClass2 in the record defining Property1, row 5 (b), the record's key fields would be Package1Class2-Property1. There is no element with such keys so the change would be applied. Thechange would then propagate to the model and Class1 would be renamed Class2 where
Class2 already exists. MapleMBSE cannot detect this conflict. When the model is saved
and opened in the corresponding tool, the tool will perform validation and detect the conflict.
For this reason, it is recommended that if the key attribute needs to be changed it should bedone in the record where the key is the final key field, like in the example above.
• Modifying nonkey attribute field
When a nonkey attribute is changed, the change is applied to the model and is reflectedin any fields and SyncViews bound to the changed property of the changed element. The
modification can be done in the record that defines the element, like in the example below,
or in other fields linked to this property. For example, the same change for Package1 asin the example below could be done in any of the cells outlined in orange in column C(a and c).

2.6 Modifying Model Elements • 71

Figure 2.32: Modifying a Nonkey Attribute Field• Deleting value of key attribute
It is an error to delete the value of a key field attribute. Changes are not reflected in themodel.

Figure 2.33: Deleting the Value of a Key Field Attribute72 • 2 Editing the Model Spreadsheet MapleMBSE• Deleting value of nonkey attribute
If you delete the value of a nonkey attribute cell the value will be cleared. However, depending on the model, the value may be reset to a default value.

Figure 2.34: Deleting the Value of a Nonkey Field Attribute

Data type conversion
Excel cell values and model element values each have associated data types. By default,
Excel uses the General number format for worksheet cell values. The number format of acell can be configured manually through the Format Cells menu. However, depending on
the input value, there are cases where Excel will convert cell values to another format (forexample, a date).

2.6 Modifying Model Elements • 73

To avoid a mismatch of number types, MapleMBSE provides implicit data type conversionof cell values to match the values of the target model element.
• String conversion• When the target model element type is string, cell values are converted to string.
• Enum conversion• When the target model element type is enum, string or integer is converted toenum. If it fails, "Invalid Value" error is annotated to the cell.
• EDataType conversion• When the target model element is of other EDataType and the cell value is text,
try to convert it to the target EDataType. If it fails, "Invalid Value" error isannotated to the cell.
• Number conversion

74 • 2 Editing the Model Spreadsheet MapleMBSE• When the target model element is number and the cell value is also number,the cell value is automatically cast to fit with the target model element type.
For example, if the model element is of type integer and the cell value is oftype double, the cell value is truncated to an integer and set to the value of themodel element.

Notes:• Currently MapleMBSE supports Number, Text, and Date types• You can put an apostrophe(') to quote a cell value to specify it is a text instead of setting
cell format.
• While MapleMBSE does try to convert data types, there can be no guarantee that in allcases MapleMBSE will succeed. The best way to ensure the number type consistency is
by manually formatting your Excel template.
• Some MapleMBSE configurations allow you to instantiate arrays of elements within asingle cell. Each element must be separated with the delimiter specified by the mse configuration. See the following example.
In the example below (Figure 2.35) the column, opaque expression body (column D) accepts an array of type, String. To input this kind of data you must know: which cells accept
this kind of input, the delimiter used (by default ; semi-colon) and the escape (by default \back-slash).
To input the array:[“a”, “b”, “c”, “;”, “\”]First, you need to prepend the escape string to any of the delimiter or escape symbols
within your array of string:[“a”, “b”, “c”, “\;”, “\\”]
Next, you concatenate the string separated with the delimiter:“a;b;c;\;;\\”
Now, do the same exercise backwards. To understand how to interpret a string as an arrayof string, use the example provided in cell D6:

2.6 Modifying Model Elements • 75

“formula2\;1;formula2\;2”First, you need to split the string into several strings using the delimiter that are not escaped,in other words those that are not prepend by an odd number of escapes. Notice that “2\;1”
is not a valid delimiter because it is escaped.
[“formula2\;1”; “formula2\;2”]
Next, remove the escape string within each string in the array. Sometimes this can be tricky
to do because “\\” should give us “ \” meaning that the user intended to use the escapestring and it is escaping the escape that was needed.
[“formula2;1”; “formula2;2”].

76 • 2 Editing the Model Spreadsheet MapleMBSE

Figure 2.35: Example of a MapleMBSE Configuration that Accepts Arrays of Elements in aSingle Cell

Note: There are some virtual features that can have similar effects. Contact the author ofthe .mse file for your model for further details.

Modifying Reference Fields in Bound Records
For definitions of bound and unbound records see Record State (page 62).
• Modifying reference key fieldIf you change the value of a reference key field to a value that represents another element
already existing in the model, the element being referenced is changed. An attempt tochange to a key value that does not exist in the model will result in an error.

2.6 Modifying Model Elements • 77

Figure 2.36: Changing Value of Reference Key Field, Property Type• Modifying reference nonkey fieldIf you change the value of a nonkey reference field the corresponding field in the referenced element is updated. If there is another field in the SyncView that is bound to thisproperty it will also be updated.

Figure 2.37: Changing Value of Reference Nonkey Field, Type Visibility78 • 2 Editing the Model Spreadsheet MapleMBSE• Deleting value of reference key field
Deleting the value of a reference key field is an error.

Figure 2.38: Deleting Value of a Reference Key Field• Deleting value of reference nonkey fieldIf you delete the value of a nonkey reference field the value is cleared. The changes arereflected in the referenced element. However, depending on the model, the value may bereset to a default value.

Figure 2.39: Deleting Value of a Reference Key Field

2.6 Modifying Model Elements • 79

Unmapped Fields
An unmapped field is a field in a record that is not mapped to any property of the element.
As such, values entered in unmapped fields have no influence on the model. However, unmapped fields may be useful for comments or performing Excel operations related to otherfields. Formulas for unmapped fields can be entered in the template file (see MapleMBSE
Components (page 1)) to be available whenever a model is opened. The following example
is taken from the UserGuide.MSE configuration file and the UnmappedFields spreadsheetthat is used with the AddingNewElements.uml model. These files can be found in the<MapleMBSE>/Example/UserGuide directory, where <MapleMBSE> is your
MapleMBSE installation directory.
In Figure 2.40, columns B, D, G, and I are unmapped fields. They contain formulas that
get updated as you fill out the application. For example, the formula for cell B3 is displayedin the Figure below in the Formula Bar.

Figure 2.40: Unmapped Fields

As you complete Step 1, filling the package name in column C, the fields get updated.

Figure 2.41: Entering a Value for Package Name Results in Updated Mapped Fields

The formulas do not get applied to new rows in a SyncView automatically. You can do somanually by clicking on the bottom right corner of the cell with the formula and dragging
in down to expand to the number of desired rows.

80 • 2 Editing the Model Spreadsheet MapleMBSE

Figure 2.42: Formulas Must be Updated Manually

The SyncView area is extended to include those rows. The warnings in the cells in column
C indicate that the key field needs to be filled. You can extend the other formulas over the
SyncView area as well. The formulas get updated with respect to the rows. For example,
the formula for B4 is updated with respect to C4.

Figure 2.43: With the SyncView Extended, Key Fields Need to be Filled

Now you can follow Steps specified in in columns B, D, and G to define desired elements.
Tip: This example follows the steps of the example in Alternative Groups (page 50).
Define Class1 in Package1.

Figure 2.44: Defining Class1 Inside of Package1

Define Package2 in Package1.

2.7 Locking Elements in a Worksheet • 81

Figure 2.45: Defining Package2 Inside of Package1

Define Class2 in Package2.

Figure 2.46: Defining Class2 Inside of Package2

2.7 Locking Elements in a Worksheet
The locking features available in MapleMBSE provide a means of controlling simultaneous
editing of model elements so that one user's changes are not overwritten.
When users edit models, MapleMBSE attempts to lock the specific model element beingchanged. If successful, the locks are kept by MapleMBSE and the models will be changed.
Otherwise, if unsuccessful, MapleMBSE will report errors and the changes will be reverted.
All the locks automatically acquired by MapleMBSE will be released when:• Users commit their changes;• Users reload the model; or• MapleMBSE terminates.

82 • 2 Editing the Model Spreadsheet MapleMBSE

Notes:• When you attempt to edit a model element that has been locked an error message is displayed that also displays the id of the user who has the locked the model element.
• If MapleMBSE crashes the locks on the elements will remain.
• Locking success is not guaranteed (for example, if you are using an older version of
MapleMBSE that does not support element locking).

Acquiring Locks While Editing
If you change something in MapleMBSE, it tries to acquire locks of model elements to bechanged.
In the image below, the name of requirement, X02 is changed to "New Requirement-UnderEdit".

Figure 2.47: MapleMBSE Attempts to Acquire Locks When Element is Being Changed

Failure to Acquire Locks
MapleMBSE shows error message in Excel as "Unable to lock the model elements".
MapleMBSE will revert user's changes.

2.7 Locking Elements in a Worksheet • 83

Figure 2.48: Failure to Lock Model Elements Error Message

Committing Changes and Cleaning Up Code
When MapleMBSE commits the changes, terminates, or reloads the models, it automaticallyreleases all of the locks automatically acquired while the user edits the model. Other locks,
already acquired by other applications, remain in place.
Note: If MapleMBSE is abnormally terminated (crashes) the locks it has set will remain.
Users will have to manually remove these locks through: Cameo Systems Modeler, MagicDraw, or through the Teamwork Cloud Web UI.

Figure 2.49: Manually Releasing Locked Element

84 • 2 Editing the Model Spreadsheet MapleMBSE

Working with Other Dependencies
If there are additional dependencies or requirements, then they are locked.

2.8 Other Editing Operations in Excel
CutCopy Mode
The CutCopy mode in Excel is a mode in which the area selected for cutting/copying issurrounded by a dotted line as shown in the Figure below. Normally in Excel, the CutCopy
mode is maintained after pasting is performed. In MapleMBSE the CutCopy mode is cancelled after pasting and processing is done.

Figure 2.50: CutCopy Mode

Cell Formatting• Only the value of the cell is saved in the model. The style and formatting of the cell is
not saved and is not reflected in the model.

Undo/Redo
Use CTRL+Shift+Z to undo the previous action. For example, deleting a list of Actors froma table, would be one action. Pressing CTRL+Shift+Z will undo this one action.
Use CTRL+Shift+Y to reapply (redo) the changes undone by the undo feature.
Notes:• If the action has an error, if the user performs an undo, the row in the table containing
the error will not be removed, however the previously completed action will be undone.

2.9 File Attachments in the SyncView Area of a Worksheet • 85

2.9 File Attachments in the SyncView Area of aWorksheet
File attachments in the table cells of a SyncView area are displayed as hyperlinks.

When you click the hyperlink, the file is opened in its native application.

Note: The files displayed in table cells are read-only.

86 • 2 Editing the Model Spreadsheet MapleMBSE

2.10 Opening a Model Diagram
You can use the hyperlinks in the spreadsheet (for example, see the Diagram column in theexample spreadsheet below) to open a model diagram that represents the sysML model.

Notes:• To view the diagrams, you must have either MagicDraw or Cameo Systems Modeleropen.
• If you did not install the MapleMBSE sysML Diagram plugin when you installed
MapleMBSE, see the Getting Started with the MapleMBSE sysML Diagram Plugin
section of the MapleMBSE Installation and Licensing Guide for instructions on how
to load the plugin, after installation.

Viewing SVG Files
MapleMBSE offers a feature that creates SVG files of various model layouts. For Windows
users, the the default program for SVG files may be set to something other than the system's

2.11 Formula Evaluation • 87

default browser.
For more information, see

2.11 Formula Evaluation
Formula evaluation is a feature that works in the context of an InstanceMatrix. It is used toevaluate constraint properties defined in SysML-based Parametric Diagrams in an Excel
worksheet. The formula evaluation feature allows the user to edit, manipulate and save thesevalues to the worksheet and commit these values to the CATIA No Magic server.

The Instance Matrix
The instance matrix comprised of instance specifications (columns), the blocks and value
properties (rows) where they intersect is the data (slot values). The instance is a representationof a block, with values. These values are stored in the slots. Slots are placeholders for values.
Slot values are linked to a specific property. Properties become slots in the instance specification.
For example, consider a simple model with the following relationship between the Blocks:

In MapleMBSE, this corresponds to the following two worksheets:88 • 2 Editing the Model Spreadsheet MapleMBSE

An InstanceTemplate (Instance of Parent Block):

A BlockTemplate:

These two worksheets are combined in the InstanceTableTemplate to create a matrix, where
the rows of the matrix are Blocks and Value Properties and the columns of the matrix are
the instance specifications of the Parent Block. The cells where the rows and columns intersect hold the data and these cells are known as slots.

Parametric Diagrams and Constraint Properties
While Block Definition Diagrams describe the hierarchy of a model and inform the user ofthe value properties that each block in the model owns, it is the Parametric Diagram that
describes how formulas are being connected through the use of constraint properties.
It is these constraint properties that the Formula Evaluation feature evaluates and which aredisplayed as slot values.

2.11 Formula Evaluation • 89

Executing Calculations in the Worksheet
To execute the instance matrix calculations in the worksheet:
1. Open the worksheet that contains the instance table in the SyncView.
2. Do one of the following:• Press CTRL+Shift+K.
• Click Evaluate Formulas, from the MapleMBSE Ribbon menu

A progress bar is displayed as the calculations in the instance table are executed.

The following message will be displayed if the calculations were completed successfully:

Changing the Value of the Inputs in the Instance Matrix:
Drop-down list boxes in the instance table provide the opportunity to change input values
in the instance table.

90 • 2 Editing the Model Spreadsheet MapleMBSE

Once you have selected the value you want to use from the list, all other values are automatically updated.

Adding Additional Instance Specifications to the Instance Matrix
Adding additional instance specifications allow you to change slot values, re-run simulations
and compare results side-by-side.
To add additional scenarios do the following:
1. In the adjacent cell to the right of the instance Column, start typing a name for the new
instance specification.

2. The rest of the cells in the column will populate automatically.

3. Repeat Step 1 for as many scenarios you want to simulate.

2.11 Formula Evaluation • 91

4. Select Evaluate Formulas, from the MapleMBSE Ribbon menu, or press CTRL+Shift
K to run the simulations.

Sharing Instances
You can choose to share or unshare instances in the Instance Matrix.
To share an instance value:
1. Select the target cell where the instance will be shared.
2. Next, right click on the instance that you want to share.

92 • 2 Editing the Model Spreadsheet MapleMBSE

3. From the context menu, select Share Instance.
4. In the dialog box, click the instance you want to share and click Ok.

Note: Any changes you make to the original instance are automatically made to the sharedinstances as well.

3 Default Value Generation in a Column
3.1 Introduction
The default value column is used to generate a value for the model element that you want
to auto-generate. For example, if you enter the Class and want to auto-generate the Property
column. You can generate 4 type of values with the help of default value generation:• Text• Sequence number• Universally unique identifier (UUID)• Text with Sequence number

3.2 Default Value Generation and Requirements IDs
When you create Requirements for your project they are numbered automatically withunique IDs. The number system for the unique IDs must be setup in your modeling tool.
There are special validation rules used to make sure that each of the Requirement IDs inyour project are unique.
If you want a different Requirement numbering than the default, you can customize it
manually by using the Element Numbering dialog.
MapleMBSE extends default value generation to include Requirement ID generation.
This means that MapleMBSE is able to continue with the numbering conventions that you
have assigned to your project through your modeling tool. Even for custom numbering.
If you enter the requirement name and want MapleMBSE to create the ID, leave the ID
column blank. MapleMBSE will calculate the latest ID available in the model and assignthat ID for the requirement.

3.3 Limitations
Default value generation column doesn't work in the following cases:• In root dimension key column• In alternative, group, optional key columns

9394 • 3 Default Value Generation in a Column

Appendix A Log Files
A.1 Description of Log Files
The table below describes the log files created by MapleMBSE.
In the table, <InstallDir> refers to the installation folder of MapleMBSE and %USERPROFILE% refers to the value of environment variable, USERPROFILE.
Normally the value USERPROFILE is set to the following:• In Windows 11 and 10: C:\Users\<User Name>
Log File
Description%USERPROFILE%\MapleMBSE_Launcher.log Log data from MapleMBSE.exe%USERPROFILE%\MapleMBSE_OSGiBridge.log • Log data from a module (OSGiBridge) which
is used to load a module of MapleMBSE in
Excel.
• You can specify a log level in<InstallDir>\OSGiBridge.ini.
%USERPROFILE%\Documents\MapleMBSE.log • The MapleMBSE.log file is located in the My
Documents folder• Log data from MapleMBSE itself• You can specify a log level in<InstallDir>\OSGiBridge\log4j.properties.
• The MapleMBSE.log file will be overwritten
whenever starting MapleMBSE.

A.2 Using a Log File to Identify a Problem
In the MapleMBSE.log file, the values in cells updated in the worksheet are recorded.
Note that your computer will run slow due to the large volume of data logged and the sizeof MapleMBSE.log file will be tens of MB or more.
1. Rename <InstallDir>\OSGiBridge\log4j.properties. Name it log4j-orig.properties.
2. Rename <InstallDir>\OSGiBridge\log4j-debug.properties. Name it log4j.properties.
3. Restart MapleMBSE.
4. Reproduce your problem in MapleMBSE.
5. After you have completed the above steps, copy MapleMBSE.log located in %USERPROFILE%\Documents in an appropriate location.

95

96 • Appendix A Log Files

6. Return the logging properties to the original settings by renaming <InstallDir>\OSGiBridge\log4j-orig.properties to log4j.properties.

A.3 VBA Logging
VBA logging is available to record information about the vba methods that are executed
because of user action. By default, VBA logging is enabled.
To disable VBA logging, you must create an environment variable,
MapleMBSE_VBA_LOGGER and set the value of this environment variable to false.
The location of the VBA logs is C:\Users\<username>\AppData\Local\MapleMBSE\MapleMBSE_VBA.log.

Appendix B Error Messages
and Troubleshooting
B.1 Error Messages When Starting MapleMBSE
Error Message
MapleMBSE.exe is alreadyrunning. Close all Excel
Windows, and then confirm
MapleMBSE.exe process is
terminated.
File Open Error.

Description
Resolution
An attempt was made to start
Close all Excel windows, thenanother instance of MapleMBSE confirm that the Excel process
but failed because only one(MapleMBSE.exe) has
instance of MapleMBSE can run terminated before attempting to
at a time.
launch MapleMBSE again.
A model file or SyncModel file Follow the instructions in thecannot be opened.
error message dialog.

B.2 Error Messages Displayed When Attempting to Alterthe SyncView Table
Messages that will be displayed in a message box when editing are as follows.
These errors were handled in MapleMBSE. If these errors were caused by user, the operation
will be cancelled.
Error Message
Can’t overwrite in the leftmost
column across several rows.

Description
Resolution
Attempted to overwrite in the
The editing operation thatleftmost column across several resulted in the displayed errorrows but ID is specified in the message will be cancelled.
property of the leftmost cells so Restart MapleMBSE withoutthat MapleMBSE can manage saving a model.
data - you cannot overwrite in
the leftmost column acrossseveral rows.
Insertion to the top row is
Attempted to insert a row above Same as above
currently prohibited.
the top row of the SyncView
table but the operation is not
permitted.
Can’t delete the insertion row or Attempted to delete the insertion Same as above
column.
row or column but the operation
is not permitted.
Can’t move the table.
Attempted to move SyncView Same as abovetable but the operation is not
permitted.
Can’t update across several
Attempted to update acrossSame as above
rectangular areas at one time.
several rectangular areas. For9798 • Appendix B Error Messages and Troubleshooting

example, copying content into
several, nonadjacent areas
selected in the table. This
operation is not permitted.
Can’t delete overall editing area Attempted to delete entire
Same as above
SyncView table but the operation
is not permitted.
Can’t delete the column.
Attempted to delete a column in Same as above
the SyncView table but theoperation is not permitted.
Can’t insert the column.
Attempted to insert the column Same as above
in SyncView but the operation is
not permitted.

B.3 Error Messages Displayed When Editing the Model
Spreadsheet
Messages that will be displayed by a comment in cell when editing are as follows.
Error Message
The key is duplicated.

The key has not been input.
No link can be found.
The value is invalid.
The cell cannot be changed.

Description
An existing key name wasspecified.

Resolution
Specify other key name or
specify including an end key if
the key is not end key.
The key has not been input.
Input the key.
No link shown in the link field Input a correct value in the link
exists.
field.
The value in the cell is invalid. Input a correct value.
Attempted to change a cell which When this error occurs after
cannot be changed.
inserting a row, you may haveinserted an invalid feature to themodel so delete the row inserted.
In addition, when this error
occurs after changing the cellvalue, you may change a feature
which cannot be changed in themodel so return to the originalvalue. In either case, the change
is not reflected on the model.

B.4 Error Messages When Editing (Unhandled
Exception/An Internal Error Occurred)
When the error of Unhandled Exception occurs, name the model and save, and then close
MapleMBSE.

Appendix B Error Messages and Troubleshooting • 99

B.5 Warning Messages for Remaining Memory
MapleMBSE checks the remaining memory usage whenever you operate. When the available
memory becomes insufficient, a warning message will appear. Follow the instructions in
the message.
If the warning about the remaining memory reappears frequently, your memory (the heap
size of Java) may be insufficient for the model you are editing. Consider expanding theheap size of Java by following the instructions in "Changing the Java Heap Size”.

B.6 Troubleshooting• Changing the Java Heap Size (page 99)

Changing the Java Heap Size
An error dialog related to insufficient memory may appear when starting or editing
MapleMBSE. If this problem occurs adjust the java heap size:
1. Right-click on the MapleMBSE shortcut on your desktop (or the folder of the application)and select Properties.
2. In the Target: field add the command line option, /R <memsize> to the end of theshortcut link target (for example, "C:\Program Files\MapleMBSE2024\MapleMBSE.exe"), where <memsize> is a value, between 800MB to 1100MB, ofcontinuous memory reserved for the Java Virtual Machine, some of this memory will
be used for the Java heap, some for the JVM itself. For more information, including
other options you can specify, see Launching from Command Line (page 6).
3. Click OK or Apply.
4. Double-click the shortcut to start MapleMBSE.
5. If an error message appears, increase the value of <memsize> specified in step 2 above.
Repeat this until you find a value large enough so that the error message is no longer
displayed when starting MapleMBSE.
6. Open OSGiBridge.ini, located in the MapleMBSE installation folder, in Notepad tochange the maximum heap size of JVM.
7. Find the entry “-Xmx512m” in this file. Replace "512" with the value of <memsize>
from step 2.
8. If MapleMBSE fails to launch, replace -Xmx<memsize>m, set in step 7 with a smaller
value for the Java heap, between 150MB to 200MB smaller than <memsize>. This will
leave some memory space required for the JVM itself.

100 • Appendix B Error Messages and Troubleshooting

Instance Matrix, 87
Adding Additional Instance Specifications, 90
Changing Input Values, 89
Parametric Diagrams and Constraint
Properties, 88

Index
A
Accessing a Specific No Magic Server Revision, 27
Accessing an Arbitrary Commit of a No
Magic Server Project, 26
Automatically Saving Model Changes, 25

H
How MapleMBSE Works, 3

IC

Importing Excel Files, 8Installing No Magic Libraries, 14
Using Dialog Window, 15
Using Environment Variables, 14
Using No Magic Library Not Listed in
Dialog Window, 16
Instance Matrix, 87
Adding Additional Instance Specifications, 90
Changing Input Values, 89

Caching Model Files, 20
CATIA No Magic server
Regular Log In, 16
Single Sign-On, 17
CATIA No Magic server Login, 16
Closing MapleMBSE, 12
Configuration File
Definition, 3Creating a New No Magic Server Branch,
26

L

D
Default Value Generation in a Column, 93
Definition of a Configuration File, 3E
Eclipse Capella Adaptor, 31
Editing Your Model, 22
Excel Files
Importing and Exporting, 8Executing Calculations in the Worksheet, 89
shortcut keys, 89
executing calculations in the worksheet
Excel Ribbon menu, 89
Exporting Excel Files, 8FFinding Your MapleMBSE Version Number,
13
Formula Evaluation, 91

Launching MapleMBSE
Command Line, 6GUI, 5launching MapleMBSE
command line
syntax, 6
Launching No Magic Server in MapleMBSE,
13
List of Supported Model Formats, 4M
MapleMBSE
Restarting, 10
Version Information
How to Find, 13
MapleMBSE Components, 3
Merging Syncviews, 9Model Workbook, 39101

102 • Index

Refreshing the Model, 12
Reloading the Model Spreadsheet, 8
reloading the model spreadsheet
shortcut keys, 8
Reloading Your Model after MapleMBSE
Crashes, 25
Reloading Your Model from the No Magic
Server, 29
Restart MapleMBSE, 10
restarting MapleMBSE
command line, 7

Instance Matrix, 87
Instance Matrix,Adding Additional
Instance Specifications, 90
Instance Matrix,Changing Input Values, 89
Instance Matrix,Parametric Diagrams
and Constraint Properties, 88
Locking Model Elements in a Worksheet,83
Modifying Model Elements, 79
Negative Effect on Mapping Between
MapleMBSE and Model Element, 43
Opening a Model Diagram, 86
Other Excel Operations, 84
Resulting in Error Messages, 43
Sorting Records, 57
SysML Diagram, 86
Syncviews
Merging, 9S

TN
No Magic Library Compatibility, 16
No Magic Server
Launching a Model, 13
No Magic Server Notification, 28

R

Saving a Copy of the Current Model, 9
Saving the Model File, 11
Saving Your Model, 22
SSL
Setting Up SSL Certificates, 20
Supported Model Formats
List of, 4
syncview, 37
Syncview
Placement
Horizontal Table, 38
Matrix, 38
Matrix,Multiple Dependencies, 39
Vertical Table, 37
Syncview Operations, 41
Adding File Attachments, 85
Adding Model Elements, 53
Allowed Operations, 42
Deleting Model Elements, 59
Executing Calculations in the Worksheet,89
Formula Evaluation, 91

Teamwork Cloud Adaptor, 29Installing No Magic Libraries, 14
Using a No Magic Library Not Listed
in Dialog Window, 16
Using Dialog Window, 15
Using Environment Variables, 14
Teamwork Cloud Commit Number, 21