Schedule and Execute Rules
Gainsight NXT
This article supports Gainsight NXT, the next evolution of the Customer Success platform. If you are using Gainsight CS Salesforce Edition, you can find supporting documentation by visiting the home page, and selecting CS > Salesforce Edition.
Not sure what your team is using? Click here.
重要 - 画像/情報は四半期ごとのリリースで更新されます!
四半期ごとのリリースにて、最新の機能・情報を反映し、画像を含めた情報は更新されます。
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 in chronological order.
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 from the Rule Schedule 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 set the rule frequency:
- Daily: The following options are available when you select 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.
- Daily: The following options are available when you select Daily option:
- Weekly: Select the day of the week on which the rule must run.
- Monthly: The following options are available when you select Monthly option:
- On Day: Select the day of the month on which the rule must run (Ex: ).
- On the: Select the number of any weekday in a month on which the rule must run (Ex: ).
- Yearly: The following options are available when you select Yearly option:
- On Every: Select the month and date on which the rule must run.
- On the: Select the number of any weekday in a month on which the rule must run.
- Start Date: Select the start date from which the rule execution starts.
- End Date: (Optional) Select the end date after which the rule execution ends.
- 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 > Default Time zone field. You can change the timezone to UTC.
- 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: By default, Rule Success or failure messages are sent to the logged in user. However, you can add email of other users, who must be notified about Success or failure of this rule.
- On Failure: Add Email address of users who must be notified when this rule fails. You can add multiple emails separated by a comma.
- On Success: Add Email address of users who must be notified when this rule succeeds. You can add multiple emails separated by a comma.
Gainsight NXT in Salesforce CRMContent in this section supports Gainsight NXT accessing through Salesforce Login. To learn more about Gainsight NXT in Salesforce, click here.
- Click here to expand for more information on how to change the Rule link in failure notification emails from NXT to the SFDC login path
-
Note: If you need to change the Rule link in failure notification emails from NXT to the SFDC login path, please contact Gainsight Support.
- Run for historical periods: If 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 run for a maximum of 200 weeks. 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 important 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 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 time zone selected in the Application settings > Default Time zone field. You can change the time zone to UTC.
- 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: By default Rule Success or failure messages are sent to the logged in user. However, you can add email of other users, who must be notified about Success or failure of this rule.
- On Failure: Add Email address of users who must be notified when this rule fails. You can add multiple emails with a comma.
- On Success: Add Email address of users who must be notified when this rule succeeds. You can add multiple emails separated by a comma.
Events
This Schedule Type executes a rule when an Event is triggered. There are two types of Schedules under this Scheduling method:
Events Framework
You can run a rule using an event from the Events Framework in Gainsight. Using the Event Schedule Type, 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.
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.
Schedule Rules based on events
To use events in the Rules Schedule, you must first create a Topic and then add Events related to that topic. For more information on creating Topics and Events refer to the Events Framework article.
- Navigate to Administration > Rules Engine.
- Create and configure a Rule.
- Go to the Schedule step.
- In the Schedule Type list, select Event.
- 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 configured 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.
Note: Gainsight performs a case sensitive match when comparing the old and the new file names in S3 bucket.
For more information on configuring the S3 Dataset task in Rules Engine, refer S3 Dataset Task in Rules Engine.
Example: 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 schedule a rule based on an Event for S3 File option:
- Navigate to Administration > Operations > Rules Engine.
- Create and configure a Bionic Rule.
- Navigate 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 configuration cannot use "Date Pattern".
- 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.
Rule Date
In cases where there are S3 exports or date-specific filters, the rule date is the one that is utilized inside the rule. The Rule Date is calculated as the date (in the org timezone) when the rule is triggered.
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 dots icon 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
You can see the execution history of any rule. To see the execution history:
- Navigate to Administration > Rules Engine > Rules List.
- Click on a specific rule. Preview of the selected rule appears.
- Navigate to EXECUTION HISTORY.
- Click REFRESH HISTORY to refresh the rule executions.
Note: If a rule was recently updated to run, but you haven’t left this screen, you need to click REFRESH HISTORY to see the latest rule executions.
- 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. For more information 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 which were successfully ingested. The second download link (red in color) contains the file that has records which failed to ingest. When you click the red download link, 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 is defined while creating the 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 is displayed on this page.
- Download Results: Click this icon to download the results of the selected task.
Notes:
- After seven days from 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.
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.
CAUTION: 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 the + icon next to View Logs to see the detailed information about the execution history of the specific rule.
Notes:
- Each rule is limited to 200,000 records.
- Rule updates are 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.
- Rule Preview displays basic details of tasks, including the link to download the final task output as csv as shown below.
Abort Rule
You can abort a rule while the rule run is in progress. You can abort a rule from the rule EXECUTION HISTORY tab using the Abort option next to the In Progress status. The 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.
You can also abort a rule from the TIMELINE tab. Click Abort Rule, for a rule whose execution status is In progress, to stop the rule execution.
Troubleshooting
If you face difficulty in saving your rule's schedule, ensure that there are no quotation marks in the rule's description field.