Zephr User Guide

Salesforce

0 views 0

This page provides information on the Salesforce Extension for Zephr. The plugin allows you to share user and product information between Zephr and 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.

Salesforce OAuth Details

First, click Salesforce OAuth Details. Here, you’ll need to input the following information:

  • Username
  • Password
  • Client ID
  • Client Secret
  • A token URL

If you do not have OAuth credentials, you will need to create them in Salesforce. Refer to the Salesforce Help Section for details on how to do this.

Once added, click Done.

Identity

In this section, enter the Email Verification Redirect. This is the redirect path that should be used for email verification emails delivered by Salesforce.

Once added, click Done.

Webhook Configuration

Communications from Salesforce back to Zephr are handled by issuing webhooks from Salesforce for which your Zephr tenant will listen. To help secure these webhooks, you will need to provide a secret on each webhook: the secret that Zephr will expect to receive with any webhook from Salesforce is configured here. It is recommended to use a secret that is both URL-safe and hard to guess: a UUID (v4) is ideal.

Once added, click Done.

Salesforce Integrations

On the Salesforce Integrations page, you’ll see a list of checkboxes. These checkboxes provide details on the different data flows that can take place out-of-the-box between Salesforce and Zephr.

A note on Zephr users and Salesforce Contacts/Leads: Zephr does not distinguish between Contacts and Leads in the way Salesforce does. As such, we have provided configuration options so that upon the creation of a Zephr user, the user can be synced to Salesforce as either:

  • A Salesforce Contact
  • A Salesforce Lead
  • Both a Salesforce Contact and a Salesforce Lead

Below are details on each of the options:

After a user is created in Zephr, Zephr will:

  • Check Salesforce for a Contact with the Zephr User’s email
  • If found, save the Salesforce ID to the Zephr User’s Extended Profile
  • If not found, create a Salesforce Contact

Push user changes in Zephr to Salesforce contacts

After a user is updated in Zephr, Zephr will:

  • Check for a Salesforce ID in the Zephr User’s Extended Profile
  • If found, update the Salesforce Contact
  • If not found, check Salesforce for the Zephr User’s email address
    • If found, update the Salesforce Contact
    • If not found, create a Salesforce Contact

Delete Contact on Zephr User “Forget Me”

After a user is deleted in Zephr via the “Forget Me” API, Zephr will:
  • Check for a Salesforce ID in the Zephr User’s Extended Profile
  • If found, delete the corresponding Salesforce Contact

Sync Purchases to Zephr

This will allow Purchases added in Salesforce to sync to Zephr Products, in turn granting Zephr Users access to content in line with the access rules you put in place. In order for this to work, you will need to add a mapping, which can be done in the Mapping tab of the Salesforce Configuration page within your Admin Console. See ‘Mappings between Zephr and Salesforce’ below for example mappings.

Allow Salesforce to push changes to Zephr Users

This will allow updates made in Salesforce to Contacts to also be made to the corresponding Zephr User. A mapping will be required for this. See ‘Mappings between Zephr and Salesforce’ for an example.

Create Lead on Zephr User Registration

This will create a Lead within Salesforce at the point that a User is created within Zephr. A mapping will be required for sharing information between the User and the Lead. See ‘Mappings between Zephr and Salesforce’ for an example.

Check each option that is relevant to your integration, and click Done.

Salesforce/Blaize Mapping

Here you’ll require a series of JSON mappings between Salesforce and Zephr in order to share information between the two systems. This includes mappings for:

  • Zephr Users to Salesforce Contacts
  • Zephr Users to Salesforce Leads
  • Salesforce Contacts to Zephr Users
  • Product ID Mapping

Enter your mappings as required, and click Done.

Example Zephr User to Salesforce Contact Mapping

Within the ‘attributes’ and ‘identifiers’ blocks, the format is 'zephr_key': 'salesforce key'

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

Example Zephr User to Salesforce Lead Mapping

The format for this is generally 'zephr_key': 'salesforce_key'. The exception to this is the ‘always_include’ block which notes static values to apply to Salesforce attributes (these will be applied to each Lead created).

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

Salesforce Contacts to Zephr Users

The format within the ‘attributes’ and ‘identifiers’ blocks is 'salesforce_key': 'zephr_key'.

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

Example Product Mapping

The format is 'zephr_product_id': 'salesforce_product_id'. Note: the Zephr Product ID is sometimes referred to as the ‘slug”.

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

Activate Plugin

Once you’ve input the relevant details, confirm which of your Sites the extension should be active on. To do this, use the toggles for each site under the Activate Plugin section, or choose Select All Sites.

Mailchimp - Plugin Activation

Once completed, click Save. Your extension is now enabled and will transfer data between Salesforce and Zephr based upon your integration preferences.

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
Authorization: Basic Auth
POST: https://admin.staging.demo.zephr.com/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"
}

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
Authorization: Basic Auth
POST: https://admin.staging.demo.zephr.com/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
Authorization: Basic Auth
POST: https://admin.staging.demo.zephr.com/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
Authorization: Basic Auth
POST: https://admin.staging.demo.zephr.com/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"
}