Expectations

Expectations let your Files.com site define what “correct” file delivery looks like, continuously evaluate whether it happened, and keep history when it did not.

Expectations are meant to answer operational questions like:

Did the expected file arrive?
Was it on time?
Did it meet the required shape and count rules?
Is there an active issue someone needs to acknowledge?

Expectations are different from Automations and Syncs. Automations and Syncs act on files; Expectations monitor whether expected files arrived on time, in the right place, and in the right shape. In practice, Expectations are the sensor and Automations are the actuator.

An Expectation combines four concepts:

Scope: where to look for candidate files, using path, source, and optional exclude_pattern.
Trigger / timing: when a window opens and how long it stays eligible, using trigger, schedule fields, lookback_interval, late_acceptance_interval, inactivity_interval, and max_open_interval.
Criteria: what must be true for the window to succeed, using the structured criteria JSON document.
Outcome history: what happened over time, exposed through ExpectationEvaluation history and ExpectationIncident lifecycle records.

Scope and matching

Expectations reuse the familiar Files.com path-plus-glob model.

The path field identifies the folder scope, while source identifies which files within that scope are candidates. exclude_pattern removes files from consideration.

Like Automations, these fields support glob-style matching. Expectations treat those matches as one logical candidate set for each window. A single Expectation does not implicitly fan out into separate per-customer or per-folder evaluations just because the path contains wildcards.

Expectation windows

Expectations are evaluated in windows.

Each window is persisted as an ExpectationEvaluation record. A window opens, remains open while evidence can still arrive, and then closes into a terminal result such as success, late, missing, or invalid.

An Expectation has only one open window at a time.

Trigger modes

Expectations can open windows in three ways:

daily: run on a recurring daily/weekly/monthly/quarterly/yearly cadence using interval and either recurring_day or recurring_days.
custom_schedule: run using either the reusable Site-level Schedule selected by schedule_id or specific weekdays and times stored on the Expectation.
manual: an operator explicitly opens the window.

Schedule-driven expectations define an on-time deadline and may optionally remain eligible to close as late during late_acceptance_interval.

Manual expectations have no concept of late; they open when triggered and close based on inactivity or hard-stop timing.

Success criteria

The criteria field is a structured JSON object describing what counts as success for the window.

Criteria v1 can express things like:

file count constraints
total byte constraints
allowed extensions
filename regex validation
forbidden files
required named or globbed files with their own per-file constraints

Criteria v2 adds content_validation, which runs a customer-authored Files Transform Script in either per_file or whole_batch mode. Per-file scripts receive the file contents parsed by FTS as payload. Whole-batch scripts receive an array of file objects containing path, name, size, last_modified_at, and each file's parsed payload.

A content-validation script returns true or { success: true } to pass. It returns false or { success: false, errors: [...] } to fail. Error entries may be strings or structured objects with values such as message, field, row, expected, and actual; these details are preserved in readable form in the Evaluation's criteria_errors. Script, parsing, download, and size-limit errors also fail the criterion. Each file is limited to 100 MB, and whole-batch mode additionally limits the combined raw input to 100 MB.

Required file rule keys may also include standard strftime-style date/time tokens like %Y, %m, and %d. Those tokens are resolved at evaluation time using a stable window anchor: schedule-driven expectations use the window's deadline_at, while manual and upload expectations use the window's opened_at.

History and incidents

The Expectation itself stores summary state like last_evaluated_at, last_success_at, last_failure_at, and last_result.

For deeper inspection:

ExpectationEvaluation history shows each open or closed window and the evidence captured for it.
ExpectationIncident records track ongoing failure situations over time, including acknowledge, snooze, and resolve actions.

Manual windows do not open incidents in v1. Schedule-driven failures can open incidents, and later qualifying success can resolve them.

List Expectations

SDK Method

Files::Expectation.list

Return Object

List<Expectation>

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Additional Arguments

Example Request

begin
  expectations = Files::Expectation.list
  expectations.auto_paging_each do |expectation|
    # Operate on expectation
  end
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Show Expectation

SDK Method

Files::Expectation.find

Return Object

Expectation

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Method Arguments

Argument	Description
id int64 Required	Expectation ID.

Example Request

begin
  expectation = Files::Expectation.find(id)
  # Operate on expectation
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Create Expectation

SDK Method

Files::Expectation.create

Return Object

Expectation

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Method Arguments

Argument	Default	Description
name string		Expectation name.
description string		Expectation description.
path string		Path scope for the expectation. Supports workspace-relative presentation.
source string	`"*"`	Source glob used to select candidate files.
exclude_pattern string		Optional source exclusion glob.
disabled boolean	`false`	If true, the expectation is disabled.
trigger string	`"manual"`	How this expectation opens windows. Possible values: `manual`, `upload`, `daily`, `custom_schedule`
interval string		If trigger is `daily`, this specifies how often to run the expectation.
recurring_day int64		If trigger is `daily`, this selects the day number inside the chosen interval.
recurring_days array(int64)		If trigger is `daily`, this selects one or more day numbers inside a `week`, `month`, `quarter`, or `year` interval.
schedule_id int64		If trigger is `custom_schedule`, the reusable Schedule used instead of the Expectation's schedule fields.
schedule_days_of_week array(int64)		If trigger is `custom_schedule`, the 0-based weekdays used by the schedule.
schedule_times_of_day array(string)		Times of day in HH:MM format for the Expectation schedule.
schedule_time_zone string		Time zone used by the Expectation schedule.
holiday_region string		Optional holiday region used by the Expectation schedule.
lookback_interval int64		How many seconds before the due boundary the window starts.
late_acceptance_interval int64		How many seconds a schedule-driven window may remain eligible to close as late.
inactivity_interval int64		How many quiet seconds are required before final closure.
max_open_interval int64		Hard-stop duration in seconds for unscheduled expectations.
criteria object		Versioned success criteria definition for the expectation, including optional Files Transform Script content validation in criteria v2.
workspace_id int64	`0`	Workspace ID. `0` means the default workspace.

Example Request

begin
  expectation = Files::Expectation.create(
    name: "Daily Vendor Feed"
  )
  # Operate on expectation
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Update Expectation

SDK Method

expectation.update

Return Object

Expectation

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Method Arguments

Argument	Description
name string	Expectation name.
description string	Expectation description.
path string	Path scope for the expectation. Supports workspace-relative presentation.
source string	Source glob used to select candidate files.
exclude_pattern string	Optional source exclusion glob.
disabled boolean	If true, the expectation is disabled.
trigger string	How this expectation opens windows. Possible values: `manual`, `upload`, `daily`, `custom_schedule`
interval string	If trigger is `daily`, this specifies how often to run the expectation.
recurring_day int64	If trigger is `daily`, this selects the day number inside the chosen interval.
recurring_days array(int64)	If trigger is `daily`, this selects one or more day numbers inside a `week`, `month`, `quarter`, or `year` interval.
schedule_id int64	If trigger is `custom_schedule`, the reusable Schedule used instead of the Expectation's schedule fields.
schedule_days_of_week array(int64)	If trigger is `custom_schedule`, the 0-based weekdays used by the schedule.
schedule_times_of_day array(string)	Times of day in HH:MM format for the Expectation schedule.
schedule_time_zone string	Time zone used by the Expectation schedule.
holiday_region string	Optional holiday region used by the Expectation schedule.
lookback_interval int64	How many seconds before the due boundary the window starts.
late_acceptance_interval int64	How many seconds a schedule-driven window may remain eligible to close as late.
inactivity_interval int64	How many quiet seconds are required before final closure.
max_open_interval int64	Hard-stop duration in seconds for unscheduled expectations.
criteria object	Versioned success criteria definition for the expectation, including optional Files Transform Script content validation in criteria v2.
workspace_id int64	Workspace ID. `0` means the default workspace.

Example Request

begin
  # Find the expectation object by its id.
  expectation = Files::Expectation.find(id)
  expectation.update(
    name: "Daily Vendor Feed"
  )
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Delete Expectation

SDK Method

expectation.delete

Return Object

nil

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Example Request

begin
  # Find the expectation object by its id.
  expectation = Files::Expectation.find(id)
  expectation.delete
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

The Expectation Object

Some of the methods above return a Expectation object. The attributes of this object are listed below.

Attribute	Description
id int64	Expectation ID
workspace_id int64	Workspace ID. `0` means the default workspace.
name string	Expectation name.
description string	Expectation description.
path string	Path scope for the expectation. Supports workspace-relative presentation. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
source string	Source glob used to select candidate files.
exclude_pattern string	Optional source exclusion glob.
disabled boolean	If true, the expectation is disabled.
expectations_version int64	Criteria schema version for this expectation.
trigger string	How this expectation opens windows. Possible values: `manual`, `upload`, `daily`, `custom_schedule`
interval string	If trigger is `daily`, this specifies how often to run the expectation.
recurring_day int64	If trigger is `daily`, this selects the day number inside the chosen interval.
recurring_days array(int64)	If trigger is `daily`, this selects one or more day numbers inside a `week`, `month`, `quarter`, or `year` interval.
schedule_id int64	If trigger is `custom_schedule`, the reusable Schedule used instead of the Expectation's schedule fields.
schedule_days_of_week array(int64)	If trigger is `custom_schedule`, the 0-based weekdays used by the schedule.
schedule_times_of_day array(string)	Times of day in HH:MM format for the Expectation schedule.
schedule_time_zone string	Time zone used by the Expectation schedule.
holiday_region string	Optional holiday region used by the Expectation schedule.
lookback_interval int64	How many seconds before the due boundary the window starts.
late_acceptance_interval int64	How many seconds a schedule-driven window may remain eligible to close as late.
inactivity_interval int64	How many quiet seconds are required before final closure.
max_open_interval int64	Hard-stop duration in seconds for unscheduled expectations.
criteria object	Versioned success criteria definition for the expectation. Criteria v2 supports optional FTS content validation.
last_evaluated_at date-time	Last time this expectation was evaluated.
last_success_at date-time	Last time this expectation closed successfully.
last_failure_at date-time	Last time this expectation closed with a failure result.
last_result string	Most recent terminal result for this expectation. Possible values: `success`, `late`, `missing`, `invalid`
created_at date-time	Creation time.
updated_at date-time	Last update time.

Expectations

SDK Method

Return Object

Authorization Requirement

Additional Arguments

Pagination

Sorting

Filtering

SDK Method

Return Object

Authorization Requirement

Method Arguments

SDK Method

Return Object

Authorization Requirement

Method Arguments

SDK Method

Return Object

Authorization Requirement

Method Arguments

SDK Method

Return Object

Authorization Requirement