Azure Maps Integration in CMD Application

• Current POC
  • Demo 1 | on 8th October
    • Moments of meeting - suggestions given
  • Demo 2 | 22nd October at 10:30 am
    • Moments of meeting
• Previous implementation till v1.6
  • Functionality in CMD portal to call Azure maps wrapper service:
  • Options to integrate Azure Maps in CMD
  • Azure maps wrapper service functionality:
  • Collision and Discrepancy Handling :

Current POC

Demo 1 | on 8th October

Feedback and suggestions were received from the team - Below are the Moments of the meeting.

One more session would be needed to cover the points we discussed today as well as the changes that needs to be made.

Moments of meeting - suggestions given

1. Only when mandatory fields are filled, we should call the Azure API as a form of optimization. (Suggested by Sudhir - but for your additional information, currently we actually cache the fuzzy results in UI for some time as an optimization - exact logic I can explain if you are curious but yes this can be implemented based on consensus - please let us know).
2. The map can be useful for new record creation, but in bvd flow, it might not be required. This is because we already get address suggestions from a trusted source(Suggested by Vinesh and Sudhir) Let me know if we need to implement these different kind of UIs for different scenarios.
3. Match percentage - can be displayed to the ADS for better decision (suggested by Vinesh) - but please see the below screenshot, we are getting some scores like 11.609(for the top matched result), I think this is not a percentage as such and instead just a simple score given by Azure maps - Gopala do you have any idea on how to utilize this score in a meaningful way? Please let us know if you do.
4. increase the number of match results from lets say 10 - 15/20(suggested by Vinesh) - we need to check the feasibility for the same.
5. Auto unlink if the address is changed by user in the form, or if the user selected different address on the map - suggested by almost Everyone. At the end of the call had a discussion with Snehal that the lat and long can be too technical for the users, instead, we can just remove this concept of showing it. We can just keep the lat long information internally, but not show the user anything related to it. Users can just simply select an address from the map in order to proceed, that's it. (I can make this change before the next demo).
6. How will the functionality work for existing customers - Nanditha had some questions I guess, but could not demo the same within the scheduled time, in case we deploy the same in CDT, I will share with you some sample customer codes to which you can refer.
7. Earlier Naveen, also gave some suggestions related to keeping the map inside a popup(Modal), so that users can see the map only when required - it can help in optimization and aids the #point number 1 (above). We don't have a UX for it, but if you have more ideas then please let us know since it's in the POC stage. Below is the idea shared by Naveen for the map integration, wherein the map would not be initially shown by default. Instead, there will be a button of let's say "Point Address" on the customer details page,

on clicking which can open a modal view like the one below (in case this simplifies the current implementation FYR).

---

Demo 2 | 22nd October at 10:30 am

Moments of meeting

1. Current challenges of mapping the Azure address with CMD fields for different countries and approaches around that. Ex: Some fields are getting repeated values like City-Subarea and Apartment and City fields if we go with static mapping.
2. The current problem of transliteration for countries to acceptable CMD regex for ex: China/EU countries etc - Rahul
3. Showing address suggestions when all mandatory fields are entered by ADs - Snehal
4. The accuracy of the Azure map view suggestion with respect to previous implementations. - Gopala suggested this POI endpoint. https://learn.microsoft.com/en-us/rest/api/maps/search/get-search-poi?view=rest-maps-1.0&tabs=HTTP

So there are still some unknowns for which we will need solutioning.

---

Previous implementation till v1.6

To enrich the customer address in CMD application, Azure maps will be used to replace the Address Doctor in current on-prem solution. The below URL (service) will be used as REST endpoint to give input address and to capture the enriched address.

Below endpoint used to pass single line address information as input.

GET https://atlas.microsoft.com/search/address/json?api-version=1.0&query=15127 NE 24th Street, Redmond, WA 98052

Below endpoint used to pass city, country and address information (other fields) as input.

https://atlas.microsoft.com/search/address/structured/json?api-version=1.0&subscription-key=rrgsae5yO5kwwpSDDD29DCH4LhLaTwh2ioS%5FrvM1%5FHI&countryCode=IN&municipality=BANGALORE

Below is the help guide on Azure maps search/address endpoint

Search - Get Search Address - REST API (Azure Maps)

Below are the address fields in CMD poratl UI application available for user to enter. Based on country specific rules, few fields are mandatory to enter before calling the azure maps.

CMD Portal UI Field	Comments
Street Name	This is part of Address Line 1
Street Number	This is part of Address Line 1
Apartment, Suite, Floor etc	This is Address Line 2
City Sub-Area/City District	This is Address Line 3 (District)
City
Postal Code/Zip Code	Postal Code
PO Box
Region	Region Name
Country	Country Name

Below are the output fields from Azure response will be captured.

Azure Response Field	CMD Portal UI Field	Comments
streetName	Street Name
streetNumber	Street Number
buildingNumber	Apartment, Suite, Floor etc
	City Sub-Area/City District
municipality	City	In some countries, below fileds can be used.municipalitySubdivisioncountrySecondarySubdivision
postalCode	Postal/Zip Code
	PO Box
countrySubdivision	Region	In some countries, below fileds can be used.countrySubdivisionNamecountrySecondarySubdivision
country	Country
lat
lon

Customer will be onboarded in CMD through either CMD portal or using IngestAPI. CMD portal will use the Azure Maps wrapper service to call actual Azure maps service to get the enriched/quality address.

Functionality in CMD portal to call Azure maps wrapper service:

During customer creation in portal, user will enter customer name and country and automatically BVD will be called to enrich the customer data. CMD maintain the country specific rules in the backend database. Based on country code we need to check whether for that country postal code is mandatory or not. Below diagram shows the customer creation flow with BVD for enrichment and Azure maps for customer address enrichment along with integrating with GEO application.

Process to call Azure Maps wrapper service endpoint:

1. Call BVD service based on customer name and country and map the BVD fields to CMD Portal UI fields. Based on country code check whether the postal code city is mandatory and based on that get the required filed data.
2. Validate the Country, State and City data from GEO application.
3. To enrich the address data, call Azure maps wrapper end point with concatenation of all 8 address elements.
4. If the Azure maps response has address range and POA address,
   1. show them as suggested address in pop-up
   2. then based on user selection (from the list) populate the address fields in UI portal
      1. If user does not select any address from the list then trigger the workflow
   3. Persist the customer data along with address data
   4. No workflow trigger
5. If the Azure maps response does not have address range and POA addresses
   1. Call Azure Maps with Structured Address endpoint with Country, City, Region & PostalCode which are referenced from GEO
   2. Is Azure maps output is matching with input request data for Country, City, Region & PostalCode data elements.
      1. If yes, Display a note as "Partially verified address" on UI and no WF trigger
      2. If no, trigger the workflow

Based on below conditions, the address workflow will be generated or will be directly persisted in CMD without workflow.

Condition	Workflow generated?	Details
Match Type = (Point Address OR Address Range)ANDMatch_Score <= 10ANDMatch_Confidence_score <= 0.5ORUser updated address data provided by Azure maps	Yes	Low quality address, so workflow needs to be generated for approval process
Match Type = (Point Address OR Address Range)ANDMatch_Score > 10ANDMatch_Confidence_score > 0.5ANDUser will not update address data provided by Azure maps	No	Good quality address, so no need to generate the address workflow for approval process.
If azure map not returning any result	Yes	The user entered address will be retained and sent for approval.

Options to integrate Azure Maps in CMD

CMD provides 2 options/ways to integrate Azure maps in CMD.

Option 1: Manually entering/selecting address data

In this option, user will manually enter or select the address fields in CMD portal UI and then submit it for validation/enrichment. In this case, user will select country, state, city, postal code, district, city sub area fields which are populated from BVD/GEO application and along with these fields user may enter street name, street number and building Number before submit the request to Azure maps for enrichment/validation.

As mentioned in above table, if match score is greater or equal AND user will not change any data element provided by Azure maps then no address override workflow will be generated else address override workflow will be generated.

Option 2: Selecting address point on map

In this option, user will navigate in map and select the address on the map. The CMD portal UI application need to extract country, state, city, postal code, district, city sub area fields and map them in CMD portal UI application. While mapping the fields needs to be mapped between GEO and Azure maps fields. If there is mismatch in the fields user need to select the fields from drop which are populated from GEO application.

If all fields mapped between Azure maps AND match score is greater or equal as mentioned above table AND user will not change any data element provided by Azure maps then no address override workflow will be generated else address override workflow will be generated.

Azure maps wrapper service functionality:

Wrapper REST based service needs to be created on top of the Azure maps REST API to utilize the same service in below scenarios/components in modern CMD solution.

1. During creation of customer/Facility from CMD portal, which will make use of the wrapper service to feed the address data provided by end user and to get the enriched/corrected address as suggestions.
2. During creation of customer from CMD Portal using the BVD active integration, the address information provided by BVD source will be provided and the corrected/suggested address will be displayed to user to select.
3. Any other service/system can use backend wrapper service to enrich the user provided address data.

Azure wrapper service need to expose 2 endpoints

Structured Address Endpoint:

1. To get the address suggestions based on Country and {City or PostalCode} combination using the https://atlas.microsoft.com/search/address/structured Azure endpoint which will provide City, City Sub Area, District, State address fields as response.
2. The wrapper service need to suggest all addresses which are having the type=Geography and entityType=Postalcodearea in case if the input is country & postal code
3. The wrapper service need to suggest all addresses which are having the type=Geography and entityType=municipality in case if the input is country & city
4. To avoid calling the Azure endpoint for same address data (as cost involved for every hit), before calling the actual Azure endpoint need to check in the tracking table to get if it is already present else call the Azure end point.
5. If the address data not present in tracking table then call actual Azure maps and track the response in tracking table for future reference.

Fuzzy Address Endpoint:

This endpoint will be used to further get the good quality address based on all address fields(Country, {City or PostalCode}, State, City Sub area, District) which are enriched in the first call and any user entered address fields like house number, street name, street number etc.

1. This endpoint will be called based on Country, {City or PostalCode}, State, City Sub area, District fields along with additional fields like house number, street name, street number to get good quality address.
2. This endpoint need to filter and provide only one high score address data to the consumers based on below mentioned condition.
3. The address which satisfy the below condition with high score will be returned to the consumers. Match Type=Point Address OR Address Range Match_Score>= 10 Match_Confidence_score>= 0.5
4. Below is the Azure maps address fuzzy endpoint.

GET https://atlas.microsoft.com/search/fuzzy/?api-version=1.0&query=

Collision and Discrepancy Handling :

There could be cases where Azure Maps returns Country / Region / City data that doesn’t match with SMDS Geo data. This can occur due to various reasons like wrong/outdated data, geo-politics, or alias names etc.

If the Country/Region/City returned by Azure Maps doesn’t match with CMD (Geo) Reference Data, then filter out such results from Address Enrichment API.

This will ensure that CMD Portal user won’t have to re-enter the data and validate again, by going into a cyclic experience.