Skip to main content
Gainsight Inc.

Schedule and Execute Rules

This article explains how to schedule your rules. Refer to the articles Setup Rules and Setup Rule Action Types before using this article for guidance on scheduling.

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 a chronological order.

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 role on a daily, weekly, or monthly basis.

1- Basic Schedule.png

  • 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.
    • 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.
  • 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.
  • 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 Advanced schedule type enables you to run the rules as frequently as every two hours.

2- Advanced Schedule.png

  • 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 >> TBA.
    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 > Default Time zone field. You can change the timezone to UTC. .
  • 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 methods:   

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.

Create Topics and Events

To use events in the Schedule, you must first create a Topic and then add events related to that topic.

  1. Navigate to Administration > Events.
  2. Expand the Show List Of Topics.

15. Events.png

  1. Enter a name and click Create Topic.

16. Create topic.png

  1. Click the Topic created. (Here its Rules). The Create Event window is displayed.

17. Selecting the topic.png

  1. In the Create Event window, perform the following tasks:
  • Event Name: Enter a name for the event.
  • Version: enter a version number for the event.
  • Content Type: Enter content type of the event.
  • Structure: enter the Event structure event details.
  • Contract Mandatory: Select True or False.
  • Click Create Event.

18. Event creation.png

You can view the event in the list of events.

19. Events list.png

To delete the event, click the Delete icon under Action.

Schedule Rule based on events

  1. Navigate to Administration > Rules Engine.
  2. Create and configure a Rule.
  3. Go to the Schedule step.
  4. In the Schedule Type list, select Event.
  5. Select a Topic from the list.
  6. Select an event from the list.
  7. Click SAVE. After the save is successful, the SHOW CURL COMMAND option appears.
  8. Click SHOW CURL COMMAND. The CURL command appears on the screen.
  9. Click Copy command to clipboard option.
  10. 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.  

20. Event based scheduling.gif

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.

3. Startswith.png

To schedule a rule based on an Event for S3 File option:

  1. Navigate to Administration > Operations > Rules Engine.
  2. Create and configure a Bionic Rule.
  3. Navigate to the Schedule step.
  4. In the Schedule Type list, select Event.
  5. Select the S3 File option.
  6. Select the S3 dataset from the Task drop-down menu.
  7. Click SAVE.

4. S3 file schedule.gif

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.

Run Now

After a Rule is created, you have the option to run the Rule Now as shown below:

  1. Navigate to Rules Engine > RULES LIST tab.
  2. Select a specific rule and click RUN NOW. The rule date defaults to today's date.
    Note: Rule Date is the date on which the rule is triggered, and Run Date is the date on which the rule execution begins.
    Example: If a rule is triggered on 7th Feb 11:50 PM and it went into the queue, and after 30 minutes if the execution starts i.e., 8th Feb 12:20 AM, so the Rule Date is 7th Feb and Run Date is 8th Feb.

5. Run now.png

  1. 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.

Run_Now.png

  1. Enter additional email address in the field, Send a copy of Rule Result email to. Logged-in user email id is auto-populated for sending rule result. In addition, you can send rule execution details to the email IDs entered in this field.
  2. Select the Include Gainsight support check box if you want to send the execution results to Gainsight support.
  3. Click RUN.

Pause and Resume Rule Schedule  

If a Rule becomes inactive due to:

  • Execution failure
  • Abrupt interruption
  • Rule status is changed manually,

The schedule associated with the rule is not deleted. The schedule is paused. Once you make the rule active again, the schedule associated with the rule also becomes active (rule schedule resumes).

Note: If your Rule schedule type was set to Event, the event is deleted, when the rule execution fails. Rule Schedule is paused only when Schedule type is either Basic or Advanced.

7. Making Rule inactive.gif

Schedules of Cloned 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.  

In the below image, you can see that the Source Rule Account Rule has a schedule (10/18/2018 12.00 pm) and is active. However, the cloned rule Copy of Account rule is active, but does not have a schedule.

8. Rule Cloning.gif

Execution History

You can see the execution history of any rule. To see the execution history:

  1. Navigate to Administration > Rules Engine > Rules List.
  2. Click on a specific rule. Preview of the selected rule appears.
  3. Navigate to EXECUTION HISTORY.
  4. 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.

clipboard_eb9f6cbd89d4305bfffa9c393f5148342.png*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 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 colour) contains the file that has records which were successfully ingested. The second download link (red in colour) 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.

10. Partial_Success.png

*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 are displayed in this page.
    • Download Results: Click this icon to download the results of the selected task.

11. PreviewDownloadResults.gifNotes:

  • 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.

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.

12. Task.png

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. 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.

13. AbortExecutionHistory.gif

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.

pasted image 0.png

Troubleshooting

If you face difficulty in saving your rule's schedule, ensure that there are no quotation marks in the rule's description field.

  • Was this article helpful?