Salesforce

Configuring the Salesforce Extension

To enable the Salesforce Extension within Zephr, navigate to Settings > Extensions > Salesforce. If you cannot see the Salesforce option in your list of Extensions, email support@zephr.com.

Once on the configuration screen, you’ll see a number of sections – Salesforce OAuth Details, Identity, Webhook Configuration, Salesforce Integrations, Salesforce/Blaize Mapping and Activate Plugin.

{
    "attributes": {
       "first-name": "FirstName",
       "last-name": "LastName"
    },
    "identifiers": {
       "email_address": "Email"
    },
    "email_verified": "CustomSalesforceEmailVerifiedField"
}

{
    "always_include": {
       "Blaize_Registered_User__c": true,
       "LeadSource": "Website Registration"
},
    "attributes": {
       "first-name": "FirstName",
       "last-name": "LastName"
},
    "identifiers": {
       "email_address": "Email"
},
    "email_verified": "CustomSalesforceEmailVerifiedField",
    "tracking_id": "Blaize_Tracking_Id__c",
    "user_id": "Blaize_User_Id__c"
}

{
     "attributes": {
       "FirstName": "first-name",
       "LastName": "last-name"
     },
     "identifiers": {
       "Email": "email_address"
     }
 }

{
    "product-one": "01234ABC",
    "product-two": "56789DEF"
}

Integrating Zephr within Salesforce

Certain aspects of the Zephr and Salesforce integration will require you to set up webhooks and triggers within Salesforce – for example, if you wish to update a User in Zephr when their corresponding Contact is updated in Salesforce.

Below is the URL and format that needs to be called when setting these up, along with a list of event names that can be called in order to trigger different events within Zephr. For information on how to add webhooks within Salesforce, consult the Salesforce Help Section.

URL and Format to Call:

/plugins/salesforce/webhooks?event={eventName}&code={secretCode}

Note: secretCode references the Webhook Secret set in your configuration of the Salesforce plugin above.

createUser

This is used to create a user within Zephr when a Contact is registered within Salesforce. This will:

• Check Zephr for a Salesforce Contact’s Email
  • If found this will:
    • Update the Zephr User
    • Save the Salesforce ID to the Zephr User’s Extended Profile

• • If not found this will:
    • Create a Zephr User
    • Save the Salesforce ID to the Zephr User’s Extended Profile

Example:

Content-Type: application/json
POST: /plugins/salesforce/webhooks?event=createUser&code=bf6414ce-1221-4a90-a9f2-975c67288abe

Note: The body must include the productId, email and contactId.

{
    "Id":"<id>",
    "Email":"<email>",
    "<mapped_attribute_1>": "<mapped_attribute_1_value>",
    "<mapped_attribute_2>": "<mapped_attribute_2_value>",
    "<mapped_attribute_3>": "<mapped_attribute_3_value>"
    ...
}

So, for example, where FirstName and LastName are values in the mapping config (please see the example in ‘Salesforce Contacts to Zephr Users’ above), the body would look like so:

{
    "Id": "<id>",
    "Email": "<email>",
    "FirstName": "<first_name>",
    "LastName": "<last_name>"
}

updateUser

This is used to update a User within Zephr when the corresponding Contact is updated within Salesforce. This will:

• Map the Salesforce Product ID to a Zephr Product ID
• Check Zephr for the Salesforce Contact’s email
  • If found this will:
    • Purchase the Zephr Product
    • Update the Zephr User’s Extended Profile with Product Grants
  • If not found this will:
    • Create a Zephr User
    • Purchase the Zephr Product
    • Update the Zephr User’s Extended Profile with Product Grants

Example:

Content-Type: application/json
POST: /plugins/salesforce/webhooks?event=updateUser&code=bf6414ce-1221-4a90-a9f2-975c67288abe

Note: The body must include email and contactId

{
    "Email": "frank@zephr.com",
    "contactId": "384975982743985234"
}

Or

{
    "Id": "384975982743985234",
    "Email": "frank@zephr.com",
    "FirstName": "Frank",
    "LastName": "Blaize",
    "MailingStreet": "1 Frank Street",
    "MailingCity": "London",
    "MailingState": "",
    "MailingPostalCode": "EC4A 2DQ",
    "MailingCountry": "United Kingdom",
    "Phone": "+441234567891",
    "JobTitle": "Blaize",
    "contactId": "384975982743985234"
  }

buyProduct

This is used to add a product grant to a Zephr User when a product or subscription is added to the corresponding Salesforce Contact – for example if an in-house sales teams makes a sale over the phone, and adds the customer’s subscription manually. This will:

• Map the Salesforce Product ID to a Zephr Product ID
• Check Zephr for the Salesforce Contact’s Email
  • If found this will:
    • Grant the user access to the Zephr Product
  • If not found this will:
    • Create a Zephr User
    • Grant the user access to the Zephr Product

Note: If the mapping between the Salesforce Product ID fails (due either to an error in the webhook payload, or an error in the plugin configuration), an error will be returned and the user will not be created (if they did not exist already).

Products to be purchased for a user can be submitted in 3 different ways:

1. As a string representing a single Salesforce product ID using the `productId` field. Any successful product purchases will have a starting time matching the time that Zephr received the webhook and no ending time (the user’s access will continue until cancelled).
2. Multiple strings representing Salesforce product IDs may be supplied in a JSON array with the `productIds` field. Any successful product purchases will have a starting time matching the time that Zephr received the webhook and no ending time (the user’s access will continue until cancelled).
3. As an array of objects to the `products` field. This option allows the caller to optionally specify start and end times for a product grant. Dates should be supplied as strings and will be parsed as a Javascript Date(). It is recommended to supply date strings in ISO 8601 to avoid ambiguity and for maximum precision.

Example:

Content-Type: application/json
POST: /plugins/salesforce/webhooks?event=buyProduct&code=bf6414ce-1221-4a90-a9f2-975c67288abe

Note: The body must include the email, contactId and one of the ‘productId’, ‘productIds’, or ‘products’.

{
    "productId":"7011o0000011UsOAAU",
    "email":"emaill@email.com",
    "contactId":"0031q00000EC3YNAA1"
}

Example with start and end times for products:

{
    "contactId": "7011o0000011UsOAAU",
    "email": "email@email.com",
    "products": [
        {
            "id": "abc123",
            "start_time": "2020-10-15T23:06:59.000Z",
            "end_time": "2021-10-15T23:06:59.000Z"
        },
        {
            "id": "56789DEF",
            "start_time": "2020-10-15T20:06:59.000Z",
            "end_time": "2020-11-15T20:06:59.000Z"
        }
    ]
}

Note: the `id` field is the only required field in each product object. Products with or without start/end times may be mixed and matched as desired within the `products` field. Any products that do not state end times will provide access indefinitely (until explicitly cancelled).

cancelProduct

This is used to remove a product grant from a Zephr User when a product or subscription is removed from the corresponding Salesforce Contact – for example if a user has phoned the customer service team asking to put a hold on their subscription. This will:

• Check Zephr for the Salesforce Contact’s Email
  • If found this will:
    • Check for Product Grants in Zephr User’s Extended Profile
    • Revoke the matching Product ID
    • Update the Zephr User’s Extended Profile with remaining Product Grants

Example:

Content-Type: application/json
POST: /plugins/salesforce/webhooks?event=cancelProduct&code=bf6414ce-1221-4a90-a9f2-975c67288abe

Note: the body must include the productId, email and contactId

{
    "productId":"701240000009JyLAAU",
    "email":"email@world.com",
    "contactId":"0031q00000925cVAAQ"
}