Last updated: 5/15/2025

Configuration

---

This section of the documentation will look at the details of Structure navigation configurations. It is expected that the reader is familiar with the Structure Concepts described in the Concept Documentation before reading this section.

Create structure in ConfigTool

---

To create a structure in the Config Tool:

1. Select project
2. Select STRUCTURES
3. Hit the 'add structure' button

1. Select the object you just created in the last step
2. Fill in Id and Name
3. Hit 'add link' to create the first object in your structure.

1. Your Id and Name could look like the following. The 'Id' must be unique among all the structures The 'Name' is the menu item shown to the user to be able to see this structure. Therefore 'Name' must be descriptive and easily understood.
2. Fill in the first linking as shown.
3. Choose the children you will be linking
4. Hit the plus button after you have chosen a child in 3. You may have several children that you link to. Remember that you must then include in this structure a definition/link of each child. Sometimes the child is pointing to itself as in this example with "NextAssemblyUsages" and then the definition/link already exists.
5. Hit the 'add link' button once more to define the document

Define your document as follows. Note that this document has no children but it must be defined here because it was referred to in the last link.

Hit the 'add select' button 6 times.

Fill in the "selects" as shown below. Note that the FieldRef often has 'value.' added. When the 'value.' is added it means that it refers to a field on the SoftType. When there is no 'value.' then it refers to the relationship object as in this example with 'Quantity' which is on the NextAssemblyUsage relationship object.

Hit the OrderBy 'add select' button once.

1. Fill in the Order and Select field as shown below.
2. Hit the Presentation's 'add column' button 4 times

1. Make sure the language code is correct
2. Fill in the columns as shown below.

Meta data

---

Each structure definition has a set of metadata describing the definition.

• $id - Unique id for the structure definition
• name - Name of the structure definition

"structures": [
  {
    "$id": "TechnicalPartStructure",
    "definition": {
      "name": "Technical Part Structure",
      "linking": ...,
      "select": ...,
      "orderBy": ...,
      "presentation": ...
    }
  }
]

linking

---

The linking section of the structure definition defines what SoftTypes to use within the structure navigation, the navigation it self, as well as the output schemas to use when loading structure nodes. Also included is a reference to a view to be used when editing the structure from each SoftType.

In the example below, we can see that the TechnicalPartStructure structure will be displaying two SoftTypes, TechnicalPart and TechnicalDocument. Both TechnicalPart and TechnicalDocument has an output schema named structureOut (note that these are two separate schemas). The TechnicalPart SoftType will have the edit button active while in the structure module since the $editView and $inputSchemaRef are set. TechnicalDocument is not defining an $editView or an $inputSchemaRef and will because of that not be editable.

The final part of the linking objects is the children section. children is an array of strings where each string refers to a property of the output schema for the SoftType. This tells the API handling the structure navigation that these are the "relations" to navigate over. Since the TechnicalDocument has no children section defined, the TechnicalDocument will only be displayed as leaf nodes in the tree view (i.e. no further navigation possible), there is however no limitation in defining children for all SoftTypes defined in the structure definition.

Warning

It is recommended to not use the resolve (see Output schema resolve) attribute when defining the structure output schemas. If the resolve is set the structure will load recursively which may have an impact on the application performance. The Output Schema used by the edit view should however use the resolve attribute on its Output Schema for the view to be able to display the children.

"linking": [
  {
    "$softTypeRef": "TechnicalPart",
    "$outputSchemaRef": "structureOut",
    "$inputSchemaRef": "editStructureIn",
    "$editView": "editStructure",
    "children": [
      {
        "id": "NextAssemblyUsages"
      },
      {
        "id": "documents"
      }
    ]
  },
  {
    "$softTypeRef": "TechnicalDocument",
    "$outputSchemaRef": "structureOut"
  }
]

select

---

The select section of the structure definition is used to define the structure output data. The $fieldRef binds to properties in the Output Schemas of the included SoftTypes. And the $id is used to define the output property name. If one of the SoftTypes does not have a matching value in its output the value will be left empty. The value of $fieldRef can use the . annotation to navigate to values within a JSON object defined in the Output Schema.

"select": [
  {
    "$id": "instanceId",
    "$fieldRef": "id"
  },
  {
    "$id": "id",
    "$fieldRef": "value.id"
  },
  {
    "$id": "versionId",
    "$fieldRef": "value.versionId"
  },
  {
    "$id": "name",
    "$fieldRef": "value.name"
  },
  {
    "$id": "description",
    "$fieldRef": "value.description"
  }
]

presentation

---

To define the table columns for a the tree table result the presentation section is used. It is possible to define multiple presentations, one per language code. Each column binds to the select via the $selectId property. The value of displayName will be used as the column header and the width defines the column width in pixels. If the optional link attribute is set to true values in that column will have a link for navigating down in the structure.

Note

Multi language support is not yet implemented, use langugeCode "en".

{
  ...
  "presentation": [
    {
      "languageCode": "en",
      "columns": [
        {
          "$selectId": "instanceId",
          "displayName": "Instance Id",
          "width": 200
        },
        {
          "$selectId": "id",
          "displayName": "Id",
          "width": 200
        },
        {
          "$selectId": "versionId",
          "displayName": "Version Id",
          "width": 200
        },
        {
          "$selectId": "name",
          "displayName": "Name",
          "link": true,
          "width": 200
        },
        {
          "$selectId": "description",
          "displayName": "Description",
          "width": 200
        }
      ]
    }
  ],
  ...
}

orderBy

---

The orderBy section is used to set the sorting of the result table for each structure navigation result. order can be set to either descending or ascending. It is possible to define multiple order conditions. The conditions are executed in the order they appear in the array.

{
  ...
  "orderBy": [
    {
      "order": "descending",
      "$selectId": "id"
    }
  ],
  ...
}

Entry reference configuration

---

This feature allows for configuring the REST APIs and the ShareAspace user interface in order to reference entries within a SoftType from another SoftType.

To explain this in a simpler manner we will use an example to describe what we want to be able to achieve. It is, however, important to know that this feature is not limited to this particular example. It can be applied to any SoftType to SoftType-entry reference configuration.

Note

All configuration steps will not be described. It is expected that the reader is familiar with SoftType configuration before following this configuration guide.

The setup

---

As for the example - we will configure an Engineering Change Order. From a business perspective an Engineering Change Order would typically describe input and output activates representing something to change (input) and the state after the change (output).

In this very simplified scenario we want to have a SoftType configuration of an Engineering Change Order to describe that a reference between a parent part and one of its children parts should be changed. I.e. we want to represent the data to be modified by the Change Order - the input to the Change Order activity.

This could have been done (with some restrictions) by having the Engineering Change Order referring to the parent part and the child part. This would however cause an issue. What if the same child appears as a child of the parent multiple times? How can we explicitly state that it is a specific reference? The answer is - we reference the explicit reference object (SoftType entry) from the Change Order.

Model representation

• Base PLM type ChangeOrder to be configured as the Engineering Change Order
• The Engineering Change Order will have one identifier and one name
• The Engineering Change Order will have an array of ActivityInputReference each referring to a NextAssemblyUsage

Note

This configuration setup is very simplified. The purpose is to describe the SoftType to SoftType-Entry reference support. In a real world scenario the Engineering Change Order would probably be configured to support more meta data, more references to documents, etc. As well as having output references in the same type of configuration as for the input references.

New features

---

To facilitate this configuration a set of changes and features were introduced.

• SoftType engine support for referencing entries in one SoftType from another SoftType
  • The old engine were limited to the Master-Version-Definition objects.
• Connection Ports can now be combined with other ports.
• A new user interface control, Child SoftType link, used for rendering a reference (entry) including information about the parent and the child.
• Updated versions of the single and multi quick select search controls in order to pick and display entries and the parent / child relations.

Known limit

The entries selected will be filtered on the effectivity dates of the entries them selves. i.e. the entry being referenced will be only returned if its effectivity span is valid within the effectivity span of the referencing entry.

Configuration steps

---

For the following example, we use the Configuration Tool to reconfigure a template to include Engineering Change Orders.

Part SoftType

Data section

We start by adding a few configurations to our Part SoftType. The Part SoftType has a configuration on the "General" definition for NextAssemblyUsage that references the Part SoftType as possible children.

We add a Connection Port configuration to the NextAssemblyUsage called childNAUs. This in order to be able to tell the SoftType engine what entry we want to create references to.

Note

Note that the group for our child relations, i.e. the NextAssemblyUsages is called NextAssemblyUsages. We will need to know about this value at a later stage of the configuration setup.

Next we add a configuration for the database id of the NextAssemblyUsage entry. This is in order to be able to provide the SoftType engine (via the API) with the information on which explicit entry to reference to. We do this by adding a Value Port with id nauOId for the oid property.

Later on in the configuration we need to be able to configure a presentation of the single entries. The user interface will automatically present the parent and child SoftTypes for the references but we also have the possibility to present information about the entry itself. Typically this could be an identifier or name of the entry. In this case, however, we do not have either of the two. We could add them but in this example there is a position property on the NextAssemblyUsage. Note this - we will use it later when configuring the UI controls.

Output schemas section

• Add the NextAssemblyUsage array property to the the configured default output schema

Warning

LIMITATION Note that the NextAssemblyUsage array is added to the default output schema. Make sure that the child references are not resolved.

Engineering change order SoftType

Data

• We setup a SoftType identified as ECO for the base type ChangeOrder. Adding an identifier and a name.
• We add a configuration for activityInputReferences, grouped under inputs.
  • Here we keep the model cardinality, i.e. inputs will be an array of references to NextAssemblyUsages.

Note here that when we select the Part SoftType for the referenceElement property, we are using the connection port that we defined for the NextAssemblyUsage in the Part SoftType. This is key in order for the SoftType engine to know that we want to be able to reference the NextAssemblyUsage.

Schemas

The next step is to add the inputs property to our input and output schemas. We do not need to resolve the reference in the output schema.

Views

For the Create and Edit views we will be using the Multi Quick Select Control. This control has a mode capability, allowing us to search for a SoftType and select entries within that SoftType instance.

Multi quick select control

Property		Description
Label	Required	The binding for the label of the control. Binds to the configured label settings. Language dependent.
Description	Required	The binding for the text to be used as the description of the control. Binds to the configured label settings. Language dependent.
Binding	Required	The schema binding to the array that this configured control should manage. In this case it is the input objects array called inputs.
Mode	Required	The mode for the quick select: normal or childSelect. normal will only pick SoftTypes, i.e. not entries within a SoftType. For this configuration we pick childSelect since we want to pick an entry within a SoftType.
Relation Property	Required	The name of the property on the referenced SoftType schema that contains the entry configurations. In this case it is the NextAssemblyUsages property on the Part SoftType. Note that this property must exist in the default output schema of the referenced SoftType.
Value Property	Required	The name of the property that holds the reference to the "child". In this example the Part SoftType has the array NextAssemblyUsages. Each object within that array has a property value that holds the object reference to the child Part.
Relation Format	Required	The string format that will be used to represent the selectable instance. Works like the default presentation of a SoftType but is pivoted round the object within the reference array. In this case we pick the position value for the NextAssemblyUsage but this string could have picked any of the loaded values from the reference. {position.pvalue).
Relation OId Path	Required	The name of the property that has the database id of the reference. In our configuration we have loaded the database id to the property nauOId.

Note

In this scenario we are using an array of references to entries. In case of a single entry reference we would instead use Single Quick Select Control. The configuration follows the same patterns as the Multi Quick Select Control described above.

For the Read View we will also use the Multi Quick Select Control but set it to Disabled.

Note

If we were to present a single entry reference there is a special control for this. Child SoftType Link. But since this control can only manage one entry we need to use the Multi Quick Select Control in this example. This is a known limitation.

Child SoftType link

Property		Description
Label	Required	The binding for the label of the control. Binds to the configured label settings. Language dependent.
Description	Required	The binding for the text to be used as the description of the control. Binds to the configured label settings. Language dependent.
Binding	Required	The schema binding to what array that this configured control should manage. In this case it is the input objects array called inputs.
Relation Property	Required	The name of the property on the referenced SoftType schema that contains the entry configurations. In this case it is the NextAssemblyUsages property on the Part SoftType.
Value Property	Required	Required	The name of the property that holds the reference to the "child". In this example the Part SoftType has the array NextAssemblyUsages each object within that array has a property value that holds the object reference to the child Part.
Relation Format	Required	The string format that will be used to represent the selectable instance. Works like the default presentation of a SoftType but is pivoted round the object within the reference array. In this case we pick the position value for the NextAssemblyUsage but this string could have picked any of the loaded values from the reference. {position.pvalue).
Relation OId Path	Required	The name of the property that has the database id of the reference. In our configuration we have loaded the database id to the property nauOId.

Demonstration screens

---

Create ECO

To select an entry. Search for the parent, in this case a Part. Using the configured multi quick select control. Use the + button to expand the configured children of that parent. Select the reference entry to add.

Edit ECO

View ECO

REST API

---

When using the REST API to create the reference, note that the value to pass in for the reference ObjectId must be the one of the entries to refer to. I.e. it is not possible to just send the ObjectId of a Master, Version, or Definition.