Once you have downloaded the Verify and Confirm Connector, and set up the credentials to enable the API, use this guide to configure the Nexus connector functions for address processing.
Introduction
The Verify and Confirm connector allows a Salesforce Administrator to link their addresses in Salesforce to a powerful CASS (Coding Accuracy Support System) and NCOA (National Change of Address) processing system powered by TEC Mailing Solutions. This functionality allows a Salesforce Administrator to check and change all the addresses in their Salesforce instance to ensure that they comply with Postal Address standards, and all the addresses have been confirmed against NCOA data provided by your customers. Over 100,000 people move every day in the United States - so it is important to continually Verify and Confirm that your addresses are correct.
The Nexus connector allows you as the administrator to set up a connection between any address fields you have in Salesforce (e.g. Account, Contact, or even custom objects with their own addresses). Once you have mapped the addresses you wish to send through the Verify and Confirm process, you can simply launch the function - and your addresses will be processed to update them for CASS accuracy and NCOA updates. You don't need to export/import or do any other data manipulation functions.
Function Overview
The Verify and Confirm capability requires initial setup by the TEC Mailing Solutions team. When you sign up for this service, the TEC Mailing team will configure a Userid and also create a PAF (Processing Acknowledgement Form). This form is required to confirm the ownership of a list of records that is being processed by the US Postal Service. You will notice this form being referenced in later setup information - as your Salesforce list process must be accompanied by a PAF to certify authenticity as it is processed by the USPS.
Once you have established your setup with TEC Mailing Solutions, you will receive your welcome email to install the Nexus Connector for Salesforce. Note that after you have set up your account with TEC Mailing, you will receive API credentials (Username, Password, Database ID). You will need to input these into the Credentials section of the Nexus setup screens. Choose the 'View Connector Credentials' from dropdown arrow of the connector on the Nexus Admin main page, and from there select 'View Connector Settings' for the 'Default' credential.
You will always enter 'PROD' for the Processor Environment unless otherwise instructed by someone from TEC Mailing or IOLITE. Complete the additional fields with the account setup information received from TEC Mailing and save.
Setup Options and Considerations
When you are correcting addresses - you can choose one of two methods of managing addresses - either a direct overlay of corrections, or a collection of changes into separate fields, and then manually updating the records after a review.
Depending on the options you choose, you may need to set up additional fields to receive the returned data from TEC Mailing Solutions. It is highly recommended that you enable History Tracking on the object so that you can see what updates have been made.
There are a couple of considerations for how the Verify and Confirm process works that require special setup of some fields. There are special handling data fields that need to be set up:
- Address data is returned from TECMailing in separate fields: Primary Address, Secondary Address, City, State, Zip and Zip4. Salesforce requires all of this data to be updated into a single Address data block field - which means that all this data must be individually captured, and then concatenated and stored into the Salesforce Address data block.
- TECMailing does not support view of data that is not housed on the object that you're mapping to. So - if you are referencing data that is not on the Contact object (which is the Base object in our examples), you will need to create formula fields and/or Flows to move the data onto the Base object. This consideration is not an issue if all data is contained on your Base record.
In addition, there are some supplemental fields that are returned from TECMailing that may be of value: Congressional District, County, Federal Information Processing Series Code (FIPS Code - which can be decoded into the Metropolitan Statistical Area <MSA> for which the address is part of).
Finally, there are also some status fields that need to be created so that the status/error codes on each record can be returned. We also are suggesting a Checkbox field that can be used to determine if a change was detected on a record (this sample formula is shown using the Mailing address on Contact). This field is optional.
Before starting - it is recommended that you create the following fields on your Base record:
Address Fields:
| TEC_Primary_Address__c | Text(255) |
| TEC_Secondary_Address__c | Text(80) |
| TEC_City__c | Text(255) |
| TEC_State__c | Text(80) |
| TEC_Zip__c | Text(10) |
| TEC_Zip4__c | Text(10) |
Supplemental Fields:
| TEC_Congressional_District__c | Text(40) |
| TEC_FIPS_Code__c | Text(10) |
| TEC_County__c | Text(80) |
Status Fields
| TEC_COA_Record_Code__c | Text(40) |
| TEC_Dupe_Group__c | Text(10) |
| TEC_Dupe_Status__c | Text(5) |
| TEC_Status__c | Text(40) |
Change Detection
| TEC_Change_Detected__c | Formula(Checkbox) <Optional> |
IF(OR(LOWER(SUBSTITUTE(MailingStreet, ',', '')) <> LOWER(TEC_Primary_Address__c & IF(ISBLANK(TEC_Secondary_Address__c),'',' '&TEC_Secondary_Address__c) ), LOWER(MailingCity) <> LOWER(TEC_City__c), LOWER(MailingState) <> LOWER(TEC_State__c), MailingPostalCode <> TEC_Zip__c & '-' & TEC_Zip4__c), true, false) |
Implementation Strategy
Once you have chosen a method for how you want to manage address updates (either Option 1 - direct update, or Option 2 - indirect storage of the updates with a review), and once you have defined the processing fields on your Base record, you can proceed with mapping.
Depending on which edition of Salesforce you have, there are a few considerations for managing the updates.
NonProfit Edition:
In the Non-Profit edition, there is a child address object called npsp__Address__c. This address can be created and then marked as default. If you wish to create a new Address child record if there is a change detected, you can set up a flow to create this record. The conditions for triggering this flow are as follows: TEC_Status__c field starts with "S" - which indicates a successful response from TECMailing, and the TEC_Change_Detected__c Checkbox has been evaluated to TRUE (Checked). The flow needs to create this new Address record in the NPSP edition, and mark that address as the default address, and set the "verified" flag to true. Note that in this flow - any record that does not have the TEC_Status__c field populated will be ignored. Also note that this flow would create a new Address record, but does not delete the prior address record - so that if desired - the record can be reverted to the prior value.
Standard Salesforce Editions:
The TEC_* fields that you have created on the record will house the "corrected" addresses from TECMailing. If you wish to "archive" your prior version of address, you should create some "Prior Address" fields, and use a flow to copy the current address fields to this prior address fields. Note: this may not be required if you are satisfied with enabling History Tracking on the object.
If you only update the standard address fields with the TEC fields, you can use a flow to accomplish this.
Note: Primary/Secondary Address and Zip/Zip4 fields must be concatenated to create the proper Salesforce Address block format.
Configuring the 'Process Address List' and/or 'Submit Order' Outbound Data Event
You will be required to set up either 'Process Address List' if you are processing only a small subset of records, and/or 'Submit Order' and 'Get Order' asynchronous functions for larger lists. Since larger lists take longer to process through the back end system, using Submit Order will help to avoid timeout errors with the API. You can always process smaller lists using the async functions, so that is generally the preferred method.
The Process Address List function contains both Outbound and an Inbound Data Events. The Submit Order function only contains an Outbound Event while the Inbound Event is mapped in the Get Order function configuration. The mappings steps will be the same, just split up between the two functions.
This outbound Data Event is mapped to the Salesforce location that you want to SEND your addresses from.
Select the View Data Events menu option on the Process Address List or Submit Order connector function.
Once you have selected this Function, choose the Outbound Data Event and select Record Details. This record will be identified as a "Base Object Only" Data Event:
Next, select the Object you wish to select your Addresses from. Configure this Object in the Objects tab. In this example, we are connecting the Mailing Addresses from the Contact object - and these fields will be mapped into the Outbound message. Enable this object for selection by performing Create New Data Event Object
Input the Object API Name. Remember that Standard Salesforce objects API names are just the object name, while custom Salesforce object API Names end with "__c". Choose the Data Event Object Type of "Base". The Data Event Object Label will autopopulate.
Once you have selected the Base object (in this case Contact), then navigate to the Fields tab to map the fields you wish to send in the Outbound message:
Select and expand each field in the Data Event Field Map and assign the appropriate Salesforce field to the data:
Repeat for each item in the list.
Next, navigate back to the Data Events for the Inbound Data Event
Configuring the 'Process Address List' and/or 'Get Order' Inbound Data Event
Similarly, the Inbound Data Event (the returned message from address processing), is a 'Base Object Only" mapping. However, you will need to map the fields into the "TEC_*" fields you created on the Base object.
Configure the Inbound Data Event Details as follows: (Base Object Only)
Select your Object. In our example - we are putting the data back into the same Contact object from which we sent it. Adjust the object you wish to map the return data into accordingly.
Finally, update the Fields that you wish to receive the response data into. This should be the TEC_* fields that you created earlier.
Configuring the 'DownloadFile' Data Event
DownloadFile is primarily pre-configured, however you will need to create the Data Event Object for it to work. First off, select 'View Data Events' from the DownloadFile function...
and click on 'Record Details'...
From the Objects tab, create a new Data Event Object and enter 'inxs__Request_Message_Detail__c' as the object name and choose 'Base' as the object type. Accept the default label and save. There are no fields that will need to be mapped, so you can return to the List and then the Functions List when finished.
Activating the Connector Functions
Once Object and Field mapping is complete, and you have returned to the Function List, choose the 'Edit Connector Function' option from the dropdown menu on each item. This is where you will set the Credentials, Profiles and Activate each of individual functions so they can be used.
You will also want to select the 'Include in Execution Manager' option for the 'DownloadFile' function. This will make it available to use from the Request Message Details records.
If you plan on using the NCOA option, you will need to also activate the 'GetPAFs' function so you can retrieve your available PAFs from the List Builder page before executing an order.
Async AutoRun Enablement
When utilizing the asynchronous SubmitOrder/GetOrder functions, Nexus has the ability to create a job in Salesforce (called an Enqueueable class) that will automatically trigger the inbound GetOrder process after allowing some time to pass after the outbound SubmitOrder process has completed. This will be flagged in the Request Message Status as a 'Long Running Process'.
You will need to map and activate your GetOrder Connector Function for it to be visible as a an AutoRun option. You can then edit your SubmitOrder Connector Function and make the selection. This is particularly useful if you are getting address from different objects. For example, you may want to process addresses from both Account and Contact. Using the Clone Connector Function option in Nexus and doing separate mappings for each object will give you this option.
To maintain manual handling of the asynchronous function, choose the 'None' option. The SubmitOrder will be marked as 'Complete' in Request Message.
IMPORTANT: Use caution when choosing an inbound function. Selecting a function mapped to a different object type will likely result in conflicts with matching Salesforce Record Ids in the Upsert process and new records being created on the inbound object. Use the 'Event Name' when naming your clones functions to help identify which async functions go together. The AutoRun dropdown will show the Inbound Async function Event Name to ease this selection.
Troubleshooting
If there are any issues with the TEC Mailing process - you can review the Request Messages tab in the Nexus Application. Navigate to the IOLITE Nexus Application, and click on the Request Messages <All view> tab. Review the status indicator on each message.
One condition that can occur is the processing of a file that has hidden Carriage Return/Line Break items inside of it. You can check for this error if the TECMail process appears to not execute. Check the Request Messages, and if the Status is "Error" and the Message Detail includes the words "File Load Processing Error", it is likely that the file you submitted had these hidden characters in it.
To check this, you can look at the file that was built and submitted to TEC Mailing. To do this, Select the Request Message that was in error and scroll to the Files section. The submission file will be the CSV formatted file that was automatically saved. Click on this link and select select the download option.
To confirm if this file had unwanted Carriage Return/Line Feed inside of it, you need to open this .csv file with Notepad/Text Edit (or equivalent text editor). When you open in this text editor, you need to scroll through the entire file to see if any records have a line break in an unnatural position. If so, you can use the Salesforce Id to find this record and edit it to delete the hidden characters or line breaks.
Understanding the TecMailing Status Codes
If the file processes completely - it will return TEC_Status__c indicators. Typically if the Status begins with "S", the record was successfully processed. If the Status begins with "E", the record was not successfully processed. Use this table to review details about the reason the record was not successfully processed: