Connect(ME) API Calls for Salesforce Lightning Scheduler¶
Starting with Salesforce Spring 2021 update, users who use the Salesforce Lightning Scheduler feature can do the following via Connect(ME):
- parse their and their colleagues’ actual calendar availability data from their MS Outlook calendars to be used in Salesforce Lightning Scheduler
- easily down-sync to MS Outlook calendar their Salesforce Events created with Scheduling App, this way ensuring that their calendars are always up to date and in sync
Tip
Also see this Connect(ME) article for more information on using Salesforce Lightning Scheduler
Connect(ME) ensures this possibility by establishing interaction between Salesforce Lightning Scheduler and the users’ Exchange accounts over several API endpoints. This article explains how these API methods and properties work.
Tip
Also see this video https://youtu.be/D6betOrxAwo to learn how exactly the users work with LinkPoint Connect(ME) in Salesforce Lightning Scheduler
Specific calendar actions performed over API¶
- Read, Create, Update, Delete calendar items on MS Exchange servers. This also includes: attendees availability spans parsing from their calendars; adding a booked Appointment based on a Lightning Scheduler Event to the attendees’ calendars
- Checking if the above listed actions were performed successfully; troubleshooting possible errors, e.g. Exchange data access issues
- Indicating which attendee is the meeting’s organizer
Prerequisites:
Slightly different sets of prerequisites are required to perform the call Read (retrieve availability) and the calls Create, Update, Delete.
For the Read method the prerequisites are:
- Create a Connect(ME) Org which the attendees belong to
- Connect(ME) access_token generated for a special user, a user belonging to the same RI Org with a valid MS Exchange credentials setup
- Other users whose availability is retrieved should belong to the same Exchange Org as the special user
For the Create, Update, Delete methods the prerequisites are:
- Create a Connect(ME) Org authorized via a service Impersonation Account which the attendees belong to
- All users whose Lightning Scheduler Events will be down-synced to Outlook should belong to the same Connect(ME) Org
- Connect(ME) access_token generated for a user belonging to the same RI Org that has Organization Admin permissions in the RI Org (the updateOrganization setting)
- Note that users mailboxes’ email aliases are not supported for these methods: each Salesforce user is matched with a single Connect(ME) user / email address
Special notes:
All date and time properties in the calls and responses are set in the ISO 8601 standard: YYYY-MM-DDThh:mm:ssZ
All input and output dates and times are set in GMT time zone.
Access authorization token¶
Access authorization required to work with MS Exchange data is granted using an access_token generated by Connect(ME) Sync Engine.
Salesforce Lightning Scheduler - Exchange downsyncing
When Events created in Lightning Scheduler are down-synchronized to MS Outlook calendar, due to a technical limitation in MS Exchange Connect(ME) creates a set of overlapping Appointments instead of a Meeting for every Attendee and the Event’s Organizer.
Endpoint 1: attendees’ calendar availability retrieval from Outlook calendar (Read)¶
This call is used to collect available slots data from an attendee’s MS Exchange calendar data. It has the following properties:
Tenant URL stands for the RI tenant URL which the attendees belong to
From and to date and time limits defining the time period over which
salesforceCorrelationId is an extra technical property which is generated by Salesforce Lightning Scheduler, it is used for troubleshooting purposes
The API Read call’s body contains the following properties:
email the email addresses of attendees from the same MS Exchange Org. Requests on different attendees’ availability are included as separate clauses in brackets.
serviceResourceId is a technical property required by the Lightning Scheduler
isOrganizer indicates if the attendee is the meeting’s Organizer; this additional property is included for future use possibilities
A sample Read call¶
POST {TENANT_URL}/api/salesforce/scheduler/availability?from=2020-10-15T00:00:00Z&to=2020-10-17T12:00:00Z&salesforceCorrelationId=abcdefg
Body:
[
{
"email": "test1@domain.com",
"serviceResourceId": "123",
"isOrganizer": true
},
{
"email": "test2@domain.com",
"serviceResourceId": "321"
}
]
The API Read response contains the following data retrieved for every attendee listed in the call:
serviceResourceId is a technical property required by the Lightning Scheduler
errorCode indicates an error code, if any, for troubleshooting, if an error occurred. NoError is displayed if there were no errors; other error indicators are also self-explanatory
unavaialbleTimeSlots is the retrieved data on the occupied slots in the attendee’s calendar over the period specified in the call. Data on different occupied slots is included as separate clauses in brackets
TimeMin is the date and time of the start of an occupied span in the attendee’s calendar
TimeMax is the date and time of the end of an occupied span in the attendee’s calendar
A sample Read response¶
POST {TENANT_URL}/api/salesforce/scheduler/availability?from=2020-10-15T00:00:00Z&to=2020-10-17T12:00:00Z&salesforceCorrelationId=abcdefg
Body:
[
{
"email": "test1@domain.com",
"serviceResourceId": "123",
"isOrganizer": true
},
{
"email": "test2@domain.com",
"serviceResourceId": "321"
}
]
Endpoint 2: saving a Lightning Scheduler Event as an Appointment in Outlook calendar (Create)¶
This call is used to create (down-sync) an Appointment in MS Exchange based on a Lightning Scheduler Event. It has the following properties:
Tenant URL stands for the RI tenant URL which the attendees belong to
API call’s body contains the following properties:
id of the Lightning Scheduler Event for which a matching Outlook Appointment should be created
organizerEmail email address of the Event’s Organizer
body body of the Appointment to be created
subject subject of the Appointment to be created
location location of the Appointment to be created
startTime start time of the Appointment to be created
endTime end time of the Appointment to be created
salesforceCorrelationId is an extra technical property which is generated by Salesforce Lightning Scheduler, it is used for troubleshooting purposes
attendees list of attendees of the Appointment to be created:
email email addresses of the attendees from the same MS Exchange Org. Requests on different attendees are included as separate clauses in brackets.
isRequired defines if an attendee is required
A sample Create call¶
POST {TENANT_URL}/api/salesforce/scheduler/postback
Body:
{
"id": "abcde-fghij-klmno-pqrst-uvwxyzfb3f11e",
"organizerEmail": "test@domain.com",
"body": "some text description",
"subject": "some subject",
"location": "meeting room 'Red'",
"startTime": "2020-10-16T10:00:00Z",
"endTime": "2020-10-20T23:00:00Z",
"salesforceCorrelationId": "ac3b40b4-2c33-463b-8bfe-8bcf077d7539",
"attendees": [
{
"email": "attendee1@domain.com",
"isRequired": "true",
},
{
"email": "attendee2@domain.com",
"isRequired": "false",
}
]
}
The API Create response contains the following data retrieved for every attendee included in the call:
email is the email addresses of attendees. Responses on different attendees’ availability are included as separate clauses in brackets
errorCode indicates an error code, if any, for troubleshooting, if an error occurred. NoError is displayed if there were no errors; other error indicators are also self-explanatory
A sample Create response¶
Response:
[
{
"email": "test@domain.com",
"errorCode": "NoError"
},
{
"email": "attendee1@domain.com",
"errorCode": "ErrorMailRecipientNotFound"
},
{
"email": "attendee2@domain.com",
"errorCode": "NoError"
}
]
Endpoint 3: updating an Appointment in Outlook calendar (Update / Modify)¶
Tenant URL stands for the RI tenant URL which the attendees belong to
API call’s body contains the following properties:
original fields of the item before updating / modifying
id of the Lightning Scheduler Event whose matching Appointment should be updated / modified
organizerEmail email address of the Event’s Organizer
body body of the Appointment to be updated / modified
subject subject of the Appointment to be updated / modified
location location of the Appointment to be updated / modified
startTime start time of the Appointment to be updated / modified
endTime end time of the Appointment to to be updated / modified
attendees list of attendees of the Appointment to be updated / modified:
email the email addresses of attendees from the same MS Exchange Org. Requests on different attendees are included as separate clauses in brackets
isRequired defines if an attendee is required
new updated fields of the item
Note: only the updated new values differ from the original values, but the call’s syntax requires including the unchanged values as well
organizerEmail email address of the Event’s Organizer
body updated body of the Appointment
subject updated subject of the Appointment to be updated / modified
location updated location of the Appointment to be updated / modified
startTime updated start time of the Appointment to be updated / modified
endTime updated end time of the Appointment to to be updated / modified
attendees updated list of attendees of the Appointment:
email the email addresses of attendees from the same MS Exchange Org. Requests on different attendees are included as separate clauses in brackets
isRequired defines if an attendee is required
salesforceCorrelationId is an extra technical property which is generated by Salesforce Lightning Scheduler, it is used for troubleshooting purposes
A sample Update call¶
PUT {TENANT_URL}/api/salesforce/scheduler/postback
Body:
{
"original": {
"id": "abcde-fghij-klmno-pqrst-uvwxyzfb3f11e",
"organizerEmail": "test@domain.com",
"body": "some text description",
"subject": "some subject",
"location": "meeting room 'Red'",
"startTime": "2020-10-16T10:00:00Z",
"endTime": "2020-10-20T23:00:00Z",
"attendees": [
{
"email": "attendee1@domain.com",
"isRequired": "true",
},
{
"email": "attendee2@domain.com",
"isRequired": "false",
}
]
},
"new": {
"organizerEmail": "test@domain.com",
"body": "some text description",
"subject": "some subject",
"location": "meeting room 'Red'",
"startTime": "2020-10-16T10:00:00Z",
"endTime": "2020-10-20T23:00:00Z",
"attendees": [
{
"email": "attendee1@domain.com",
"isRequired": "true",
},
{
"email": "attendee2@domain.com",
"isRequired": "false",
}
]
}
"salesforceCorrelationId": "ac3b40b4-2c33-463b-8bfe-8bcf077d7539"
}
The API Update response contains the following data retrieved for every attendee included in the call:
email is the email addresses of attendees. Response on different attendees are included as separate clauses in brackets
errorCode indicates an error code, if any, for troubleshooting, if an error occurred. NoError is displayed if there were no errors; other error indicators are also self-explanatory
A sample Update response¶
Response:
[
{
"email": "test@domain.com",
"errorCode": "NoError"
},
{
"email": "attendee1@domain.com",
"errorCode": "NoError"
},
{
"email": "attendee2@domain.com",
"errorCode": "ErrorMailRecipientNotFound"
}
]
Endpoint 4: deleting an Appointment from Outlook calendar (Delete)¶
Tenant URL stands for the RI tenant URL which the attendees belong to
id of the Lightning Scheduler Event whose matching Appointment should be deleted
organizerEmail email address of the Event’s Organizer
attendees list of the attendees of the item to be deleted; their emails are listed in quotation marks, no separate clauses required
A sample Delete call
DELETE {TENANT_URL}/api/salesforce/scheduler/postback
Body:
{
"id": "abcde-fghij-klmno-pqrst-uvwxyzfb3f11e",
"organizerEmail": "organizer@domain.com",
"attendees": [
"test1@domain.com",
"test2@domain.com"
]
}
The API Delete response contains the following data retrieved for every attendee included in the call:
email is email addresses of the attendees. Responses on different attendees included as separate clauses in brackets
errorCode indicates an error code, if any, for troubleshooting, if an error occurred. NoError is displayed if there were no errors; other error indicators are also self-explanatory
A sample Delete response
Response:
[
{
"email": "organizer@domain.com",
"errorCode": "NoError"
},
{
"email": "test1@domain.com",
"errorCode": "NoError"
},
{
"email": "test2@domain.com",
"errorCode": "ErrorMailRecipientNotFound"
}
]
We would love to hear from you