MATLAB Simulink

This topic covers general steps for configuring a connection to a supported MATLAB Simulink ("MATLAB") system via the Polarion Connector for MATLAB Simulink. You will need to:

Prerequisites for Installation

It is assumed that you already have an installation of a Polarion application lifecycle management product installed, configured, and running.

To use the Polarion Connector for MATLAB Simulink, you need the following:

  • MATLAB Simulink version R2013a or later, and Simulink Verification and Validation.

  • Any version of Polarion ALM, Polarion REQUIREMENTS, or Polarion QA (latest version is recommended).

    The Polarion PRO license is supported. The Polarion REVIEWER license is not supported (it does not allow users to create new Work Items).

    The connector may be integrated with a customer's instance of Polarion SaaS, but this requires customization of the instance by Polarion IT Services at additional cost.

Connector Overview

Experienced MATLAB users know that it has the capability to link model elements and subsystems in diagrams to external requirements specifications maintained in Microsoft Word. Polarion leverages this capability to enable linking of MATLAB model components to requirements managed with Polarion application lifecycle management products. This can be a significant advantage for MATLAB users who design components in companies and industries with stringent compliance mandates.

Polarion's technology is designed from the outset to facilitate wide and deep traceability through every engineering phase. In the case of MATLAB and Polarion, MATLAB model elements and subsystems can be linked to granular requirements specifications maintained in Polarion's exclusive LiveDoc documents. Process is efficiently managed across disciplines and stakeholders by means of workflow, which can be customized to suite the customers exact needs (if these fall outside the parameters of Polarion's robust default workflows for software and systems engineering projects). Inevitable change during the product lifecycle is easily managed and, most importantly, automatically tracked so that at any given time it is possible to trace who changed what, when, and why.

Traceability extends onward into testing. Test cases are linked to requirements in Polarion, which in turn link to MATLAB components, so it is easy to understand the extent of test coverage for all components and what is tested (and how). A comprehensive historical record of testing activity is automatically maintained as well.

How Traceability is Created

Creating this robust traceability is like the old joke about eating an elephant one bite at a time. By creating appropriate links every time an artifact is created, you end up with forensic levels of traceability that can satisfy the most exacting requirements.

For example, suppose the process starts with business cases created in a business case specification document. When requirements engineers create e.g. a functional requirement, they link it to the relevant business case(s) with appropriate link role(s) which describe the nature of the relationship. Then when testers create a test case. they link it to the requirement(s) it verifies, again with an appropriate link role (e.g. "covers" or "verifies").

When engineers use MATLAB to design some hardware component, they have the option of linking model elements to existing requirements in a Polarion project, or creating and linking to new requirements in Polarion. Such new requirements can either be written up by the modeling engineer, or assigned to a requirements engineer for completion. As requirements are completed, they can be assigned to testers (automatically via workflow) who them create and link test cases. The end result is traceability from a MATLAB model element to a requirement (or multiple requirements), and from the requirement(s) to test cases, which later on will be linked to Test Runs to record manual or automated test executions.

This guide explains how to set up a connection between a MATLAB installation and a Polarion project hosted on a Polarion server, and how to link model elements to existing or new requirements (or other artifacts) in a project hosted on a Polarion server.

Installation Procedure

To install the Polarion Connector for MATLAB Simulink:

  1. Extract content of the ZIP distribution archive file in an empty folder on the computer hosting MATLAB.

  2. Start MATLAB and switch to the folder (e.g. type 'cd <folder path>')

  3. Run the startup.p file.

    Note that MATLAB might warn you: "MATLAB cannot run this file because <some file> shadows it in the MATLAB path". You may select option Change Folder or Add to path to continue.

When you execute the installation program for the first time, it can display additional instructions on how to extend your existing environment (if you already have startup.p files in your paths).

Connecting MATLAB to Polarion

This section explains how to set up a connection between MATLAB and your Polarion server, and a project on that server. It is assumed that you already have a project created in Polarion to manage the requirements (and possibly test cases and testing as well) for the MATLAB project you want to connect and link to. If you do not have such a project, you should create one before going further. See the topic on Creating Projects in the User Guide part of Polarion's Help system.

It is further assumed that you have the connectivity scripts for Polarion set up and configured in your MATLAB installation.

It is not necessary that requirements pre-exist in the project, as you will be able to create these in Polarion as you being linking elements of your model in MATLAB to Polarion.

If you have existing requirements in Microsoft Word, you can import these into Polarion to take advantage of the traceability benefits mentioned earlier. Consult the User Guide topic Importing Microsoft Word Documents in Polarion Help.

The connector for MATLAB supports efficient work with one Polarion project. If the MATLAB solution should be connected to several Polarion projects (or even servers with different URL or user credentials), it could lead to inconveniences with reconfiguring settings each time... when particular block needs to be revised, for example.

Connection Setup Procedure

Before you begin, you might want to consider having your Polarion administrator create a dedicated user account to be used solely for the purpose of MATLAB accessing Polarion, with its credentials stored securely in Polarion's User Accounts Vault. This user account must have permissions to create and modify Work Items on the Polarion server in the project accessed by a MATLAB connection. For more information see the Administrator's Guide topic Configuring the User Accounts Vault.

To set up a connection to a Polarion server and project:

  1. In the MATLAB menu, choose Tools > Polarion Settings to open the Polarion Settings dialog.

  2. Specify the Polarion server's URL. For example, http://polarion.yourorg.com

  3. Specify the user name and password to be used by MATLAB to access the Polarion server.

    The specified user must have permissions to create and modify Work Items on the Polarion server for the project specified in the Project ID field of the dialog. The credentials (and other settings) are stored in persistent variables of the local MATLAB installation.

  4. Specify the ID of the Polarion project to be accessed by this Connection. Note that the ID may not be the same as the project name that appears in the Polarion user interface when you are logged in. The ID is shown in the ID field of the Project topic of Polarion Administration when you are logged in to a project. (You must have global or project administrator permissions to access it.)

  5. New Work Item Type field, specify the ID of the Work Item type that should be created when a MATLAB user takes the option to link a model element in MATLAB to a new Work Item in Polarion.

    Here again, you need the ID from the project configuration, not the Name that appears to end users in the user interface. You can find this in the project Administration: expand Work Items, select Types, and copy the value in the ID column. For example, the ID for type with the name Requirement is requirement.

    The default value is requirement, but you can specify any type configured in the target Polarion project. For example, you might have a type simulation block (an aggregate type later decomposed into individual requirements).

  6. The Search Query field is optional. Here you can enter Lucene query syntax for a query to isolate some subset of all Work Items when a MATLAB user takes the option of linking a model element to an existing Work Item in Polarion. This becomes the default query for the "Link Block/(Sub)System" action (described later). The query can be refined as needed when invoking the action.

    For example, suppose elements from some model need to be linked to Requirement items in Polarion. Entering type:requirement will cause only Work Items of the requirement type to be retrieved when a user invokes linking to an existing Work Item. The query can filter the list even more. For example, maybe the links will be to unresolved requirements planned to version 2: NOT HAS_VALUE:resolution AND type:requirement AND targetRelease:2.0

  7. Click the Save button to save the configuration.

    Settings will be used for all subsequent sessions. To work with a different server or project on the same server, reopen the Polarion Settings dialog and modify the settings as needed. Note that if the user did not execute Tools > Settings, then the Polarion context menu will offer only the option to open the Settings dialog.

When the connection is successfully completed, a context menu item Polarion appears on each type of element in MATLAB models.

Publishing MATLAB Elements to Polarion

You should now have a connection configured and working between MATLAB and a project on a Polarion server. This chapter will explain various options for "publishing" model elements in MATLAB to requirements in Polarion. (Note that although we say "requirement", because it is the most common use case, the target item can be of any type configured in the project on your Polarion server.)

Publishing means creating a link to a Work Item in Polarion... either a pre-existing item, or on you create during the process of publishing. Once published, user can easily navigate from elements and subsystems in the MATLAB model to Work Items in Polarion, and vice-versa. You can publish:

  • a single selected element to a single Work Item (existing or new)

  • multiple selected elements to multiple Work Items (existing or new)

  • an entire subsystem (to a single Work Items that may later be decomposed into sub-items)

  • an entire diagram to a single Work Item

Publishing to a New Work Item

You can select a MATLAB element and "publish" it to create a new Work Item in the configured Polarion project.

  1. Select an element in a MATLAB diagram. The element must be one supported by MATLAB's Requirements Management Interface (RMI).

  2. On the element's context menu, select Polarion < Publish Block/(Sub)System. (If the element is not supported by RMI, the Polarion menu item visible, but all actions are disabled.)

    A new Work Item of the type specified in the configuration for this connection is created in Polarion and displayed in a dialog that now pops up.

  3. Click on the Work Item listed in the dialog and wait for your web browser to open a new instance and open the new Work Item in the Polarion web interface.

  4. Optionally edit any data fields of the new Work Item... Title, Description, etc. and save the Work Item.

TIPS

Polarion users can now follow the link in the Hyperlinks section of the Work Item back to the element in MATLAB.

You can optionally link the same MATLAB element to multiple Work Items in Polarion. For example, you might link to 2 requirements: functional and non-functional.

The Polarion context menu in MATLAB now has an item Open Linked Work Item, which leads to a dialog in which you can click any listed item to open it in Polarion.

Publishing to an Existing Work Item

You can select a MATLAB element and "publish" to link it an existing Work Item in the configured Polarion project.

  1. Select any element in the MATLAB model and on its context menu, select Polarion > Link Block/(Sub)System with Existing Item.

    The Select Polarion Work Item dialog opens and lists all items found by the query specified in the MATLAB to Polarion connection settings. Note that the configured query string is shown, and that you can modify it in this dialog to retrieve a different set of items.

  2. Locate the target Work Item in the dialog, and select it.

  3. Click the Link Selected button.

A hyperlink to the MATLAB model is added to the existing Work Item in the Hyperlinks section.

Bulk Publishing to Polarion

You can publish multiple elements of a MATLAB diagram to Polarion in order to create, say, requirements for them in a single operation. For example, you could publish two selected subsystems to create Requirements in Polarion that cover both of them.

To bulk-publish elements:

  1. Select multiple elements in a MATLAB diagram... subsystems for example.

  2. Right click any selected element and on the context menu select: Polarion > Publish Block/(Sub)System.

  3. Confirm that you want to publish multiple selected items.

New Work Items are created for all elements selected and these are listed in the Following Work Items Were Linked dialog.

You can click any listed item to open it in Polarion in your web browser. Each item has the same title as the element in MATLAB, and also contains an image of the element (e.g. subsystem or block), as well as a hyperlink back to the element in MATLAB.

Publishing an Entire Diagram to Polarion

To publish an entire diagram to Polarion:

  1. Right-click on the diagram background, and on the context menu choose: Polarion > Publish Block/(Sub)System.

    A new Polarion Work Item is created in Polarion with the same title as the MATLAB diagram.

  2. Navigate to the Work Item in Polarion in your browser by clicking on the item in the dialog.

    The Work Item's Description field contains an image of the entire MATLAB diagram.

  3. Edit the data of the new Work Item as desired and save it.

    Users can follow the link in Hyperlinks to the diagram in MATLAB.

TIPS

  • Use the element context menu item Remove Highlighting in MATLAB to prevent the image in Polarion from showing highlighted elements.

  • If you modify the diagram in MATLAB, use diagram context menu item Refresh Published Diagram(s) to update the image in the Work Item on the Polarion server.

  • The diagram image is created/updated as an attachment to the Work Item, which is versioned in the repository. Older revisions of the image are accessible in the attachment history.

Using the Requirements Management Interface

MATLAB is designed to work with external requirements management tools. Polarion natively integrates with MATLAB, so you can access Polarion-managed diagrams/elements and modify their properties in MATLAB.

Right-click on any diagram element linked to Polarion, and choose Requirements on the context menu. The context menu indicates if the element is linked to any requirements. You can click any requirement beginning with Polarion: to navigate to the linked Requirement in Polarion.

Click Add-Edit links to see the link properties. You can use this dialog to unlink any element from Polarion (if an element was linked to the wrong existing Work Item by mistake, for example).