Data Architecture - City Name Alias

Jira item

Jira ticket → https://maersk-tools.atlassian.net/jira/software/c/projects/SMDSO/issues/SMDSO-1452?jql=project%20%3D%20%22SMDSO%22%20ORDER%20BY%20created%20DESC

Requirement

Copied from Jira item:

• A city must be able to have name aliases defined which are classified specifically for search purpose.

Considerations

• Name Alias for Cities must be able to be classified, e.g. SEARCH_ALIAS this can be done as nameAliasType. Other names could also be used for this classification, e.g. ALTERNATE_NAME or the like, the important thing is that the searchable name aliases must be able to be grouped together.
• The collection of name aliases for a City must become array of objects so that each alias have a nameAlias and a nameAliasType.
• Consumers can search by the alias based on the classification to filter out all other aliases not relevant for the searching. If implemented via API this can be achieved by adding a filter parameter in the GET /cities endpoint called e.g. searchByAlias that the consumer populates with the search term, if they want to search for cities by alias and not by the cityName.
• Data distributed via Event-Carried State Transfer must be published on a new topic. Consumers must switch to this new topic as we cannot change existing one as it would impact multiple consumers already on it that would then need to migrate in a big bang.
• Data tier level in Geography (e.g. the database of BLOB storage) must change to take in to account the nameAliasType. The Name Alias Type table/file must be usable for all entities needing name alias types in future; e.g. setting name aliases with types may be applicable to Countries, Locations, Defined Areas etc. as well.
• UI must change to be able to select name alias type when maintaining name aliases.
• Governance must be considered, e.g. whether a name alias must be approved by a data owner before being able to be used.
• Data migration may need to be of existing aliases that should be part of the searchable name aliases so that they get typed accordingly.
• Data clean up must be considered of existing aliases so that we don't have e.g. COPENHAGEN, DK PORT IN EUROPE or WMS Marigold as alias for Bangalore

Integrations

Involved solutions

It is important to note that the consumers of this data may not be receiving the data directly from SMDS. For example the solution SSIB is using Synergy solution for master data and reference data. Synergy consumes data from SMDS via events, stores it in a Postgres database, and then publishes the data via APIs to http://Maersk.com solutions. It is important for the planning exercise that there is visibility to all the layers and teams that must be involved to have changes done.

Data

City with name aliases (showing only a couple of properties from the City schema).

{
  "cityCode": "CNC",
  "countryCityCode": "USCNC",
  "cityName": "Charlotte",
  "nameAliases": [
    {
      "nameAlias": "The Queen City",
      "nameAliasTypeCode": "SEARCH_ALIAS"
    },
    {
      "nameAlias": "The Hornet's Nest",
      "nameAliasTypeCode": "SEARCH_ALIAS"
    }
  ]

{
  "cityCode": "BLR",
  "countryCityCode": "INKABLR",
  "cityName": "Bengaluru",
  "nameAliases": [
    {
      "nameAlias": "Bangalore",
      "nameAliasTypeCode": "ALTERNATE_NAME"
    },
    {
      "nameAlias": "BANGALORE, INDIA",
      "nameAliasTypeCode": "SEARCH_ALIAS"
    },
    {
      "nameAlias": "ICD BANGALORE",
      "nameAliasTypeCode": "SEARCH_ALIAS"
    }
  ]