Integration Details

Admin

Created June 30, 2023 08:11. Last Updated November 07, 2023 05:31

Table of Contents

Overview
1. Sending data to WorkSpan
2. Receiving data from WorkSpan
3. Integration status fields

Overview

The solution is aimed at integrating WorkSpan Ecosystem with Salesforce. More specifically—provide a mechanism to share Opportunity data with Partners in the WorkSpan system. The data is shared in the form of Referral objects that could be created from the Salesforce opportunity records. Referrals also could be received from WorkSpan.
A big part of the solution is bi-directional integration between Salesforce and WorkSpan, with both systems pushing updates to each other (see the diagram below).

1. Sending data to WorkSpan

Salesforce → WorkSpan sync is run on every change of the Referral field that is marked to be sent to WorkSpan (see Configure which fields to send to WorkSpan). Changes are detected by an apex trigger on the Referral object, which queues an asynchronous REST request to go out to the connected WorkSpan environment. Usually, this request will be executed within seconds, but Salesforce doesn’t guarantee that. Multiple consecutive updates will enqueue multiple consecutive requests.
For the generic use cases, only data from the Referral record is uploaded to WorkSpan (with a single exception: the Partner ID is taken from the Partner record that is linked to the Partner Referral record that is linked to the current Referral). For data consistency, all fields marked to be sent are added to the payload with every request, regardless of whether they were changed or how and by whom this change was triggered.

1.1. Sending Microsoft data to WorkSpan

In the Microsoft Partner Center (MPC) flows, it is required to send to WorkSpan the Solution ID values of all the MicrosoftSolution__c records linked to the Referral. So, whenever sending a Referral to WorkSpan, the package also goes through all related ReferralMicrosoftSolution__c junction records and collects all the Solution ID values from the “main” MicrosoftSolution__c records into an array. This array is then put into the msft_solutions field in the payload.

Also, no data will be sent to MPC from WorkSpan if Ready For Submit = ‘No’ on the Outgoing Referral. Ready For Submit can be set to ‘Yes’ either right from the creation as a default value or by the user clicking the Submit Referral button. However, the Ready For Submit value does not affect the exchange between Salesforce and WorkSpan: the data is sent to WorkSpan regardless of the field’s value.

1.2. Sending Amazon data to WorkSpan

During the Outgoing Amazon Referral flow, no data will be sent to AWS from WorkSpan if Ready For Submit = ‘No’ on the Outgoing Referral. Ready For Submit can be set to ‘Yes’ either right from the creation as a default value or by the user clicking the Submit Referral button. However, the Ready For Submit value does not affect the exchange between Salesforce and WorkSpan: the data is sent to WorkSpan regardless of the field’s value.

1.3. Sending Google data to WorkSpan

For the Google Referrals, no data will be sent to Google from WorkSpan if Ready For Submit = ‘No’ on the Outgoing Referral. Ready For Submit can be set to ‘Yes’ either right from the creation as a default value or by the user clicking the Submit Referral button. However, the Ready For Submit value does not affect the exchange between Salesforce and WorkSpan: the data is sent to WorkSpan regardless of the field’s value.

1.4. Sending SAP data to WorkSpan

For the SAP Referrals, no data will be sent to SAP from WorkSpan irrespective of wether Ready For Submit is ‘Yes’ or ‘No’.

2. Receiving data from WorkSpan

WorkSpan → Salesforce integration is implemented with a custom REST resource, which ingests JSON payload to create/update Referral records, create/update child partner referral records, and create new Partner records. If WorkSpan sends to Salesforce some fields that are not part of the data model, those fields are ignored. If WorkSpan sends to Salesforce some fields in the “custom_fields” section of the “partner_referral” section of the JSON, those fields are put in the Partner Custom Fields field on the Partner Referral record as plain text {value, name} pairs to be displayed in the [Partner Name] Custom Fields section. If WorkSpan sends to Salesforce a Partner ID that does not match any of the existing Partner records in the org, then the REST resource creates new Partner records with these IDs.

WorkSpan runs the sync on schedule (configurable in WorkSpan). The expected rate does not exceed 10,000 calls to Salesforce API daily.

There is a built-in mechanism to prevent redundant calls back to WorkSpan if incoming data is the only change made to the Referral record.

2.1. Receiving ‘draft’ Referrals

If a Referral is created in WorkSpan with Ready For Submit = ‘No’, then it is considered a ‘draft’ Referral, in the sense that it doesn’t need to be fully valid until it is time to submit it. But this is only true when a Referral is created/updated from WorkSpan using API (or during auto-creation or during bulk creation—if an additional condition is met). A user manually creating or editing a Referral is not allowed to skip most of the validations, regardless of the default Ready For Submit value. This means that it is possible that WorkSpan can create a Referral in Salesforce which a user will not be able to edit until meeting all the validation criteria.

2.2. Receiving Microsoft Solutions from WorkSpan

In the Microsoft Partner Center (MPC) flows it is required to receive from WorkSpan the Solution ID values of all the MicrosoftSolution__c records linked to the Referral. So, whenever receiving a Referral from WorkSpan, if the msft_solutions field is not empty, then the package parses its value into a set of IDs. Then (the same way it happens with Partner IDs), with each ID, it goes through existing “main” MicrosoftSolution__c records that are junctioned to the Referral. If none of them has it in the Solution ID field, it searches all MicrosoftSolution__c records in the org. If there is a record with this ID—it is junctioned to the Referral. If there isn’t—it creates a new MicrosoftSolution__c record with Solution ID = this ID and Name = this ID. Then junctions this new MicrosoftSolution__c record to the Referral.

If WorkSpan, for some reason, sends us duplicate Solution ID values in the same payload, then only one is processed, and repeating values are ignored.

3. Integration status fields

There is a set of system fields on the Referral object to track the integration status in several ways: from Salesforce to WorkSpan (Last Sync From Salesforce XX fields), from WorkSpan to Salesforce (Last Sync From WorkSpan XX fields), between WorkSpan and Amazon (AWS Integration XX fields), and between WorkSpan and Microsoft (Microsoft Integration XX fields). The Last Sync From Salesforce XX and Last Sync From WorkSpan XX fields are populated by the package, logging what’s happening. The AWS Integration XX and Microsoft Integration XX fields are populated with the data that is only sent from WorkSpan. This means if the fields are not populated—not necessarily something is wrong or nothing is wrong. Maybe WorkSpan just didn’t send the field values to Salesforce.

For each individual Referral, you can see the status response for the last request, the date/time when it was received, and the accompanying message (if there was any).

A quick visual summary of these fields is displayed in the Integration Status LWC.