IMPORTANTAfter the October 2018 release, Admins cannot create new Custom Rules. Gainsight recommends creating Bionic Rules as they are more powerful than Custom Rules, and they help Admins reduce the number of overall rules that you need to configure and manage. For assistance with Bionic Rules, check out the following resources:
This article explains how to schedule your rules.
Scheduling and Executing Rules
You have the option of scheduling the execution of an individual rule or setting up a Rule Chain to handle a group of related rules with a shared schedule.
Gainsight suggests few recommendations for the admins during the configuration of rules to improve the performance of the rule, minimize the rule run time, and reduce rule failure probability. These suggestions also act as a reminder/guidance for the admins to configure accurate and efficient rules.
The following areas of rule configuration in which Gainsight recommends suggestions to the admins:
- Filters in Tasks: This suggestion is displayed when no filters are added to the tasks. It is recommended to add the filters to fetch only the required data to improve the performance of a rule.
- Date Filters in Tasks: This suggestion is displayed when no date filters are added when the rule is scheduled to run regularly. It is recommended to add a date filter for a rule to fetch only the latest data.
- Unused Tasks: This suggestion is displayed when any data from the tasks is not used anywhere in the rule. Therefore, admins can delete those tasks without any impact to the rule configuration.
The above suggestions are initially displayed on the Schedule screen of the rule setup, after adding at least one dataset to the rule.

Schedule Types
Rules Engine scheduler allows you to run rules using Basic, Advanced, and Event schedulers. Select Schedule while creating a rule to navigate to scheduling screen. By default, Basic Schedule Type is selected.
Basic
The basic schedule type allows you to schedule a rule on a daily, weekly, or monthly basis.
- Frequency: Select any of the following radio-buttons to run the rules accordingly
- Daily
- Weekly
- Monthly
- Yearly
- Every weekday (MON-FRI): Select this option to run the rule every weekday.
- Every day: Select this option to run the rule every day.
- Start Date: Select the start date for the rule runs.
- End Date: Select the end date for the rule runs (Optional).
- Preferred Start Time: Select the preferred start time in hours and minutes.
- Time Zone: This is set automatically depending on the Timezone selected in the Application settings > Timezone pane. For more information about Timezone Standardization, refer to the Timezone Standardization in Gainsight article.
- Rule run preference: Select how to run the rule from the following options:
- Optimize run with other Rules: Select this option to stop other rules from running while this rule is running if they are dependent on the same objects. This option is selected by default.
- Run independent of other Rules: Select this option to allow all other rules to run in parallel with this rule while it is running.
- Send notification email: This will send emails On Success/Failures to additional specified email addresses.
- Run for historical periods: If the start date provided is in the past, checking this option will run the rule from the selected start date to the present date. The number of runs is limited when the rules are run for a historical period. Refer to the following additional note:
Additional Note: Historical Periods
When the start date in this scheduler is set to a date in the past, it will run for the historic period, and load data.
Example: If you have the rule scheduled to run daily, then you can run it for the historical period of last 200 days. In the case of a weekly schedule, it will be for the last 200 weeks max. This basically helps prevent a huge number of rule runs being triggered by mistake, or when you do not realize how much time it is going to take for all the runs to complete. It puts all of the other rules in queue and delays other rule runs.
Advanced
Using the Advanced schedule type enables you to run the rules as frequently as every two hours.
- Cron Expression: Enter the Cron expression that allow the rule runs accordingly. For more information about Cron Expressions, refer to the Cron Expression for Advanced Scheduler in Rules Engine article.
Note: The minimum time period between rule runs is two hours. - Timer icon: Click this icon to view the next five rule run schedules for the cron expression provided (as displayed in the image provided).
- Start Date: Select the start date for the rule runs.
- End Date: Select the end date for the rule runs (Optional).
- Time Zone: This is set automatically depending on the Timezone selected in the Application settings > Timezone pane. For more information about Timezone Standardization, refer to the Timezone Standardization in Gainsight article.
- Rule run preference: Select how to run the rule from the following options:
- Optimize run with other Rules: Select this option to stop other rules from running while this rule is running if they are dependent on the same objects. This option is selected by default.
- Run independent of other Rules: Select this option to allow all other rules to run in parallel with this rule while it is running.
- Send notification email: Enter the email address(es) in the respective fields to which an email is sent on Success/Failure of the rule runs.
Events
This Schedule Type executes a rule when an Event is triggered. There are two types of Schedules under this Scheduling methods:
Events Framework
You can now run a rule using an event from the Events Framework in Gainsight. In the Schedule step of a Bionic Rule, a new option is introduced for this purpose. Using the Schedule Type as Event, you can run the rule using CURL command. CURL command is a handy way to trigger a rule outside of Gainsight. In a broader sense, event-based triggering of a rule enables you to integrate rules deeper with non-Gainsight services if you have developer support. Events-based triggering of a rule helps you avoid unnecessary scheduling of a rule. For example, you might have scheduled a rule to run every two hours to check if the S3 bucket has data, this rule runs every two hours adding some load to the server. In this scenario, you can trigger the rule using CURL command only when you are sure that data is present in the S3 bucket.
To see a video about using Events in scheduling rules, see a 6-minute video on Rules and Event Triggers.
Limitations/Recommended Usage
- Use the events-based triggering of a rule only when it is required. For example, when you are sure that the rule has fetched data from the S3 bucket, then you can use the CURL command to trigger the rule.
- If there is a pending execution of a rule, the event-based execution request will be rejected. You can find the rejection reason in the rule’s execution history.
- For a Customer, 100 event-triggered rule executions are allowed in a day (24-hour period). The 24-hour period is between 12 am in a day to the next 12 am UTC.
To schedule an rule based on events:
- Navigate to Administration > Rules Engine.
- Create and configure a Bionic Rule.
- Go to the Schedule step.
- In the Schedule Type list, select Event.
- Select the Events Framework option.
- Select a Topic from the list.
- Select an Event from the list.
- Select the Rule run preference from the following options:
- Optimize run with other Rules: Select this option to stop other rules from running while this rule is running if they are dependent on the same objects. This option is selected by default.
- Run independent of other Rules: Select this option to allow all other rules to run in parallel with this rule while it is running.
- Click SAVE. After the save is successful, the SHOW CURL COMMAND option appears.
- Click SHOW CURL COMMAND. The CURL command appears on the screen.
- Click Copy command to clipboard option.
- Run the command in a Terminal to run the rule. Once the command is executed, the rule will run instantly with the current date and time.
S3 File
This schedule type is applicable only if your rule has an S3 dataset. You can use this schedule type to automatically trigger a rule which has an S3 dataset, whenever a new file is uploaded to the S3 bucket. When you upload a new CSV file which has the same configuration as defined in S3 dataset, the S3 dataset rule is triggered automatically.
If you are using the EQUALS option in the File Path field of your S3 dataset, you must ensure that the old and new file names must be the same. However, if you are using the STARTSWITH option in the File Path field of your S3 dataset, the rule is triggered for any CSV file uploaded which matches the start of the string. Gainsight performs a case sensitive match when comparing the old and the new file names in S3 bucket.
Consider an instance in which you create an S3 Dataset by selecting the STARTSWITH option in the File Path field and you have used “Accounts” as the name. If you have a file in S3 bucket as Accounts.csv, this file can trigger the rule since it meets the STARTSWITH criteria. Now, if you add two new files to your S3 bucket called Accounts1.csv and Accounts2.csv, each file can trigger the rule (The rule is executed twice; for each instance of adding the files, Accounts1.csv and Accounts2.csv). In this case, the rule is triggered based on an event. Event here corresponds to uploading a new file, which meets the STARTSWITH option criteria.
To use the S3 file configuration:
- Navigate to Administration > Operations > Rules Engine.
- Create and configure a Bionic Rule.
- Go to the Schedule step.
- In the Schedule Type list, select Event.
- Select the S3 File option.
- Select the S3 dataset from the Task drop-down menu.
- Select the Rule run preference from the following options:
- Optimize run with other Rules: Select this option to stop other rules from running while this rule is running if they are dependent on the same objects. This option is selected by default.
- Run independent of other Rules: Select this option to allow all other rules to run in parallel with this rule while it is running.
- In the Send Email Notification field, enter the email addresses of the users to be notified in case of Success or Failure of the Rule.
- Click SAVE.
Limitations of S3 file Schedule type
- The S3 Dataset rule can not be part of a rule chain.
- The File Name setting in the S3 Dataset Task cannot use the "Pattern" wildcard.
- If a rule has multiple S3 datasets, you can auto trigger the rule only for any one of the S3 datasets. This Dataset must be selected from the Task drop-down menu.
- Your CSV file must be located in the Gainsight Managed S3 bucket. Rule is not auto triggered if file is configured from any custom bucket.
Run Now
After a Rule is created, you can use the Run Now option to configure the rule to run once or at regular intervals using the Historical Periods option.
Run Once Option
To run the rule only once:
- Click the three dots icon of a specific rule and click Run Now. The rule scheduler dialog box appears.
- In the Run This Rule For field, select Once.
- Select the date of when you want to run the rule in the Select Rule Run Date field.
- (Optional) Select the Test Run check box if you want to test-run a rule and receive an email with a summarized results list.
- In the Send Rule results to these emails section, enter additional email addresses in the field to send them a copy of the Rule result email. Logged-in user’s email ID is auto-populated for sending rule results. In addition, you can send rule execution details to the email IDs entered in this field.
- Click Run Now.
Historical Run Option
To run the rule at regular intervals over a period of time:
- Click the three vertical dots menu of a specific rule and click Run Now. The rule scheduler dialog box appears.
- In the Run This Rule For field, select the For Historical Periods option.
- Select the options to set the rule frequency as required:
- Daily: The following options are available when you select the Daily option:
-
Every Weekday (MON-FRI): Select this option to run the rule only on weekdays.
-
Every day: Select this option to run the rule every day.
-
-
Weekly: Select the day of the week when the rule must run.
-
Monthly: The following options are available when you select the Monthly option:
-
On Day: Select the day and any weekday in a month of when the rule must run.
-
- Select the date range in the Select Rule Run Date Range field of when you want to run the rule.
- (Optional) Select the Test Run check box if you would like to test-run a rule and receive an email with a summarized list of results.
- Select the Run at non-peak hours checkbox to run the Rule during non-peak hours. This helps optimize the run queue for other Rules in the queue.
- In the Send Rule results to these emails section, enter additional email addresses in the field to send them a copy of the Rule result email. Logged-in user’s email ID is auto-populated for sending rule results. In addition, you can send rule execution details to the email IDs entered in this field.
- Click Run Now.
Schedule of Duplicate Rules
When you clone a rule, schedule of the source rule is not applied to the target rule. You must schedule the cloned rule manually. However, if the source rule is active, cloned rule is also active and if the source rule was inactive, cloned rule is also inactive.
Execution History
*Status: Identifies the status of the rule. The various status are:
- Success: This status is displayed when the rule is successfully executed.
- Failure: This status is displayed when the rule fails to execute.
- Aborted: This status is displayed when you stop the execution of a rule. To learn more about how to abort a rule, refer to the Abort Rule section of this article.
- Queued: The rule is currently in a queue and rule execution has not yet started.
- In progress: The rule is currently being executed.
- Partial Success: This status is applicable only for Rules which have an S3 Dataset. During the rule execution using an S3 dataset task, if some records fail to ingest due to any reason, rule is executed partially and status appears as Partial Success.
In a Partial Success rule, you can find two downloadable files for the S3 dataset. The first download link (grey in color) contains the file that has records that were successfully ingested. The second download link (red in color) contains the file that has records that failed to ingest. When you click the red download link, the error CSV file is downloaded and you can see the list of errors and records that are failed to ingest.
*Last Rule Updated By: Identifies the last person to modify the rule
*Last Rule Updated Date: Identifies when the rule was last modified
* Rule updates will be saved only if a user modifies the rule, or if the user uses the NEXT button to navigate through a rule. If a user navigates through a rule via the breadcrumb trail (tabs) along the top of the rule pages, the user’s action will not be registered as a rule update.
Preview and Download Task results
The output details of all tasks are displayed here. Select any task to view the respective details:
- Task Type: Task type as defined while creating the Bionic Rule
- Status: Status of rule run
- Records: No. of records fetched for the task defined
- Duration: Duration of the rule run
- Results: You can:
- Preview Results: Click this icon to preview the task results in a new window. A maximum of only 100 records are displayed on this page.
- Download Results: Click this icon to download the results of the selected task. The rule results are available up to 30 days for you to download.
Notes:
- Seven days after the rule run date, the preview and download options expire and an error message is displayed if you click these icons.
- These icons are disabled when the rule run is aborted.
- By default, all the task results are retrieved from S3 (Even if the Export to S3 option in the Setup Rule screen is disabled).
In the Rule results excel sheet, a separate worksheet for each action item is displayed with details of the number of records processed in each action, if the rule is executed manually or scheduled. However, by default, this feature is not enabled for scheduled runs. To enable this feature, contact support@gainsight.com.
IMPORTANT: If you enable this feature, system performance might be impacted significantly because there can be multiple rules scheduled every hour and it becomes a tedious job for the system to collect the data for every scheduled rule.
View Logs
Click + icon next to View Logs to view the detailed information about the execution history of the specific rule.
Notes:
- Each rule is limited to 200,000 records.
- Rule updates will be saved only if a user modifies the rule, or if the user uses the NEXT button to navigate through a rule. If a user navigates through a rule via the breadcrumb trail (tabs) along the top of the rule pages, the user’s action will not be registered as a rule update.
- Bionic Rule Preview displays basic details of tasks, including the link to download the final task output as CSV.
Abort Rule
You can also abort a rule when the rule run is in progress from EXECUTION HISTORY using the Abort option beside the In Progress status. Abort option is enabled for any rule scheduled for a run. You can use this option when the rule run is initiated unintentionally or if the rule is not configured as required.
Abort rule option is also available in the TIMELINE view.
When a rule that is used in a Rule Chain is aborted, you are prompted with an option to abort the rule chain in the Abort Rule dialog box.
Abort rule chain checkbox:
- Select this option to abort the Rule Chain(s) which the rule is a part of.
- Deselect this option to abort only the selected rule and the dependent rules in the respective Rule Chain(s). The independent rules in the Rule Chain are executed as scheduled.
Troubleshooting
If you face difficulty saving your rule's schedule, ensure that there are no quotation marks in the rule's description field.