PolicyMap for Salesforce: Technical overview

Updated by PolicyMap

PolicyMap for Salesforce allows Salesforce users to integrate location-based data provided by PolicyMap with their Salesforce records and view their records on a mapping application.

Features

  • Import PolicyMap data into Salesforce.
  • View PolicyMap data along with Salesforce record data on record pages, in reports, and on a map.

Users

PolicyMap for Salesforce relies on two permissions sets: PolicyMap Admin and PolicyMap User. PolicyMap Admin users may import PolicyMap data into Salesforce. PolicyMap Users may view the data but not import it. Because the data import process requires the ability to update org metadata, we recommend assigning the PolicyMap Admin permission set to a System Administrator user.

Custom Objects

PolicyMap data is imported into custom object records. These objects contain a lookup field to associate the PolicyMap data record with a Salesforce standard object record. For instance, importing PolicyMap data for Account records will add fields to the PolicyMapData_Account__c object and populate a PolicyMapData_Account__c record. These fields contain the data values from PolicyMap that correspond to the Billing or Shipping Address field of the Account record referenced in the Account__c field. No modifications are ever made to the Account record itself.

The custom objects that contain PolicyMap data are:

  • PolicyMapData_Account__c
  • PolicyMapData_Contact__c
  • PolicyMapData_Lead__c

Other custom objects:

  • PolicyMapScheduledJob__c contains information about scheduled update jobs.
  • PolicyMapFieldDetail__c contains additional information about each PolicyMap data field that can’t be accommodated in the field definition.
  • PolicyMapDataRequestDetail__c contains information about the content and status of data requests made to PolicyMap. An external id corresponds to request information stored at PolicyMap.
  • PolicyMap_Settings__c contains the PolicyMap Admin user’s selections of which records to populate with PolicyMap data. The app uses only the org defaults, as data is shared between all PolicyMap users.

Components and Pages

  • The PolicyMap Administration and Settings page is a Lightning page that contains the following Admin-only components:
    • Set PolicyMap data and geocoding specs is where PolicyMap Admin users specify which Account, Contact, and/or Lead records to retrieve PolicyMap geocode and location data.
    • Import and Organize PolicyMap Data is where PolicyMap Admin users choose which PolicyMap data to import, as well as set the order in which the resulting field data will display on single record pages.
    • View data import status is where PolicyMap Admin users can track the status of PolicyMap imports from inception through initiation of a Bulk Data Load 2.0 job.
    • Set update schedule allows PolicyMap Admin users to schedule automatic PolicyMap geocode and data updates for new records and records with changed addresses.
  • The PolicyMap Data component is a Lightning Web Component available on record pages for Account, Contact, and Lead. The component includes a list of tiles containing PolicyMap data associated with the current record, viewable by both PolicyMap User and PolicyMap Admin users. PolicyMap User users may retrieve PolicyMap data for a single record only.
  • The PolicyMap Related Record component is a Lightning Web Component available on all record pages. When adding this component to a page, the user chooses a lookup field for Account, Contact, or Lead records. The component will then display a list of tiles containing the PolicyMap data associated with the record referred to in the specified lookup field for the current record.
  • The PolicyMap Locator component is an Aura Component available on record pages for Account, Contact, Lead, and Opportunity. When adding this component to a page, the user chooses an address available to the object (if there is more than one option). The component then displays a small PolicyMap page in a Canvas app showing the record location, with a link to the PolicyMap map page.
  • The PolicyMap page is a Visualforce page containing a full-size PolicyMap page in a Canvas app and Lightning Web Components. Users may view Salesforce record locations on the map alongside PolicyMap data layers and point datasets. Salesforce records for each standard object are limited to 20,000 points for performance and viewability. Filters are available to control which records show on the map.
  • The PolicyMap folder in Reports contains reports you can use to identify addresses in your records that PolicyMap was unable to locate.

How Salesforce and PolicyMap connect

PolicyMap stores PolicyMap for Salesforce customer org IDs in its database in order to associate each org with the data available to the customer and provide customer-specific features. Only orgs known to PolicyMap have access to any PolicyMap features.

Canvas App: Signed Request

As a post-installation step, System Administrators are instructed to modify the PolicyMap Canvas Connected App policies to “Admin-approved users are pre-authorized”, and to add the PolicyMap Admin and PolicyMap User permission sets.

The PolicyMap page and the Locator components embed a PolicyMap page into Salesforce using the PolicyMap Canvas app, which uses Signed Request authentication. The Canvas’s url is a PolicyMap endpoint rather than the application page itself. The PolicyMap service parses the signed request and redirects the Canvas page to the application once it has verified that the request came from a PolicyMap customer org.

When users display Salesforce record data on the map, they choose which standard and PolicyMap fields will show. Salesforce publishes these field values, along with the location values, to the canvas as GeoJSON. The PolicyMap application then displays the GeoJSON on the map. This data is not added to PolicyMap’s database or retained in any way.

Requesting Data Import: Named Credential

Salesforce calls the PolicyMap endpoint using a Named Credential. The first time a PolicyMap Admin user launches the PolicyMap Data View and Import component, the component prompts them to complete setup by pressing a button. Completing setup populates the External Credential Principal with Basic Authentication credentials to access PolicyMap endpoints. The function that populates the credentials accesses the values from records of a package-protected custom metadata type. These credential values are not otherwise accessible.

Each callout to PolicyMap includes user and org information retrieved using Apex and passed as POST data. PolicyMap uses the POST data to both deliver a customer-specific response and also to authenticate with Salesforce using JWT (see below). Therefore, the External Credential serves only to gain access to this subsequent identification process and does not provide all that is needed to access PolicyMap data.

PolicyMap_Services endpoint: https://www.policymap.com

The POST data sent with every request:

  • User ID
  • Org ID
  • Login URL
  • Org Domain URL

The PolicyMap Data View and Import component initiates the following callouts through the Named Credential (full callout documentation):

  • callout:PolicyMap_Services/s/?act=ind
    Upon loading the import form, retrieves the data layers and time frames available to the customer. The result populates the Layer and Year combo boxes.
  • callout:PolicyMap_Services/s/?act=def&ii=[layer ids]&tfi=[time frame ids]
    Upon selecting a time frame, retrieves the geographies available for the data layer and time frame selected in the Layer and Year combo boxes. The result populates the Geography combo box.
  • callout:PolicyMap_Services/s/?act=ic
    Upon clicking the Get PolicyMap data button, POSTs the data request selections as JSON to PolicyMap. The result is a request identifier.
  • callout:PolicyMap_Services/s/?act=il&sfri=[request id]
    Upon receiving the request identifier from the previous call, initiates a Batch Apex job to provide record locations to PolicyMap. Each batch POSTs its records' ID, along with the longitude and latitude values of the user selected address. No other record data is sent to PolicyMap. (Note: we are considering, in a future version, also sending other Address fields so that we can provide our own geocoding when necessary.) Location batch data is transmitted to Amazon S3 and subsequently stored in PolicyMap’s database during data compilation, then deleted.
  • callout:PolicyMap_Services/s/?act=ie&sfri=[request id]
    Upon batch finished, notifies PolicyMap that the locations are provided, triggering PolicyMap to compile the requested location-based data.
  • callout:PolicyMap_Services/s/?act=c
    Upon loading the import form and on subsequent refreshes triggered by the user or platform events, retrieves a list of data requests both in progress and completed.
  • callout:PolicyMap_Services/s/?act=d&sfri=[request id]
    Upon user interaction, deletes a data request. If it’s in progress, it will also abort the request. If it’s completed, it merely removes it from the list.
  • callout:PolicyMap_Services/s/?act=dc
    Upon user interaction, deletes all completed requests from the list.
  • callout:PolicyMap_Services/s/?act=si
    Upon user interaction, retrieves location-based data from PolicyMap to populate existing fields for a single record. This callout is initiated in the data table view and is the only callout that may be initiated by a PolicyMap User. This allows a user to retrieve data for a record that they added themselves.

See full callout documentation at https://documenter.getpostman.com/view/39830323/2sB2qfAz68

Executing Data Import: External Client App

As a post-installation step, System Administrators are instructed to modify the PolicyMap Services External Client App policies to “Admin-approved users are pre-authorized”, and to add the PolicyMap Admin permission set.

The PolicyMap Services External Client App uses JWT authentication to allow the PolicyMap application to make REST API requests to PolicyMap. PolicyMap makes the following requests to Salesforce:

  • PolicyMap requests user info after JWT authentication.
  • Upon compiling data for a location-based data request, PolicyMap uses a Composite Tooling API request to create custom fields on the appropriate PolicyMapData custom object to contain the new data.
  • After creating the custom fields, PolicyMap uses Bulk API 2.0 requests to initiate an ingest job to import the new data into the appropriate PolicyMapData custom object.
  • Periodically, PolicyMap uses Rest API to send a custom Platform Event to trigger a refresh of the requests table in the PolicyMap Data View and Import component.

The data import process

When a user completes the form to import PolicyMap data into Salesforce, this process is initiated:

  1. Salesforce sends PolicyMap the an object containing the PolicyMap data specifications. PolicyMap sends back a Request Id.
  2. Salesforce initiates an Apex Batch job that queries the specified records for Id and Address and sends this data to PolicyMap.
  3. PolicyMap compiles the selected location-based data for each record into CSV format. Each row represents a new or updated PolicyMapData custom object:
    Name, ExtId, [standard object api name]__c, [PolicyMap data field name], …
    Name, ExtId, and [standard object api name]__c each contain the original record id. The rest of the row is comprised of the PolicyMap location and data field values.
  4. PolicyMap sends a Composite Tooling API request to create the new fields.
  5. PolicyMap sends Bulk API 2.0 ingest requests to import the data into the appropriate PolicyMapData custom object.

The following explanation of the import process is displayed to a PolicyMap Admin user after they have selected data, before they click the button to initiate the request:

How does it work?

A "Get PolicyMap Data" request will initiate the following 3-step process:

  1. An Apex batch job will compile record Address fields for records specified in the Set PolicyMap data and geocoding specs tab of the PolicyMap Administration and Settings page.
  2. PolicyMap will create a field in each PolicyMap Data object for each of the requested data items.
  3. PolicyMap will compile the requested data and populate the new fields via one or more Bulk Data Load jobs.

You can monitor the progress of these steps in the View data import status tab of the PolicyMap Administration and Settings page. During Step 1 above, you may monitor the progress of the Apex batch job in the Apex Jobs page in Setup. Once the Bulk Data job is initiated, you may monitor its progress in the Bulk Data Load Jobs page in Setup.

Once the Bulk Data job is completed, the data will be available in the specified PolicyMap Data objects. You may delete the field in the PolicyMap Data object if desired. This will remove the row from the PolicyMap Data component. Do not manually create new fields or modify existing fields in the PolicyMap Data object.

Appendix: PolicyMap’s security certifications

HIPAA

PolicyMap is certified for the U.S. Health Insurance Portability and Accountability Act of 1996 (HIPAA), enabling staff, customers, and users of the application a secure environment to process, transmit, maintain, and store protected health information (PHI).  PolicyMap achieved its first HIPAA compliance in 2020, and it has been renewed each subsequent year.

PCI DSS (tests conducting by Security Metrics)

Payment Card Industry Data Security Standard (PCI DSS) is a proprietary information security standard administered by the PCI Security Standards Council. The compliance is designed to protect businesses and their customers against payment card theft and fraud, and the quarterly testing process monitors and reports on site vulnerabilities. PolicyMap first achieved PCI DSS compliance in 2011, and it has been renewed each quarter of each subsequent year.

Penetration Test (test conducted by Security Metrics)

In May 2024 a penetration test was conducted on the PolicyMap PolicyMap SaaS Product to simulate a cyberattack and identify security vulnerabilities in the application. The test employed the same tools and techniques used by malicious actors and provided a thorough evaluation of the application’s security protections. The application passed the test with no vulnerabilities exposed.

How did we do?