PolicyMap for Salesforce: Technical overview

Updated by PolicyMap

PolicyMap for Salesforce: Technical overview

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 a custom object record. This object contains lookup fields to associate the PolicyMap data record with a standard or custom object record. No modifications are ever made to the related record itself.

The custom object that contains PolicyMap data is:

  • PolicyMapData__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_Object_Setting__c, list type custom setting, contains the PolicyMap Admin user’s selections of which objects' records to populate with PolicyMap data.
  • PolicyMap_Child_Object_Setting__c, list type custom setting, contains the PolicyMap Admin user’s selections of which objects to show PolicyMap data belonging to related records.

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 object 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 completion of a Bulk Data Load 2.0 job.
  • Set update schedule allows PolicyMap Admin users to schedule automatic PolicyMap data updates for new records and records with changed addresses.
  • The PolicyMap Index Card component is a Lightning Web Component available on record pages. 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 Record Locator component is an Aura Component available on record pages. The component 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.

Platform Events

The app has one custom event channel:

  1. The PolicyMap Channel contains one channel member: PolicyMapDataImport. Currently, this channel is used for one event: PolicyMap Data Import with one field: Action. Some Lightning Web Components listen for an “update” action, sent via REST API from PolicyMap. Upon “update”, the component refreshes. This is to allow PolicyMap to provide live import status information.

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 External Client 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
  • Package major version

The PolicyMap Admin component initiates the following callout through the Named Credential (full callout documentation):

  • callout:PolicyMap_Services/s/?act=ver
    Upon page load, queries PolicyMap for the latest version of the package. This callout serves to both validate the Named Credential, and can be used to notify PolicyMap Admin users that a newer version is available.

The Set PolicyMap data and geocoding specs tab in PolicyMap Admin initiates the following callouts through the Named Credential (full callout documentation):

  • callout:PolicyMap_Services/s/?act=dlt
    Upon creating a new PolicyMap_Object_Setting__c record, notifies PolicyMap to create the necessary lookup field on the PolicyMapData__c object to relate the data records to the selected object’s records as well as formula fields that detect changes in the related record’s location in order to flag stale data records.

The Import and organize PolicyMap data tab in PolicyMap Admin 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.

The data request batch process initiates following callouts through the Named Credential (full callout documentation):

  • callout:PolicyMap_Services/s/?act=ic
    Upon beginning the first batch in the data request batch chain, 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 location values. No other data from these records is sent to PolicyMap. 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=s
    In the case of a batch encounters an error or finds no locations to process, notifies PolicyMap. The information is then stored to display in the View data import status tab.

The View data import status tab in PolicyMap Admin page initiates the following callouts through the Named Credential (full callout documentation):

  • callout:PolicyMap_Services/s/?act=c
    Upon loading the status table 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=j
    Upon loading the status table and on subsequent refreshes triggered by the user or platform events, retrieves the status of Bulk Data Load jobs that were previously in progress.
  • 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.

The PolicyMap Index Card component initiates the following callouts through the Named Credential (full callout documentation):

  • callout:PolicyMap_Services/s/?act=si
    Upon user interaction, retrieves location-based data from PolicyMap to populate existing fields for a single record. This 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 Salesforce. PolicyMap makes the following requests to Salesforce:

  • PolicyMap requests user info after JWT authentication.
  • Upon creating a new object setting, PolicyMap uses a Composite Tooling API request to create a custom lookup field on the PolicyMapData custom object to relate the data to the object’s records, and formula fields to detect changes in the related record’s location to flag stale data records.
  • Since the PolicyMap_User permission set does not have broad read access to the data object (in order to expose related record address in the formula field), PolicyMap sends an Apex REST request for the package to assign field permissions to only those fields that require them.
  • Upon compiling data for a location-based data request, PolicyMap uses a Composite Tooling API request to create custom fields on the PolicyMapData custom object to contain the new data, and again sends an Apex REST request to assign the appropriate field permissions to the new fields.
  • After creating the custom fields, PolicyMap uses Bulk API 2.0 requests to initiate an ingest job to import the new data into the PolicyMapData custom object.
  • When requested, PolicyMap uses Rest API to query the state of specified Bulk API 2.0 jobs.
  • Periodically, PolicyMap uses Rest API to send a custom Platform Event to trigger a refresh of Lightning Web components.

The data import process

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

  1. Salesforce initiates a chain of Apex Batch jobs that queries the specified records for Id and Address and sends this data to PolicyMap. Upon starting the first job in the chain, Salesforce sends PolicyMap an object containing the PolicyMap data specifications. PolicyMap sends back a Request Id to use throughout the batch chain.
  2. 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 lookup field values, PolicyMap location and data field values.
  3. PolicyMap sends a Composite Tooling API request to create the new fields and an Apex REST request to trigger assignment of the appropriate field permissions.
  4. PolicyMap sends Bulk API 2.0 ingest requests to import the data into the appropriate PolicyMapData custom 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?