From fd6c99a4869171dbff8662cbbe9cd6c3c8224fe8 Mon Sep 17 00:00:00 2001 From: Nico Koprowski Date: Mon, 22 Jul 2024 10:37:15 +0800 Subject: [PATCH] docs(Orchestrator-API): add more descriptions to Orchestrator API model --- .../orchestrator/api/model/BusinessPartner.kt | 127 +++++++- docs/api/orchestrator.json | 274 +++++++++++------- docs/api/orchestrator.yaml | 141 +++++++-- 3 files changed, 418 insertions(+), 124 deletions(-) diff --git a/bpdm-orchestrator-api/src/main/kotlin/org/eclipse/tractusx/orchestrator/api/model/BusinessPartner.kt b/bpdm-orchestrator-api/src/main/kotlin/org/eclipse/tractusx/orchestrator/api/model/BusinessPartner.kt index eca48e867..97b6efc78 100644 --- a/bpdm-orchestrator-api/src/main/kotlin/org/eclipse/tractusx/orchestrator/api/model/BusinessPartner.kt +++ b/bpdm-orchestrator-api/src/main/kotlin/org/eclipse/tractusx/orchestrator/api/model/BusinessPartner.kt @@ -19,13 +19,23 @@ package org.eclipse.tractusx.orchestrator.api.model +import io.swagger.v3.oas.annotations.media.Schema +import org.eclipse.tractusx.bpdm.common.dto.openapidescription.PostalAddressDescription +import org.eclipse.tractusx.bpdm.common.dto.openapidescription.StreetDescription import org.eclipse.tractusx.bpdm.common.model.BusinessStateType import org.eclipse.tractusx.bpdm.common.model.DeliveryServiceType import java.time.Instant - +@Schema(description = "Generic business partner data for golden record processing. " + + "Typically a sharing member shares incomplete and/or uncategorized business partner data to the golden record process. " + + "The golden record process categorizes and completes the data in order to create and update the resulting golden records. " + + "The golden records are found in the legalEntity, site and additionalAddress fields. " + + "The business partner data needs to contain the full golden record parent relationship. " + + "This means, if an additional address is specified in the business partner data, also its legal entity and also its site parent (if a site exists) needs to be specified. ") data class BusinessPartner( + @Schema(description = "Fully categorized and cleaned name parts based on the uncategorized name parts provided") val nameParts: List, + @Schema(description = "The BPNL of the legal entity to which this business partner data belongs to") val owningCompany: String?, val uncategorized: UncategorizedProperties, val legalEntity: LegalEntity, @@ -43,6 +53,11 @@ data class BusinessPartner( ) } + @Schema(description = "The recognized golden record type this business partner data contains.\n" + + "* `Legal Entity`: The business partner data only contains legal entity and legal address information.\n" + + "* `Site`: The business partner data contains site, site main address and its parent legal entity information.\n" + + "* `Additional Address`: The business partner data contains an additional address, (optional) parent site and parent legal entity information.\n" + + "* `Null`: No clear type determined, undecided. The golden record process will not create golden record from this business partner data.") val type: GoldenRecordType? = when{ additionalAddress != null -> GoldenRecordType.Address site != null -> GoldenRecordType.Site @@ -51,26 +66,53 @@ data class BusinessPartner( } } +@Schema(description = "A categorized name part for this business partner data") data class NamePart( + @Schema(description = "The name part value") val name: String, + @get:Schema(description = "NamePartType:\n" + + "* `LegalName` - Value is part of the legal entities' legal name\n" + + "* `ShortName` - Value is part of the legal entities' short name\n" + + "* `LegalForm` - Value is part of the legal entities' legal form name\n" + + "* `SiteName` - Value is part of the site's name\n" + + "* `AddressName` - Value is part of the address name\n") val type: NamePartType ) +@Schema(description = "The additional identifiers of this business partner (excluding the BPN)") data class Identifier( + @get:Schema(description = "Value of the identifier") val value: String?, + @get:Schema(description = "The type of identifier") val type: String?, + @get:Schema(description = "The organisation that issued this identifier") val issuingBody: String? ) +@Schema(description = "The business state information for the corresponding business partner") data class BusinessState( + @get:Schema(description = "Date since when the status is/was valid.") val validFrom: Instant?, + @get:Schema(description = "Date until the status was valid, if applicable.") val validTo: Instant?, + @get:Schema(description = "The type of this specified status.") val type: BusinessStateType? ) +@Schema(description = "A reference to a BPN for the corresponding business partner data. " + + "Either this reference contains an existing BPN or a BPN request identifier. " + + "The golden record process makes sure that the each unique BPN request identifier is associated to a unique BPN. " + + "For a new BPN request identifier the golden record process creates a new BPN (and golden record) and associates it with the BPN request identifier. " + + "Known BPN request identifiers are resolved to the BPN and the corresponding golden record is updated with the business partner data. " + + "This makes it possible for duplication check services to reference unique business partners by their own BPN request identifiers instead of needing to rely on BPNs for identification.") data class BpnReference( + @Schema(description = "The value of the reference, either an existing BPN or a BPN request identifier (which is freely chosen by the duplication check provider)") val referenceValue: String?, + @Schema(description = "The desired BPN when a new golden record has to be created for this business partner data." + + "Requires a BPN request identifier that is not associated with an existing BPN. " + + "At this moment the golden record process does not support creating desired BPNs and ignores this field. ") val desiredBpn: String?, + @Schema(description = "Whether this reference is a BPN or BPN request identifier") val referenceType: BpnReferenceType? ){ companion object{ @@ -78,14 +120,22 @@ data class BpnReference( } } +@Schema(description = "Address information of this business partner data. " + + "The address can be either a legal, site main and/or additional address. " + + "This can also refer to address information which is unknown to which type it belongs to.") data class PostalAddress( val bpnReference: BpnReference, + @Schema( description = "The name of this address") val addressName: String?, + @Schema(description = "Identifiers for this address (in addition to the BPNA)") val identifiers: List, + @Schema(description = "The business state history of this address") val states: List, val confidenceCriteria: ConfidenceCriteria, val physicalAddress: PhysicalAddress, val alternativeAddress: AlternativeAddress?, + @Schema(description = "Whether this address information differs from its golden record counterpart in the Pool." + + "Currently deprecated and ignored by the golden record creation and update process.", deprecated = true) val hasChanged: Boolean? ){ companion object{ @@ -102,21 +152,35 @@ data class PostalAddress( } } +@Schema(description = PostalAddressDescription.headerPhysical) data class PhysicalAddress( val geographicCoordinates: GeoCoordinate, + @Schema(description = PostalAddressDescription.country) val country: String?, + @Schema(description = PostalAddressDescription.administrativeAreaLevel1) val administrativeAreaLevel1: String?, + @Schema(description = PostalAddressDescription.administrativeAreaLevel2) val administrativeAreaLevel2: String?, + @Schema(description = PostalAddressDescription.administrativeAreaLevel3) val administrativeAreaLevel3: String?, + @Schema(description = PostalAddressDescription.postalCode) val postalCode: String?, + @Schema(description = PostalAddressDescription.city) val city: String?, + @Schema(description = PostalAddressDescription.district) val district: String?, val street: Street, + @Schema(description = PostalAddressDescription.companyPostalCode) val companyPostalCode: String?, + @Schema(description = PostalAddressDescription.industrialZone) val industrialZone: String?, + @Schema(description = PostalAddressDescription.building) val building: String?, + @Schema(description = PostalAddressDescription.floor) val floor: String?, + @Schema(description = PostalAddressDescription.door) val door: String?, + @Schema(description = PostalAddressDescription.taxJurisdictionCode) val taxJurisdictionCode: String? ){ companion object { @@ -128,14 +192,22 @@ data class PhysicalAddress( } } +@Schema(description = PostalAddressDescription.headerAlternative) data class AlternativeAddress( val geographicCoordinates: GeoCoordinate, + @Schema(description = PostalAddressDescription.country) val country: String?, + @Schema(description = PostalAddressDescription.administrativeAreaLevel1) val administrativeAreaLevel1: String?, + @Schema(description = PostalAddressDescription.postalCode) val postalCode: String?, + @Schema(description = PostalAddressDescription.city) val city: String?, + @Schema(description = PostalAddressDescription.deliveryServiceType) val deliveryServiceType: DeliveryServiceType?, + @Schema(description = PostalAddressDescription.deliveryServiceQualifier) val deliveryServiceQualifier: String?, + @Schema(description = PostalAddressDescription.deliveryServiceNumber) val deliveryServiceNumber: String? ){ companion object{ @@ -145,6 +217,7 @@ data class AlternativeAddress( } } +@Schema(description = PostalAddressDescription.headerGeoCoordinates) data class GeoCoordinate( val longitude: Float?, val latitude: Float?, @@ -155,15 +228,25 @@ data class GeoCoordinate( } } +@Schema(description = StreetDescription.header) data class Street( + @Schema(description = StreetDescription.name) val name: String?, + @Schema(description = StreetDescription.houseNumber) val houseNumber: String?, + @Schema(description = "The supplement to the house number") val houseNumberSupplement: String?, + @Schema(description = StreetDescription.milestone) val milestone: String?, + @Schema(description = StreetDescription.direction) val direction: String?, + @Schema(description = StreetDescription.namePrefix) val namePrefix: String?, + @Schema(description = StreetDescription.additionalNamePrefix) val additionalNamePrefix: String?, + @Schema(description = StreetDescription.nameSuffix) val nameSuffix: String?, + @Schema(description = StreetDescription.additionalNameSuffix) val additionalNameSuffix: String?, ){ companion object{ @@ -171,12 +254,20 @@ data class Street( } } +@Schema(description = "Contains information to evaluate how good or verified the information in the attached business partner data is. " + + "This information will be directly written in the matched golden record's confidence criteria.") data class ConfidenceCriteria( + @Schema(description = "Whether the business partner data is shared by the actual owner") val sharedByOwner: Boolean?, + @Schema(description = "The corresponding business partner data has been verified by an external data source, like an official register") val checkedByExternalDataSource: Boolean?, + @Schema(description = "How many sharing members have already shared the matched golden record") val numberOfSharingMembers: Int?, + @Schema(description = "Last time the confidence values have been checked (and updated if needed)") val lastConfidenceCheckAt: Instant?, + @Schema(description = "Next time the confidence values should be checked") val nextConfidenceCheckAt: Instant?, + @Schema(description = "The overall confidence level of the matched golden record") val confidenceLevel: Int? ){ companion object{ @@ -191,21 +282,40 @@ data class ConfidenceCriteria( } } +@Schema(description = "The additional address information of this business partner data. " + + "An additional address is an address that is distinct from the legal and site main address. " + + "The additional address is either an additional address of the legal entity (site is null) or of the site (site is not null). " + + "An additional address of 'Null' means the business partner data has no additional address") data class AdditionalAddress( val addressBpn: BpnReference, + @Schema(description = "Whether this additional address information differs from its golden record counterpart in the Pool. +" + + "The Pool will not update the address if it is set to false. " + + "However, if this address constitutes a new additional address golden record, it is still created independent of this flag.") val hasChanged: Boolean?, val postalProperties: PostalAddress ) +@Schema(description = "Legal entity information for this business partner data. " + + "Every business partner either is a legal entity or belongs to a legal entity." + + "There, a legal entity property is not allowed to be 'null'. " ) data class LegalEntity( val bpnReference: BpnReference, + @Schema(description = "The legal name of this legal entity according to official registers") val legalName: String?, + @Schema(description = "The abbreviated name of this legal entity, if it exists") val legalShortName: String?, + @Schema(description = "The legal form of this legal entity") val legalForm: String?, + @Schema(description = "Identifiers for this legal entity (in addition to the BPNL)") val identifiers: List, + @Schema(description = "The business state history of this legal entity") val states: List, val confidenceCriteria: ConfidenceCriteria, + @Schema(description = "Whether this legal entity is part of the Catena-X network") val isCatenaXMemberData: Boolean?, + @Schema(description = "Whether this legal entity information differs from its golden record counterpart in the Pool. +" + + "The Pool will not update the legal entity if it is set to false. " + + "However, if this legal entity constitutes a new legal entity golden record, it is still created independent of this flag.") val hasChanged: Boolean?, val legalAddress: PostalAddress ){ @@ -225,11 +335,18 @@ data class LegalEntity( } } +@Schema(description = "Site information for this business partner data. " + + "A site of 'null' means the business partner data has no site.") data class Site( val bpnReference: BpnReference, + @Schema(description = "The name of this site") val siteName: String?, + @Schema(description = "The business state history of this site") val states: List, val confidenceCriteria: ConfidenceCriteria, + @Schema(description = "Whether this site information differs from its golden record counterpart in the Pool. +" + + "The Pool will not update the site if it is set to false. " + + "However, if this site constitutes a new site golden record, it is still created independent of this flag.") val hasChanged: Boolean?, val siteMainAddress: PostalAddress? ){ @@ -244,14 +361,20 @@ data class Site( ) } + @Schema(description = "This site's main address is the legal address of the legal entity. " + + "The address information therefore is stored in the legal address.") val siteMainIsLegalAddress = siteMainAddress == null } - +@Schema(description = "Business partner data that has not yet or can not be categorized") data class UncategorizedProperties( + @Schema(description = "The plain uncategorized name of the business partner how it appears in the sharing member system",) val nameParts: List, + @Schema(description = "Identifiers for which it is unknown whether they belong to the legal entity, site or any address") val identifiers: List, + @Schema(description = "Business states for which it is unknown whether they belong to the legal entity, site or any address") val states: List, + @Schema(description = "Address information for which it is unknown whether they belong to the legal, site main or additional address") val address: PostalAddress? ){ companion object{ diff --git a/docs/api/orchestrator.json b/docs/api/orchestrator.json index 1bc0eb595..f835b6c43 100644 --- a/docs/api/orchestrator.json +++ b/docs/api/orchestrator.json @@ -3,7 +3,7 @@ "info": { "title": "Business Partner Data Management Orchestrator", "description": "Orchestrator component acts as a passive component and offers for each processing steps individual endpoints", - "version": "6.1.0-SNAPSHOT" + "version": "6.1.1-SNAPSHOT" }, "servers": [ { @@ -11,14 +11,6 @@ "description": "Generated server url" } ], - "security": [ - { - "open_id_scheme": [] - }, - { - "bearer_scheme": [] - } - ], "paths": { "/v6/golden-record-tasks": { "post": { @@ -166,19 +158,24 @@ "$ref": "#/components/schemas/GeoCoordinate" }, "country": { - "type": "string" + "type": "string", + "description": "The 2-digit country code of the physical postal address according to ISO 3166-1." }, "administrativeAreaLevel1": { - "type": "string" + "type": "string", + "description": "The 2-digit country subdivision code according to ISO 3166-2, such as a region within a country." }, "postalCode": { - "type": "string" + "type": "string", + "description": "The alphanumeric identifier (sometimes including spaces or punctuation) of the physical postal address for the purpose of sorting mail, synonyms:postcode, post code, PIN or ZIP code." }, "city": { - "type": "string" + "type": "string", + "description": "The name of the city of the physical postal address, synonyms: town, village, municipality." }, "deliveryServiceType": { "type": "string", + "description": "One of the alternative postal address types: P.O. box, private bag, boite postale.", "enum": [ "PO_BOX", "PRIVATE_BAG", @@ -186,30 +183,37 @@ ] }, "deliveryServiceQualifier": { - "type": "string" + "type": "string", + "description": "The qualifier uniquely identifying the delivery service endpoint of the alternative postal address in conjunction with the delivery service number. In some countries for example, entering a P.O. box number, postal code and city is not sufficient to uniquely identify a P.O. box, because the same P.O. box number is assigned multiple times in some cities." }, "deliveryServiceNumber": { - "type": "string" + "type": "string", + "description": "The number indicating the delivery service endpoint of the alternative postal address to which the delivery is to be delivered, such as a P.O. box number or a private bag number." } - } + }, + "description": "An alternative postal address describes an alternative way of delivery for example if the goods are to be picked up somewhere else." }, "BpnReference": { "type": "object", "properties": { "referenceValue": { - "type": "string" + "type": "string", + "description": "The value of the reference, either an existing BPN or a BPN request identifier (which is freely chosen by the duplication check provider)" }, "desiredBpn": { - "type": "string" + "type": "string", + "description": "The desired BPN when a new golden record has to be created for this business partner data.Requires a BPN request identifier that is not associated with an existing BPN. At this moment the golden record process does not support creating desired BPNs and ignores this field. " }, "referenceType": { "type": "string", + "description": "Whether this reference is a BPN or BPN request identifier", "enum": [ "Bpn", "BpnRequestIdentifier" ] } - } + }, + "description": "A reference to a BPN for the corresponding business partner data. Either this reference contains an existing BPN or a BPN request identifier. The golden record process makes sure that the each unique BPN request identifier is associated to a unique BPN. For a new BPN request identifier the golden record process creates a new BPN (and golden record) and associates it with the BPN request identifier. Known BPN request identifiers are resolved to the BPN and the corresponding golden record is updated with the business partner data. This makes it possible for duplication check services to reference unique business partners by their own BPN request identifiers instead of needing to rely on BPNs for identification." }, "BusinessPartner": { "required": [ @@ -221,12 +225,14 @@ "properties": { "nameParts": { "type": "array", + "description": "Fully categorized and cleaned name parts based on the uncategorized name parts provided", "items": { "$ref": "#/components/schemas/NamePart" } }, "owningCompany": { - "type": "string" + "type": "string", + "description": "The BPNL of the legal entity to which this business partner data belongs to" }, "uncategorized": { "$ref": "#/components/schemas/UncategorizedProperties" @@ -242,60 +248,73 @@ }, "type": { "type": "string", + "description": "The recognized golden record type this business partner data contains.\n* `Legal Entity`: The business partner data only contains legal entity and legal address information.\n* `Site`: The business partner data contains site, site main address and its parent legal entity information.\n* `Additional Address`: The business partner data contains an additional address, (optional) parent site and parent legal entity information.\n* `Null`: No clear type determined, undecided. The golden record process will not create golden record from this business partner data.", "enum": [ "LegalEntity", "Site", "Address" ] } - } + }, + "description": "Generic business partner data for golden record processing. Typically a sharing member shares incomplete and/or uncategorized business partner data to the golden record process. The golden record process categorizes and completes the data in order to create and update the resulting golden records. The golden records are found in the legalEntity, site and additionalAddress fields. The business partner data needs to contain the full golden record parent relationship. This means, if an additional address is specified in the business partner data, also its legal entity and also its site parent (if a site exists) needs to be specified. " }, "BusinessState": { "type": "object", "properties": { "validFrom": { "type": "string", + "description": "Date since when the status is/was valid.", "format": "date-time" }, "validTo": { "type": "string", + "description": "Date until the status was valid, if applicable.", "format": "date-time" }, "type": { "type": "string", + "description": "The type of this specified status.", "enum": [ "ACTIVE", "INACTIVE" ] } - } + }, + "description": "The business state information for the corresponding business partner" }, "ConfidenceCriteria": { "type": "object", "properties": { "sharedByOwner": { - "type": "boolean" + "type": "boolean", + "description": "Whether the business partner data is shared by the actual owner" }, "checkedByExternalDataSource": { - "type": "boolean" + "type": "boolean", + "description": "The corresponding business partner data has been verified by an external data source, like an official register" }, "numberOfSharingMembers": { "type": "integer", + "description": "How many sharing members have already shared the matched golden record", "format": "int32" }, "lastConfidenceCheckAt": { "type": "string", + "description": "Last time the confidence values have been checked (and updated if needed)", "format": "date-time" }, "nextConfidenceCheckAt": { "type": "string", + "description": "Next time the confidence values should be checked", "format": "date-time" }, "confidenceLevel": { "type": "integer", + "description": "The overall confidence level of the matched golden record", "format": "int32" } - } + }, + "description": "Contains information to evaluate how good or verified the information in the attached business partner data is. This information will be directly written in the matched golden record's confidence criteria." }, "GeoCoordinate": { "type": "object", @@ -312,21 +331,26 @@ "type": "number", "format": "float" } - } + }, + "description": "The exact location of the physical postal address in latitude, longitude, and altitude." }, "Identifier": { "type": "object", "properties": { "value": { - "type": "string" + "type": "string", + "description": "Value of the identifier" }, "type": { - "type": "string" + "type": "string", + "description": "The type of identifier" }, "issuingBody": { - "type": "string" + "type": "string", + "description": "The organisation that issued this identifier" } - } + }, + "description": "The additional identifiers of this business partner (excluding the BPN)" }, "LegalEntity": { "required": [ @@ -342,22 +366,27 @@ "$ref": "#/components/schemas/BpnReference" }, "legalName": { - "type": "string" + "type": "string", + "description": "The legal name of this legal entity according to official registers" }, "legalShortName": { - "type": "string" + "type": "string", + "description": "The abbreviated name of this legal entity, if it exists" }, "legalForm": { - "type": "string" + "type": "string", + "description": "The legal form of this legal entity" }, "identifiers": { "type": "array", + "description": "Identifiers for this legal entity (in addition to the BPNL)", "items": { "$ref": "#/components/schemas/Identifier" } }, "states": { "type": "array", + "description": "The business state history of this legal entity", "items": { "$ref": "#/components/schemas/BusinessState" } @@ -366,15 +395,18 @@ "$ref": "#/components/schemas/ConfidenceCriteria" }, "isCatenaXMemberData": { - "type": "boolean" + "type": "boolean", + "description": "Whether this legal entity is part of the Catena-X network" }, "hasChanged": { - "type": "boolean" + "type": "boolean", + "description": "Whether this legal entity information differs from its golden record counterpart in the Pool. +The Pool will not update the legal entity if it is set to false. However, if this legal entity constitutes a new legal entity golden record, it is still created independent of this flag." }, "legalAddress": { "$ref": "#/components/schemas/PostalAddress" } - } + }, + "description": "Legal entity information for this business partner data. Every business partner either is a legal entity or belongs to a legal entity.There, a legal entity property is not allowed to be 'null'. " }, "NamePart": { "required": [ @@ -384,10 +416,12 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name part value" }, "type": { "type": "string", + "description": "NamePartType:\n* `LegalName` - Value is part of the legal entities' legal name\n* `ShortName` - Value is part of the legal entities' short name\n* `LegalForm` - Value is part of the legal entities' legal form name\n* `SiteName` - Value is part of the site's name\n* `AddressName` - Value is part of the address name\n", "enum": [ "LegalName", "ShortName", @@ -396,7 +430,8 @@ "AddressName" ] } - } + }, + "description": "A categorized name part for this business partner data" }, "PhysicalAddress": { "required": [ @@ -409,48 +444,62 @@ "$ref": "#/components/schemas/GeoCoordinate" }, "country": { - "type": "string" + "type": "string", + "description": "The 2-digit country code of the physical postal address according to ISO 3166-1." }, "administrativeAreaLevel1": { - "type": "string" + "type": "string", + "description": "The 2-digit country subdivision code according to ISO 3166-2, such as a region within a country." }, "administrativeAreaLevel2": { - "type": "string" + "type": "string", + "description": "The name of the locally regulated secondary country subdivision of the physical postal address, such as county within a country." }, "administrativeAreaLevel3": { - "type": "string" + "type": "string", + "description": "The name of the locally regulated tertiary country subdivision of the physical address, such as townships within a country." }, "postalCode": { - "type": "string" + "type": "string", + "description": "The alphanumeric identifier (sometimes including spaces or punctuation) of the physical postal address for the purpose of sorting mail, synonyms:postcode, post code, PIN or ZIP code." }, "city": { - "type": "string" + "type": "string", + "description": "The name of the city of the physical postal address, synonyms: town, village, municipality." }, "district": { - "type": "string" + "type": "string", + "description": "The name of the district of the physical postal address which divides the city in several smaller areas." }, "street": { "$ref": "#/components/schemas/Street" }, "companyPostalCode": { - "type": "string" + "type": "string", + "description": "The company postal code of the physical postal address, which is sometimes required for large companies." }, "industrialZone": { - "type": "string" + "type": "string", + "description": "The industrial zone of the physical postal address, designating an area for industrial development, synonym: industrial area." }, "building": { - "type": "string" + "type": "string", + "description": "The alphanumeric identifier of the building addressed by the physical postal address." }, "floor": { - "type": "string" + "type": "string", + "description": "The number of a floor in the building addressed by the physical postal address, synonym: level." }, "door": { - "type": "string" + "type": "string", + "description": "The number of a door in the building on the respective floor addressed by the physical postal address, synonyms: room, suite." }, "taxJurisdictionCode": { - "type": "string" + "type": "string", + "description": "Tax jurisdiction codes are used to identify the specific jurisdiction(s) that a company belong to, particularly in bureaucratic processes such as tax returns and IRS forms." } - } + }, + "description": "A physical postal address describes the physical location of an office, warehouse, gate, etc." }, "PostalAddress": { "required": [ @@ -466,16 +515,19 @@ "$ref": "#/components/schemas/BpnReference" }, "addressName": { - "type": "string" + "type": "string", + "description": "The name of this address" }, "identifiers": { "type": "array", + "description": "Identifiers for this address (in addition to the BPNA)", "items": { "$ref": "#/components/schemas/Identifier" } }, "states": { "type": "array", + "description": "The business state history of this address", "items": { "$ref": "#/components/schemas/BusinessState" } @@ -490,9 +542,12 @@ "$ref": "#/components/schemas/AlternativeAddress" }, "hasChanged": { - "type": "boolean" + "type": "boolean", + "description": "Whether this address information differs from its golden record counterpart in the Pool.Currently deprecated and ignored by the golden record creation and update process.", + "deprecated": true } - } + }, + "description": "Address information of this business partner data. The address can be either a legal, site main and/or additional address. This can also refer to address information which is unknown to which type it belongs to." }, "Site": { "required": [ @@ -507,10 +562,12 @@ "$ref": "#/components/schemas/BpnReference" }, "siteName": { - "type": "string" + "type": "string", + "description": "The name of this site" }, "states": { "type": "array", + "description": "The business state history of this site", "items": { "$ref": "#/components/schemas/BusinessState" } @@ -519,52 +576,66 @@ "$ref": "#/components/schemas/ConfidenceCriteria" }, "hasChanged": { - "type": "boolean" + "type": "boolean", + "description": "Whether this site information differs from its golden record counterpart in the Pool. +The Pool will not update the site if it is set to false. However, if this site constitutes a new site golden record, it is still created independent of this flag." }, "siteMainAddress": { "$ref": "#/components/schemas/PostalAddress" }, "siteMainIsLegalAddress": { - "type": "boolean" + "type": "boolean", + "description": "This site's main address is the legal address of the legal entity. The address information therefore is stored in the legal address." } - } + }, + "description": "Site information for this business partner data. A site of 'null' means the business partner data has no site." }, "Street": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the street." }, "houseNumber": { - "type": "string" + "type": "string", + "description": "The number representing the exact location of a building within the street." }, "houseNumberSupplement": { - "type": "string" + "type": "string", + "description": "The supplement to the house number" }, "milestone": { - "type": "string" + "type": "string", + "description": "The number representing the exact location of an addressed object within a street without house numbers, such as within long roads." }, "direction": { - "type": "string" + "type": "string", + "description": "The cardinal direction describing where the exit to the location of the addressed object on large highways / motorways is located, such as Highway 101 South." }, "namePrefix": { - "type": "string" + "type": "string", + "description": "The street related information, which is usually printed before the official street name on an address label." }, "additionalNamePrefix": { - "type": "string" + "type": "string", + "description": "The additional street related information, which is usually printed before the official street name on an address label." }, "nameSuffix": { - "type": "string" + "type": "string", + "description": "The street related information, which is usually printed after the official street name on an address label." }, "additionalNameSuffix": { - "type": "string" + "type": "string", + "description": "The additional street related information, which is usually printed after the official street name on an address label." } - } + }, + "description": "The street of the physical postal address, synonyms: road, avenue, lane, boulevard, highway" }, "TaskClientStateDto": { "required": [ "businessPartnerResult", "processingState", + "recordId", "taskId" ], "type": "object", @@ -572,6 +643,10 @@ "taskId": { "type": "string" }, + "recordId": { + "type": "string", + "description": "The identifier of the gate record for which this task has been created" + }, "businessPartnerResult": { "$ref": "#/components/schemas/BusinessPartner" }, @@ -583,8 +658,8 @@ }, "TaskCreateRequest": { "required": [ - "businessPartners", - "mode" + "mode", + "requests" ], "type": "object", "properties": { @@ -596,16 +671,31 @@ "UpdateFromPool" ] }, - "businessPartners": { + "requests": { "type": "array", - "description": "The list of business partner data to be processed", + "description": "The list of tasks to create", "items": { - "$ref": "#/components/schemas/BusinessPartner" + "$ref": "#/components/schemas/TaskCreateRequestEntry" } } }, "description": "Request object to specify for which business partner data tasks should be created and in which mode" }, + "TaskCreateRequestEntry": { + "required": [ + "businessPartner" + ], + "type": "object", + "properties": { + "recordId": { + "type": "string", + "description": "The unique identifier for this record which was previously issued by the Orchestrator" + }, + "businessPartner": { + "$ref": "#/components/schemas/BusinessPartner" + } + } + }, "TaskCreateResponse": { "required": [ "createdTasks" @@ -742,6 +832,7 @@ "TaskStepReservationEntryDto": { "required": [ "businessPartner", + "recordId", "requestKey", "taskId" ], @@ -751,6 +842,10 @@ "type": "string", "description": "The identifier of the reserved task" }, + "recordId": { + "type": "string", + "description": "The identifier of the gate record for which this task has been created" + }, "businessPartner": { "$ref": "#/components/schemas/BusinessPartner" }, @@ -867,18 +962,22 @@ "properties": { "nameParts": { "type": "array", + "description": "The plain uncategorized name of the business partner how it appears in the sharing member system", "items": { - "type": "string" + "type": "string", + "description": "The plain uncategorized name of the business partner how it appears in the sharing member system" } }, "identifiers": { "type": "array", + "description": "Identifiers for which it is unknown whether they belong to the legal entity, site or any address", "items": { "$ref": "#/components/schemas/Identifier" } }, "states": { "type": "array", + "description": "Business states for which it is unknown whether they belong to the legal entity, site or any address", "items": { "$ref": "#/components/schemas/BusinessState" } @@ -886,29 +985,8 @@ "address": { "$ref": "#/components/schemas/PostalAddress" } - } - } - }, - "securitySchemes": { - "open_id_scheme": { - "type": "oauth2", - "flows": { - "clientCredentials": { - "tokenUrl": "http://localhost:8180/realms/CX-Central/protocol/openid-connect/token", - "scopes": {} - }, - "authorizationCode": { - "authorizationUrl": "http://localhost:8180/realms/CX-Central/protocol/openid-connect/auth", - "tokenUrl": "http://localhost:8180/realms/CX-Central/protocol/openid-connect/token", - "refreshUrl": "http://localhost:8180/realms/CX-Central/protocol/openid-connect/token", - "scopes": {} - } - } - }, - "bearer_scheme": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT" + }, + "description": "Business partner data that has not yet or can not be categorized" } } } diff --git a/docs/api/orchestrator.yaml b/docs/api/orchestrator.yaml index 199e413fc..c002016c8 100644 --- a/docs/api/orchestrator.yaml +++ b/docs/api/orchestrator.yaml @@ -2,13 +2,10 @@ openapi: 3.0.1 info: title: Business Partner Data Management Orchestrator description: Orchestrator component acts as a passive component and offers for each processing steps individual endpoints - version: 6.1.0-SNAPSHOT + version: 6.1.1-SNAPSHOT servers: - url: http://localhost:8085 description: Generated server url -security: - - open_id_scheme: [] - - bearer_scheme: [] paths: /v6/golden-record-tasks: post: @@ -105,34 +102,46 @@ components: $ref: '#/components/schemas/GeoCoordinate' country: type: string + description: The 2-digit country code of the physical postal address according to ISO 3166-1. administrativeAreaLevel1: type: string + description: The 2-digit country subdivision code according to ISO 3166-2, such as a region within a country. postalCode: type: string + description: The alphanumeric identifier (sometimes including spaces or punctuation) of the physical postal address for the purpose of sorting mail, synonyms:postcode, post code, PIN or ZIP code. city: type: string + description: 'The name of the city of the physical postal address, synonyms: town, village, municipality.' deliveryServiceType: type: string + description: 'One of the alternative postal address types: P.O. box, private bag, boite postale.' enum: - PO_BOX - PRIVATE_BAG - BOITE_POSTALE deliveryServiceQualifier: type: string + description: The qualifier uniquely identifying the delivery service endpoint of the alternative postal address in conjunction with the delivery service number. In some countries for example, entering a P.O. box number, postal code and city is not sufficient to uniquely identify a P.O. box, because the same P.O. box number is assigned multiple times in some cities. deliveryServiceNumber: type: string + description: The number indicating the delivery service endpoint of the alternative postal address to which the delivery is to be delivered, such as a P.O. box number or a private bag number. + description: An alternative postal address describes an alternative way of delivery for example if the goods are to be picked up somewhere else. BpnReference: type: object properties: referenceValue: type: string + description: The value of the reference, either an existing BPN or a BPN request identifier (which is freely chosen by the duplication check provider) desiredBpn: type: string + description: 'The desired BPN when a new golden record has to be created for this business partner data.Requires a BPN request identifier that is not associated with an existing BPN. At this moment the golden record process does not support creating desired BPNs and ignores this field. ' referenceType: type: string + description: Whether this reference is a BPN or BPN request identifier enum: - Bpn - BpnRequestIdentifier + description: A reference to a BPN for the corresponding business partner data. Either this reference contains an existing BPN or a BPN request identifier. The golden record process makes sure that the each unique BPN request identifier is associated to a unique BPN. For a new BPN request identifier the golden record process creates a new BPN (and golden record) and associates it with the BPN request identifier. Known BPN request identifiers are resolved to the BPN and the corresponding golden record is updated with the business partner data. This makes it possible for duplication check services to reference unique business partners by their own BPN request identifiers instead of needing to rely on BPNs for identification. BusinessPartner: required: - legalEntity @@ -142,10 +151,12 @@ components: properties: nameParts: type: array + description: Fully categorized and cleaned name parts based on the uncategorized name parts provided items: $ref: '#/components/schemas/NamePart' owningCompany: type: string + description: The BPNL of the legal entity to which this business partner data belongs to uncategorized: $ref: '#/components/schemas/UncategorizedProperties' legalEntity: @@ -156,43 +167,61 @@ components: $ref: '#/components/schemas/PostalAddress' type: type: string + description: |- + The recognized golden record type this business partner data contains. + * `Legal Entity`: The business partner data only contains legal entity and legal address information. + * `Site`: The business partner data contains site, site main address and its parent legal entity information. + * `Additional Address`: The business partner data contains an additional address, (optional) parent site and parent legal entity information. + * `Null`: No clear type determined, undecided. The golden record process will not create golden record from this business partner data. enum: - LegalEntity - Site - Address + description: 'Generic business partner data for golden record processing. Typically a sharing member shares incomplete and/or uncategorized business partner data to the golden record process. The golden record process categorizes and completes the data in order to create and update the resulting golden records. The golden records are found in the legalEntity, site and additionalAddress fields. The business partner data needs to contain the full golden record parent relationship. This means, if an additional address is specified in the business partner data, also its legal entity and also its site parent (if a site exists) needs to be specified. ' BusinessState: type: object properties: validFrom: type: string + description: Date since when the status is/was valid. format: date-time validTo: type: string + description: Date until the status was valid, if applicable. format: date-time type: type: string + description: The type of this specified status. enum: - ACTIVE - INACTIVE + description: The business state information for the corresponding business partner ConfidenceCriteria: type: object properties: sharedByOwner: type: boolean + description: Whether the business partner data is shared by the actual owner checkedByExternalDataSource: type: boolean + description: The corresponding business partner data has been verified by an external data source, like an official register numberOfSharingMembers: type: integer + description: How many sharing members have already shared the matched golden record format: int32 lastConfidenceCheckAt: type: string + description: Last time the confidence values have been checked (and updated if needed) format: date-time nextConfidenceCheckAt: type: string + description: Next time the confidence values should be checked format: date-time confidenceLevel: type: integer + description: The overall confidence level of the matched golden record format: int32 + description: Contains information to evaluate how good or verified the information in the attached business partner data is. This information will be directly written in the matched golden record's confidence criteria. GeoCoordinate: type: object properties: @@ -205,15 +234,20 @@ components: altitude: type: number format: float + description: The exact location of the physical postal address in latitude, longitude, and altitude. Identifier: type: object properties: value: type: string + description: Value of the identifier type: type: string + description: The type of identifier issuingBody: type: string + description: The organisation that issued this identifier + description: The additional identifiers of this business partner (excluding the BPN) LegalEntity: required: - bpnReference @@ -227,26 +261,34 @@ components: $ref: '#/components/schemas/BpnReference' legalName: type: string + description: The legal name of this legal entity according to official registers legalShortName: type: string + description: The abbreviated name of this legal entity, if it exists legalForm: type: string + description: The legal form of this legal entity identifiers: type: array + description: Identifiers for this legal entity (in addition to the BPNL) items: $ref: '#/components/schemas/Identifier' states: type: array + description: The business state history of this legal entity items: $ref: '#/components/schemas/BusinessState' confidenceCriteria: $ref: '#/components/schemas/ConfidenceCriteria' isCatenaXMemberData: type: boolean + description: Whether this legal entity is part of the Catena-X network hasChanged: type: boolean + description: Whether this legal entity information differs from its golden record counterpart in the Pool. +The Pool will not update the legal entity if it is set to false. However, if this legal entity constitutes a new legal entity golden record, it is still created independent of this flag. legalAddress: $ref: '#/components/schemas/PostalAddress' + description: 'Legal entity information for this business partner data. Every business partner either is a legal entity or belongs to a legal entity.There, a legal entity property is not allowed to be ''null''. ' NamePart: required: - name @@ -255,14 +297,23 @@ components: properties: name: type: string + description: The name part value type: type: string + description: | + NamePartType: + * `LegalName` - Value is part of the legal entities' legal name + * `ShortName` - Value is part of the legal entities' short name + * `LegalForm` - Value is part of the legal entities' legal form name + * `SiteName` - Value is part of the site's name + * `AddressName` - Value is part of the address name enum: - LegalName - ShortName - LegalForm - SiteName - AddressName + description: A categorized name part for this business partner data PhysicalAddress: required: - geographicCoordinates @@ -273,32 +324,46 @@ components: $ref: '#/components/schemas/GeoCoordinate' country: type: string + description: The 2-digit country code of the physical postal address according to ISO 3166-1. administrativeAreaLevel1: type: string + description: The 2-digit country subdivision code according to ISO 3166-2, such as a region within a country. administrativeAreaLevel2: type: string + description: The name of the locally regulated secondary country subdivision of the physical postal address, such as county within a country. administrativeAreaLevel3: type: string + description: The name of the locally regulated tertiary country subdivision of the physical address, such as townships within a country. postalCode: type: string + description: The alphanumeric identifier (sometimes including spaces or punctuation) of the physical postal address for the purpose of sorting mail, synonyms:postcode, post code, PIN or ZIP code. city: type: string + description: 'The name of the city of the physical postal address, synonyms: town, village, municipality.' district: type: string + description: The name of the district of the physical postal address which divides the city in several smaller areas. street: $ref: '#/components/schemas/Street' companyPostalCode: type: string + description: The company postal code of the physical postal address, which is sometimes required for large companies. industrialZone: type: string + description: 'The industrial zone of the physical postal address, designating an area for industrial development, synonym: industrial area.' building: type: string + description: The alphanumeric identifier of the building addressed by the physical postal address. floor: type: string + description: 'The number of a floor in the building addressed by the physical postal address, synonym: level.' door: type: string + description: 'The number of a door in the building on the respective floor addressed by the physical postal address, synonyms: room, suite.' taxJurisdictionCode: type: string + description: Tax jurisdiction codes are used to identify the specific jurisdiction(s) that a company belong to, particularly in bureaucratic processes such as tax returns and IRS forms. + description: A physical postal address describes the physical location of an office, warehouse, gate, etc. PostalAddress: required: - bpnReference @@ -312,12 +377,15 @@ components: $ref: '#/components/schemas/BpnReference' addressName: type: string + description: The name of this address identifiers: type: array + description: Identifiers for this address (in addition to the BPNA) items: $ref: '#/components/schemas/Identifier' states: type: array + description: The business state history of this address items: $ref: '#/components/schemas/BusinessState' confidenceCriteria: @@ -328,6 +396,9 @@ components: $ref: '#/components/schemas/AlternativeAddress' hasChanged: type: boolean + description: Whether this address information differs from its golden record counterpart in the Pool.Currently deprecated and ignored by the golden record creation and update process. + deprecated: true + description: Address information of this business partner data. The address can be either a legal, site main and/or additional address. This can also refer to address information which is unknown to which type it belongs to. Site: required: - bpnReference @@ -340,48 +411,67 @@ components: $ref: '#/components/schemas/BpnReference' siteName: type: string + description: The name of this site states: type: array + description: The business state history of this site items: $ref: '#/components/schemas/BusinessState' confidenceCriteria: $ref: '#/components/schemas/ConfidenceCriteria' hasChanged: type: boolean + description: Whether this site information differs from its golden record counterpart in the Pool. +The Pool will not update the site if it is set to false. However, if this site constitutes a new site golden record, it is still created independent of this flag. siteMainAddress: $ref: '#/components/schemas/PostalAddress' siteMainIsLegalAddress: type: boolean + description: This site's main address is the legal address of the legal entity. The address information therefore is stored in the legal address. + description: Site information for this business partner data. A site of 'null' means the business partner data has no site. Street: type: object properties: name: type: string + description: The name of the street. houseNumber: type: string + description: The number representing the exact location of a building within the street. houseNumberSupplement: type: string + description: The supplement to the house number milestone: type: string + description: The number representing the exact location of an addressed object within a street without house numbers, such as within long roads. direction: type: string + description: The cardinal direction describing where the exit to the location of the addressed object on large highways / motorways is located, such as Highway 101 South. namePrefix: type: string + description: The street related information, which is usually printed before the official street name on an address label. additionalNamePrefix: type: string + description: The additional street related information, which is usually printed before the official street name on an address label. nameSuffix: type: string + description: The street related information, which is usually printed after the official street name on an address label. additionalNameSuffix: type: string + description: The additional street related information, which is usually printed after the official street name on an address label. + description: 'The street of the physical postal address, synonyms: road, avenue, lane, boulevard, highway' TaskClientStateDto: required: - businessPartnerResult - processingState + - recordId - taskId type: object properties: taskId: type: string + recordId: + type: string + description: The identifier of the gate record for which this task has been created businessPartnerResult: $ref: '#/components/schemas/BusinessPartner' processingState: @@ -389,8 +479,8 @@ components: description: The golden record task's processing state together with optional business partner data in case processing is done TaskCreateRequest: required: - - businessPartners - mode + - requests type: object properties: mode: @@ -399,12 +489,22 @@ components: enum: - UpdateFromSharingMember - UpdateFromPool - businessPartners: + requests: type: array - description: The list of business partner data to be processed + description: The list of tasks to create items: - $ref: '#/components/schemas/BusinessPartner' + $ref: '#/components/schemas/TaskCreateRequestEntry' description: Request object to specify for which business partner data tasks should be created and in which mode + TaskCreateRequestEntry: + required: + - businessPartner + type: object + properties: + recordId: + type: string + description: The unique identifier for this record which was previously issued by the Orchestrator + businessPartner: + $ref: '#/components/schemas/BusinessPartner' TaskCreateResponse: required: - createdTasks @@ -506,6 +606,7 @@ components: TaskStepReservationEntryDto: required: - businessPartner + - recordId - requestKey - taskId type: object @@ -513,6 +614,9 @@ components: taskId: type: string description: The identifier of the reserved task + recordId: + type: string + description: The identifier of the gate record for which this task has been created businessPartner: $ref: '#/components/schemas/BusinessPartner' requestKey: @@ -598,31 +702,20 @@ components: properties: nameParts: type: array + description: The plain uncategorized name of the business partner how it appears in the sharing member system items: type: string + description: The plain uncategorized name of the business partner how it appears in the sharing member system identifiers: type: array + description: Identifiers for which it is unknown whether they belong to the legal entity, site or any address items: $ref: '#/components/schemas/Identifier' states: type: array + description: Business states for which it is unknown whether they belong to the legal entity, site or any address items: $ref: '#/components/schemas/BusinessState' address: $ref: '#/components/schemas/PostalAddress' - securitySchemes: - open_id_scheme: - type: oauth2 - flows: - clientCredentials: - tokenUrl: http://localhost:8180/realms/CX-Central/protocol/openid-connect/token - scopes: {} - authorizationCode: - authorizationUrl: http://localhost:8180/realms/CX-Central/protocol/openid-connect/auth - tokenUrl: http://localhost:8180/realms/CX-Central/protocol/openid-connect/token - refreshUrl: http://localhost:8180/realms/CX-Central/protocol/openid-connect/token - scopes: {} - bearer_scheme: - type: http - scheme: bearer - bearerFormat: JWT + description: Business partner data that has not yet or can not be categorized