Skip to main content
menu-icon.png

 

x
Optimizely Knowledge Base

Variations in OpX

Variations define how users will experience your experiment. Just like in Optimizely, each variation is a different version of a Salesforce experience (for example, a particular page layout) that will be delivered to the users included in your experiment. In the process of building your variations, you’ll create both variation records and variation experiences.

Create a variation record

The first step will be creating a new variation record. To do so, follow these steps:

  1. First, open the experiment that will include the new variation. From the variations list, click New.

If the experiment is running or archived, update its status to Paused before creating a new variation.

  1. Fill out the required fields (marked with a red asterisk * ).

Optimizely will automatically generate a unique variation ID and variation key when you save the new variation. For this reason, we do not recommend manually filling in these fields. 

  • The Experiment field will be automatically populated with the appropriate experiment ID. Do not modify this field.

  • The API Name field will appear if you are running an experiment with the subtype set to Lightning Page Builder or Flow Builder:

    • If you are running a Lightning Page Builder experiment, enter an API Name of your choosing. You will copy this API Name and paste it into the Lightning Page Builder template when it’s time to create the variation experience.

    • If you are running a flow experiment, open the Flow Builder and copy the flow API name of the flow that will be associated with this variation record. Then paste that value into the API Name field.

  1.  When you’re done, click Save.

Below is an example of a completed variation record.

Change a variation’s status

A variation’s status can be set to Active, Paused, or Archived. When you activate an experiment, it must have at least one active variation.

If you change the status of a variation to Paused, the system will automatically reset the traffic distribution for that variation to 0%. You will have to manually update the other variation’s traffic distributions accordingly.

Change a variation’s traffic distribution

You can control the percentage of users who see each variation by modifying the Traffic Distribution % field. This will adjust the relative distribution of each variation to users bucketed into a particular experiment.

The sum of traffic distribution percentages across all active variations in an active experiment must equal 100%. You can change traffic distribution when the experiment’s status is set to Not Started or Paused. Just be sure total distribution adds up to 100% before reactivating your experiment. 

Create variation experiences

The variation experience is what your users see. You can create variation experiences from templates provided by Optimizely, or you can use custom Apex code. 

In this section, we review common variation experiences you can easily create using the two unmanaged package templates provided by Optimizely:

  • Lightning Page Layout Experiment Builder, and

  • Lightning Flow Builder Experiment Builder

Optimizely provides experiment builder templates as part of our unmanaged package. However, if your organization is unable to install unmanaged packages, or if you prefer to create your own experiment builder templates, we recommend that you do the following:

  1. Install Optimizely's DNA app and Optimizely's unmanaged package in a developer org. This could be your own developer sandbox org, or use Salesforce DX.
  2. Pull Optmizely's templates into your repository. You can use the template in a Git repository as a reference point for what you would like to build against.
  3. Test in a QA org before migrating to production

Optimizely also provides Salesforce global classes that provide invocable methods, making it easy to call Optmizely’s Agent API to run Flow and custom-back end experiments against. Learn how to do this in the "Invocable Operations" section at the end of this "Variations in OpX" guide.

Create a page layout experiment

You can use Optmizely’s Lighting Page Builder template to create different iterations of page layouts. To use the template, your team must install an unmanaged package provided by Optimizely. The following steps guide you through how to create multiple custom page layouts for an experiment or for feature management.

Step 1: Configure the experiment and associated records

Before you use the Lightning Page Builder template, be sure your experiment records have been configured properly.

  1. Create an experiment record with the subtype set to Lightning Page Builder.

  1. Complete all required experiment record fields and configure all associated records—events, metrics, etc.

  2. Update the experiment record’s status to Running.

    • This makes sure you can associate the experiment with the variation experience you are about to create. 

    • This step will not actually change what your users see—for that to happen, you’ll have to finish the steps that follow and then complete the layout activation process.

Step 2: Create a Lightning Page Builder template

Once you have activated the associated experiment, you can create the template you will use to create your layouts:

  1. Open Salesforce Setup, then search for and click Lightning App Builder.

    • You can also accomplish this from within a record itself: 

      1. Click Setup

      2. Click Edit Page.

      3. From the Pages dropdown menu, click + New Page.

  2. From inside the Lightning Pages pane, click New.

  1. Click Record Page, followed by Next.

  1. In the appropriate field, enter a label. We recommend entering the Optimizely experiment name from the associated experiment record.

  2. Select Object (for example, Case.)

  1. Choose Lightning Page Builder Template under Custom.

  2. Click Finish.

Step 3: Create custom layouts and assign your custom page

The Lightning Page Builder template allows you to create up to three page variations. These will be the variation experiences linked to your experiment.

To create a custom layout, follow these steps:

  1. From the custom component list in the left-hand panel, drag Lightning Page Builder Setup to the top section of the page where Add Component(s) Here appears.

  1. At this point, Add Component(s) Here will be replaced with Click to configure; click this to continue. A new control panel on the right side of the screen will appear.

  2. In that new control panel, click inside the Experiment field to select the experiment record you’ll link to this variation experience.

If your experiment does not appear in the Experiment field, visit the record and ensure its status is set to Running.

  1. Open the first variation record listed in the experiment record (this should be your default variation) and copy the API name. (We recommend opening this in a separate browser tab instead of navigating away from App Builder.)

  1. Paste the API name into the Variation 1 API Name field in the Lightning Page Builder template. The API name must be copied exactly.This will create a new layout selector with a corresponding API name in the left side of the layout editor.

If, at any point, you modify the API name in your variation record, you must make a corresponding update to the API name in the Lightning Page Builder template. Otherwise, your experiment will not run correctly.

  1. Repeat the previous two steps for each variation record in your experiment.

If you only have two variation records, leave the Variation 3 API Name and Variation 3 Layout Type fields empty.

  1. Using the Variation X Layout Type field, select the desired layout style for each variation.

  2. In the layout editor, click the first variation API name in the list to design the page for that variation.

  1. Design the page using the available components.

  2. Repeat the entire process for each of the other variations.

  1. Click Save as needed throughout the process.

  2. When ready, click Activation to assign your customized page.

  3. Complete QA/QC on your experiment.

Your experiment is now fully configured, running, and validated to be operating properly.

  • Once an experiment has been activated, you do not need to reactivate again later, even if you paused or archived the experiment. Activation simply determines which users will see the variation experience.

  • Do not add the ‘Flow Builder’ custom Lightning component to the Lighting Page Builder template. The app does not support running an experiment within another experiment.

Variation, Region and Component Support

A Lightning page region can contain up to 100 Lightning Web Components (LWC) and Aura Lightning Components. A template component can contain up to 25 Lightning page regions. 

With OpX Lighting Page Builder, you can create up to three page variations. The total number of variations you have affects the total number of regions and Lightning Web Components supported:

    • 2 page variations

      • up to 12 regions each

      • up to 1,200 LWC/Aura Components across the 12 regions

    • 3 page variations

      • up to 8 regions each

      • up to 800 LWC/Aura Components across the 8 regions

The number of available regions in the Lightning Page Builder does not switch automatically to 12 if you use only two variations instead of three. The template component regions must be set up manually by a developer in order to change region configurations. Here is the Salesforce developer guide on template components: step 2 has a detailed explanation on configuring template regions.

Create a flow experiment

You can use Optmizely’s Flow Builder template to create different iterations of flows. To use the template, your team must first install an unmanaged package provided by Optimizely. The following steps will guide you through the process of creating multiple custom flows for an experiment or feature management.

Step 1: Configure your experiment and any associated records

Before you use the Flow Builder template, be sure your experiment records have been configured properly.

  1. Create an experiment record and set the subtype to Flow Builder.

Optionally, you can create the variation records for the experiment before completing the steps below, but you will need to update the API Name for those records when you create flow variations.

  1. Complete all required experiment record fields and configure all associated records — events, metrics, etc.

    Do NOT activate the experiment record at this stage. You must create your flow variations first.

Step 2: Create flow variations

  1. Open Salesforce Setup.

  2. Search for and click on Flows.

Optimizely’s unmanaged package includes sample flows that can be used for testing.

  1. Click New Flow to create a new flow (for example, a new call center flow script).

  1. Define your flow and click Activate when you’re ready.

  1. Create any desired subflows for this flow. The flow and any associated subflows collectively represent one variation experience, which you will associate with one variation record in an experiment.

  2. Create and activate additional flows and associated subflows that you’d like to associate with each variation record.

  3. Click the gear icon in the list view of flows; then click Select Fields to Display

  4. Add Flow API Name. We recommend placing this directly next to Flow Label for ease of use.

  1. Copy the flow API name of the first flow (your default variation) you would like to include in your experiment.

  1. Open the first variation record listed in the associated experiment record and paste the Flow API Name value into the API Name field. (We recommend opening this in a separate browser tab instead of navigating away from Flow Builder.)

If, at any point, you modify the flow API name in Flows Setup, you must make a corresponding update to the API name in the associated variation record. Otherwise, your experiment will not run correctly.

  1. Repeat this entire process for each flow and variation record.

  2. Update the status of the experiment record to Running. This lets you associate the experiment with the variation experience you are about to create.

Changing the status of the experiment record to running will not change what your users see. You’ll have to finish the steps that follow and complete the layout activation process first.

Step 3: Add Flow Builder component to a page and assign your page

Next, you will configure the variation experience for your flow experiment.

  1. Open Salesforce Setup.

  2. Click the Object Manager tab.

  3. Select the object where you would like to place the flow variations (for example, Case).

  4. Select Lightning Record Pages and click Edit. Alternately, visit the object where you would like to place the flow (e.g. open an existing case), then click setup and select Edit Page.

  5. Under the Components selector, select Flow Builder from the custom components list.

  1. Place the Flow Builder component on the page as desired.

  2. Click into the Flow Experiment field to select the experiment record that you will link to this variation experience.

If your experiment does not appear, visit the record and make sure its status is set to Running.

  1. For the Experiment Subject field, choose your desired subject.

The subject must be set to Current Record if the custom flow component is placed on the home or app page.

  1. For the Heading field, choose the desired text that should be displayed at the top of the flow.

  1. When ready, click Activation to assign your customized page.

  2. Complete QA/QC on your experiment.

Your experiment is now fully configured, running, and validated to be operating properly.

Invocable Operations

Optimizely provides Salesforce global classes that provide invocable methods so that you can optionally call Optmizely’s Agent API to run Flow and custom-back end experiments against. The experiment templates covered in the previous sections are just example customizations that execute platform events.

Attribution Request

The AttributionRequest class has an invocable method labeled “Bucket into Experiment”. The purpose of this method is to provide you with the ability to call out to Optimizely with Salesforce Org-specific data concerning a Lead or Contact record. 

This invocable method takes three parameters:

  1. RecordID

    • This required parameter is where you pass in a single Lead or Contact Id.

    • This parameter only takes a single RecordID. Since this invocable method is making an API call to the Optimizely Agent API and the invocable method can be leveraged in a process builder, we have moved the API call to a QueueItem class where bulkification is managed. 

  2. Experiment Key

    • This required parameter is in the Optimizely Experiment Key

  3. Enforce Validations

    • This boolean is not required.

    • When set to False (the DEFAULT operation and recommended for most situations), your process will run without interruption regardless of whether you provide an invalid experiment Key or your experiment is no longer set to Running. Any errors will appear in your Logs (visit Logs within the Optimizely app). 

    • When set to True, your process will NOT run if there is an invalid experiment Key or your experiment is no longer set to Running. For example, if you were to try to create a new web Lead as part of the example described above, and the experiment is Paused, a Lead will not be created and an error message will be shown.

When you invoke an Apex class to make a call out to Optimizely, Optimizely will return a decision event indicating which variation should be served. The OpX app maps this response to an associated Variation API Name. Your team will define this parameter for each Flow and in the app Variation Record:

Leveraging Invocables

There are two ways you can leverage the invocable methods provided within our application: programmatically (custom Apex) and declaratively (Process Builder paired with Flow Builder).

In parallel, regardless of which approach you take, you will use Optimizely’s app to create and manage Project, Experiment, Variation, Event, and Metric records — the first step of any experiment is to create these records. 

When creating the Experiment record for an experiment that will use the invocable method for an Autolaunched flow, set the experiment subtype to, “Autolaunched Flow”.

When creating the Experiment record for an experiment that will use the invocable method for an experiment that is not an Autolaunched flow, set the experiment subtype to, “Screen Flow” or “Lightning Page Builder” — depending on the Flow you are setting up.

Process Builder - Declarative

You can create Flow experiments by pairing Process Builder with Autolaunched Flows. When building your “AutoLaunched Flow” there is a required input parameter that you must have present within your custom flow, and it must be formatted as such: recordId (this of the Lead or Contact ID). 

You can invoke our Apex class using Process Builder, that will make a call out to Optimizely, and the decision event response specifies which Autolaunched Flow variation should be served. When a decision event is returned, the OpX app automatically maps the decision event to the variation API Name specified for your Flow and specified in your experiment’s associated variation record. This operation will run the custom flow you built, and designated within the Experiment’s Variation API Name field.

Here is how to configure Process Builder:

  1. Open Process Builder

  2. Designate the business logic will trigger an action related to a Lead or Contact

    • e.g. Set your logic to apply this update to any Lead with the source set to “Web”.

    • Be sure that your configurations within the Process Builder are set up to only fire when the intended change is made; and not every time a change is made within a record that has a status of interest. 

  3. Click Immediate Actions

    • Select the option, Run Apex

    • Choose Apex Class: Bucket Into Experience

    • Enter the Experiment Key for the Experiment that you want to bucks the visitor into — retrieve this from Experiment record under “Key”

    • Enter recordId field reference

      • The recordId will be either a lead or contact Id depending on which object is triggering the bucketing request — e.g. [Lead ID] if a Lead or [Contact ID] if a Contact

    • Modify the validation enforcement, if desired (not recommended)

  4. Activate the process

When Optimizely’s Agent responds with a decision event, it will specify which variation should be used. 

If you plan to use a Flow to leverage an invocable method, any user of the Flow must have permissions to Optimizely's Apex classes in order to leverage the invocable methods in the class. Additionally, your flow will not actually invoke Optimizely's methods until the Flow is completed - so calls to Apex classes do not occur from paused Flows or during the actual Flow itself. 

Get a Decision Event Using Apex

Below are code examples for programmatic experimentation. You’ll receive a response with the Variation that is assigned and then take action based on the response — your team will be responsible for handling the variation that should be served to the end-user.

Note, when you generate the Visitor ID, you’ll need to store it first before making an API request.

Without the Invocable Method

Below is an example of how to generate a VisitorID and get a decision when using the Lead or Contact object.

private static String getVariationKey(String experimentKey,Id leadOrContactId) {
  String visitorId = null;
  Boolean updateLeadOrContact = false;
  //Attempt to get existing visitorId from lead or contact
  if(leadOrContactId.getSobjectType() == Lead.getSObjectType()){
      visitorId = [SELECT Id,optimizely_dna__Visitor_Id__c From Lead WHERE Id =:leadOrContactId Limit 1][0].Visitor_Id__c;
  }
  if(leadOrContactId.getSobjectType() == Contact.SObjectType){
      visitorId = [SELECT Id,optimizely_dna__Visitor_Id__c From Contact WHERE Id =:leadOrContactId Limit 1][0].Visitor_Id__c;
  }
  //If visitorId is still null, generate new one
  if(visitorId == null){
      visitorId = optimizely_dna.OpXClient.generateVisitorId();
      //Set flag to true to update record
      updateLeadOrContact = true;
  }
  String variationKey;
  optimizely_dna.OpXClient.VariationRequest request = new optimizely_dna.OpXClient.VariationRequest(
          visitorId,
          experimentKey
  );
  optimizely_dna.OpXClient.VariationResponse response = optimizely_dna.OpXClient.getDecisionEvent(request);
  if (response.variationKey != null) {
      variationKey = response.variationKey;
  } else if (response.errorMessage != null) {
      throw new AuraHandledException(response.errorMessage);
  }
  if(updateLeadOrContact){
      //Update Lead or Contact with visitor Id
      String objectName = leadOrContactId.getSobjectType().getDescribe().getName();
      sObject sObj = Schema.getGlobalDescribe().get(objectName).newSObject();
      sObj.put('optimizely_dna__Visitor_Id__c',visitorId);
      update sObj;
  }
  return variationKey;
}

Below is an example of how to generate a VisitorID and get a decision when using a Salesforce User rather than a Lead or Contact object.

/**
* builds variation request with visitor id and experiment key,
* returns experiment key from OpX decision event
*
* @return  {String}   variation key
*/
private static String getVariationKey(String experimentKey) {
  String visitorId = optimizely_dna.OpXClient.generateVisitorId('User');
  String variationKey;

  optimizely_dna.OpXClient.VariationRequest request = new optimizely_dna.OpXClient.VariationRequest(
      visitorId,
      experimentKey
  );
  optimizely_dna.OpXClient.VariationResponse response = optimizely_dna.OpXClient.getDecisionEvent(request);

  if (response.variationKey != null) {
      variationKey = response.variationKey;
  } else if (response.errorMessage != null) {
      throw new AuraHandledException(response.errorMessage);
  }

  return variationKey;
}

With the Invocable Method

In order to make the invocable methods available, their classes were made global, so you can access them from your own custom Apex implementations. Each of the above mentioned invocable methods provide details on what the method is used for and the parameters it takes. 

When leveraging this invocable method programmatically, be sure you are not iterating through your collection of Leads or Contacts when using the invocable method. You should bulkify your programmatic submission to the invocable. 

Here is the code snippet that you can use to bucket into experiments from Apex:

 

//Create array

List<optimizely_dna.AttributionRequest.BucketingRequest> requests = new List<optimizely_dna.AttributionRequest.BucketingRequest>();

//Contacts or Leads can be used

for(Contact c:contacts){

    //Create single instance

optimizely_dna.AttributionRequest.BucketingRequest request = new optimizely_dna.AttributionRequest.BucketingRequest();

    request.recordId = c.Id; //Lead or Contact Id

    request.experimentKey = 'REPLACE_WITH_EXPERIMENT_KEY'; //The Optimizely Experiment Key.

    request.enforceValidation = false; //When true, validations will run.  If there is a failure, the transaction will fail right away vs silently.  The default is false

    //Add to array

    requests.add(request);

}

//Call InvocableMethod to Bucket into Experiment

optimizely_dna.AttributionRequest.process(requests);