Get Element Type

Overview

This API describes the element type in detail for OpsHub to be able to integrate various basic and complex data for a given element type.

Note: It is important to return a complete and accurate response for this API, as OpsHub relies heavily on these inputs to automatically handle multiple connector tasks.

API URI

This is the URI OpsHub will execute to call this API:

GET: /mbse/api/1.0/element-types?projectId=<projectId>&elementTypeId=<elementTypeId>

URI Parameters

Name

Required

Type

Description

projectId

query

True

String

ID of the project for which element type details must be returned. The projectId here will be the same as the id provided in the /projects API response

elementTypeId

query

True

String

‘id’ of element type provided in the 'Element Type Metadata' json.

Response Payload


{

  "multiStepUpdate": "NO_SUB_STEPS, STATIC_SUB_STEPS, DYNAMIC_SUB_STEPS",

  "commitStrategy": "COMMIT_TO_MAIN_BRANCH, COMMIT_TO_TEMP_BRANCH_AND_MERGE",

  "history": {

    "type": "FIELD_BASED, FULL_STATE_BASED",

    "revisionDateFormat": "dd/MM/YYYY’T’hh:mm:ss.SSSz",
    
    "revisionUserDataType": "USERNAME_AS_USER, EMAIL_AS_USER",

    "isRevisionIdNumeric": "true/false | datatype: boolean",
    
    "sortableFields":"CREATED_UPDATED_TIME, ENTITY_ID, REVISION_ID"

  },

  "elementScope": {

    "additionalScopePropertyName": "property id used as additional scope"

  },
  
  "isTagIdConstantAcrossProjects": "true/false | datatype: boolean",

  "isInternalValueExistForEnumeration": "true/false | datatype: boolean",
  
  "searchElementInfo": {

    "isRecursiveSearchSupported" : "true/false | datatype: boolean",
    
    "sortableFields": "CREATED_UPDATED_TIME, ENTITY_ID, REVISION_ID",

    "isGroupingSupported": "true / false",

    "isSearchPossibleOnAnyField": "true / false",

    "isCriteriaInSystemNativeFormat": "true / false",

    "dateTimeFormat": "dd/MM/YYYY’T’hh:mm:ss.SSSz",
    
    "batchSizeForInQuery": "number of entities that can be passed in 'IN' or 'OR' query"

  },

  "comments": {

    "commentElementMetadata": {
      
      "elementTypeId": "id of the element type",
              
      "titlePropertyName": "property name of element in which title of comment is stored",
      
      "bodyPropertyName": "property name of the element in which body of the comment is stored"
      
    },
    
    "commentBodyDataType": "TEXT, HTML, WIKI",
    
    "authorDataType": "USERNAME_AS_USER, EMAIL_AS_USER",
    
    "typesOfComments": [

      "Private",

      "Public",

      "etc."

    ]

  },

  "files": {
    
    "deleteSupported": "true/false | datatype: boolean"
    
  },

  "relations": {

    "deleteSupported": "true/false | datatype: boolean",

    "relationTypes": [

      {

        "relationType": "Name of the relation between current element and the other element",

        "reverseRelationType": "Name of the relation from the other element to the current element.",

        "isMultiRelationAllowed": "true/false | datatype: boolean",

        "isMandatory": "true/false | datatype: boolean"
      }

    ]

  },
  
  "updateLockScope": "ELEMENT, PROJECT, NONE"

}

Response Parameters

Parent Parameters

Name

Required

Type

Description

multiStepUpdate

True

Enum

Determines whether all properties/tags of an element can be updated in a single update API call or require multiple update calls. If all properties/tags can be updated in a single API call in the end system, pass NO_SUB_STEPS. If the end system provides a separate API to transition an element from one state to another, the connector should pass STATIC_SUB_STEPS or DYNAMIC_SUB_STEPS, depending on the requirement.. * NO_SUB_STEP: All the fields of an element can be updated in single update element API call. * STATIC_SUB_STEPS: Step number of the field to be updated is predefined. So, every time when multiple fields are updated in single update, based on updateStepNumber of field, the order of field can be decided for the update. * DYNAMIC_SUB_STEPS: The order in which the fields can be passed to the end system for the update is dynamically decided based on field value. E.g., if the element is getting closed along with few other fields getting updated. In this case, other fields must be updated first and then element status should be updated to closed.

commitStrategy

True

Enum

OpsHub uses this flag to identify how changes should be committed in the end system repository. Based on the repository workflow and branching model, the connector specifies whether the changes should be committed directly to the main branch or first committed to a temporary branch and then merged. * COMMIT_TO_MAIN_BRANCH: Commits the changes directly to the main branch. This is suitable when direct commits are allowed and revisions can be added to the main branch without additional governance, review, or merge steps. * COMMIT_TO_TEMP_BRANCH_AND_MERGE: Changes are first committed to a temporary branch and then merged into the main branch. This is suitable when the end system creates a new revision for every update and revisions need to be introduced into the main branch in a governed or review-based flow.

History

False

Pass this parameter, if the pollerType for element type is ENTITY_WISE_HISTORY

Type

True

Enum

Specifies how the end system returns element history. FIELD_BASED: For a given revision, only the properties/tags that changed in that transaction are returned, along with their old and new value. FULL_STATE_BASED: For a given revision, the end system returns the element field state for all fields as of that revision.

revisionDateFormat

True

String

Date format for the property/tag, which contains revision date time

revisionUserDataType

True

Enum

Data type of the revision user. EMAIL_AS_USER: When the user’s email is provided in the revision user property/tag. USERNAME_AS_USER: When the username is provided in the revision user property/tag.

isRevisionIdNumeric

True

Boolean

When set to true, revision sorting is performed using the numeric value of the revision ID. When set to false, revision sorting is performed using the string value of the revision ID. Default value is false.

sortableFields

False

Set<Enum>

Set of properties/tags on which the end system supports sorting in the History API. The properties/tags may be provided in any order. The connector must support sorting on all fields specified in this set. Example: If end system supports sorting on ENTITY_ID, CREATED_UPDATED_TIME and REVISION_ID: sortableFields = {CREATED_UPDATED_TIME, ENTITY_ID, REVISION_ID}<br><br> `If end system supports sorting only on CREATED_UPDATED_TIME: `sortableField={CREATED_UPDATED_TIME}. In case of history, CREATED_UPDATED_TIME is same as REVISION_DATE_TIME.

Parent Parameter

Name

Required

Type

Description

elementScope

False

If element scope is decided based on only element type and any additionalScopeField (like a project) is not required, this property can be set to null.

additionalScopePropertyName

True, if elementScope is passed.

Boolean

Name of the property that determines additional scope for the element. If the scope depends only on the element type, this value can be set to null. If the scope depends on both the element type and another element property (e.g., projectId, workspaceId, or domainId), provide the name of that property.

isTagIdConstantAcrossProjects

True

Boolean

Indicates whether the Tag ID remains the same for the same Tag across different projects. Set to true if the Tag ID is consistent across projects. Set to false if the Tag ID differs across projects. Example:If a Tag with display name Text has ID 100 in Project A and 101 in Project B, set this value to false. If the Tag ID is the same (e.g., Text or 100) across all projects, set this value to true. If set to true, OpsHub will use the Tag ID for mapping. Otherwise, it will use the Tag name.

isInternalValueExistForEnumeration

True

Boolean

Indicates whether enumeration literals have separate internal and display values. Set to 'True' if the enumeration literals have different internal and display values. Set to 'False' if the enumeration literals have only one value, the display value. Example 1:

"isInternalValueExistForEnumeration": true
 [ { "id": "low", "value": "Low" }, { "id": "medium", "value": "Medium" }, { "id": "high", "value": "High" } ]

Here, enumeration literals of priority has values having different internal value and display value. Example 2:

"isInternalValueExistForEnumeration": false, [ { "id": "Low", "value": "Low" }, { "id": "Medium", "value": "Medium" }, { "id": "High", "value": "High" } ]

Here, the enumeration literals of priority field does not have a different value for internal value.

Parent Parameter

Name

Required

Type

Description

searchElementInfo

True

Contains metadata required for querying the end system to search elements.

isRecursiveSearchSupported

False

Boolean

Indicates whether the end system supports recursive search functionality. Set this flag to True if the end system allows searching across hierarchical levels (for example, retrieving items from nested folders, child containers, or substructures within a single search operation). Set it to False if recursive or hierarchical search is not supported and only direct-level search is possible.

sortableFields

False

Set<Enum>

Set of fields for which the end system supports sorting in search operations. Fields may be provided in any order. For searchElementInfo no need to pass REVISION_ID in sortableFields set. E.g. If end system supports sorting on both ENTITY_ID and CREATED_UPDATED_TIME, sortableFields = {ENTITY_ID, CREATED_UPDATED_TIME}

isSearchPossibleOnAnyField

True

Boolean

Indicates whether the configured search criteria can be stored and executed directly in the end system. Set to true only if the field selected for criteria storage is queryable in the end system. Set to false if search criteria cannot be stored or executed natively in the end system.* To get more details on end system criteria storage, refer [[ Integration_Configuration#Criteria_Configuration

isCriteriaInSystemNativeFormat

True

Boolean

Set to true if the configured criteria in OpsHub will be provided in the end system’s native query format. In this case, the criteria must exactly match the query syntax supported by the end system. Set to false if the criteria will be provided in the standard OpsHub JSON query format.

dateTimeFormat

True

String

Date time format supported within the query. E.g., (where updatedDate > ‘2021-12-31 00:00:00’). Here, dateTimeFormat should be set as yyyy-MM-dd HH:mm:ss

batchSizeForInQuery

False

Integer

Number of entities end system supports in "IN" or "OR" query. Default will be 250. E.g. for IN query: entityId IN (1, 2, 3) E.g. for OR query: (entityId = 1) OR (entityId = 2) OR (entityId = 3)

Parent Parameter

Name

Required

Type

Description

comments

False

Provide this parameter if the end system supports comments as elements for a given element type. If this parameter is included, the MBSE SDK must implement all required Comment APIs. If comments are not supported, this parameter should not be sent.

commentElementMetadata

True

Metadata configuration required when comments are treated as elements in the end system. Defines how comment information is stored and mapped

commentElementMetadata.elementTypeId

True

String

Identifier of the element type that represents comments in the end system.

commentElementMetadata.titlePropertyName

True

String

Name of the property of the comment element in which the comment title is stored. If the end system does not support a separate title field, this may be set to null.

commentElementMetadata.bodyPropertyName

True

String

Name of the property of the comment element in which the comment body/content is stored

commentBodyDataType

True

Enum

Data type of the comment body. Supported values: TEXT, HTML, WIKI.

authorDataType

False

Enum

Defines how user information should be provided when creating or syncing comments. Use USERNAME_AS_USER if the end system expects a username. Use EMAIL_AS_USER if the end system expects an email address.

htmlReplacementForNewLine

True

String

Exact value for new line character in the comment. Possible values are: ‘ ’, ‘\n’ or null.

typesOfComments

True

List<String>

The supported list of comment types. E.g., Internal, External, Work Notes, Additional etc. OpsHub will display these comment types under comment mapping. The user can map comment types across connectors to decide the type of comments they want to integrate.

Parent Parameter

Name

Required

Type

Description

files

False

Pass this parameter if you want to integrate files for a given element type. Otherwise, do not send the files parameter at all. If this parameter is passed, MBSE SDK must implement all the Files APIs.

deleteSupported

True

Boolean

Send true if the end system has an API to delete the file; otherwise, false.

Parent Parameter

Name

Required

Type

Description

relations

False

Provide this parameter if the end system supports element relationships for a given element type. If this parameter is included, all required Relations APIs must be implemented. If relationships are not supported, this parameter should not be sent.

deleteSupported

True

Boolean

Indicates whether the end system allows deletion of an existing relation between elements.

relationTypes

True

relationType

True

String

Name of relation type: Parent, Child, Relates To, Satisfies, Association, etc

reverseRelationType

True

String

Name of its reverse relation. E.g., if the relation type is Parent, then the opposite relationType is Child, i.e. Entity E1 is the parent of element E2, and E2 is the child of E1

isMultiRelationAllowed

True

Boolean

Indicates whether multiple relations of this type can be created for a single element. True: If multiple relations of this type can be created. False: if only one relation of this type can be created. For example: Adding only one parent is allowed to be added for any element, so set multiRelationAllowed to false for Parent Type. On the other hand, for the ‘Related’ relation type, any number of relations can be added, so send true

isMandatory

True

Boolean

Indicates whether this relation type is mandatory during element creation or update. Set to true if at least one relation of this type must exist. Set to false if the relation is optional. For example, it might be mandatory to have a Parent relation to another work item for sub-task or task element type. In this case, send true for the Parent relation type for Task

updateLockScope

True

Enum

OpsHub uses this flag to determine the scope at which a lock should be applied during an update operation. This helps prevent concurrent modification conflicts based on how the end system manages updates. * ELEMENT: A lock is applied only at the individual element level during update. Other elements within the same project can still be updated concurrently. * PROJECT: A lock is applied at the project level. While an element is being updated, other elements within the same project cannot be updated simultaneously. * NONE: No explicit lock is applied during update operations. The end system handles concurrency independently or does not require locking.

PreviousGet All Workspaces

NextGet Stereotypes

Last updated 1 month ago