Skip to main content

CMD Application Integration

CMD Integration with GEO Application

While onboarding customers in CMD application, customer address information like country, state, city, subcity and postal code will be referenced by GEO MDM application. The application is MDM solution for address information, it will have master data about continents, country, state, city, subcity and postal code.

In CMD application, the customer ingest API will consume the REST endpoints exposed by GEO application to get/validate the address fields (country, state, city, subcity and postal code) entered by business user while onboarding customer in CMD.

CMD also will maintain the cache of same data for further use from cache instead of from GEO REST API to improve the response time of service. This cache data will be refreshed periodically (based on scheduled time ex: every 1 hour).

Below diagram shows the integration approach

Below is the GEO API endpoint to consume from CMD

EnvironmentEndpoint URLComments
DEV
SIT
PREPROD
PROD

From CMD application, below are the service which will make use of the GEO service in various scenarios to get the GEO data mainly Country, State, City, PostalCode data

  1. Search Customer
  2. Create/Update Customer
  3. Search Facility
  4. Create Facility
  5. Reference Data API

Azure Maps Integration in CMD Application

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

https://learn.microsoft.com/en-us/rest/api/maps/search/get-search-address?tabs=HTTP

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 FieldComments
Street NameThis is part of Address Line 1
Street NumberThis is part of Address Line 1
Apartment, Suite, Floor etcThis is Address Line 2
City Sub-Area/City DistrictThis is Address Line 3 (District)
City
Postal Code/Zip CodePostal Code
PO Box
RegionRegion Name
CountryCountry Name

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

Azure Response FieldCMD Portal UI FieldComments
streetNameStreet Name
streetNumberStreet Number
buildingNumberApartment, Suite, Floor etc
City Sub-Area/City District
municipalityCityIn some countries, below fileds can be used.municipalitySubdivisioncountrySecondarySubdivision
postalCodePostal/Zip Code
PO Box
countrySubdivisionRegionIn some countries, below fileds can be used.countrySubdivisionNamecountrySecondarySubdivision
countryCountry
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.

ConditionWorkflow generated?Details
Match Type = (Point Address OR Address Range)ANDMatch_Score <= 10ANDMatch_Confidence_score <= 0.5ORUser updated address data provided by Azure mapsYesLow 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 mapsNoGood quality address, so no need to generate the address workflow for approval process.
If azure map not returning any resultYesThe 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.

Existing On-Prem CMD & SCV Replica Integration

Below are few application which are consuming the data from CMD via SCV Replica on on-prem system.

CODS, GCSS, GEMS, RKTS, AFLS, MEPC.

CODS, GCSS, GEMS applications are planning to move to EMP platform to consume CMD data directly.

RKTS, AFLS, MEPC applications are not ready to move to EMP platform so we need to continue the existing SCV replica for these systems to continue consuming messages.

Below are different use cases list and expected message from CMD replica MQ feed.

  1. Normal Customer
    1. Create customer
    2. Update customer
    3. Inactivate customer
  2. Customer with contact
    1. Create Customer
    2. Update contact
    3. Add new contact
    4. Remove contact
    5. Inactivate Contact
    6. Reactivate Contact
    7. Inactivate customer having multiple contact
  3. Customer with web bl information
    1. Create Customer with WEB BL information
    2. Update customer Web bl information
    3. Inactivate customer having WEB BL
  4. Customer with CBU information
    1. Create Customer with CBU information
    2. Remove CBU information
    3. Update CBU information
    4. Inactivate customer having CBU
  5. Customer with Customer relationship
    1. Create customer with customer relationship
    2. Remove customer relationship
    3. Inactivate customer having customer relationship
  6. Create Customer contact with Communication preference information
    1. Create customer
    2. Add contact
    3. Add communication preference
    4. Remove communication preference
    5. Inactivate customer

The below diagram shows the existing on-prem SCV replica solution.

The Filed mapping between CMD to SCV Replica TAGs is provided in below confluence page.

CMD & Interface Field Mapping

CMD application publish the CREATE & UPDATE events on Customer, Contact, Concern & Customer Facility entities to SCV Replica.

SC300S Power Center Job picks the message (with code & action) from queue and process it to prepare snapshot of customer/contact/concern/facility entity message in XML format.

SC300S job connects to CMD and GEO database to get complete snapshot of the respective entity information and push the snapshot XML message into message queue. Sample message is given below.

CMD MQ Push (SCV Replica) Java application will consumes the snapshot XML message pushed by SC300S job and convert the XML message into TAG based encoded message which can be readable by SCV Replica consumers.

CMD MQ Push, publishes separate entities (Customer, Contact, Concern & Customer Facility) into separate output queues with TAG based structure.

CMD MQ Push also connect to CMD (C_PTR_ALT_CODES, C_PTR_REL, C_PTR_CONT tables) and GEO (C_ALT_CODE, C_GDA_DFND,AREA C_TYP_TYPE tables) database to get additional information.

The fields from SC300S job message is mapped to SCV replica TAG based message fields based on below mapping

CMD & Interface Field Mapping

Below are the tables and fields red by CMD MQ Push application

CMD/GEO Table.Field Name
C_ALT_CODE.GDA_DFND_AREA_ROWID
C_ALT_CODE.CODE
C_TYP_TYPE.CODE
C_GDA_DFND_AREA.ROWID_OBJECT
C_GDA_DFND_AREA.NAME
C_GDA_DFND_AREA.DESCRIPTION
C_GDA_DFND_AREA.TYP_TYPE_CD
C_GDA_DFND_AREA.ACTIVE_FLAG
C_GDA_DFND_AREA.NAME
C_PTR_CONT.prmry_email
C_PTR_ALT_CODES.CODE
C_PTR_ALT_CODES.CREATE_DATE
C_PTR_ALT_CODES.LAST_UPDATE_DATE
C_GDA_DFND_AREA_REL.Gda_Dfnd_Area_Prnt_Rowid
C_GDA_DFND_AREA_REL.Typ_Type_Cd

SCV Replica Solution Design on Cloud​

The below diagram shows the how the SCV replica solution needs to be implemented in modern platform without impacting the few SCV Replica consumers.

On modernization platform, below are the events on which the SCV message replication event should be triggered to publish the message to SCV consumers. These events should be identified by Ingest API or separate component to trigger the SCVReplicator java component.

  1. Normal Customer
    1. Create customer
    2. Update customer
    3. Inactivate customer
  2. Customer with contact
    1. Create Customer
    2. Update contact
    3. Add new contact
    4. Remove contact
    5. Inactivate Contact
    6. Reactivate Contact
    7. Inactivate customer having multiple contact
  3. Customer with web bl information
    1. Create Customer with WEB BL information
    2. Update customer Web bl information
    3. Inactivate customer having WEB BL
  4. Customer with CBU information
    1. Create Customer with CBU information
    2. Remove CBU information
    3. Update CBU information
    4. Inactivate customer having CBU
  5. Customer with Customer relationship
    1. Create customer with customer relationship
    2. Remove customer relationship
    3. Inactivate customer having customer relationship
  6. Create Customer contact with Communication preference information
    1. Create customer
    2. Add contact
    3. Add communication preference
    4. Remove communication preference
    5. Inactivate customer

EMP Publish services:

EMP publish services (Customer, Contact, Concern & Customer Facility) needs to be developed/updated to include additional fields which are missing in the current version of the AVRO schema which are required for SCV Replica consumers.

  1. Respective entity JSON object will be generated along with additional fields required for SCV replica
  2. Using GEO APIs, get the country, state, city codes as applicable

The EMP publish services AVRO message structure if already defined and might need to be enhanced with additional fields required for SCV replica.

TBD

CityGeo exception will not occur on modern platform as GEO application will provide all GEO Ids.

SCVPush Java component Logic:

SCVPush is an existing Java component needs to be refactored to consume JSON message from On Ground EMP topic replicated from cloud EMP topics instead of XML message. Below are key points:

  1. Existing CMD MQ Push application will be refactored to consume JSON message from On Ground EMP topic replicated from cloud EMP topics instead of XML message.
  2. Extract the data elements from JSON message and map it to respective SCV specific TAGs mentioned in CMD & Interface Field Mapping page.
  3. Push the encoded (in TAG format) message to IIB to push further to SCV consumer specific MQs.
  4. Each entity message is processed independently and each entity message should have all required data elements as part of the message.
  5. Deploy the application on-prem Weblogic server.

Sample output message from SC300S Job (On-Prem)

`<?xml version="1.0" encoding="UTF-8" standalone="no"?>`
<CUSTOMER
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ACTION &gt; UPDATE</ACTION>
<SEQUENCENO &gt; 88223</SEQUENCENO>
<ORGDETAIL>
<CUSTNO1>
<CUSTNO &gt; 11700187045</CUSTNO>
<COUNTRYCODE &gt; 117</COUNTRYCODE>
<CUNAME &gt; ACCENTURE 001</CUNAME>
<CNSTATUS &gt; ACTIVE</CNSTATUS>
<CNTYPE &gt; 1</CNTYPE>
<LEGACYCUSTNO &gt; IE00187045</LEGACYCUSTNO>
<LEGACYSYSTEMID &gt; 1</LEGACYSYSTEMID>
</CUSTNO1>
<CNACCOUNTGROUPID &gt; 2</CNACCOUNTGROUPID>
<CSHORT &gt; ACCENTURE </CSHORT>
<AFFILIATEID &gt; 1</AFFILIATEID>
<AFFILIATEID &gt; 2</AFFILIATEID>
<AFFILIATEID &gt; 5</AFFILIATEID>
<AFFILIATEID &gt; 6</AFFILIATEID>
<AFFILIATEID &gt; 7</AFFILIATEID>
<AFFILIATEID &gt; 8</AFFILIATEID>
`<GEO\_REGION\_ID > 0000000000048</GEO\_REGION\_ID>`
<LANGUAGEKEYID &gt; EN</LANGUAGEKEYID>
`</ORGDETAIL>`
`<LOCDETAIL>`
`<CUSTNO2>`
<CUSTNO &gt; 11700187046</CUSTNO>
<COUNTRYCODE &gt; 117</COUNTRYCODE>
<CUNAME &gt; ACCENTURE 001</CUNAME>
<CNSTATUS &gt; ACTIVE</CNSTATUS>
<CNTYPE &gt; 2</CNTYPE>
<LEGACYCUSTNO &gt; IE00187046</LEGACYCUSTNO>
<LEGACYSYSTEMID &gt; 1</LEGACYSYSTEMID>
`</CUSTNO2>`
<STREETNAME &gt; GRAND CANAL SQUARE</STREETNAME>
<STREETNO &gt; 1</STREETNO>
<ALINE2 &gt; GRAND CANAL HARBOUR</ALINE2>
<ALINE3 &gt; 2 DUBLIN</ALINE3>
<CITYGEOID &gt; 1JKROT9381ABJ</CITYGEOID>
`</LOCDETAIL>`
<LKSTATUS &gt; ACTIVE</LKSTATUS>
<PHONE &gt; 353-0000000000</PHONE>
`<EMAIL>`Standard@pilot.com`</EMAIL>`
`</CUSTOMER>`

Questions/Points to be relooked into to clarify

  1. For Location (Customer Facility) few fields like customerNumber,name,countryCode,customerType,status,createTimeStamp,countryGeoId,locationCode,createByUser,updateByUser,addressName,zipCode,zipGeoId,zipCity are missing in EMP publish facility we need to include them to send SCV replica. OR we need to verify that these fields are really required to send.
  2. There are around 20 attributes which we need to check whether these fields are required or we can skip them. Need to analyze, If required how to get them. These fields are listed in filed mapping page.
  3. In existing MQ PUSH application, we are using few tables CUSTOMER_ACTION_HIST, CBU_ACTION_HIST, CMD_MQPUSH_FAILED_MESSAGES, CMD_MQPUSH_MESSAGES, CMD_MQPUSH_PARKED_MESSAGES etc in MD schema. In modernization solution where we need to keep these tables? Are these tables really required now?
  4. In SC300S job, we need to check and implement logic related to below items:
    1. CityGeo Exception logic
    2. How AFFILIATEID Ids are getting generated
  5. Need to update MQ PUSH application to consume messages from respective topics and deploy it in Weblogic server.

CMD and RKTS Integration

In existing on-prem system rkts07-integration application will convert the SC300S XML message into RKTS tag based message format and push into MQ and from there RKTS application will consume the data.

In modernization, CMD will publish the messages into EMP topic on cloud and from there messages will be replicated to ground by EMP. The messages from ground topic will be consumed and converted to RKTS tag based message format.

The below diagram shows the how the RKTSPush solution needs to be implemented in modern platform without impacting the RKTS application.

Below table shows field mapping and transformation logic from CMD to RKST. This is not fully completed, needs to be mapped all fields.

CMD EMP FieldsTransformation LogicRKTS FieldsDefault Value
MESSAGE_IDSCVFE001
VERSION1
Current DatetimesendTimeNow
Get Previous time from config filesendTimePrevious
TAG_IDTAG001
externalSystemReferenceexternalSystemName=SCVcustomerNumber
tradingNamecustomerName
tradingNamecustomerAbbrName
apartmentOrFloor,streetNamecustomerAddress1
streetNumber,subArea,district,cityNamecustomerAddress2
regionCode,postalCode,isoCountryCodecustomerAddress3
customerAddress4
zipCode
regionCodestate
linkPhoneNumber
LINK_EXPORT_FAX
telefax
concernCode
vipNonRollvipClass
EDI_SYSTEM
MSL_EXPORT_SALES_CODE
FORWARDERS_BROKER
FORWARDERS_COMMUNICATION
ORG_BROKERAGE
orgFmcCode
EMPLOYEE_CODE
BUREAU_OF_CONSENSUS_AUTHORIZED
EXCLUDE_FORWARDER
EXCLUDE_BROKER
LOCAL_MARK
identifierValueidentifierType=TAX, identifierCodetaxReference
PREPAID_PAY_AT_PORT
COLLECT_PAY_AT_PORT
PREPAID_PAYER
COLLECT_PAYER
LINK_IMPORT_FAX
MSL_IMPORT_SALES_CODE
SCL_EXPORT_SALES_CODE
SCL_IMPORT_SALES_CODE
locAddressName
locPoBoxNumber
locStreetName
locStreetNumber
locAddressLine2
locCityCode
locAddressLine3
ACTION1
Was this page helpful?