Open APIs

 View Only
  • 1.  External IDs of resources

    TM Forum Member
    Posted Sep 01, 2020 11:12
    Hi,

    I was wondering how I should deal with the external IDs of some resources such as Agreement.
    Agreement as a resource has a unique identifier. We can imagine there are multiple systems storing Agreement items (1 for GSM, 1 for FTTx for instance), case in which we would have the Agreement resource ID related to the system storing it.
    Considering the above I was thinking would be useful to have a list of external IDs which would include a list of IDs of the resource in a specific system. What is your opinion on that? Do you have a solution already for that?

    Thanks,
    Calin

    ------------------------------
    Calin Mates
    Aplication Architect
    IBM Corporation
    ------------------------------


  • 2.  RE: External IDs of resources

    TM Forum Member
    Posted Sep 07, 2020 02:18

    Hi Calin

    You will be pleased to learn that we recently introduced a full ExternalIdentifier pattern into the Open API, which does answer your need. It will probably take time for the concept to be adopted in all relevant places, and input from the community will no doubt be helpful here.
    Its recommended use looks like this:
    "externalIdentifier": {
    "type": "array",
    "items": {
    "$ref": "../Common/ExternalIdentifier.schema.json#/definitions/ExternalIdentifier"
    }
    },
    and the structure itself looks like this:
    "properties": {
    "owner": {
    "type": "string",
    "description": "Name of the external system that owns the entity.",
    "examples": [
    "MagentoCommerce"
    ]
    },
    "externalIdentifierType": {
    "type": "string",
    "description": "Type of the identification, typically would be the type of the entity within the external system",
    "examples": [
    "ProductOrder"
    ]
    },
    "id": {
    "type": "string",
    "description": "identification of the entity within the external system.",
    "examples": [
    "MC2255771199555"
    ]
    }
    },



    ------------------------------
    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: External IDs of resources

    TM Forum Member
    Posted Sep 25, 2023 03:10

    Hi Jonathan

    In the TMF656 Service Problem Mgmt v4.0.0 API, the id within ExternalIdentifier[s] is required as defined within the OAS.  However, the new v5 specs appear to have the id field as optional.  This allows us to use the ExternalIdenfiers pattern to distinguish, for example, which billing system (owner) is being used for a particular customer (without having access to the id of the customer on the external system).  Please can you confirm whether it is the intention to make the id optional in all  future v5 specs?

    Thanks!



    ------------------------------
    Dan d'Albuquerque
    Individual
    ------------------------------



  • 4.  RE: External IDs of resources

    TM Forum Member
    Posted Sep 28, 2023 11:32

    This is somewhat tricky. The externalidentifier structure is itself optional. We need to somehow express the semantic that if the structure is present, then the id is mandatory. This is done in the conformance profile, something like this:

          externalReference:
            condition: ""
            comment: Array of ExternalIdentifier
          externalReference.@type:
            condition: M
            comment: if present
          externalReference.externalIdentifierType:
            condition: M
            comment: if present
          externalReference.id:
            condition: M
            comment: if present

    But I don't think we have an equivalent semantic in the OAS/Swagger file - because if you specify something in the schema as mandatory I believe it will be considered mandatory unconditionally.

    Hope it helps



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



  • 5.  RE: External IDs of resources

    TM Forum Member
    Posted Oct 17, 2023 22:41
    Edited by Srinivasa Vellanki Oct 17, 2023 22:44

    Hi Jonathan,

    Hope am not missing anything..

    We can have externalIdentifier as optional while id within the externalIdentifier can be required, which make id required only when ExternalIdentifier exists and hence conditional.

    Think every Entity(and EntityRef) should have an option to be identified by ExternalIdentifier.

    "Entity": {
    "type": "object",
    "description": "Base entity schema for use in TMForum Open-APIs. Property.",
    "allOf": [
    {
    "$ref": "#/components/schemas/Extensible"
    },
    {
    "$ref": "#/components/schemas/Addressable"
    }
    ]
    }
    ------------------------------
    Srinivasa Vellanki
    Jio Platforms Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of my employer or TM Forum.
    ------------------------------

    This is somewhat tricky. The externalidentifier structure is itself optional. We need to somehow express the semantic that if the structure is present, then the id is mandatory. This is done in the conformance profile, something like this:

          externalReference:
            condition: ""
            comment: Array of ExternalIdentifier
          externalReference.@type:
            condition: M
            comment: if present
          externalReference.externalIdentifierType:
            condition: M
            comment: if present
          externalReference.id:
            condition: M
            comment: if present

    But I don't think we have an equivalent semantic in the OAS/Swagger file - because if you specify something in the schema as mandatory I believe it will be considered mandatory unconditionally.

    Hope it helps



    ------------------------------
    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:
    Sent: Sep 25, 2023 03:09
    From: Dan d'Albuquerque
    Subject: External IDs of resources

    Hi Jonathan

    In the TMF656 Service Problem Mgmt v4.0.0 API, the id within ExternalIdentifier[s] is required as defined within the OAS.  However, the new v5 specs appear to have the id field as optional.  This allows us to use the ExternalIdenfiers pattern to distinguish, for example, which billing system (owner) is being used for a particular customer (without having access to the id of the customer on the external system).  Please can you confirm whether it is the intention to make the id optional in all  future v5 specs?

    Thanks!



    ------------------------------
    Dan d'Albuquerque
    Individual

    Original Message:
    Sent: Sep 07, 2020 02:18
    From: Jonathan Goldberg
    Subject: External IDs of resources

    Hi Calin

    You will be pleased to learn that we recently introduced a full ExternalIdentifier pattern into the Open API, which does answer your need. It will probably take time for the concept to be adopted in all relevant places, and input from the community will no doubt be helpful here.
    Its recommended use looks like this:
    "externalIdentifier": {
    "type": "array",
    "items": {
    "$ref": "../Common/ExternalIdentifier.schema.json#/definitions/ExternalIdentifier"
    }
    },
    and the structure itself looks like this:
    "properties": {
    "owner": {
    "type": "string",
    "description": "Name of the external system that owns the entity.",
    "examples": [
    "MagentoCommerce"
    ]
    },
    "externalIdentifierType": {
    "type": "string",
    "description": "Type of the identification, typically would be the type of the entity within the external system",
    "examples": [
    "ProductOrder"
    ]
    },
    "id": {
    "type": "string",
    "description": "identification of the entity within the external system.",
    "examples": [
    "MC2255771199555"
    ]
    }
    },



    ------------------------------
    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:
    Sent: Sep 01, 2020 11:12
    From: Calin Mates
    Subject: External IDs of resources

    Hi,

    I was wondering how I should deal with the external IDs of some resources such as Agreement.
    Agreement as a resource has a unique identifier. We can imagine there are multiple systems storing Agreement items (1 for GSM, 1 for FTTx for instance), case in which we would have the Agreement resource ID related to the system storing it.
    Considering the above I was thinking would be useful to have a list of external IDs which would include a list of IDs of the resource in a specific system. What is your opinion on that? Do you have a solution already for that?

    Thanks,
    Calin

    ------------------------------
    Calin Mates
    Aplication Architect
    IBM Corporation
    ------------------------------



  • 6.  RE: External IDs of resources

    TM Forum Member
    Posted Oct 18, 2023 04:04

    Hi all,

    when I look into the OpenAPI 5 Git, I see that the ExternalIdentifier schema is defined with mandatory id:

    {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "$id": "ExternalIdentifier.schema.json",
        "title": "ExternalIdentifier",
        "definitions": {
            "ExternalIdentifier": {
                "$id": "#ExternalIdentifier",
                "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.",
                "type": "object",
                "properties": {
                    "owner": {
                        "type": "string",
                        "description": "Name of the external system that owns the entity.",
                        "examples": [
                            "MagentoCommerce"
                        ]
                    },
                    "externalIdentifierType": {
                        "type": "string",
                        "description": "Type of the identification, typically would be the type of the entity within the external system",
                        "examples": [
                            "ProductOrder"
                        ]
                    },
                    "id": {
                        "type": "string",
                        "description": "identification of the entity within the external system."
                    }
                },
                "allOf": [
                    {
                        "$ref": "../Common/Extensible.schema.json#Extensible"
                    }
                ],
                "required": [
                    "id"
                ]
            }
        }
    }

    That should be sufficient to ensure that if there is an externalIdentifier attached to some entity, it must contain an id. Additionally marking that in the conformance profile should not be necessary, I'd expect that for this the above is sufficient. But probably it must be expressed that the ExternalIdentity must be implemented by a service providing the API in order to be compliant?

    In any case, I would also support to add the externalIdentifier array on the base class "Entity", so that it can be used anywhere.



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