Skip to content

Revenue Grid 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 Revenue Grid:

  • 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 Revenue Grid article for more information on using Salesforce Lightning Scheduler

 

Revenue Grid 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 Revenue Inbox 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 Revenue Grid Org which the attendees belong to
  • Revenue Grid 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 Revenue Grid 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 Revenue Grid Org
  • Revenue Grid 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 Revenue Grid 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 Revenue Grid 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 Revenue Grid 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": "[email protected]",
        "serviceResourceId": "123",
        "isOrganizer": true
    },
    {
        "email": "[email protected]",
        "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": "[email protected]",
        "serviceResourceId": "123",
        "isOrganizer": true
    },
    {
        "email": "[email protected]",
        "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": "[email protected]",
    "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": "[email protected]",
            "isRequired": "true",
        },
        {
            "email": "[email protected]",
            "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": "[email protected]",
        "errorCode": "NoError"
    },
    {
        "email": "[email protected]",
        "errorCode": "ErrorMailRecipientNotFound"
    },
    {
        "email": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
                "isRequired": "true",
            },
            {
                "email": "[email protected]",
                "isRequired": "false",
            }
        ]
    },
    "new": {
        "organizerEmail": "[email protected]",
        "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": "[email protected]",
                "isRequired": "true",
            },
            {
                "email": "[email protected]",
                "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": "[email protected]",
        "errorCode": "NoError"
    },
    {
        "email": "[email protected]",
        "errorCode": "NoError"
    },
    {
        "email": "[email protected]",
        "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": "[email protected]",
    "attendees": [
        "[email protected]",
        "[email protected]"
    ]
}

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": "[email protected]",
        "errorCode": "NoError"
    },
    {
        "email": "[email protected]",
        "errorCode": "NoError"
    },
    {
        "email": "[email protected]",
        "errorCode": "ErrorMailRecipientNotFound"
    }
]

 

 


Get back to us
We would love to hear from you

Name:

E-mail:

Question or comment: