Adding an Export Schedule

Specify the enterprise locations for which an export configuration exports data, sets the export frequency and recurrence, and specify how the system delivers the exported data file.

Overview

An export schedule defines the specific locations for an export, the time, the frequency of the export configuration, and where to deliver the export.

It also defines the export file name and if the export is compressed or encrypted.

When you activate the export itself, the delivery options are validated. An active schedule needs to be deactivated to make changes.

Prerequisites

Required system privileges: Export Schedules and Add/Edit/View/Delete Schedules.

When you add an export schedule, you select a delivery profile and you can select a location group. Add the delivery profile and location group before adding the export schedule.

Failed Schedules

If a new export schedule fails to execute or deliver for three consecutive executions, for the complete location scope, it will be deactivated and the owner of the schedule receives a notification email. Previously working schedules that start failing are deactivated after seven consecutive failures and the owner is notified.

Configuring a New Schedule

  1. In Reporting and Analytics, click the side navigation menu, click Reports, click Exports, click Schedules, and then click Add Export Schedule.
  2. Specify a name for the schedule, select an export configuration, and then click Add.
  3. If you do not need to immediately run the export configuration with the schedule you are creating, leave the default status as Inactive. See Step 10 for instructions to validate and activate the export schedule.
  4. In the Location Scope section, select the locations for which data is exported.

    Choose from individual locations, all locations underneath the selected organizational level, or a custom group of locations.

    To export data for a group of locations, you need to create the location group first before you can select it from the Location Group drop-down.

    To include inactive locations in an export, select Include inactive locations in level / location group' option.

  5. In the Frequency section, set the export first run date, run time, time zone, and recurrence type.

    Note:

    • If the First Run Date is set to the past, the export engine runs the export starting from the selected date until the current date when the schedule is first activated. It then continues to run based on the recurrence type and export the most recent data.

    • The Run Time with Time Zone defines the time that the schedule starts executing. Depending on the Conditions settings, it executes at the set time, or it will start checking for End of Day conditions starting at the set time.

    • The Target Time should be set to the time when downstream systems expect the export to be completed for all selected locations. It is used within the Notifications emails.

    • Depending on the recurrence type, different options become available in the Recurrence section to configure the day of the export run.

    Important:

    Review each location’s time zone and schedule time zone. Schedule the export for at least 2 hours after the last location’s start of day (SOD) time.
  6. Select the recurrence options that appear based on your recurrence type selection.
  7. In the Conditions section, select the condition that starts the export and how frequently the system checks to determine if the condition is met. Select one of the following options:
    • Choose Export based on cloud posted date if your configuration contains transaction-based subject areas and if you want to receive a delta export for transactions. That means, the export contains data that was posted to the cloud on the date that the export is running for. Export files thus may contain transactions from previous business dates if previously offline workstations came online on that day, or transactions are made on checks that are left open for more than one business date. This option only works for transaction-based subject areasFoot 1. All other subject areas are exported based on business date only. For example, Daily Totals is exported at the configured run time of the schedule. Make sure to schedule the export at a time you can guarantee the End of Day to have completed for all locations.

      Note:

      On-demand and catch-up jobs of the schedule are run based on business date only.
    • Choose Export based on business date if your export configuration contains subject areas with aggregated data, or if you want to make sure to export only once the End of Day has completed for each location. Then select one of the following options:

      • Choose Export without checking End of Day condition to trigger the export for all locations at the configured run time. The engine will not check if all End of Day data is available and run at the configured time. Only use this option if you can guarantee, that the End of Day has completed for all locations. The resulting exports only contain data for the business date(s) it is running for.

      • Choose Check End of Day condition every 15 minutes for 6 hours to trigger exports as soon as the End of Day data for a location is available. If the condition is not met, the engine checks again after 15 minutes, for a total of 6 hours. This option should be selected if you cannot guarantee the availability of all End of Day data at the run time, or if you schedule for locations across time zones. The resulting exports will only contain data for the business date(s) it is running for.

        • Choose additional triggering options. They define if the export will be triggered if all transactions are posted, or not.

  8. In the Export Delivery Options section, specify basic properties for the data export file, such as the name of the file.

    In the Export File Name field, enter the name of the export file with the file extension. You can use a combination of text and tokens. The following sample file name includes text and tokens for location reference and business date:

    Daily_Export_${locationName}_${businessDate(YYYY-MM-DD)}.csv

    The system supports the following tokens:

    • ${organizationId}

    • ${organizationName} - If any of the following reserved characters are used in location names, they will be replaced with a dash (-) character: / ,\ ,| ,? ,* , < , > , : ," (double quote)

    • ${locationId}

    • ${locationRef}

    • ${businessDate}

    • ${country}

    • ${region}

    • ${locationName} - If any of the following reserved characters are used in location names, they will be replaced with a dash (-) character: / ,\ ,| ,? ,* , < , > , : ," (double quote)

    • ${month}

    • ${week}

    • ${counter-10000} - Resets at 10000

    • ${dateCounter} - Increments for the same day and resets at change of business date

    • ${dayCounter} - Increments each day and resets when reaches 1000

    • ${startDate} & ${endDate}

    • ${startTime} & ${endTime}

    • ${siteID}

    • ${financialWeekNum}

    • ${fixedPeriod}

    • ${financialPeriodNum}

    • ${timeZone}

    The ${businessDate}, ${startDate}, ${endDate}, ${startTime}, and ${endTime} tokens support the following date and time sub-tokens to customize date and time in the file name:

    • YYYY: four-digit year

    • YY: two-digit year

    • MM: two-digit month (examples: 01 for January, 02 for February)

    • MMM: three-character description of the month (examples: JAN, FEB, MAR)

    • DD: two-digit day of month (01 through 31)

    • hh: two digits of hour (00 through 23; do not use am and pm values)

    • mm: two digits of minute (00 through 59)

    • ss: two digits of second (00 through 59)

    The following examples show valid token and sub-token combinations:

    • ${businessDate(YYYY-MMM-DD)}

    • ${startDate(YYYY-MMM-DD)}

    • ${endDate(YYYY-MMM-DD)}

    • ${startTime(YYYY-MM-DDThh:mm:ss)}

    • ${endTime(YYYY-MMM-DDThh:mm:ss)}

    To create a ZIP version of the export file, select Compress Export. The compressed file has a file extension of .zip and the file name is the same as defined in the Export File Name field.

    To encrypt the data, select Encrypt using PGP Encryption and then paste an encryption key in the text box. Consider the following details when encrypting the data:

    • Make sure the PGP public key is an RSA encrypt key with minimum key size of 2048 (see RFC 4880 for information).

    • The data is encrypted using first public-key available in PGP key ring.

    • The encrypted output is an ASCII Armored Message (zip compressed).

    • You can decrypt the data using the PGP private key associated with PGP public key.

  9. Select the Delivery Profile.
    The delivery profile defines the settings for delivering the exported data file to the end point. The delivery profile owner must have the data permissions for the subject areas that are used in the configuration.
  10. Validate and activate the export schedule. Only active schedules generate an export. An inactive schedule does not generate an export. To activate the schedule:
    1. Change the status to Active and then click Save and Validate to view the validation step.
    2. Select the export scope Location Name and Date for which to validate export generation. To validate against sample data, select Use sample data to validate configuration.
    3. Click Validate. The validation steps are displayed on the screen. If validation completes successfully, the schedule is saved and activated. If validation fails, the detailed failure message is displayed to help resolve the problem. In this case, try validation again.

      Note:

      The successful validation uploads an export file to the sftp server or https endpoint using the defined delivery profile. If sample data was used to validate the export, make sure to not import the file in the downstream system.

Parent topic: Export Data from Reporting and Analytics

Known Error Messages

The error message Code too large is displayed while validating the schedule or the existing active schedule fails with Code too large error.

Explanation: The Code too large error typically arises when:
  • A step query in the export configuration contains a large number of non-trivial expressions instead of simple column references. This could be large CASE statements or a large number of AND/OR predicates.
  • The SELECT clause includes complex calculations or operations that significantly increase code complexity.

How to fix: To prevent this issue and ensure efficient export execution, the step queries must be simplified. Review the Best Practices in Adding an Export Configuration.


Footnote Legend

Footnote 1: For example, Cash Management, KDS Details, Non Sales, Time Cards, Guest Check Headers, Guest Check Discounts, Guest Check Menu Items, Guest Check Taxes, Guest Check Tender Media, Guest Check GST, Guest Check VAT, Guest Check Service Charges, Guest Check Other Details, Guest Check Extensions, and Guest Check Line Item Extensions