Using the GoSpotCheck Salesforce Managed Package
After you've successfully installed and completed the initial setup of the GoSpotCheck Salesforce Managed Package, it's time to get started using the integration. Below is a user guide covering all of the details and specifics you need to know as a Managed Package user.
Whats Included In The App
The managed package primarily contains custom code used to facilitate the integration between Salesforce and GoSpotCheck. This portion of the managed application is not included in this guide. Further architectural information can be obtained by contacting GoSpotCheck.
Data Model
The data model consists of custom fields on the standard Account and User object. Then several custom objects to match the data model in GoSpotCheck.
All Sync Objects
The following fields are included on Account, User and the custom objects used in the integration which includes Place Group, Team, and User Assigned Place. These fields work identically for each of these objects:
Label |
API Name |
Description |
Purpose |
| Sync To GoSpotCheck | SyncToGoSpotCheck | A checkbox to determine if a record will be included in the integration. | The primary purpose of this field is to allow each customer to determine the subset of records that should be synced. Some customers may prefer to include all records and others may prefer to include only specific records. See “Automating Syncing” for ideas on how to determine the record population to integrate with GoSpotCheck. For custom objects, this value defaults to true. |
| GSC Id | GSCId | The Id of the corresponding record. | Used to determine a new record (POST) or update an existing record (PUT). If an existing integration exists with GoSpotCheck, populate this field with the current GSC Id of the corresponding record. |
| Last Sync | gsc_mc__Last_Sync__c | The datetime of the last attempt to integrate with GoSpotCheck. | This field is used primarily for informational purposes and for reporting. |
| API Log | gsc_mc__API_Log__c | The response returned from GoSpotCheck if an error occurred or a message displayed to indicate the integration was successful. Stores the response from the most recent response only. | Used to display information for errors and/or to indicate the last attempted integration was successful. Used primarily for debugging. |
| API Error | gsc_mc__API_Error__c | A checkbox to indicate that the last integration attempt did not succeed. | Used in reporting and to manage integration errors. See the errors section for more detail. |
| Auto Retry | gsc_mc__Auto_Retry__c | Forces the record to be reintegrated with GoSpotCheck. | When back-populating data from an existing integration and wanting to resync the current information from Salesforce to GoSpotCheck, this field can be used to push all records into the queue to be reintegrated with GoSpotCheck. |
Accounts
Accounts in Salesforce integrate to Places in GoSpotCheck. No additional custom fields exist on the Account object.
Users
Users in Salesforce integrate to Users in GoSpotCheck. No additional custom fields exist on the User object.
Place Group
Place Groups are a custom object that integrate directly with Place Groups in GoSpotCheck. In addition to the fields in the “All Sync Objects” section. Place Groups have the following fields:
Label |
API Name |
Description |
Purpose |
| Add/Remove Place API Log | gsc_mc__ Add_Remove_Place_API_Log__c | The response returned from GoSpotCheck for adding or removing places to this place group. Will display error messages as well as success messages. | This field summarizes the Add/Remove places to a place group response information. Can be used for debugging and to view the response of a successful sync. |
| Last Add/Remove Place Sync | gsc_mc__ Last_Add_Remove_Place_Sync__c | The date/time of the last attempt to add or remove places to a place group. | This field is used primarily for informational purposes and reporting. |
| Auto Retry Places | gsc_mc__Auto_Retry_Places__c | Forces the places currently assigned to a place group to be reintegrated with GoSpotCheck. | When errors occur or when back-populating data, this field will force all places to be added to the place group. The GoSpotCheck API prevents the same place from being added to a place group more than once. |
Place Group Places
Place Group Places are a custom object that act as a junction between accounts and place groups to create a many to many relationship. Place Group Places are synced by default. A lookup field exists for an Account and a Place Group. Sync information is stored on the Place Group object described above.
Teams
Team is a custom object that integrates directly with Teams in GoSpotCheck. In addition to the fields in the “All Sync Objects” section, Teams have the following fields:
Label |
API Name |
Description |
Purpose |
| Add/Remove User API Log | gsc_mc__ Add_Remove_User_API_Log__c | The response returned from GoSpotCheck for adding or removing users (Team Members) to this Team. Will display error messages as well as success messages | This field summarizes the Add/Remove users to a team response information. Can be used for debugging and to view the response of a successful sync. |
| Last Add/Remove User Sync | gsc_mc__ Last_Add_Remove_User_Sync__c | The date/time of the last attempt to add or remove users to a team. | This field is used primarily for informational purposes and reporting. |
| Auto Retry Users | gsc_mc__Auto_Retry_User__c | Forces the users currently assigned to a team to be reintegrated with GoSpotCheck. | When errors occur or when back-populating data, this field will force all users to be added to the team in GoSpotCheck. The GoSpotCheck API prevents the same user from being added to a team more than once. |
Team Members
Team Members are a custom object that act as a junction between users and teams to create a many to many relationship. Team Members are synced by default. A lookup field exists for a User and a Team. Sync information is stored on the Teams object described above.
User Assigned Places
User Assigned Places are a custom object that act as a junction between users and accounts to create a many to many relationship. User Assigned Places are synced by default. A lookup field exists for a User and an Account. This object contains the standard sync fields (e.g. Sync To GoSpotCheck, GSC Id, etc.)
GSC Queued Requests
The GSC Queued Requests is an object used in the integration framework to bridge the gap between Salesforce’s limitations and the current limitations of the GoSpotCheck API. No details are provided in this guide to its data model. It is highly recommended to not change this object in any way. To see more details about how the queue works see “Understanding the Queue”.
GSC Error Logs
Used to store errors that occur within Salesforce. API errors returned from the GoSpotCheck API are stored on the individual records affected. This is used to assist in identifying issues with new features, enhancements, and configuration. Any records contained in this object need to be reported to GoSpotCheck. See “Application Errors” for more information.
Apps
For ease in navigating to the objects included in the integration and to setup the managed package, two apps are included in the managed package. These apps contain the same tabs. One app is used for the Salesforce Lightning Experience and the other for Salesforce Classic.
- Salesforce Lightning App > "GSC Lightning" App
- Salesforce Classic App > "GoSpotCheck" App
The apps contain the following sets of tabs related to the integration:
- GSC Admin (Custom UI Interface. See “User Interfaces” for more information)
- GSC Queued Requests (Custom Object Tab)
- Accounts (Standard Object Tab)
- GSC Place Groups (Custom Object Tab)
- GSC Error Logs (Custom Object Tab)
- GSC Teams (Custom Object Tab)
- GSC User Management (Custom UI Interface. See “User Interfaces” for more information)
User Interfaces
Custom UI’s are included in the application to make set up and implementation of the application easier. These custom UI’s are included in both apps included as part of the package.
GSC Admin
The GSC Admin page is used to setup the application and turn on the integration. Some of the information included in this page of the application is the endpoint and API Token for the GoSpotCheck API, custom mappings to map Accounts to Places and Users to Users in GoSpotCheck, as well as the ability to start the backend queue (See “ Understanding The Queue” for more information on the backend queue).
At a high level the following is accessible from this user interface:
- Set the app token and endpoint for the integration
- Change the mappings for Accounts to Places and Users to GSC Users
- Restart the Queue (if it has stopped)
More information on this page can be found in the Implementation and Installation Article.
GSC User Management
The GSC User Management page is used to work with User’s in Salesforce as a collection only as it applies to the integration. From this UI, you can search for specific groups of users and interact with one of more users at a time.
A list of selectable users is exposed and the following actions can be applied:
- Filter Users by Role, Profile, Set to “Sync to GoSpotCheck”, Team Membership, and others.
- Add/Remove multiple users to a Team.
- Check/Uncheck multiple users to “Sync To GoSpotCheck”.
In Salesforce, Users are a setup object and the standard object functionality is limited. In addition, working with groups of users is difficult. This interface is provided in order to fill that gap. More information on this page can be found later in the document.
Process Builder
Custom process builder steps have been included in the managed package in order to automate adding/removing users to/from a team and to automate adding/removing places to a place group.
Each action using these predefined methods will apply to 1 Place Group or 1 Team. If there are 50 Place Groups that need to have records automatically added, then 50 actions will need to be set up in 1 or many processes in Process Builder to automate adding to all 50 Place Groups.
Once the package is installed the following methods will be available in process builder:
- Add to Team/Place Group
- Remove from Team/Place Group
Method parameters
| Name | Type | Description | Example |
|
accountOrUserId |
Field Reference |
This is the Id of the record in context in the process. This will be a field reference. | [Account].Id OR [User].Id |
|
isPlaceGroup |
Boolean |
Use this to identify that this process is adding Places to a Place Group. Use only for ACCOUNT based processes. | True |
|
isTeam |
Boolean |
Use this to identify that this process is adding Users to a Team. Use only for USER based processes. | True |
|
placeGroupOrTeamGSCId |
String |
GoSpotCheck Id of the Place Group or Team that exists in Salesforce and has been synced. A single action will be set up for each Place Group or Team where automation should occur. | 206543 |
Determining When & How a Record Is Synced
The following objects use the “Sync To GoSpotCheck” field to determine IF a record should be synced:
- Accounts
- Users
- Place Groups
- Teams
- User Assigned Places.
This field is used to determine the subset of data that exists in Salesforce that should be included in the integration to GoSpotCheck. This guide will break down each of the objects included in the integration to give a closer look at when a record will sync, when updates will be synced, and what occurs when a record that has been synced is no longer selected to be included in the integration.
Create/Update
By default, Accounts and Users will not sync to GoSpotCheck. This is because the “Sync To GoSpotCheck” field defaults to false. See “Automating Syncing” for ideas on how to automatically check this field for Accounts and Users.
Teams, Place Groups, Place Group Places, Team Members, and User Assigned Places all automatically sync. These are custom objects that are used specifically for the integration. They will always sync on create and update.
What happens when I check the Sync To GoSpotCheck field?
- Record without a GSC Id: The sync will happen near real time and create a new record in GoSpotCheck. The GSC Id will be stored on the Salesforce record along with log information and date/time stamp.
- Records without a GSC Id: The sync will not occur real time for a bulk transaction. Instead the records will be added to the queue to be processed. Once processed by the queue, each account will be created as a Place in GoSpotCheck. The GSC Id of the created Place will be stored on the corresponding Salesforce record along with log information and date/time stamp. See “Understanding the Queue”.
- Record with a GSC Id: The sync will happen near real time and update an existing record in GoSpotCheck. The GSC Id will remain unchanged.
- Records with a GSC Id: The sync will not occur real time for a bulk transaction. Instead the records will be added to the queue to be processed. Once processed by the queue, each record in GoSpotCheck will be updated by the most recent Salesforce record information. The GSC Id will remain unchanged.
What Happens When I change A Record That is Being Synced To GoSpotCheck?
When a record is updated in Salesforce that has a GSC Id and the “Sync To GoSpotCheck” is checked, the integration will determine if the data that is mapped from Salesforce to GoSpotCheck changed, to determine if an update should be made.
Changes to records in Salesforce are validated to determine that the record change affects the data mapped between Salesforce and GoSpotCheck.
Simple Example
In this scenario, the Account Shipping Address is currently mapped to sync to Places. The Billing Address is not included.
- If the account Billing State was updated, this would not trigger a sync to GoSpotCheck.
-
- Reason: Billing State is not a mapped field.
-
- If the account Shipping State was updated, this would trigger a sync to GoSpotCheck.
-
- Reason: Shipping State in this example is a mapped field.
-
- If the account Type was updated, this would not trigger a sync to GoSpotCheck.
-
- Reason: Account Type is not a mapped field.
-
- If the account was saved with no changes, this would not trigger a sync to GoSpotCheck.
- Reason: Even though the record was saved, there were no changes to a mapped field. No sync would occur.
Deleting a Record
When a record that is currently synced to GoSpotCheck is deleted, the deletion will be picked up by the queue and processed in GoSpotCheck. No response information is stored from the delete as the Salesforce record no longer exists.
Single and bulk transactions are processed by the queue for delete.
Setting the Sync Checkbox to "False"
When a synced record’s “Sync To GoSpotCheck” is set to false, the record will be disabled in GoSpotCheck. This applies only to Users and Places. Disabling the checkbox for the GSC integration objects (Place Groups, Teams, etc.) will simply prevent any additional changes from being pushed to GoSpotCheck.
In addition, any record set to false will no longer push updates to GoSpotCheck from Salesforce.
Exposing Sync Information To Users
You can expose sync information to users through the use of permission sets and page layout changes.
Permission Sets
Permissions to the GSC Admin, GSCMappings, GSCUsers, and PlaceroupResyncPlaces Visualforce pages can be shared through the Setup > Custom Code > Visualforce Pages > Security path. This will allow you to make those pages available to any profile that exists within your organization without having to share the package with all users.
Page Layout Changes
For the objects that are specific to this managed package, no page layout changes are required. Page layout changes need to be made on the Account and User objects. This includes adding custom fields (See “Data Model” to determine which fields to expose) as well as adding related lists to the layouts. For Accounts, related lists are available for Place Group Places and User Assigned Places. For Users, Team Members is available as a related list.
Automating Syncing
To automate syncing any process can check the “Sync To GoSpotCheck” field on any of the objects. By default only Accounts and Users are not checked by default. No automation is needed for Place Groups, Teams, Team Members, Place Group Places, or User Assigned Places.
To automate syncing the following methods in Salesforce can be utilized:
- Workflow Rules
- Process Builder
- Apex Triggers
- External Integration
If all Accounts or all Users need to be synced, the easiest solution is to create a Workflow rule for the object and set the criteria for entry to be ISNEW(). Adding a workflow field update to check the sync will complete the process. If additional assistance is needed in determining the best way to automate the sync, please contact GoSpotCheck.
Understanding The Queue
Due to limitations in Salesforce and the current architecture of the GoSpotCheck API, a queue has been set up to handle bulk transactions.
The queue runs in the background of Salesforce and will process all integrations for all objects every 15-20 minutes by default. If a different interval is needed, this can be configured by contacting GoSpotCheck.
The queue works by storing requests that need to be sent to GoSpotCheck. Records are added to the queue only when bulk transactions occur in Salesforce for records that need to be synced or for deletion of synced records.
Records are added to the queue with the same validation for near real time transactions. Additional logic exists to prevent duplicates in the queue as well as tied in to near real time transactions.
For example, if a record is added to the queue due to a bulk transaction and before it is processed, if a user were to update the record manually. The manual update would trigger a real time sync and the record would be removed from the queue.
Additional logic exists for the queue.
Managing Errors
There are two types of errors logged by the managed package:
- Errors that are returned from GoSpotCheck (Sync Errors) and
- Errors that occur in the managed package code (Application Errors).
Visibility into both of these types of errors are included in the managed package.
Reporting on Errors
Using the “Data Model” as a reference, there are API Logs and an API Error checkbox that exists on synced records. These fields can be included in a report or list view to be able to report or view records where sync errors occurred.
Any account/user report can be created to filter records with a GSC Id, that are currently set to Sync and that have a “True” value for the field, “API Error”. These fields can also be filtered on in a list view.
Viewing & Managing Sync Errors
It is recommended to include the “API Log”, “GSC Id”, “Sync To GoSpotCheck”, and “API Error” fields on to existing Account and User layouts. This will give visibility on individual records into errors that have occurred. It is also recommended to create List Views for Accounts and Users to retrieve records with an “API Error” set to True.
An internal business process will need to be set up to routinely check for and report on errors. Any sync errors that are unable to be resolved can be forwarded to GoSpotCheck for additional assistance.
Viewing & Managing Application Errors
As part of the Apps included in the managed package, there is a GSC Error Logs tab. This tab contains all of the application records that have been created. Periodically these errors should be reviewed to determine if there is an error occurring in the integration code. This tab is a custom object tab and includes all of the out of the box functionality available with out of the box Salesforce.
When integration errors are occurring in a Salesforce org, this tab should be the first place to check for errors. The errors can be included in a report and forwarded to GoSpotCheck to be resolved. When creating a report, please include all fields for the GSC Error Log object. Additionally, screen shots of specific errors can be sent. These errors provide context for errors that have already occurred and increase the speed and reliability of fixes for the app.