createWorkspace

Create SysML v2 workspace

Since R2026a

Syntax

workspace = createWorkspace(project,branchId=branch,retrieveElements=retrieve)

Description

workspace = createWorkspace(project,branchId=branch,retrieveElements=retrieve) creates a workspace for a specified commit in the SysML^® v2 project, project. If you call createWorkspace with no arguments, the workspace created is anchored to the head commit of the default branch and retrieves all elements. Specify the branch ID using branch, and choose to retrieve all elements upon creation using retrieve, which has a default value of true.

example

Examples

collapse all

Connect to Repository and Get Elements

This example assumes a SysML v2 project with specific content described by this SysML v2 text.

package test1 {
    part def myArch;
    part def subArch :> myArch;
    part def myTopArch {
      part A:subArch;
    }
}

If you have access to a SysML v2 editor, you can publish SysML v2 text into a repository.

Connect to a local repository. When published into a repository, the SysML v2 text gets translated into SysML v2 elements you can access via the getElements function.

First, connect to the server. If your server supports authentication via bearer token, then provide your token as the credentials argument systemcomposer.sysml.Repository.connect(serverUrl,credentials="my-token").

serverUrl = 'http://vdi-abcde-123:8000';
repo = systemcomposer.sysml.Repository.connect(serverUrl)

repo = 
  Repository with properties:

    BaseUri: 'http://vdi-abcde-123:8000'

You can obtain information about all the projects in the repository by calling getProjects. Alternatively, if you know the ID of the project you want to use, then you can retrieve it directly by calling getProjectById.

allProjects = repo.getProjects();
projectToUse = repo.getProjectById('f6deaa82-d16f-40aa-a2bb-f4b04f8e0fc6')

projectToUse = 
  Project with properties:

    ResourceIdentifier: 'http://vdi-ahdsl2-016:9000/projects/f6deaa82-d16f-40aa-a2bb-f4b04f8e0fc6'
                    Id: 'f6deaa82-d16f-40aa-a2bb-f4b04f8e0fc6'
           Description: ''
                  Name: 'supers'

To look at the elements of a project, first create a workspace for a specified commit in the project by calling createWorkspace. If you call createWorkspace with no arguments, the workspace created is anchored to the head commit of the default branch and retrieves all elements. Alternatively, if you know the branch that you are working with, then you can provide the branch ID by calling createWorkspace(branchId="123456").

myFullWorkspace = projectToUse.createWorkspace()

myFullWorkspace = 
  Workspace with no properties.

The simplest technique for inspecting the elements of a workspace is to call getElements, which lists all the elements in the snapshot for the anchored commit for the workspace and retrieves all elements if they were not retrieved upon workspace creation. The output shows that this snapshot has 17 elements, which populates a local cache of the snapshot, organized as a graph based on the SysML v2 metamodel.

allElements = myFullWorkspace.getElements()

allElements = 

  1×17 Element array with properties:

    meta

You can now write code to inspect the elements of the workspace. For example, you can find all the elements that are of type Package. In this example, only one element, test1, has this type.

theOnlyPackage = allElements([allElements.meta] == "Package");
theOnlyPackage.get("declaredName")

ans = "test1"

From any element, you can navigate to related elements using the SysML v2 properties of that element. For example, we can look at one of the members of the package.

allOwnedMembers = theOnlyPackage.ownedMember
aMember = allOwnedMembers(3);
aMember.get("declaredName")

ans = "myTopArch"

This member is a part definition that contains a single part. You can find that part and its type. The owner of this type is the original package.

thePart = aMember.ownedPart
thePartsType = thePart.type
backToTheStart = thePartsType.owner == theOnlyPackage

thePart = 
  Element with properties:

                        meta: "PartUsage"
                    aliasIds: []
                declaredName: "A"
                 isComposite: 1
           declaredShortName: []
                        type: [1×1 systemcomposer.sysml.Element]
                   isPortion: 0
                  isConstant: 0
           isImpliedIncluded: 0
                   direction: []
                  isAbstract: 0
                   elementId: "d94aa221-0952-4e8e-8a66-51488d990275"
                ownedFeature: [0×0 systemcomposer.sysml.Element]
                   isDerived: 0
                     feature: [0×0 systemcomposer.sysml.Element]
                isSufficient: 0
                       isEnd: 0
                     variant: [0×0 systemcomposer.sysml.Element]
                isIndividual: 0
                   isOrdered: 0
               documentation: [0×0 systemcomposer.sysml.Element]
                    isUnique: 1
                  isVariable: 0
                 isVariation: 0
           ownedRelationship: [1×2 systemcomposer.sysml.Element]
          owningRelationship: [1×1 systemcomposer.sysml.Element]
                 portionKind: []
                  annotation: [0×0 systemcomposer.sysml.Element]
             chainingFeature: [0×0 systemcomposer.sysml.Element]
                  definition: [1×1 systemcomposer.sysml.Element]
             nestedAttribute: [0×0 systemcomposer.sysml.Element]
                  nestedPart: [0×0 systemcomposer.sysml.Element]
      ownedFeatureMembership: [0×0 systemcomposer.sysml.Element]
                ownedElement: [1×1 systemcomposer.sysml.Element]
             ownedEndFeature: [0×0 systemcomposer.sysml.Element]
        ownedFeatureChaining: [0×0 systemcomposer.sysml.Element]
             ownedSubsetting: [0×0 systemcomposer.sysml.Element]
                 ownedImport: [0×0 systemcomposer.sysml.Element]
                 ownedMember: [1×1 systemcomposer.sysml.Element]
                 ownedTyping: [1×1 systemcomposer.sysml.Element]
             ownedMembership: [1×1 systemcomposer.sysml.Element]
           ownedRedefinition: [0×0 systemcomposer.sysml.Element]
    ownedReferenceSubsetting: [0×0 systemcomposer.sysml.Element]
                       owner: [1×1 systemcomposer.sysml.Element]
                typedFeature: [0×0 systemcomposer.sysml.Element]
         referenceExpression: [0×0 systemcomposer.sysml.Element]
        satisfiedRequirement: [0×0 systemcomposer.sysml.Element]
                  subsetting: [0×0 systemcomposer.sysml.Element]
       textualRepresentation: [0×0 systemcomposer.sysml.Element]
                       usage: [0×0 systemcomposer.sysml.Element]
                   valuation: [0×0 systemcomposer.sysml.Element]

thePartsType = 
  Element with properties:

                      meta: "PartDefinition"
                  aliasIds: []
              declaredName: "subArch"
                   variant: [0×0 systemcomposer.sysml.Element]
              isIndividual: 0
         declaredShortName: []
                 elementId: "9c0d5f85-07cb-4013-aaec-7be7c8bc362e"
                   feature: [0×0 systemcomposer.sysml.Element]
              isSufficient: 0
                isAbstract: 0
         isImpliedIncluded: 0
               isVariation: 0
         ownedRelationship: [1×1 systemcomposer.sysml.Element]
        owningRelationship: [1×1 systemcomposer.sysml.Element]
                annotation: [0×0 systemcomposer.sysml.Element]
             documentation: [0×0 systemcomposer.sysml.Element]
            ownedAttribute: [0×0 systemcomposer.sysml.Element]
    ownedFeatureMembership: [0×0 systemcomposer.sysml.Element]
              ownedElement: [0×0 systemcomposer.sysml.Element]
           ownedEndFeature: [0×0 systemcomposer.sysml.Element]
              ownedFeature: [0×0 systemcomposer.sysml.Element]
               ownedImport: [0×0 systemcomposer.sysml.Element]
               ownedMember: [0×0 systemcomposer.sysml.Element]
           ownedMembership: [0×0 systemcomposer.sysml.Element]
                 ownedPart: [0×0 systemcomposer.sysml.Element]
    ownedSubclassification: [1×1 systemcomposer.sysml.Element]
                     owner: [1×1 systemcomposer.sysml.Element]
     textualRepresentation: [0×0 systemcomposer.sysml.Element]
              typedFeature: [0×0 systemcomposer.sysml.Element]
                     usage: [0×0 systemcomposer.sysml.Element]

backToTheStart = logical
   1

Get the element relationships around the PartUsage element to learn more about how the elements are connected.

elemRels = getElementRelationships(myFullWorkspace,thePart)

elemRels = 

  1×3 Element array with properties:

    meta

Confirm that the element thePart is the only element of type PartUsage.

queryString = '{"@type":"Query","name":"string","where":{"@type":"PrimitiveConstraint","operator":"=","property":"@type","value":["PartUsage"]}}';
flag = isequal(getElement(myFullWorkspace,"d94aa221-0952-4e8e-8a66-51488d990275"),...
executeQuery(work,queryString))

flag =

  logical

   1

Writing code is the most flexible approach to finding elements, but you can also get element relationships by looking at the root elements of a project. Root elements have no owner. In this case, the project has only one root element, which has a single member, the package test1.

root = myFullWorkspace.getRootElements()
rootMember = root.ownedMember.get("declaredName")

root = 
  Element with properties:

                     meta: "Namespace"
                 aliasIds: []
             declaredName: []
        declaredShortName: []
               annotation: [0×0 systemcomposer.sysml.Element]
                elementId: "2e329208-1900-4282-9229-7f5da441bee5"
        isImpliedIncluded: 0
       owningRelationship: [0×0 systemcomposer.sysml.Element]
        ownedRelationship: [1×1 systemcomposer.sysml.Element]
            documentation: [0×0 systemcomposer.sysml.Element]
             ownedElement: [1×1 systemcomposer.sysml.Element]
              ownedImport: [0×0 systemcomposer.sysml.Element]
              ownedMember: [1×1 systemcomposer.sysml.Element]
          ownedMembership: [1×1 systemcomposer.sysml.Element]
                    owner: [0×0 systemcomposer.sysml.Element]
    textualRepresentation: [0×0 systemcomposer.sysml.Element]

rootMember = "test1"

You can also find elements with a given meta type and name.

theTopArch = myFullWorkspace.getElementsByTypeAndName('PartDefinition','myTopArch');
theTopArch.get("declaredName")

ans = "myTopArch"

Once the elements for a given commit are in the cache, you can use MATLAB^® to explore the element graph for the project. However, you can obtain some collections of elements via a single function call. For example, you can get all the members of a namespace by using getMembershipHierarchy. The first element in the returned vector is the source element. Conversely, you can find the ownership hierarchy of an element by calling getOwnershipHierarchy. As previously, the first element of the vector is the source element.

myMembers = myFullWorkspace.getMembershipHierarchy(theOnlyPackage)
myOwners = myFullWorkspace.getOwnershipHierarchy(thePart)

myMembers = 

  1×7 Element array with properties:

    meta

myOwners = 

  1×4 Element array with properties:

    meta

SysML v2 also enables easy classification of elements. You can find the subclasses of a definition by using the getDescendants method. In this case, subArch is the only subclass.

myArch = myFullWorkspace.getElementsByTypeAndName('PartDefinition','myArch');
mySubDefinitions = myFullWorkspace.getDescendants(myArch)
mySubDefinitions(end).get("declaredName")

mySubDefinitions = 

  1×2 Element array with properties:

    meta

ans = "subArch"

You can find its superclasses by calling getAncestors. In this case, myArch is the only superclass.

mySuperDefinitions = myFullWorkspace.getAncestors(subArch)
mySuperDefinitions(end).get("declaredName")

mySuperDefinitions = 

  1×2 Element array with properties:

    meta

ans = "myArch"

You can also find all the usages of a given definition by using the getUsages method. In this project, only one definition has any usages, subArch, which has a PartUsage A.

theOnlyUsage = myFullWorkspace.getUsages(subArch);
theOnlyUsage.get("declaredName")

ans = "A"

Input Arguments

collapse all

`project` — Project
project object

Project, specified as a systemcomposer.sysml.Project object.

`branch` — Branch ID
string

Branch ID, specified as a string.

Data Types: string

`retrieve` — Option to retrieve all elements upon creation
`1` (`true`) (default) | `0` (`false`)

Option to retrieve all elements upon creation, specified as 1 (true) or 0 (false).

Data Types: logical

Output Arguments

collapse all

`workspace` — Workspace
workspace object

Workspace, returned as a systemcomposer.sysml.Workspace object.

More About

collapse all

Definitions

Term	Definition	Application	More Information
Repository	A repository is a storage location for SysML v2 projects.	Connect to a remote repository via its URL. Then, retrieve the details of all projects in the repository.	`systemcomposer.sysml.Repository`
Project	A project is a container for SysML v2 data elements. A project contains a set of commits, which are time-stamped snapshots of the project. Projects also contain a set of branches that describe parallel development paths in the project.	Use projects to store data for a SysML v2 modeling activity.	`systemcomposer.sysml.Project`
Workspace	A workspace holds a local cache of the snapshot for a given project commit.	Use a workspace to access all SysML v2 elements in a snapshot at a given point in the evolution of a project.	`systemcomposer.sysml.Workspace`
Element	An element is a fundamental unit of modeling. Elements are the building blocks of SysML v2 models and include parts, blocks, requirements, activities, interfaces, and relationships. Each element has a unique identity within the repository and can be referenced and reused across projects.	An element in a workspace corresponds to a SysML v2 element or elements. You can use an element object to access data and relationships specific to a SysML v2 element.	`systemcomposer.sysml.Element`

Version History

Introduced in R2026a

createWorkspace

Syntax

Description

Examples

Connect to Repository and Get Elements

Input Arguments

`project` — Project
project object

`branch` — Branch ID
string

`retrieve` — Option to retrieve all elements upon creation
`1` (`true`) (default) | `0` (`false`)

Output Arguments

`workspace` — Workspace
workspace object

More About

Definitions

Version History

See Also

Objects

Functions

Topics

External Websites

createWorkspace

Syntax

Description

Examples

Connect to Repository and Get Elements

Input Arguments

project — Project project object

branch — Branch ID string

retrieve — Option to retrieve all elements upon creation 1 (true) (default) | 0 (false)

Output Arguments

workspace — Workspace workspace object

More About

Definitions

Version History

See Also

Objects

Functions

Topics

External Websites

`project` — Project
project object

`branch` — Branch ID
string

`retrieve` — Option to retrieve all elements upon creation
`1` (`true`) (default) | `0` (`false`)

`workspace` — Workspace
workspace object