Skip to main content
Gainsight Inc.

Add Participants to a Program

The green participants icon at the beginning of every model gives users the option to add recipients to the outreach from four potential sources: Event, Power List, CSV, and Query Builder.


Three steps are needed to complete adding Participant sources to a Program: adding Participant Sources, Filtering Criteria on Participants, and Mapping Participant Sources

Adding/Scheduling Participant Sources

Multiple sources can be selected and used in a single Program. The participants from all of the sources can be synced into a single list.

Note: Users can add multiple sources for each source type to a Program. However, the total count for adding multiple sources must not exceed the limit of five. If you need to add more than five sources, please contact Gainsight Support.

To begin adding participant sources, click the green participants icon in a Program model and then click the + SOURCE button in the Participant Source section to select a source type.



Allows users to add participants from Gainsight’s Event Framework found under Administration > Events. Events can be defined as activities that are triggered as a result of some other activity. For example: A case satisfaction survey to be sent whenever a case is closed can be configured as an event, or a notification email to be sent whenever a participant responds to a survey.

To add an event, perform the following steps:

  1. Select Events from the Add Sources (+) menu.
  2. Select the required topic from the drop-down list.
  3. Select an event associated with the topic.
    Note: Values in the Event menu are populated based on the topic selected in the previous step.
  4. Select a version associated with the event, and click SAVE. The required event is added as a participant to the outreach.
    Note: You can add only one Event source per advanced outreach.

For detailed information on the Events framework and how they are created, see the Events Framework article.

Power List 

Allows users to add participants from an existing power list. Users can add one power list per Program. For more information on how to create power lists, refer to Create Journey Orchestrator Power Lists (aka, email contact list) and Create Power List from a CSV file articles.

Power List Scheduler

Participants can be added from a Power list in one of two ways:

  • Statically, where all members of the list at the time of selection are added as participants to the Program.
  • Dynamically, where new members who later meet the criteria of the power list will be added as participants. If the dynamic option is selected, you will have access to the scheduler feature to decide when the power list will be queried for new participants. The Scheduler can be configured on a Daily, Weekly, or Monthly schedule, with a Start Date, End Date, and a Preferred Time to run the query. This schedule can be edited after the Program has been published. The outreach will follow the new schedule going forward. When the schedule runs, it will run the Power List query for new contacts to be added as participants. Each scheduling options has different selections available:
    • The Daily option allows you to select either every week day, or every day.
    • The Weekly option allows you to select which day of the week you would like to run the query.
    • The Monthly option allows you to select a specific day within the month to run the query (1st - 31st as well as the Last day of the month). You can also choose to run the query on a timed day of the week such as the 1st Sunday, or 3rd Tuesday of the month.



  • A scheduled Power list query will not run unless the Program is in the Active or Scheduled status. For more information on Program statuses, refer to Program List View and Create New Program.
  • When the Program pulls Participants from a Power list, this does not trigger a refresh process within the Power list, unless the list is configured to do so. In order to keep the Participant list as up-to-date as possible, check the Refresh the power list before Outreach/Program execution checkbox on the Power List Configuration page.
  • Power List is not supported in the Data Designer objects.

refresh power list.png

  • The Program calendar view displays refresh schedules for all Program sources alongside publishing schedules for Programs and Outreaches. For more information on the calendar view, refer to Program List View and Create New Program.


Allows users to upload participants from CSV files. You can directly upload a CSV file with a limit of 10K records per CSV, and up to 5 CSVs total can be uploaded to a Program. Users can download a CSV template from the link illustrated below:


Note: When loading participants through CSV as a source, please ensure that the SFDC Account IDs are framed with 18 characters instead of 15 characters. This will avoid potential future errors.

Query Builder

Allows users to create a bionic query that will add participants. For more general information regarding queries used with Bionic Rules, refer to Getting Started with Bionic Rules.

After selecting the Query Builder as a source, you will need to provide a name for the query builder source to proceed.


You can then add a Dataset Task to configure the source.


The query builder functionality allows users to pull in contact information using an interface identical to Bionic Rules.


Users are able to query source objects from Salesforce Data, Matrix Data, and Data Spaces. The Task Name and Output Dataset Name must be filled out before the Dataset Task can be saved. These fields allow users to differentiate between different Dataset Tasks that might be added to the query. 

Within the Show section of the Query Builder, users can select fields from the source object that they would like to reference. The data from these fields will then be available when mapping the participants later.

The Filter section of the Query Builder will set the criteria for what contacts are pulled in by the query. Only contacts that meet this criteria will be pulled in as participants.

Once the query is configured, click SAVE in the top-right to save the Dataset Task. You can also click PREVIEW to preview the results of the dataset task. This feature is designed to help admins monitor the output of each task to ensure that the configured task is accurate and meets the needs of the Program.

Clicking this option will open a pop-up window with the preview results of the task.


In addition to Dataset Tasks, you can also add Transformation, Merge, and Pivot tasks within the Query Builder by clicking +TASK

query builder pivot.png

Query Builder Scheduler

After you have configured all Tasks to be used by the query, you have the option to schedule the query to run and pull in participants. Click the SCHEDULE option in the top-right of the Participants configuration.


This schedule can be configured one of two ways:

  • Statically, where all contacts that are pulled in by the query at the time are added as participants to the Program.
  • Dynamically, where new members who later meet the criteria of the power list will be added as participants. If the dynamic option is selected, you will have access to the scheduler feature to decide when the query will run for new participants. The Scheduler can be configured on a Daily, Weekly, or Monthly schedule, with a Start Date, End Date, and a Preferred Time to run the query. When the schedule runs, it will run the query for new contacts to be added as participants. This schedule can be edited after the Program has been published. The outreach will follow the new schedule going forward. Each scheduling options has different selections available:
    • The Daily option allows you to select either every week day, or every day.
    • The Weekly option allows you to select which day of the week you would like to run the query.
    • The Monthly option allows you to select a specific day within the month to run the query (1st - 31st as well as the Last day of the month). You can also choose to run the query on a timed day of the week such as the 1st Sunday, or 3rd Tuesday of the month.

bionic rule source schedule.gif


  • A scheduled Query Builder query will not run unless the Program is in the Active or Scheduled status. For more information on Program statuses, refer to Program List View and Create New Program.
  • The Program calendar view displays refresh schedules for all Program sources alongside publishing schedules for Programs and Outreaches. For more information on the calendar view, refer to Program List View and Create New Program.
Query Builder Execution History

Admins can view the detailed logs for the activities that are performed while building and fetching data in Query Builder. Apart from logs, it also provides other details such as execution history of query builder source in programs, status, data flow diagram, and downloading option for the result set.

Beside each Query Builder source in the Participants Configuration page, an Execution History Preview option is added for admins to view the logs, history, status, and flow diagram of the Query Builder.


Admins can view the following status symbols as Execution History Preview options:

  • EH3.png - This status is displayed when the query builder source is successfully executed.

  • EH4.png - This status is displayed when the query builder source is partially executed.

  • EH5.png - This status is displayed when the execution of the query builder source has failed.


Admins can click on the Execution History Preview option to view the preview of that particular Query Builder source in the following tabs:



Query Setup Tab

In the QUERY SETUP tab, admins can view the data flow diagram of the tasks created and also the information related to each task or merge details they have provided while creating a query builder.


Execution History Tab

In the EXECUTION HISTORY tab, admins can view the execution history of all the tasks in query builder along with the following information:

  • Status of the Query Builder source.

  • Query Builder Start and End time.

  • Query Builder schedule type, either Manual or Scheduled.

Note: Admins can click the REFRESH HISTORY option to view the latest query builder executions.


Select any task in the EXECUTION HISTORY tab to view the following  output details of that task:

  • Task Type: The type of task defined while creating the Query Builder.

  • Status: The status of the Query Builder.

  • Records: The Number of records fetched for the task defined.

  • Duration: The duration of the query builder run.

  • Results: Admins can:

    • Preview Results: Click the preview icon to preview the task results in a new window. 

    • Download Results: Click the download icon to download the results of the selected task.


Click the + icon next to View Logs to view the detailed information about the execution history of the query builder.


Admins can click the EDIT option, if required, to edit the tasks in the query builder source directly from this new window.


Filter Criteria on Participants

Users have several options to further define and configure Participants.


  1. Uniqueness Criteria: Sets the field that is used to determine if an individual participant is unique from other participants. Only unique participants will be included in the outreach. This prevents contacts from being sent multiple, identical emails as part of the outreach.

    When selecting Uniqueness Criteria for Programs, Admins can decide if contacts with the same Uniqueness Criteria can only be added to the Participant Lifecycle once in the lifetime of a Program, or if they should be added again after reaching a selected Participant State. This feature can be configured so that participants can be re-added after reaching any combination of Participant States. For example, if you would like contacts to be re-added after they leave the Participant Lifecycle because they were “Knocked Off” or encountered a “System Error”, you can select those options. This option can be configured after the Program is published.

    Prevent Participants from Receiving Surveys Repeatedly: When selecting the option for users to be re-added after they reach a participant state, it is recommended to use the option "Participant with same email address can enter once in X days". This will prevent the participant from being added to the outreach again if they have already been added to it within a set amount of time, even if they meet other criteria set within the Uniqueness Criteria section. This will prevent the participant from receiving duplicate messages. See the Advanced Criteria section for more information.


  1. Exclusion List: Users can upload a CSV of contacts that they would like to exclude from the outreach, even if they are added as unique participants from a source. After this CSV is uploaded, users will need to select a criteria field to determine how participants are excluded. The available fields will be pulled from the CSV’s headers. This list will be considered when the sync feature consolidates each source into a single participant list. Any contact on this list will not be added by a source during the sync. 

    Exclusion lists can be deleted after a Program has been published by clicking on the trash can icon next to an uploaded list. After the list is deleted, if a participant that would have been excluded by the list is then added by a source, it will enter the participant cycle of the Program.


  1. Advanced Criteria

    Users can select checkboxes that will: 
  • Prevent a Participant with the same email address from being added to the Outreach within a set number of days. The number of days can be customized by the user.
  • Allow participants without valid Salesforce Account IDs to be added to the outreach.
  1. Save/Discard: Save or discard the changes you have made to Participant Criteria.

Mapping Participant Sources

Since it is possible to add participants from multiple sources in a single Program, it is important to map the data being pulled from each source to the fields within the Participants object. In the Standard Field Mapping section, the column on the far left will display a list of standard fields from the participant object. Each Participant source will display an adjacent column, giving users the chance to select which source field is mapped to a standard participant field. Additional custom fields can be added and mapped as well. You can select both Standard and Custom fields as tokenization options in a Program's email steps. The Program feature can map fields from SFDC and Gainsight standard objects.

Context ID

For certain models, such as the Customer Satisfaction Survey, you are required to map to a field called the Context ID. This field is used to define the context for why the survey is being sent, and to link the survey's responses to the appropriate files in Gainsight. For example, when sending a case closure survey, we need to pull in the Case ID field as part of a Participant Source, and then map it to the Context ID field. This enables us to tie participant's survey responses to the appropriate case.


Custom Field Mapping


Click + ADD CUSTOM FIELD to add a new custom field to be mapped.


After a custom field is added, you will be able to configure the display name and map it as you would a standard field. You can also click the trash can icon to delete the field. Each field type has a different symbol associated with it to help differentiate them (Integer and Double use the same symbol). You can add the following types of custom fields:

  • String Snip20180719_97.png
  • Integer Snip20180719_98.png
  • Double Snip20180719_98.png
  • Boolean Snip20180719_99.png
  • Date Snip20180719_100.png
  • External Id Snip20180719_101.png
  • Email Snip20180719_102.png
  • Picklist PK.png

  • Both Integer and Double types of custom fields are number fields. But, if Integer is selected, the system rounds off the values when the field is having decimal values.
  • Syntax Validation for the content of the custom email fields will occur during Participant Sync. If the validation fails, the participant will move to the list of Failed Participants.
  • Custom email fields can be used to configure the fields “To”, “Reply-to”, “From Email”, and “Email Copy to”; as well as the tokens within a Program’s email steps. For more information on configuring email steps, refer to Configure Model and Emails for Programs.

After mapping your fields, click SAVE at the bottom of this section to save your configurations. You can also click DISCARD to discard any changes you made and revert the section back to its previous configuration.

The user can add maximum of 50 fields for all data types together or any one data type in the Participant List configuration area of a Program. This eases the configuration of complex multi step programs, and also allows admins to define programs easily.

This configuration is only applicable for newly created Programs. The user cannot add any Custom Fields if the Program already exists and it’s in an Active status. However, if the created Program is in Draft stage, the user can add more fields by deleting the existing Custom Fields.


  • The same functionality is also applicable for cloned Programs. The user must delete the existing Custom Fields and can add a maximum of 50 fields.
  • If you need to add more than 50 fields, raise a request to

Business Use Case: Consider a scenario where you need to add many Email steps or CTAs in a Program. With this enhancement, admins can define up to 50 custom fields which can be used as Tokens in the Email/CTA steps of a Program.

Pick List Datatype Fields

When customers map Picklist fields of an MDA objects to a token, mails were sent with ID's instead of resolved values. In order to solve this use case, Gainsight is supporting the Picklist data type fields in Programs. 

To use the picklist fields in Programs, admins must first create custom fields in the standard and custom objects with datatype as Dropdown List and select an associated category for mapping to this field. For more information on how to create a custom category, refer to Dropdown List and Multi-Select Dropdown List

Admins can then use the Custom Field Mapping section in the Participants Configuration page to add the Picklist fields defined in the Data Management page with datatype as Dropdown List.


To add a Picklist datatype field in Program:

  1. Navigate to Journey Orchestrator > Programs.
  2. Click to open an existing program, or click the +CREATE to create a new program
  3. In the program model configuration screen, click the green Participants icon. The Participant Configuration page appears.
  4. In the Participants Configuration page, click the Mapping Participant Sources section.
  5. In the Custom Field Mapping section, click +ADD CUSTOM FIELD and select Picklist datatype field. The Category dialog appears.
  6. Select the Picklist type from the dropdown option.
  7. Click SAVE.
  8. Select which source field to be mapped for the picklist field.


After a Picklist Field is created, admins can add it as a tokenization option while configuring any program Email Step and can be used in the tokenization option while configuring any text field in the Create CTA and Close CTA steps.


Admins can select the conditions in the Conditional Wait step based on the Calculated Field configured on the picklist field created. These picklist fields can also be used as a filter option while configuring Calculated Fields and using reports in email templates.


If admin previews the Conditional Wait and Email Template steps, it displays the actual values of the Picklist field configured.


Email Settings

Under Email Settings, admins can configure Programs to log all emails in Salesforce on the Contact record. If this setting is enabled for an AO already in progress, it will log all emails sent going forward. By default, this setting is turned off.

To enable this option, navigate to a specific Program, and the Participants Configuration > Email Settings section.

Note: To successfully log emails to Salesforce Activities for Accounts, it’s mandatory to map the SFDC Contact Id in the mapping Participant Sources step. To successfully log emails to Salesforce Activities for Relationships, SFDC Relationship and Relationship contact ID is mandatory. 


Click the checkbox and Save to activate the feature. Each email will be saved in the Contact’s Activity History.

Admins can configure the Task Owner Field to select who will own the email activity record in Salesforce. The Default Task Owner can be configured to assign the task to a default user, in case the owner field is not available.

Click the SAVE button to save configurations you have made, or the DISCARD button to remove your changes.

Calculated Fields

Users can add Calculated Fields to be used as part of Send Email, CTA, and Conditional Wait steps they add to the Program. Under this section, you can add Calculated Fields by clicking +CALCULATED FIELD. You can also view any calculated fields that have been added to this program. For more information on adding Calculated fields, refer to Programs: Using Calculated Fields.


Event Fields

Use this option to configure a new Event Field. Once it is created, it can be accessed in other Conditional Wait steps in the AO and in the Event Field within the Participants Configuration section. Use this option to configure Event Fields without having to navigate to the Participants Configuration section. For more information on configuring event fields within Conditional Wait, refer to the Programs: Using Event Fields article.


Additional Participant Configuration Options

Additional options are available for Participants Configuration.


Sync Sources 


This gathers all contacts from all of the sources and syncs them into a single Participants list.

If the Program already has a participant list, the following message will display if the sync option is clicked:

“This will clear and sync all participants from the sources again. Do you wish to continue?”

Followed by the options YES and NO, SYNC ONLY NEW PARTICIPANTS.

sync new participants.png

Clicking YES will clear the current participant list and sync participants from all sources again. Clicking NO, SYNC ONLY NEW PARTICIPANTS will only sync new participants to the existing participant list.

Participants List/Failed Participants List


View the list of all Participants created by the Sync Sources option. This view can display up to 1,000 records. This list will display the state of each Participant within the Participant Lifecycle.

You can also click the Failed Participants tab to view a list of contacts who were not added as Participants to the Program for any reason. The list is generated after participants are synced (manually or via schedule) and after uniqueness criteria and advanced criteria are applied.

The list will include a column displaying the reason for failure.


Admins can also create reports on failed participant data in Report Builder to see failure reasons for participants across all Programs. To create a report on this data, navigate to Administration > Report Builder and select AO Failed Participants History as the source object.

Note: Failed participant data can also be found under the AO Failed Participants source object. However, filtering is not supported for participant fields on this object.

The following are conditions for why a participant might fail to sync and the message associated with that condition:


Failure Message

Unique Criteria

Participant filtered due to unique criteria

Don’t Send Emails in X days

Participant filtered due to advanced criteria

Hard Bounce

Participant email address part of hard bounce list

Soft Bounce

Participant email address part of soft bounce list

Unsubscribed Email

Participant has unsubscribed from Survey/Journey Orchestrator Emails

Invalid Email

Invalid Email Address

Exclusion List CSV

Participant part of CSV Exclusion List uploaded into the Program

Operational Email - Rule 1

Operational Email - More than 5000 active participants in the Program

Operational Email - Rule 2

Operational Email - More than 5000 participants synced per day

No Sfdc Account Id or Company Id or Sfdc RelationShip Id or Gs Relationship Id

Participant Account/Relationship Id not synced correctly



Navigates back to the Program model configuration page.

Knock-Off or Remove Participants

You can remove one or multiple participants that have been added to a program with a status of DRAFT. To perform this, take the following steps:

  1. Click the Participants icon at the top-right of the Participant Configuration page to open the participant's list. 
  2. You can select the required participants that should be deleted from one of the following options:
  • Select one or multiple participants using the checkbox next to each participant's name.
  • Click the Filter icon at the top-right of the page and apply criteria by Source and Participant State, as required.
  • Enter value in the required field search box to filter participants and then select the required participants from the filtered list.
  1. Click either KNOCK OFF or REMOVE to select the participant as “Knocked Off” from the Program or removed from the Program permanently. 


  • Before you select one of the options, ensure that you know the difference between the options. 
  • Once you Knock-off any participant(s) using this option, you can add them again using the option Entry Criteria in the Participant configuration Filter Criteria on Participants. For more information, refer to the Filter Criteria on Participants section.
  • Once you knock-off any participant(s), you can remove them only after adding them again using the above option.

Knockoff or Remove.gif

You can search for specific Participants using the fields within the Participant List. You can not delete Participants in a Completed or Paused Participant State.


  • It is not possible to remove participants from a program with a status of ACTIVE.
  • If the Uniqueness Criteria of a Program is configured to allow "Knocked Off" participants to be re-added to the Participant Lifecycle, it is possible for participants who were removed using this method to be re-added to the Program as they are considered "Knocked Off".

Exporting Participants

Admins can export the list of participants either by downloading the CSV file or as an email attachment based on the report read limit. 

This functionality is applicable for the following participants grids in tabular formats:

  • Program analytics
  • Snapshot view
  • Participant list view
  • Failed Participants
  • Summary View
  • Participant Activity


Note: The export option is disabled if the participants grids has zero records.


If any filters are applied to the participant grid or inline search is performed, only those list of participants applicable for the applied filters are download or exported based on the report read limit for that tenant.


Similarly, the columns which are selected to display in the grid are download or exported based on the report read limit for that tenant.


Deleting Participant and Relationship Records

Gainsight Admins can delete Participant records from Programs using the Company/Relationship delete operation. For more information on this operation, refer to Data Operation.

When this action is taken as part of a company delete, affected participants that are currently active in a Program will be dropped and the company ID value in the participant record is set to null.

When this action is taken as part of a relationship delete, all participants that belonged to the relationship are dropped. Any Programs that belong to the relationship will be stopped, and the relationship ID will be marked as null at the Program and participant level.

Unsubscribe Process

After a participant has received a Program, they can choose the option to unsubscribe. When a user clicks this option there are two categories they can unsubscribe from: Customer Success Communication and Survey Communication. Depending on how a user has unsubscribed, a Program will perform in the following ways:

  • When a Program is published, a check is performed against the list of unsubscribed contacts (contacts who have unsubscribed earlier from all communications). Participants that match this list are dropped from the Program.This is applicable for all survey models: NPS, CSAT and Generic Survey Model.
  • If the Participant unsubscribes within the Program NPS journey and chooses either Survey Communication or Customer Success Communication, they will be dropped from the NPS journey and will not receive any further communications such as reminder emails or escalation emails.
  • Within an Email Chain model, only participants who have unsubscribed from the category - Customer Success Communication are not added to the Program and are dropped from the journey.

As part of Program analytics, you can see the number of emails which were unsubscribed as part of each email step.


Edit Sources after Publishing a Program

Admins can edit/delete the sources of an Active program even after it is published. This solves many problems for customers. For example, if an admin adds a CSV file or a sample source to test the program for some participants, now they can come back and delete the existing source and add a new source, to the same set of participants, before making the program live. 

Admins can perform the following actions to the Sources of an Active Program after it is published:

  • Add and merge tasks in Bionic Query.
  • Add new fields to the existing source.
  • Map the new fields and also modify the existing mapping.
  • Make modifications in source filter criteria.
  • Add/Delete participant source(s). But, at least one source must be present.
  • Delete existing Custom fields if they are not used in any other criteria or steps.

Source Editability.gif

By default, source modifications performed by an admin are only applicable to the new participants added in the program, and do not impact the already synced participants. Admins must use the Sync icon to manually sync the participants to immediately apply the modifications to the source. After the sync is done manually, participants are added to the Program list in the REVIEW state.

Source Editability1.gif

If Admins sync the participants manually, they must navigate to the Participants list page and perform the following actions as per their requirement:

  • ADD TO PROGRAM: Adds participants to the existing Program.
  • KNOCK OFF: Knocks off the participant from the program and they no longer receive messages as part of the Program.
  • REMOVE: Removes the existing participants from the Program, if added unintentionally.

Source Editability2 (1).gif

Additionally, bulk KNOCK OFF and REMOVE options are supported in this feature. Admins can use this feature to move all of the participants to Knock off state and even remove them completely from the Program, if they are not required.

Note: Select all checkbox, for bulk Knock off and Remove options, is only enabled when the participants are filtered by REVIEW, NEW, or ACTIVE state.

Source Editability33 (1).gif

If syncing of the participants for an Active program is scheduled for an automatic syncing after adding new source to a program, this also publishes all the Review participants present in the system. Before the schedule runs, user must manually KNOCK OFF/REMOVE if they do not want to publish any participant who are already in REVIEW state. 

Bounced/Unsubscribed Participants

Bounced and Unsubscribed contacts will not be added to the Participants data table in a Program. Gainsight will safely drop this data before adding Participants to the data table.

If you have questions or feedback about the feature explained in this article, please share them on