Reason Codes For Relations

[nicoprow]

Description

As a dataspace participant I am interested in why exactly a relation has been created between two business partners. This helps me to decide the legitimacy of the relation and the additional information may be useful for further business cases.

The reason code should consists of an actual machine-readable code for integration purposes and a further free text field for commentary purposes.

The sharing member as well as the refinement processor should be able to set reason codes for relations.

Assumption is:

• Operator is responsible for maintaining available reason codes
• No fallback option should be included
• Assumption is that the sharing member contacts Cofinity-X if another reason code is needed so they can introduce it on short notice
• Assumption is that owners are responsible for selecting and requesting the most correct reason code

Technical Considerations

The idea is to add two new fields to business partner relations reasonCode and reasonDescription.
The code is a mandatory metadata technical key.
As with other metadata the available codes are listed in a metadata endpoint of the Pool API.
The reason description should be a free text field but should be filled as well and not optional.

Gate

Add new fields

The relation DTOs, model objects and entities need to be enhanced with the two no mandatory fields.

classDiagram
    class Relation{
      String externalId
      String businessPartnerSourceExternalId
      String businessPartnerTargetExternalId
      String reasonCode
      String reasonDescription
      ValidityPeriod[] validityPeriods
      RelationType relationType
    }

Loading

Orchestrator

Add new fields

The relation DTOs, model objects and entities need to be enhanced with the two no mandatory fields.

classDiagram
    class Relation{
      String businessPartnerSourceBpnl
      String businessPartnerTargetBpnl
      String reasonCode
      String reasonDescription
      ValidityPeriod[] validityPeriods
      RelationType relationType
    }

Loading

Pool

Add new metadata

The Pool needs to add a new metadata object: reason code.
Analogous to other metadata the available reason codes should be searchable over an API endpoint.

API Level:

classDiagram
    class ReasonCode{
      String technicalKey
      String description
    }

Loading

Database Level:

erDiagram
    reason_codes{
        BIGINT id "PK"
        VARCHAR technical_key "UNIQUE NOT NULL"
        VARCHAR description "NOT NULL"
    }

Loading

Add new fields

The relation DTOs, model objects and entities need to be enhanced with the two no mandatory fields.

API Level:

classDiagram
    class RelationDTO{
      String businessPartnerSourceBpnl
      String businessPartnerTargetBpnl
      String reasonCode
      String reasonDescription
      ValidityPeriod[] validityPeriods
      RelationType relationType
    }

Loading

Database Level:

  erDiagram
      reason_codes ||--o{ relations : "have reason"
      
      relations {
          BIGINT id "PK"
          VARCHAR relation_type "NOT NULL"
          BIGINT source_id "FK"
          BIGINT target_id "FK"
          BIGINT reason_code_id "FK" 
          VARCHAR reason_description "NOT NULL"
      }

Loading

Validate reason codes

When processing relation golden record tasks the Pool needs to validate that the specified reason code really exists in the database.
Otherwise a validation error is returned.

[nicoprow]

Notes:

• No fallback value 'OTHER'
• No enumeration but an endpoint to give all possible reason code values (metadata)
• No list of reason codes in the standard
• Assumption is that the sharing member contacts Cofinity-X if another reason code is needed so they can introduce it on short notice
• Assumption is that owners are responsible for selecting and requesting the most correct reason code

[nicoprow]

Added assumptions and technical considerations detailing the work load