Open APIs

 View Only

  • 1.  ExternalReference or externalId or ExternalIdentifier

    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

    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.
    ------------------------------



  • 3.  RE: ExternalReference or externalId or ExternalIdentifier

    Posted Mar 09, 2023 10:21

    Hi Jonathan,

    what is the decision for V5? In the Git we still see lots of ExternalReference, e.g. in Party Management API, but in others there is ExternalIdentifier. And in some examples there is still externalId.
    I'd assume that we should have only one of the two structures?

    And then: What is the rule to which API/resource it should be attached?
    I'd assume that having an externalIdentifier is of value for virtually every entity, in particular when the TMF openAPIs are introduced during transition from a legacy environment. So maybe it should even go to Core, maybe even to Addressable or at least to Entity?

    Regards,

    Lutz



    ------------------------------
    Lutz Bettge
    Deutsche Telekom AG
    ------------------------------

    Original Message


  • 4.  RE: ExternalReference or externalId or ExternalIdentifier

    Posted Mar 09, 2023 15:38

    It's going to take time, Lutz, and we cannot guarantee perfect consistency.

    Not every entity necessarily needs external identifiers, so it would be a case-by-case definition.

    Feel free to contribute to the discussion in the regular Open API team meetings - possibly the Thursday architecture call is most appropriate for this.



    ------------------------------
    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.
    ------------------------------

    Original Message


Related Content