Components

Components can be thought of as the building blocks of systems. They are reusable elements that can stand alone as a single function or be connected with other Components for extended capabilities. In Tangram Pro™, we use Component Types to define Components and Component Implementations to model and build Component-based systems.

COMPONENT TYPES are the external view of a component where a component's category, messages, ports, and properties are defined.

Component Types are the starting point for using Tangram Pro™ to model systems. You can think of a Component Type as the outside of an apartment building: it shows you the building's shape and size, and how things get in and out of it, but you don't know what the rooms inside look like This section of the user manual provides details and instructions for managing these key resources in Tangram Pro™.

COMPONENT IMPLEMENTATIONS are the internal view of a component where its behavior is characterized through the structure and function of its subcomponents and connections to other systems and components.

In Tangram Pro™, a Component Implementation is where you determine the capabilities of a Component by connecting it to subcomponents and building its structure. A single Component can have multiple Implementations. Implementations are like the apartments inside of an apartment building: the placement of furniture and appliances changes the function of each room. The next section of the user manual, Implementations, provides details and instructions.

Create a Component

Components are owned by Teams. Team Members and Owners can create, edit, and create Implementations for all of the team's Components in the Component Library.

important

Tangram Pro™ users can view another team's Component but cannot make changes to Components belonging to another team.

How to create a Component

1. Click + New Component
2. Name the Component and select its Category
3. Select the Team that will own the Component, then click Create Component

The New Component is created, and its Component Details Pane is shown.

Step One: Create a New Component

Interfaces can be created from the Components Library Tab or from a Workspace. Clicking the + New Component button in either location opens the Create New Component Pane.

Step Two: Define the Component

Components require a Name and Category. There is an optional field for entering a Description, which is useful for Components that may be used in multiple implementations.

Component Names and Descriptions can be managed after the interface is created, but Category and Team cannot be changed.

Component Categories

Categories define the identity and features of a Component. The category describes how a component functions.

COMPONENT CATEGORIES

• Bus: A data-exchange mechanism

• Data: A data placeholder (i.e. a C++ class)

• Memory: Model data storage

• Process: An address space

• Processor: A schedule component

• System: Container for components and other systems

• Thread: Schedulable events

• Thread Group: A hierarchy of threads

Step Three: Create Your Component

The final step to creating a Component is selecting the Team to which it will belong and clicking Create Component. All of the Teams to which you belong will be shown in the Team Dropdown.

Components cannot be created without a Team. If you are not part of any Teams, you must create one to complete this step.

Clicking Create Component closes the Create Component Pane closes and shows the new Component's Details Pane in its place. You can now add ports and properties to the Component Type and create Component Implementations for it.

Ports and Properties

Ports and Properties can be added to a Component Type in the Component Details Pane and in workspaces for the Component's Implementations. Ports specify the Messages a component will use to communicate, and Properties describe the component.

Adding Ports to a Component Type

Ports are the interface ports that a Component Type used to exchange data or events in an Implementation. A Component Type can contain ports from multiple message sets and of multiple types.

How to add ports to a Component Type

1. Click Edit Type and select Add Port
2. Select a Message Set to use for the port, then click in the Select Message Field and type in a message name or select on from the list
3. Set the port Direction and Type
4. Repeat Steps 1-3 until all desired ports are added, then click Save

The ports will be applied to the Component Type on Save.

Step One: Edit Type

On click. the Edit Type button opens the Component Type Ports and Properties Panel. Clicking Add Port immediately adds a Port Field to the panel.

Step Two: Select Messages

All available Message Sets and their Messages are shown in their respective dropdown menus. You can search the list of messages in a message set by typing into the Select Message Field or by scrolling through the Message Dropdown. Clicking on a message adds it to the port.

Step Three: Set Port Direction and Type

A port's Direction specifies if the port sends or receives a message.

• In: The port receives the specified message

• Out: The port sends the specified message

• In-Out: The port sends and receives the specified message

A port's Type specifies the Component Type's interaction points.

• Data: The port sends or receives data synchronously

• Event: The port sends or receives a signal without any data

Port Directions and Types are selected from their dropdown menus.

Step Four: Save Ports

Ports are not added to the Component Type until you click the Save button in the panel. Tangram Pro™ automatically names each port, but you may update it if you choose before saving. Clicking Save applies the changes and creates a new revision of the Component Type. The saved Ports will now be shown on the Component Type Details Pane.

Adding Properties to a Component Type

Adding Properties is a simple process in the Edit Component Type Panel.

How to add properties to a Component Type

1. Click Edit Type and select Add Property
2. Enter a Key Name and a Property Value
3. Repeat Steps 1&2 until all desired properties are added, then click Save

The properties will be applied to the Component Type on Save.

Edit a Component

Tangram Users can edit names, descriptions, and Component Type details of components belonging to their Teams from the Component Details Panel.

Edit Names and Descriptions

How to edit a Component name and description

1. Navigate to the Component Library and click on a Component belonging to your team
2. Hover over the Component Name or Description and click on the Edit Icon
3. Update the Name or Description, then click Save

The updates will be applied to the Component and shown throughout Tangram Pro™.

Edit Component Type

Ports and properties that define a Component Type can be changed, removed, and added from the Component Details Pane in the Component Library or from the Edit Component Pane in a Workspace for one of its Implementations.

How to edit a Component Type's ports and properties

1. Click Edit Type on a Component Details Pane or the Edit Button from the side menu in a Workspace for one of the Component's implementations
2. Add a new Port or Property, click the X button next to an existing one to remove it from the Component Type, or make changes to an existing Port or Property
3. Repeat Step 2 until all desired changes are made, then click Save

The changes will be applied to the Component on Save.

important

Making changes to Component Type creates a new revision of the component. New Implementations will always use the latest revision of the component. Places the component is already in use will not be affected until it is updated manually.

Copy a Component

Components can be copied by any user in a Tangram Pro™ instance. There are two major reasons to copy a Component: first, changing the ports and properties for a Component that belongs to your team changes the resource for everyone who may want to use it. Creating a copy allows you to make changes without impacting anyone else. Second, you cannot make changes to the Component Type or create Implementations of a Component that is not owned by one of your teams. Creating a copy of another team's Component allows your team to use and edit the Component on your own.

note

Copies of components become their own independent resource. They will not be impacted by changes to the original Component and will not maintain any of the original Component's Implementations Ownership of the original Component will not be transferred to the copy.

How to copy a Component

1. Navigate to the Component Library and click on the Component you wish to copy
2. Click the Copy button in the Component Details Pane
3. Enter a name for the Component and select a team
4. Click Copy Component

A new Component is created with the same category and Component Type as the original.

Component Implementations

Components are stable elements of functionality that communicate with other components using messages through ports defined by their Component Type. In Tangram Pro™, components are the building blocks of systems. Tangram Pro™ users design system architectures and models in Component Implementations. There are two ways to think of an Implementation:

A SIMPLE IMPLEMENTATION is the use of a component by itself, without adding any subcomponents to it.

A SYSTEM IMPLEMENTATION is the use of a component with at least one subcomponent added to it.

Every Component Implementation can be used as a subcomponent of another Implementation. The following sections will describe how to use Tangram Pro™ to design and connect Component Implementations together.

Introduction

All of a Component's existing Implementations are listed in the Component Details Pane. Any Tangram Pro™ user can view the Implementations and details about it. This can help you understand the ways a single Component can be reused in different Implementations.

How to view Component Implementations

1. Navigate to the Component Library and click on a Component
2. Click on one of the Component's Implementations to view its details

Component Details Panes display all of the Component's Implementations. Selecting one opens the Implementation Details where you can view its subcomponents and workflows.

Adding Implementations

You can create new Implementations for Components owned by a team to which you belong from the Component Library. Components can have multiple Implementations.

How to add an Implementation to a Component

1. Navigate to the Components Library and click on a component to view its Details Pane
2. Click Add Implementation
3. Name the Implementation and add a description if desired, then click Create Implementation

The Component Implementation is created and shown in the Details Pane.

Workspaces

Component Implementations are viewed, designed, and managed in Workspaces using a variety of tools with powerful functionalities:

• View Structure and Functions of a Component Implementation

• Add and Connect Subcomponents to your Component Implementation

• Add Source Code to a Component Implementation

• Edit Component Type Details to build flexible communication layers

• Access Workflows - see Workflows section for more information

Tangram Pro™ users can view the Workspace for any Component Implementation in the instance. Users who do not belong to the team who owns the Component have Read Only access in its Implementations' Workspaces and cannot make changes.

How to open a Component Implementation Workspace

1. Navigate to the Components Library and click on a component to view its Details Pane
2. Click on one of the Component's Implementations
3. Click Open Workspace

The Workspace for the Component Implementation is opened and displays all of its subcomponents and available tools based on their ownership of the component.

In addition to the subcomponents and connections in an Implementation, viewers can also see the Component Type, the Implementation team's Component Library, and a summary of the Implementation's Workflows in its Workspace.

Subcomponents

Component Implementations are system models that show the internal structure of a Component through the arrangement and connections of its Subcomponents. Team Members and Owners use Workspaces to design these models and associate source code to its Component Implementations.

The most basic Component Implementations represent a single function. More complex Component Implementations contain subcomponents and can perform many functions.

A SUBCOMPONENT is a Component Implementation used as part of an Implementation of another component.

Workspaces have tools to add subcomponents and connections to build Component Implementations.

The Component Library panel in the Workspace allows users to select an existing Component Implementation to add as a subcomponent or to create a new one to use in your Implementation.

Implementations of Components that do not belong to your team can be used as subcomponents in your Implementation, however you cannot make changes to it or its Type.

Component Reuse

You can select Implementation of your Tangram Pro™ instance's existing Components to use as a subcomponent in your Component Implementation. It is a simple process to add an existing Component.

How to use an existing Component Implementation as a subcomponent

1. Open the Workspace for a Component Implementation, then click on the Component Library Icon
2. Click on the Component List Item for the Component you wish to use in your Implementation
3. Decide which of Implementation to use as a subcomponent, then drag and drop it into your Component Implementation Workspace
4. Repeat steps 2 and 3 until you've added all the subcomponents you wish to, then click Save in the upper right corner of the Workspace

The selected subcomponents are now added to your Component Implementation.

By default, the Component Library Tab is filtered to show Components owned by the same team that owns the Component Implementation you are working on. You can use the team switcher to select another team and use one of their Components in your Implementation.

Add Subcomponents

If a subcomponent you need doesn't yet exist in Tangram Pro™, you can create it right from the Component Workspace. There are two ways to do this. First, you can create a new Implementation of a Component that already exists. This is especially useful if you need a custom version of the Component in your own Implementation.

How to create a new Component Implementation in a Workspace

1. Open the Workspace for a Component Implementation, then click on the Component Library Icon
2. Click on the Component List Item for the Component you wish to use in your Implementation
3. Click the + icon in the Component Implementation Dropdown
4. Name your Implementation, then click Create Implementation

The new Implementation is created and can be added to your Component Implementation Workspace following the steps in the previous section.

note

If the selected Component does not yet have any Implementations, an Add Implementation button will be shown in its dropdown. Click this and continue to step 4.

The second method you can use is to create a new Component and add an Implementation for it right from the Workspace. This follows the same rules detailed in the Components section of the manual.

How to create a new Component in a Workspace

1. Open the Workspace for a Component Implementation, then click on the Component Library Icon
2. Click on the + New Component Button
3. Enter a Name for the new Component, then select its Category and Team and enter a description if desired, then click Next
4. Specify the Component Type and click Next
5. Name the Implementation and click Create Implementation

The new Component and its First Implementation are created. The new Implementation can be added to your Component Implementation Workspace following the steps in the previous section.

Manage Subcomponents

You can also manage the subcomponents in your Component Implementation Workspace. You can remove subcomponents that are no longer needed, view details about your subcomponents, and switch to different Implementations of your subcomponents to further configure your Component Implementations.

important

Making changes to a Component Implementation creates a new revision of the Implementation. See the Revision Management section for details.

Remove Subcomponents

If a subcomponent is no longer needed in your Component Implementation, it is simple to remove it from the Workspace.

How to remove a subcomponent from a Component Implementation

1. Click Open Workspace for your Component Implementation
2. Click on the Menu icon on the Subcomponent you wish to remove
3. Click Remove, then click Save

The subcomponent will be removed from the Component Implementation.

Subcomponent Details

You can view the Component Type, Details, and Component Implementation for each subcomponent without leaving your Implementation's Workspace.

How to view subcomponent details

1. Navigate to your Component Implementation Workspace
2. Click on the Status icon next to its version

A popup is opened and shows the subcomponent's Component Type and details.

How to view a subcomponent's Component Implementation

1. Navigate to your Component Implementation Workspace
2. Click on the Menu Icon for one of your subcomponents
3. Click Open New Tab

A new Workspace Tab is opened and shows the Component Implementation for the selected subcomponent.

important

You can make changes to the subcomponent's Component Type or Component Implementation if it belongs to a team you are part of. This will create a new revision of the Type or Implementation and be reflected throughout Tangram Pro™. See the Revision Management section of the manual for more details.

Swap Implementations

You can quickly switch out the Implementation of a component that you are using as a subcomponent in your Implementation right from your Implementation Workspace.

How to swap subcomponent Implementations

1. Navigate to your Component Implementation Workspace
2. Click on the Menu Icon for a subcomponent that has multiple Implementations
3. Click Swap Implementation
4. Click on the Implementation you wish to use, then click Save

The subcomponent is updated in your Component Implementation.

Connect Components

Components send and receive messages through ports. Connections specify how subcomponents communicate. Subcomponents can connect to one another and to the parent Component. The connection defines how (and if) Components work together within an Implementation.

There are two requirements for creating connections:

DIRECTIONALITY: All connections must have a port that can send a message and a port that can receive a message.

PORT MESSAGES: Connection ports must use the same messages, or a Transform must exist between the messages of the selected ports.

note

A TRANSFORM is code that enables messages to get from one format to another. Tangram Pro™ can generate Transform code in C++ and Java.

Connect Subcomponents

Subcomponents with ports that communicate using the same messages with the proper directionality are compatible by default and simple to connect in Tangram Pro™ Workspaces.

Tangram Pro™ automatically suggests connections between matching ports in the *Connections Pane.*

How to connect subcomponents with matching port messages

1. Click on a subcomponent's Connection Button
2. Click on the Connection Button for the subcomponent to connect to open the Connections Pane
3. Click Add Suggested. All of the subcomponents' compatible ports will be shown.
4. Click on the ports you wish to connect, then click Done

The Connections Pane closes and the connection is created and shown in the Workspace.

tip

Hover over the new Connection line for a quick view message pane.

important

Components can be connected through ports that send and receive different message types when a Transform is available.

Tangram Pro™ indicates when a Transform is required between ports. If a Transform exists, it will be applied to the connection automatically. If a Transform does not exist, an error message is shown. A different port must be used to create the new connection.

How to connect subcomponents with different port messages

1. Click on a subcomponent's Connection Button
2. Click on the Connection Button for the subcomponent to connect to open the Connections Pane
3. Click New Connection
4. Select ports for which a Transform exists
5. Click Done

A message is shown when a Transform exists. The connection is created and shown in the Workspace.

Connect to a Parent Component

Connections between subcomponents and the parent Component (the Component that you are creating an Implementation for) are simple to create. These types of connections specify how a subcomponent works with the Component and follow the same rules as connecting subcomponents to one another within an Implementation.

How to connect a subcomponent to its parent Component

1. Click on the Connect button shown on the upper left side of the Implementation Workspace
2. Click the Connect button on the subcomponent you wish to connect to
3. Click the + New Connection button or the Add Suggested button and connect the Components
4. Click Done

The Connections Pane closes and the connection is created.

Update Connections

Lines between subcomponents indicate existing connections in the Workspace. Clicking on a connection line between two Components opens the Connections Pane where changes to existing connections can be made.

How to edit Component connections

1. Click on a connection line
2. Update an existing connection by changing the ports used to communicate or the Connection name
3. Click Done

The Connection Modal closes, and connection is updated.

How to remove Component connections

1. Click on a connection line
2. Click X on an existing connection
3. Click Done

The Connection Modal closes, and the connection is removed.

important

Removing connections between Components that use a Transform will impact all of the parent Components' existing Workflows which rely on it. In this case, an alert will be shown and require confirmation before the connection is removed.

Workspace Editing

Component Implementation Workspaces provide additional tools for editing and managing components that your team owns. You can update or change the Component Type definition, change its name and description, and add source code to it.

Component Type

You can add and change a Component Type's ports and properties from the Component Implementation Workspace in the Edit Type Panel.

How to update a Component Type definition in a Workspace

1. Click the Edit Type menu button in the Implementation Workspace
2. Make updates to the ports and/or properties
3. Click Update Type

Updates to the Component Type are saved and applied to the Implementation.

You cannot make changes to Component Types owned by another team, even if you are using one of its Implementations as a subcomponent.

Other Implementations using the Component will continue to use the original revision of the Component Type. Clicking the Edit Type button in the other Implementation Workspaces will give a prompt to apply the update manually.

Component Details

You can update a Component's name and description from the Component Implementation Workspace in the Component Information Panel.

How to update Component details in a Workspace

1. Click the Component Information menu button in the Implementation Workspace
2. Hover over the Component's Name or Description and click the Edit button
3. Make desired changes, then click Save

Updates to the Component Details are saved.

Changes to the Component Name and Descriptions will be reflected immediately throughout the app.

Source Code Integrations

Component Implementations can be integrated with source code repositories in Implementation Workspaces. Each Implementation of a Component can have its own integration, and they are easy to set up.

Teams must have a Source Code Repository connected to Tangram Pro™ to use this feature. See Repositories section for more information.

Teams that have repositories integrated with Tangram Pro™ can add source code to their Component Implementations in Workspaces.

How to add source doe to a Component Implementation

1. Click the Edit Source button in the Workspace Menu
2. Click on the Select Platform Carat and select a Platform from the dropdown list
3. Select a Repository from the repository list to add to the Component Implementation

The repository is connected to the Component Implementation and the Source Panel closes.

important

If the Component Implementation is used elsewhere in Tangram Pro™ as a subcomponent, the previous revision of the Component Implementation will continue to be used until it is manually updated. See the Revision Management section.

Update Integrations

Teams can also update and remove source code integrations in Component Workspaces.

How to update an existing source code integration

1. Click the Edit Source button in the Workspace Menu
2. Click on the Select Platform Carat and select a Platform from the dropdown list
3. Select a Repository from the repository list to use for the Component Implementation

The Component Implementation's source code integration is updated and the Source Panel closes.

How to remove a source code integration

1. Click the Edit Source button in the component's Workspace
2. Click the X button on the active repository

The Component Implementation's source code integration is removed.

important

If the Component Implementation is used elsewhere in Tangram Pro™ as a subcomponent, the previous revision of the Component Implementation will continue to be used until it is manually updated. See the Revision Management section.

Revision Management

Making changes to a Component Type or Implementation creates a new revision of the resource. The new revision applies immediately to the base Component and Component Implementation- this means that if a Component Type is updated, any new Implementation of that Component will use the most recent revision of the Type, and if a Component Implementation is updated, any new use of that Implementation as a subcomponent somewhere else will use its latest revision.

Since Components are designed to be reusable, existing Component Implementations remain stable when a Component Type changes until they are updated manually. Similarly, anywhere that an updated Component Implementation is used as a subcomponent will be unaffected until it is manually updated. This means that when the subcomponents or you use in your Component Implementations are edited somewhere else, you must manually apply the updates in order to use the most current revision of the resource.

Update Revisions

A new revision of a Component Type is created when any user:

• Adds, edits, or removes ports from the Component Type

• Adds, edits, or removes properties from the Component Type

Clicking Save after making changes to a Component Type's ports or properties creates a new revision of the Component Type. New Implementations of the Component will use the new revision of the updated Type. Existing Component Implementations will continue to use the old version until updated manually. If the change to the Component Type is made in a Workspace, the updated Component Type is immediately applied to that Component Implementation.

An alert is shown on the Component Details Pane and in the Component Implementation Workspace when an Implementation is using an outdated revision of the Component Type.

Your Component Implementations will not be impacted by changes to Component Types until review and acceptance of the changes in the Implementation Workspace.

How to update to the latest version of an interface definition

1. Click Open Workspace for a Component Implementation using an outdated revision of a Component Type
2. Click on the Edit Type menu button
3. Review the changes in the Update Interface Modal
4. Click Use Latest Revision

The modal closes and your Component Implementation updates to use the newest revision of the Component Type.

note

Updating to the latest version of a Component Type is optional. If you do decide to accept the changes, a new revision of your Component Interface will be created using the updated Type.

A new revision of a Component Implementation is created when any user:

• Adds or removes a subcomponent to the Implementation

• Adds, edits, or removes connections in the Implementation

• Edits or changes the Component Type used by the Implementation

• Adds, edits, or removes a source code integration from the Implementation

Since any Component Implementation in Tangram Pro™ can be used as a subcomponent to another, the following rules apply to avoid conflicts:

• Saving changes to a Component Implementation in its Workspace creates a new revision of the Implementation immediately

• New uses of the Implementation as a subcomponent will use the
  newest revision

• Existing uses of the Implementation as a subcomponent continue to use the old version

The subcomponents in your Component Implementations will remain stable until you manually update them. You can choose when and if to update to the new revision of the subcomponent.

This seems like a lot to keep track of, but Tangram Pro™ makes it easy to see when a new revision of a subcomponent is available. When you open your Component Implementation Workspace, an alert icon will be shown on any subcomponent that has an update available.

The alert also functions as an update button. When clicked, the Update Modal opens and shows the changes available in the new revision, including any changes to the subcomponent's Type and Implementation.

How to update a subcomponent to its latest revision

1. Click Open Workspace for a Component Implementation
2. Click on the Red Revision Update Icon for an outdated subcomponent
3. Review the changes in the Subcomponent Update Modal
4. Click Accept Latest

The modal closes and the subcomponent updates to its newest revision.