Document revision 1.0
Contents Installing the Application... 3 Basic Setup... 4 Lightning New/Edit Page Configuration... 6 Lightning App Page Configuration... 8 Standardization Options... 12 Enabling and Configuring Standardization... 12 Validation Options... 15 Enabling and Configuring Validation... 15 Org-Wide Activation... 15 Address Block Settings Configuration... 16 Country Specific Settings Configuration... 17 Validate ZIP Code Pattern... 19 Custom Address Block Configuration... 20 ZIP Codes Lookup... 23 Enable ZIP Codes Lookup... 23 QuickComplete Country... 25 Enabling and Configuring QuickComplete Country... 25 Other Settings... 28 Security & Permissions... 29 Help & Support... 30 Page 2 of 30
Installing the Application The following steps assume that you are installing AddressTools either from the AppExchange Get it Now button, or via direct link provided to you by ProvenWorks. On the installation screen, choose who you want to install AddressTools for. When the option is selected, press Install. Note: If Install for Admins Only or Install for Specific Profiles is chosen, see Security & Permissions to view the permissions that require alterations to allow users access AddressTools functionality. Next, tick Yes, grant access to these third-party web sites and select Continue. The application will now be installing into your Salesforce environment; you will receive an email once this process has completed. Page 3 of 30
Basic Setup Once installed, navigate to the Salesforce App Launcher Administration under All Items. and then select AddressTools You are required to add the Salesforce Metadata API to your remote site settings, so start by selecting Create Remote Site Setting. All the settings will be pre-filled so simply select Save to confirm. Page 4 of 30
Once the Remote Site Setting has been saved, open the Salesforce App Launcher then select AddressTools Administration under All Items. and Select Install Defaults to install the latest Country, State and Zip code data as well as configure the basic default setting within the package. The data will now download and install into your Org, this process can take a few minutes so why not grab a coffee? Once complete, you will be notified on screen. Be sure to clear your browser s cache once the process has completed if you re still planning to use Salesforce Classic. Press OK to dismiss the message. Page 5 of 30
Lightning New/Edit Page Configuration AddressTools functionality can be supported on any Salesforce New/Edit page (and detail, but we ll show that later!). After installing defaults, the package is configured to support Accounts, Contacts, Contracts and Leads. The following steps are to demonstrate the configuration on the Account object, but the process is the same for all. Note that My Domain must be enabled and deployed to your users to take advantage of Managed Lightning Components. Navigate to Setup and select Object Manager. Once the page has loaded, select the object you want to enable the functionality on by clicking the Label. From the sidebar, choose Buttons, Links and Actions, then scroll to locate New. Once found, click Other Options and then select Edit. Page 6 of 30
In the Lightning Experience Override section, select Lightning component and choose pw_ccpro:addresstoolsoverride from the dropdown. Then press Save to confirm the change. You now have all the AddressTools functionality available at point of record entry. You can repeat the above steps for the Edit button, but it must be noted that overriding an edit button in your Salesforce Org will remove inline edit functionality on the detail component for that object on the Record App Page. If inline editing is something you want to keep available, then move on to the next step which shows how to place the AddressTools component onto your Record App Page. If this isn t something that concerns you, then feel free to override the Edit button and then continue through to the next steps. You will now notice AddressTools functionality on any of the New/Edit pages you have configured. Page 7 of 30
Lightning App Page Configuration AddressTools also supports Lightning App Pages with the AddressTools App. You can place this on any of your configured objects to edit addresses on the fly with our interactive functionality. Navigate to Setup and select Object Manager. Once the page has loaded, select the object you want to enable the functionality on by clicking the Label. Select Lightning Record Pages and press New to configure a new record page, alternatively if you already have a custom record page, select its label and press Edit. Page 8 of 30
Select AddressTools Component from the Lightning Components list on the left of the screen and drag the component to your desired location on your page layout. The AddressTools Component has two custom design parameters for configuring on the right side of the screen: 1) Address block (required) For selecting the address you want to display on your page. You can add multiple AddressTools components to your layout allowing you to display multiple addresses. Ensure that you have configured the address block in the Fields to Validate/Standardize settings before this step. 2) Component header title The text field allows you to change the default text displayed on the component. Note: you can use Add Filter to create rules for when the component is visible. i.e hide if country is empty. Page 9 of 30
Once your component s parameters have been populated and you re happy with its position, press Save at the top of the page. If the page you have saved is not yet active in your Org, you will receive a prompt asking you to activate it. Select Activate. You can assign your page based around different levels. For this example, we will set the Org Default by pressing Assign as Org Default but you can select the different tabs and follow the steps based on your requirements. Page 10 of 30
Review your page assignment changes and when you re happy, press Save. Once saved, press Back to exit the App Builder page. Now when you go to view a record in your Org with the AddressTools Component configured, you will be able to see it in action! Note: Validate button and Address Status will only be visible when Premise-Level Address Validation is enabled within your Org. Page 11 of 30
Standardization Options AddressTools has the ability to standardize the values entered in the country and state fields on records being created and updated, this includes data being imported through your desired data loading solution such as SimpleImport! This ensures that all country and state values are unified. For example, if US or USA is entered, the value will be automatically saved as United States (The full ISO name), or vice versa. Enabling and Configuring Standardization Navigate to the Salesforce App Launcher and then select AddressTools Administration under All Items. Once loaded, select the Settings sub-tab. Check Standardization Enabled to activate the standardization functionality and then choose the desired option of either Name, ISO-2 and ISO-3 from the Store country value as picklist. Select Save All to store the settings. Note: an AddressTools trigger must be enabled on the configured object(s) for standardization to run on insert/update. Page 12 of 30
Scroll down the page and locate Fields to Validate/Standardize. Select Edit on the row of the address block that you want to configure validation for. Note: You can determine the address block by reading the object name country field. By default, all Account, Contact, Contract and Lead address blocks will be configured. Locate Global Settings and use the check boxes for Standardize Country and Standardize State to enable your desired standardization for the address block. Select Save to confirm the changes. Repeat the above step for each address block in the Fields to Validate/Standardize section to control the behavior across all your objects. Page 13 of 30
States have the option to be stored as their Full Name as well as their ISO-2 value. This is handled on per country basis allowing users to choose what format they want stored for different countries. To switch between Full Name and ISO-2, navigate to the Salesforce App Launcher then select Countries under All Items. and Find the Country Record that you wish to alter, click Other Options Edit. and then select Enabling the Use Subcountry Code in State field will store the value in it s ISO-2 format and disabling this will store the values in their full names. Select Save to confirm your changes. Once all the above settings have configured, enabled and saved, you will now see the Country and State standardization happening every time you save a record ensuring much cleaner address data! Page 14 of 30
Validation Options AddressTools comes packed with a handful of different validation settings that allows you to have customizable control over all your addresses, whether it be fields being mandatory, or to ensure that only states belonging to their correct country are stored! These validation rules can be configured so that at any data entry point, the records will be validated before insertion. Enabling and Configuring Validation Validation configuration is a three step process: 1) Org-Wide Activation 2) Address Block Settings Configuration 3) Country Specific Settings Configuration Org-Wide Activation Navigate to the Salesforce App Launcher and then select AddressTools Administration under All Items. Once loaded, select the Settings sub-tab. Check Validation Enabled to activate the validation functionality and then select Save All. Note: an AddressTools trigger must be enabled on the configured object(s) for validation to run on insert/update. Page 15 of 30
Address Block Settings Configuration Navigate to the Salesforce App Launcher and then select AddressTools Administration under All Items. Once loaded, select the Settings sub-tab. Scroll down the page and locate Fields to Validate/Standardize. Select Edit on the row of the address block that you want to configure validation for. Note: You can determine the address block by reading the object name and country field. By default, all Account, Contact, Contract and Lead address blocks will be configured. Locate Global Settings and Country Specific settings and use the checkboxes to toggle the validation behavior you require on the address block. If you re unsure what any of the features do, you can hover your cursor over the tooltips for more information. Press Save to confirm your changes. Repeat the above step for each address block in the Fields to Validate/Standardize section to control the behavior across all your objects. Page 16 of 30
Country Specific Settings Configuration The country specific settings allow you to configure the validation rules that you have set on your address blocks on a per country basis. For example, if you d like state to only be mandatory when the country is United States. Navigate to the Salesforce App Launcher and then select AddressTools Administration under All Items. Once loaded, select the Settings sub-tab. Scroll down the page and locate Country Specific Settings. There are eight dueling picklists, seven of which relate to validation configuration. You can use the arrows provided to Add or Remove the countries from one list to another to configure AddressTools to meet your requirement. All validation related option and descriptions can be seen below: 1) Allow only listed states means that only values on the state object can be saved into the state field for that specific country. Additional state values can be added to the pick-list by visiting the properties page for the corresponding country. 2) State is mandatory means that a value must be enter into the state field when the country is chosen. 3) City is mandatory means that a value must be enter into the city field when the country is chosen. 4) Street Line 1 is mandatory means that a value must be enter into the street line 1 field when the country is chosen. 5) Street Line 2 is mandatory means that a value must be enter into the street line 2 field when the country is chosen. Page 17 of 30
6) Validate ZIP code pattern means that the zip-codes of these countries must validate against a regular expression. Once you have added a value to the list click edit in the bottom Validate Zip Code Pattern section to add a custom regular expression. 7) ZIP code is mandatory means that a value must be enter into the zip code field when the country is chosen. When happy with your Country Specific Settings, select Save All. Page 18 of 30
Validate ZIP Code Pattern If you are using Validate ZIP Code Pattern, you can configure the RegEx at the bottom of the Settings tab as well as create your own error messages that are displayed to your users if they enter an invalid ZIP Code. Navigate to the Salesforce App Launcher and then select AddressTools Administration under All Items. Once loaded, select the Settings sub-tab. Scroll to the bottom of the page and select Edit next to the country you want to configure. Note: You must add the countries to the Validate ZIP Code Pattern list shown in the previous step for the country to appear in the above list. Once in the ZIP Code Regular Expressions editor, you have the option to change the Fail message as well as the Regular expression to meet your requirement. Once happy with your changes, press Save. Page 19 of 30
Custom Address Block Configuration On installation, AddressTools will configure Account, Contact, Contract and Lead address blocks. AddressTools Premium allows you to also configure custom objects and custom fields. Navigate to the Salesforce App Launcher and then select AddressTools Administration under All Items. Once loaded, select the Settings sub-tab. Scroll down the page and locate Fields to Validate/Standardize. Select Add to add a new address block or press Edit next to an already existing block if you wish to make changes to it. For this example, we will configure a Custom Object named Location. Start by choosing the Object and then Record Type if applicable. If you do not choose a record type, the settings will be followed on all record types for the object. Note: The Record Type field will be hidden if Record Types are not configured for the object. Page 20 of 30
After the object and record type has been selected, choose Fields from your org s object for each of the labeled fields. Field Mapping information: 1) Country Field Text field where the country value is entered 2) State Field Text field where the state value is entered 3) City Field Text field where the city value is entered 4) Street Fields (+) Text field where the street value(s) are entered. Press the green (+) for access to street line 2 entry 5) ZIP Code Field Text field where the ZIP/Postal Code value is entered 6) Address Status Field (Optional*) Picklist field containing the Premise-Level Address Validation status when Premise-Level Address Validation is in use 7) County Field (Optional*) Text field for being populated with the address subadministativearea when Premise-Level Address Validation is in use 8) Location Accuracy Field (Optional*) Picklist field containing the Premise-Level Address Validation accuracy when Premise-Level Address Validation is in use 9) Location Source Field (Optional*) Picklist field containing the Premise-Level Address Validation source when Premise-Level Address Validation is in use Page 21 of 30
10) Country Lookup (Optional*) Lookup field linked to the Country object which matches the Country Field entry allowing you to create formula fields against the country object to populate further country related data. 11) State Lookup (Optional*) Lookup field linked to the State object which matches the State Field entry allowing you to create formula fields against the State object to populate further State related data. 12) ZIP Code Lookup (Optional*) Lookup field linked to the ZIP Code object which matches the ZIP Code Field entry allowing you to create formula fields against the ZIP Code object to populate further ZIP Code related data. Note: If you have some users on classic, you will need to include Field IDs alongside the Field Names. Finally choose the appropriate settings in the Global Settings, Country Specific Settings and Premise-Level Validation Options for the address block. When complete, select Add & Save. Page 22 of 30
ZIP Codes Lookup AddressTools Premium provides your Org with US 5-digit ZIP Code reference data in the package. This allows for quick validation of US addresses and also provides users with the ZIP Codes Lookup feature! As you type your US ZIP Code into the address block, the State and City fields automatically populate or provide suggestions to your users if the Zip Code spans multiple cities. You will also be notified if the entry is incorrect providing suggestions for correction. This saves time and reduces user error! Enable ZIP Codes Lookup Navigate to the Salesforce App Launcher and then select AddressTools Administration under All Items. Once loaded, select the Settings sub-tab. Check Enable ZIP Codes Lookup and press Save All. Page 23 of 30
After confirming your changes, you will now be able to see the ZIP Codes Lookup functionality available on the address blocks of your configured addresses! Note: United States (or configured alternate country names) must be present in the Country field for the functionality to run. Page 24 of 30
QuickComplete Country Provide your AddressTools users with a super quick and easy link to a country of your choice saving them time at point of entry by just clicking the link instead of typing out the country each time! Enabling and Configuring QuickComplete Country Navigate to the Salesforce App Launcher and then select AddressTools Administration under All Items. Once loaded, select the Installation sub-tab. Choose a country from the picklist provided under QuickComplete Country settings and press Install to set this as the country for all users. If you d like to install a different QuickComplete Country for individual users, see the following: Navigate to Setup and select Users then Users. Once on the page, select Edit next to the user that you want to change the QuickComplete Country for. Page 25 of 30
Locate Additional Information and change the QuickComplete Country text field to the country of choice. Note: if the QuickComplete Country field isn t visible on the User page layout, add the field to the page by going Setup Object Manager User User Page Layouts Edit next to the page layout Drag QuickComplete Country onto the layout Save Layout. Select Save to confirm the change. With the country values now configured for your users, you must now activate the functionality. Navigate to the Salesforce App Launcher and then select AddressTools Administration under All Items. Once loaded, select the Settings sub-tab. Select Enable QuickComplete Country and press Save All. Page 26 of 30
Now when editing an address with the AddressTools override page or AddressTools app, your country will be available to press! Page 27 of 30
Other Settings 1) Run the AddressTools trigger to validate / standardize objects only once (useful if you have multiple triggers on validated objects) By default, the AddressTools Standardization and Validation will repeatedly execute on save until all operations are completed. This is to ensure that the changes it makes to your address data are confirmed. In most orgs, this won t cause any issues however if you have multiple different on-save operations executing, it is possible you will hit governor limits. If this is the case, you can check this option to only fire the AddressTools functionality once. This does mean that you cannot guarantee that it will be the last process to operate. As a result, if any of your other operations make changes to the address data, the standardization and validation changes may not be present. 2) Only standardize and validate when either Country, State or Zip is changed (existing invalid values will not cause an error) This setting is used to disable the AddressTools on-save functionality if no changes to address fields have been made. This allows existing records with bad data in your org to be edited successfully without hitting the AddressTools validation rules. Page 28 of 30
Security & Permissions During the installation process, selecting Grant access to all users is easiest. If this is not possible, granting access to admins only will prevent access to the AddressTools Administration, Interactive Batch Validation and Scheduled Batch Validation tabs for your users, but the core functionality of auto complete, standardization and field validation will still be available. To allow all functionality usage for all users, each user profile will require access to the AddressTools Apex Classes and the pw_ccpro SessionIdPage Visualforce page. This is not setup by default if you chose to install for admin only. You can manually add access to the Apex Classes in the Profile Setup. Navigate to Setup and select Users then then Profiles. Once on the page, select the Name of the profile that you want to allow access to the AddressTools Apex Classes. Scroll down the page to locate Enable Apex Class Access and select Edit. Add all of the Apex Classes with the pw_ccpro prefix to the right column. Select Save when complete. Next, navigate to to Setup and select Visualforce Pages. Find SessionIdPage and press Security. Add all necessary profiles to the Enabled Profiles list then select Save. Page 29 of 30
Help & Support If you have any problems with installation or configuration please get in touch with us via email at support@provenworks.com where a member of the team will be more than happy to assist you with your setup. Unsure of any of the AddressTools Premium features listed in the guide or unsure about a specific requirement you may have? Reach out to one of our team at info@provenworks.com and set up a demo as well as tell us about your requirements to see if we can help! Page 30 of 30