Add Element

API Name

API Name: Element – Create

---

Overview

This API creates a new element in the specified project (and optional branch).

MBSE Core uses this API to:

• Create new model elements

• Establish parent-child hierarchy

• Set initial properties and tags

• Establish mandatory relations during creation

Connector responsibility:

• Prepare the create request according to end system requirements.

• Create the element in the specified project and branch.

• Apply provided properties.

• Create or update supplied tags using connector-supported tag APIs.

• Create required relations as part of element creation.

• Convert the final created element into MbseElement format and return it.

---

API URI

POST: /mbse/api/1.0/elements
    ?projectId={projectId}
    &elementTypeId={elementTypeId}
    &branchId={branchId}

---

URI Parameters

Name	Mandatory	Type	Description
projectId	True	String	ID of the project where the element will be created.
elementTypeId	True	String	ID of the element type to be created.
branchId	False	String	ID of the branch. If omitted, default branch behavior applies.

---

Request Body

{
  "name": "System Block",
  "parentElementId": "package_1",
  "properties": {
    "status": "Draft"
  },
  "tags": {
    "criticality": "High"
  },
  "requiredRelations": [
    {
      "relationType": "dependency",
      "targetElementId": "requirement_55",
      "targetElementTypeId": "Requirement",
      "projectId": "123"
    }
  ]
}

---

Request Body Parameters

Name	Mandatory	Type	Description
name	True	String	Name of the element.
parentElementId	False	String	ID of the parent element.
properties	False	Map<String,Object>	Properties to set during creation.
tags	False	Map<String,Object>	Tagged values to set during creation.
requiredRelations	False	List	List of mandatory relations to establish during creation.

---

Behavior Rules

1. Element must be created within the scope of:

   • projectId

   • elementTypeId

   • Optional branchId

2. Only properties provided in the request must be set.

3. Connector must not modify or inject additional fields unless required by the end system.

4. Tags:

   • If tag exists → update it.

   • If tag does not exist → create it.

   • MBSE Core may provide utilities to support tag lifecycle management.

5. Required relations must be created during element creation if supported by the end system.

6. If creation fails:

   • Return appropriate HTTP error code.

7. The response must return the fully created element in MbseElement format.

---

Response Payload

Sample Response

{
  "elementId": "block_200",
  "name": "System Block",
  "elementTypeId": "Block",
  "qualifiedName": "Model::System::Block",
  "projectId": "123",
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdDate": "2026-02-14T12:00:00.000Z",
  "updatedDate": "2026-02-14T12:00:00.000Z",
  "parentElementId": "package_1",
  "properties": {
    "status": "Draft"
  },
  "tags": {
    "criticality": "High"
  },
  "relations": [
    {
      "relationType": "dependency",
      "targetElementId": "requirement_55",
      "targetElementTypeId": "Requirement",
      "projectId": "123"
    }
  ]
}

---

Response Parameters

The response must conform to the MbseElement structure defined in the Element – Get API.

Name	Required	Type	Description
elementId	True	String	Unique identifier of the created element.
name	True	String	Name of the element.
elementTypeId	True	String	ID of the element type.
projectId	True	String	Project ID.
createdBy	False	String	User who created the element.
createdDate	False	String (ISO-8601)	Creation timestamp.
properties	False	Map<String,Object>	Properties set during creation.
tags	False	Map<String,Object>	Tags set during creation.
relations	False	List	Relations created during creation.

Relation Object

Name	Required	Type	Description
relationType	True	String	Type of relation (association, dependency, etc.).
targetElementId	True	String	Target element ID.
targetElementTypeId	True	String	Target element type ID.
projectId	True	String	Project ID of the target element.
author	False	String	Creator of relation.
createdDate	False	String	Relation creation timestamp.

---

Error Handling

HTTP Status	Description
400	Invalid input parameters.
404	Project or parent element not found.
409	Conflict during creation (duplicate element, constraint violation).
500	Internal server error during element creation.

---

Implementation Guidelines

• Validate elementTypeId before creation.

• Validate parent element existence if parentElementId is provided.

• Avoid partial creation:

  • If property or tag creation fails, roll back if supported by the end system.

• Ensure timestamp format follows ISO-8601.

• Return consistent MbseElement structure.

---

Design Rationale

This API enables controlled element creation with:

• Hierarchical support

• Property initialization

• Tag lifecycle management

• Mandatory relation establishment

By separating creation from update and enforcing structured expansion rules, the MBSE integration layer remains deterministic and system-agnostic.