Open APIs

Expand all | Collapse all

ExternalReference or externalId or ExternalIdentifier

  • 1.  ExternalReference or externalId or ExternalIdentifier

    TM Forum Member
    Posted Aug 26, 2021 01:43
    Hi Folks,

    I know that there are currently several variations on how to "attach" external IDs to a TMF OpenAPI resource.

    Variant A: ExternalReference array
    "ExternalReference": {
              "type": "object",
              "description": "External reference of the individual or reference in other system",
              "required": [
                  "name"
              ],
              "properties": {
                  "id": {
                      "type": "string",
                      "description": "unique identifier"
                  },
                  "href": {
                      "type": "string",
                      "format": "uri",
                      "description": "Hyperlink reference"
                  },
                  "externalReferenceType": {
                      "type": "string",
                      "description": "Type of the external reference"
                  },
                  "name": {
                      "type": "string",
                      "description": "External reference name"
                  },
                  "@baseType": {
                      "type": "string",
                      "description": "When sub-classing, this defines the super-class"
                  },
                  "@schemaLocation": {
                      "type": "string",
                      "format": "uri",
                      "description": "A URI to a JSON-Schema file that defines additional attributes and relationships"
                  },
                  "@type": {
                      "type": "string",
                      "description": "When sub-classing, this defines the sub-class Extensible name"
                  }
              }
          }​
    Seen e.g. in TMF641 (v4.1.0)

    Variant B: externalId String
    "externalId": {
              "type": "string",
              "description": "DEPRECATED: Use externalReference Instead. ID given by the consumer (to facilitate searches afterwards)"
            }​

    Seen e.g. in TMF652 ResourceOrder

    Variant C: ExternalIdentifier array

    "ExternalIdentifier": {
                "type": "object",
                "description": "An identification of an entity that is owned by or originates in a software system different from the current system, for example a ProductOrder handed off from a commerce platform into an order handling system. The structure identifies the system itself, the nature of the entity within the system (e.g. class name) and the unique ID of the entity within the system. It is anticipated that multiple external IDs can be held for a single entity, e.g. if the entity passed through multiple systems on the way to the current system. In this case the consumer is expected to sequence the IDs in the array in reverse order of provenance, i.e. most recent system first in the list.",
                "required": [
                    "id"
                ],
                "properties": {
                    "id": {
                        "example": "MC2255771199555",
                        "type": "string",
                        "description": "identification of the entity within the external system."
                    },
                    "href": {
                        "type": "string",
                        "format": "uri",
                        "description": "Hyperlink reference"
                    },
                    "externalIdentifierType": {
                        "example": "ProductOrder",
                        "type": "string",
                        "description": "Type of the identification, typically would be the type of the entity within the external system"
                    },
                    "owner": {
                        "example": "MagentoCommerce",
                        "type": "string",
                        "description": "Name of the external system that owns the entity."
                    },
                    "@baseType": {
                        "type": "string",
                        "description": "When sub-classing, this defines the super-class"
                    },
                    "@schemaLocation": {
                        "type": "string",
                        "format": "uri",
                        "description": "A URI to a JSON-Schema file that defines additional attributes and relationships"
                    },
                    "@type": {
                        "type": "string",
                        "description": "When sub-classing, this defines the sub-class Extensible name"
                    }
                }
            }


    Seen e.g. in TMF656 Service Problem Mgmt v4.0.0

    Is there already a decision by the OpenAPI working group whether one of the variants should replace the others in the medium term?
    Currently it seems to me that variant A is the preferred choice, it would be great if someone could confirm this.

    Thanks a lot,

    Jan



    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------


  • 2.  RE: ExternalReference or externalId or ExternalIdentifier

    TM Forum Member
    Posted Aug 26, 2021 02:28
    Hi Jan
    Good question
    The guideline going forward is C; ExternalIdentifier. Typically you would have an array of ExternalIdentifier in your managed entity. This allows for a number of different use cases, such as:
    • Order chaining, a port out order may have been received from a number porting clearing house, which in turn received it from a CSP asking for port in - your order could hold the id of the order in the source CSP and in the clearing house
    • Catalog federation, a catalog item in your catalog that was imported from another catalog could hold the source catalog's id of the item
    Hope this is clear

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------