Table of Contents
Last updated: 2024-11-14

Origin

Introduction

The Origin capability has been extended with extra functionality.

A SoftType can be configured to expose one or more Origin SoftType reference ports, these ports will have a default value (typically the ShareAspace Origin) but could also accept an input value.

While using the API the Origin ports cannot be used, that is, the SoftType instances will be created using their default defined origin.

A data mapper component using the SoftType schemas can however make use of the exposed origin ports. There are three scenarios:

  • The mapper does not set any origin value - the default origin as defined in the configuration will be used when importing the data.
  • The mapper uses a "keyword origin instance", there are two:
    • Context/origin:context - the import will use the context origin defined on the import DataExchange job. e.g. a Job is configured to import data from SystemX, the mapper mapping information from SystemX has defined that data mastered in SystemX has the "Context" origin. The Job will replace the "Context" with the SystemX origin before importing. Because of the "Context" construct the same mapper could be used when integrating with SystemY (provided the mapping schemas are the same).
    • Unknown/origin:unknown - the import will make sure that any data tagged with the Origin "Unknown" already exists within the database before committing an import. e.g. When integrating with a SystemX that masters Parts, these Parts could have references to Documents mastered in SystemY. When importing data from SystemX the import could contain Parts with Document references. If in the mapper, the Documents are tagged with the "Unknown" Origin, the importer will make sure to only allow the import of there document references if the referenced documents are already in the database (loaded from SystemY).

Configuration

DataExchange job - Origin context

This setting is configured within the attributes array of the DataExchange SoftType. The setting is used to indicate which origin is to be used for creating new incoming data when executing the job.

This is the way to indicate that a job is actually set for a specific source system as explained in the concept section.

The OriginContext setting is of type string and the value is supposed to be the uri of an instance of an OriginatingSystem configured SoftType.

An example of how the resulting JSON will look is given below:

{
  "$type": "StringAttribute",
  "$rules": [
    {
      "lower": "0",
      "upper": "1"
    }
  ],
  "name": {
    "$type": "String",
    "$port": {
      "value": "OriginContext",
      "$type": "Value"
    }
  },
  "value": {
    "$type": "String",
    "$port": {
      "id": "originContext",
      "$type": "Value"
    }
  }
}
Note

In most of the preconfigured space templates, the OriginatingSystem representing the ShareAspace space has the uri set to **sas:nova:@guid:@spaceId**.

The value in this settings is used by the ShareAspace Consolidation Engine logic for choosing the originating system for the incoming data. The incoming data has to be associated with an OriginatingSystem that has an uri value set to one of the following keywords:

  • origin:unknown: in this case the incoming data must exists in the ShareAspace space with its own OriginatingSystem. Therefore the data is only available for reference and no modification is allowed in the space.
  • origin:context: in this case the incoming data will be considered as coming from the system represented by the OriginContext set at the job level. If the job level setting is set to the default ShareAspace space uri, then, after creation or consolidation, the data is available for modification within the space. Otherwise the data is only available for reference and no modification is allowed in the space.
Important

Cases resulting with an Exception

  1. When using origin:unknown for the OriginatingSystem associated with the incoming data and that data does not exist.
  2. When using origin:context for the OriginatingSystem associated with the incoming data and that data already exists with an OriginatingSystem different to the one set at the job level.

Origin instances

The two "keyword instances" of the Origin SoftType (Context and Unknown) must be added to the space template configuration.

{
  ...
  "softTypes": [
  {
    "$id": "OriginatingSystem",
    ...
    "instances": [
      {
        "$id": "origin:context",
        "$inputSchemaRef": "defaultIn",
        "data": {
        "name": "Context",
        "uri": "origin:context"
        }
      },
      {
        "$id": "origin:unknown",
        "$inputSchemaRef": "defaultIn",
        "data": {
        "name": "Unknown",
        "uri": "origin:unknown"
        }
      }
    ]
  },
    ...

Origin SoftType reference

Example of a SoftType origin port configuration.

"origin": {
  "$port": {
    "$type": "SoftTypeInstanceReference",
    "id": "originMaster",
    "softTypeRef": [
      {
        "$type": "Implicit",
        "allowedInstances": [
          "ShareAspace",
          "SystemX"
        ],
        "connection": "sasOriginatingSystem",
        "instanceRef": "ShareAspace",
        "softTypeId": "OriginatingSystem"
      }
    ]
  }
Note
  • That both the allowedInstances and instanceRef are set. This enables overriding the default ShareAspace origin when running import jobs with ContextOrigin set.
  • That the $port has an id defined. This allows the port to be exposed in schemas.
    • This port cannot have values set when using the API, however a mapper can set the value of the port to either origin:context or origin:unknown.

Example of a SoftType JSON payload instantiating two instances of the SoftType "Part" using different schemas. The "Part" SoftType in this example has exposed two Origin ports (origin, genDefOrigin).

{
  "softTypes": [
    {
      "$id": "Part",
      "instances": [
        {
          "$id": "1",
          "$inputSchemaRef": "importExternalOrigin",
          "data": {
            "id": "Part1",
            "name": "Part1-ShareAspace",
            "origin": "origin:context",
            "versionId": "A",
            "genDefOrigin": "origin:context",
            "Material": {
              "value": "Steel"
            },
            "ReadyForReview": {
              "value": "True"
            },
            "ContentAccepted": {
              "value": "False"
            },
            "NextAssemblyUsages": [
              {
                "value": {
                  "$softType": "Part",
                  "$instanceRef": "2"
                }
              }
            ]
          }
        },
        {
          "$id": "2",
          "$inputSchemaRef": "importRef",
          "data": {
            "id": "Part2",
            "origin": "origin:unknown",
            "genDefOrigin": "origin:unknown"
          }
        }
      ]
    }
  ]
 }