Salesforce Calendar Connector Guide

This article provides direction on how to configure and manage your Salesforce Calendar connector.

Table of Contents

Purpose

Prerequisites 

Connector Configuration

Limitations

Troubleshooting

Documentation and External Links

Purpose

The purpose of the connector is to bridge Booxi to a Salesforce Calendar account using a standard connected app to share and synchronize appointment data between both environments. Booxi can interface with Salesforce Core and Service Cloud. 

Prerequisites

In order to create and configure a calendar connector, you will need to fulfill these prerequisites. Before proceeding forward, make sure you meet all the requirements listed below.

• You must run one of these Salesforce editions: Enterprise Edition, Performance Edition, Unlimited Edition or Developer Edition
• This integration requires the creation of a connected app for Booxi including a client ID and client secret. Your Salesforce account must have administrator rights or the equivalent to perform this task
• This integration requires object mapping between Booxi's and Salesforce's entities (client, staff, event, service)
• API Host 
• Determine if Booxi can create a staff, service, client if it doesn't exist in Salesforce
• Determine if Booxi can cancel an event in Salesforce if it has been canceled in Booxi

Connector Configuration

Salesforce’s interface comes in two flavors, Salesforce Classic and Lightning Experience. While the differences are mostly UI-related from a user perspective, this guide will provide a detailed explanation on how to complete each step for both interfaces. Follow instructions as provided below.

First, a connected app must be created in order to gather the necessary information to configure the Booxi connector.

---

Create a Connected App

Connect to your Salesforce account and follow these steps.

If you are using Salesforce Classic:

1. Click on “Setup”.

2. On the left-hand side menu, under Build - Create, click on Apps.
3. Under Connected Apps, click on the New button. Then, jump to step “4”.

 

If you are using Salesforce Lightning:

① From the Lightning home page, click on the gear icon and select Setup.

② From the Setup home page type “App Manager” in the quick find box.

③ Select “App Manager” in the search results.

④ Click on “New Connected App”.

⑤ Populate the mandatory fields marked in red.

• Under Basic Information, fill out the following fields:
  • Connected App Name : Booxi Salesforce Calendar
  • API Name : booxi_salesforce_calendar
  • Contact Email : it@booxi.com

⑥ Under API, check OAuth Settings and follow the below steps:

• In the Callback URL textbox, type one of the following URL based on your Booxi hosting region.
  • North America: http://connector.booxi.com/sf-calendar/v0/oauth/callback
  • Europe: http://connector.booxi.eu/sf-calendar/v0/oauth/callback
• Next, check the “Use digital signatures” checkbox.
• Click on “Choose file” and select the certificate file provided by Booxi. If you haven’t been provided with the certificate file, please consult your Booxi representative.
• In Selected OAuth Scopes, add the following scopes:
  • Access all Data Cloud API resources (cdp_api)
  • Access the Identity URL service (ID, profile, email, address, phone)
  • Access unique user Identifiers (openId)
  • Manage user data via Web browsers (web)
  • Manage user data via APIs (api)
  • Perform request at any time (refresh_token, offline access)
• Last, check the “Issue JSON Web Token” checkbox. For  further details about the JSON Web Token, consult the following link.

⑦ Next, check “Configure ID Token” and add the following settings:

• In the Token ID Audiences textbox, type the URL of your authentication server:
  • https://test.salesforce.com,
  • https://login.salesforce.com
  • https://site.force.com/customers if for an Experience Cloud site.
• Check “Include Standard Claims”.

⑧ Click on the Save button at the bottom of the page.

When prompted to do so, click on Continue.

⑨ Back on the Setup home page, select “Manage” from the newly created app.

⑩ Click on “Edit Profile”.

⑪ Under “OAuth Policies”, set the property “Permitted Users” to “Admin approved users are pre-authorized”. Confirm the change by clicking on “Ok”.

⑫ Under “JWT-Based Access Token Settings”, make sure “Issue JSON Web Token” is checked. Then, click on the Save button at the bottom of the page.

⑬ Back on the App summary page, scroll down to the section named “Profiles” and click on “Manage Profiles”.

⑭Scroll down and check ”System Administrator”. Click on the Save button. The connected app is now fully configured in Salesforce.

⑮On the summary page of your connected app, take note of the following information and share it with tour Booxi representative so the connector can be configured.

• OAuth Client ID, known as Consumer ID.
• OAuth Client Secret, known as Consumer Secret.
• Audience: The authentication server to encode in the JWT claim.                       
  (i.e. test.salesforce.com, login.salesforce.com)
• Subject: the email associated with the Booxi Salesforce configuration.

Once the connector is created and configured, you must pair data from Salesforce and Booxi. This process is known as mapping.

Troubleshooting

If you are prompted with the following error message, this usually means the certificate has not been uploaded.

{"error":"invalid_grant","error_description":"invalid assertion"}

---

Configure Booxi Connector

Once the connected app is configured, the Booxi team will finalize and activate the connector.

With this process now complete, you must pair data from one database to another. This process is known as mapping.

Object Mapping

Object mapping consists in associating data from one database to another. This task is performed by Booxi staff, from an excel sheet where objects and fields have been paired to their respective counterparts. Only by doing so will the connector know how to create calendar entries in accordance with your Salesforce database.

A default object mapping will suffice if you aren’t using custom objects or fields. On the contrary, if you do use custom objects or fields a custom mapping (see section below) may be required.

Default Object Mapping

Here’s a list of standard objects and fields as supported by the connector. All entries listed below are mapped by default in lib-salesforce. Customers are not required to provide their own mapping if their objects and fields are included in the below list. 

Standard Objects

Standard Fields per Object

Object	Salesforce Field	Booxi Field	Description
event	Event	“name”	Name of Object
	OwnerId	“staff”	Staff assigned to this event
	Subject	“subject”
	Whold	“contact”
	ActivityDateTime	“start”
	ShowAs	“status”
	Description	“description”	Contains the description associated with the event as well as any survey answer and additional request.
	WhatId	“service”
	DurationInMinutes	“duration”
contact	Contact	“name”	Name of object
	Id	“id”
	FirstName	“firstName”
	LastName	“lastName”
	Email	“email”	Field used for matching when basic data is not sufficient.
	Phone	“phone”
staff	User	“name”	Name of object
	Id	“id”	Staff’s ID
	FirstName	“firstName”	Staff’s first name
	LastName	“lastName”	Staff’s last name
	Email	“email”	Staff’s email address
service	Service	“name”	Name of object
	Id	“id”
	Name	“name”	Field used for matching when basic data is not sufficient.

---

Mapping Exception - Salesforce Core

Salesforce Classic uses all standard objects and properties as listed above in default mapping. However, take note that the following exception applies:

---

Mapping Exception - Salesforce Service Cloud

Similarly, Salesforce Service Cloud mapping uses all standard objects and properties as listed in default mapping. However, take note that the following exception applies:

Custom Object Mapping

Salesforce custom objects can be mapped comparably as a standard object. However, they must always be mapped to an existing object or field in the Booxi database. The following will present how to create a custom mapping using a JSON file instead of an excel sheet.

---

How to implement a custom mapping JSON

A custom mapping JSON must minimally include a choice of format and mappings for all four required objects: event, contact, staff and service.

Format

The format determines if a calendar entry will be created as an Appointment or as a Service.

withAppointment: set to “true” to link Salesforce Event as an Appointment. Only in Salesforce Classic.

withService: set to “true” to link Salesforce Event as a Service.

 

Objects

Event

Create an object “event” and, within an array map all standard or custom fields pertaining to an event, task or appointment.

Example JSON Format

"event": 
{                
   "name": "Event",        
   "fields": 
   {            
     "subject": "Subject", 
     "contact": "WhoId", 
     "service": "WhatId", 
     "start": "StartDateTime", 
     "end": "EndDateTime", 
     "status": "status__c", 
     "WhatId": "content.booking.client.id", 
     "description": "Description", 
     "custom":
     {
       "Consultant__c": "content.staffs.metadata.salesforce_staff_id",
       "Shop__c": "content.merchant.metadata.salesforce_store_id",
       "Service__c": "content.services.metadata.salesforce_service_id",
       "Note__c": "content.booking.quickNote"
     }
   }
},

Mappable Variables from the Webhook Payload

Here’s a list of all variables found in the webhook payload that can be mapped to any custom object defined by a salesforce user. All variables are stored in content.booking.

 

Contact

Create an object “contact” and, within an array map all standard or custom fields pertaining to the client or account being served.

Example JSON Format

"contact":
{
   "name": "Account__c",
   "fields":
   {
     "id": "Id",
     "firstName": "FirstName",
     "lastName": "LastName",
     "email": "PersonEmail",
     "phone": "Phone"
   }
},

Staff

Create an object “staff” and, within an array map all standard or custom fields pertaining to the resource involved in rendering the service.

Example JSON Format

"staff":
{
   "name": "Consultant__c",
   "fields":
   {
     "id": "Id",
     "lastName": "Last_Name__c",
     "firstName": "First_Name__c"
   }
},

Service

Create an object “service” and, within an array map all standard or custom fields pertaining to the service being rendered.

Example JSON Format

"service":
{
   "name": "Service__c",
   "fields":
   {
     "id": "Id",
     "name": "Name"
   }
}

Your final custom mapping JSON should be as the following:

"{
   "withAppointment": false,        
   "withService": true,        
   "event": 
   {                
      "name": "Event",        
      "fields": 
      {            
         "subject": "Subject", 
         "contact": "WhoId", 
         "service": "WhatId", 
         "start": "StartDateTime", 
         "end": "EndDateTime", 
         "status": "status__c", 
         "WhatId": "content.booking.client.id", 
         "description": "Description", 
         "custom":
         {
            "Consultant__c": "content.staffs.metadata.salesforce_staff_id",
            "Shop__c": "content.merchant.metadata.salesforce_store_id",
            "Service__c": "content.services.metadata.salesforce_service_id",
            "Note__c": "content.booking.quickNote"
         }
      }
   },

   "contact":
   {
      "name": "Account__c",
      "fields":
      {
         "id": "Id",
         "firstName": "FirstName",
         "lastName": "LastName",
         "email": "PersonEmail",
         "phone": "Phone"
      }
   },

   "staff":
   {
      "name": "Consultant__c",
      "fields":
      {
         "id": "Id",
         "lastName": "Last_Name__c",
         "firstName": "First_Name__c"
      }
   },

   "service":
   {
      "name": "Service__c",
      "fields":
      {
         "id": "Id",
         "name": "Name"
      }
   }
}"

---

How to Link Services and Staff to Salesforce

Services and Staff in Booxi can be linked to their Salesforce’s equivalents. To do so, each service and staff must be assigned their corresponding Salesforce ID. 

For Services
To assign an ID to a service specific to a merchant, proceed to the Back Office and follow the Back Office instructions listed below. If you are using service templates to update several merchants at a time, proceed to the Head Office and follow the Head Office instructions below.

In the Back Office, follow these steps:

• Select any service.
• In its summary page, click on “Integration Module Links” ①.
• Type in its corresponding Salesforce service Id ② and click on “Save” ③.

In the Head Office, follow these steps:

• Select any service template.
• In its summary page, click on “Integration Module Links” ①.
• Type in its corresponding Salesforce service Id ② and click on “Save” ③.
• Repeat these steps for every service you wish to assign an ID.

To apply your changes to all assigned stores, you must perform an “update service to stores” by following these steps:

• Select the service you wish to update to stores ①. Only one service at a time.
• From the Options menu, select “Update Service To Stores” ②.
  

• Check Service Details ③ and expand the list ④.

• Make sure “Integration Module Link” ⑤ is included, then click on “Update” ⑥.
• Once the update is completed, you will be prompted with a success message.

 

For Staff

• Select any staff member.
• In its summary page, click on “Integration Module Links” ①.
• Type in its corresponding Salesforce employee Id ② and click on “Save” ③.

---

Client Record - Creation and Matching

Upon creating an appointment, Booxi will validate if the client already exists in Salesforce. If it does, it will be linked to its corresponding entry in the Salesforce database. If it doesn't, a new entry will be created in Salesforce by the connector.. New clients are created and linked automatically by the connector. The connector must have the access rights for that step to be performed.

In order to identify if a client exists or not, a search will be performed using the following matching rules.

 

Matching Rules

Client ID

When an appointment is created in Booxi with a “Salesforce Client ID”,  a webhook event will be sent to the connector and, using the Salesforce API, the client will be identified with the provided ID.

Client’s full name or email address

When an appointment is created in Booxi without a “Salesforce Client ID”,  a webhook event will be sent to the connector and, using the Salesforce API, the client will be identified with its full name (first and last). If its name is missing or incomplete, then the matching will be performed with its email address.

Limitations

• You must run one of these Salesforce editions: Enterprise Edition, Performance Edition, Unlimited Edition or Developer Edition.

Troubleshooting

Remember that the connector offers the option to send out error messages to one or multiple recipients. Consult the section "Configure Booxi Connector" for further details.

 

Common Error Messages

 

In most cases, errors are due to a mismatch between Booxi’s and Salesforce’s databases.  To solve the problem, take the following steps:

• Review and compare data assigned in the Back Office for typos or mismatches.
• Review mapping file for any discrepancies in objects or fields.

Documentation and External Links

Salesforce Connected App:             Salesforce Connected App Help 

Salesforce Object Documentation:        Salesforce Standard Object Reference