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:

  1. Scope: where to look for candidate files, using path, source, and optional exclude_pattern.
  2. 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.
  3. Criteria: what must be true for the window to succeed, using the structured criteria JSON document.
  4. 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

expectation.List()

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.

Additional Arguments

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/expectation"
)

expectationIterator, err := expectation.List(files_sdk.ExpectationListParams{})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for expectationIterator.Next() {
    expectation := expectationIterator.expectation()
}
err = expectationIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Show Expectation

SDK Method

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.

ExpectationFindParams Fields

FieldDescription
Id
int64
Required		Expectation ID.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/expectation"
)

expectation, err := expectation.Find(files_sdk.ExpectationFindParams{Id: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Create Expectation

SDK Method

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.

ExpectationCreateParams Fields

FieldDefaultDescription
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.
ExcludePattern
string		Optional source exclusion glob.
Disabled
boolean		falseIf 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.
RecurringDay
int64		If trigger is daily, this selects the day number inside the chosen interval.
RecurringDays
array(int64)		If trigger is daily, this selects one or more day numbers inside a week, month, quarter, or year interval.
ScheduleId
int64		If trigger is custom_schedule, the reusable Schedule used instead of the Expectation's schedule fields.
ScheduleDaysOfWeek
array(int64)		If trigger is custom_schedule, the 0-based weekdays used by the schedule.
ScheduleTimesOfDay
array(string)		Times of day in HH:MM format for the Expectation schedule.
ScheduleTimeZone
string		Time zone used by the Expectation schedule.
HolidayRegion
string		Optional holiday region used by the Expectation schedule.
LookbackInterval
int64		How many seconds before the due boundary the window starts.
LateAcceptanceInterval
int64		How many seconds a schedule-driven window may remain eligible to close as late.
InactivityInterval
int64		How many quiet seconds are required before final closure.
MaxOpenInterval
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.
WorkspaceId
int64		0Workspace ID. 0 means the default workspace.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/expectation"
)

expectation, err := expectation.Create(files_sdk.ExpectationCreateParams{Name: "Daily Vendor Feed"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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.

ExpectationUpdateParams Fields

FieldDescription
Id
int64
Required		Expectation ID.
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.
ExcludePattern
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.
RecurringDay
int64		If trigger is daily, this selects the day number inside the chosen interval.
RecurringDays
array(int64)		If trigger is daily, this selects one or more day numbers inside a week, month, quarter, or year interval.
ScheduleId
int64		If trigger is custom_schedule, the reusable Schedule used instead of the Expectation's schedule fields.
ScheduleDaysOfWeek
array(int64)		If trigger is custom_schedule, the 0-based weekdays used by the schedule.
ScheduleTimesOfDay
array(string)		Times of day in HH:MM format for the Expectation schedule.
ScheduleTimeZone
string		Time zone used by the Expectation schedule.
HolidayRegion
string		Optional holiday region used by the Expectation schedule.
LookbackInterval
int64		How many seconds before the due boundary the window starts.
LateAcceptanceInterval
int64		How many seconds a schedule-driven window may remain eligible to close as late.
InactivityInterval
int64		How many quiet seconds are required before final closure.
MaxOpenInterval
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.
WorkspaceId
int64		Workspace ID. 0 means the default workspace.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/expectation"
)

expectation, err := expectation.Update(files_sdk.ExpectationUpdateParams{
  Id: 1,
  Name: "Daily Vendor Feed"
})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Delete Expectation

SDK Method

expectation.Delete()

Return Object

No return value.

Authorization Requirement

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

ExpectationDeleteParams Fields

FieldDescription
Id
int64
Required		Expectation ID.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/expectation"
)

err := expectation.Delete(files_sdk.ExpectationDeleteParams{Id: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

The Expectation Object

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

AttributeDescription
Id
int64		Expectation ID
WorkspaceId
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.
ExcludePattern
string		Optional source exclusion glob.
Disabled
boolean		If true, the expectation is disabled.
ExpectationsVersion
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.
RecurringDay
int64		If trigger is daily, this selects the day number inside the chosen interval.
RecurringDays
array(int64)		If trigger is daily, this selects one or more day numbers inside a week, month, quarter, or year interval.
ScheduleId
int64		If trigger is custom_schedule, the reusable Schedule used instead of the Expectation's schedule fields.
ScheduleDaysOfWeek
array(int64)		If trigger is custom_schedule, the 0-based weekdays used by the schedule.
ScheduleTimesOfDay
array(string)		Times of day in HH:MM format for the Expectation schedule.
ScheduleTimeZone
string		Time zone used by the Expectation schedule.
HolidayRegion
string		Optional holiday region used by the Expectation schedule.
LookbackInterval
int64		How many seconds before the due boundary the window starts.
LateAcceptanceInterval
int64		How many seconds a schedule-driven window may remain eligible to close as late.
InactivityInterval
int64		How many quiet seconds are required before final closure.
MaxOpenInterval
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.
LastEvaluatedAt
date-time		Last time this expectation was evaluated.
LastSuccessAt
date-time		Last time this expectation closed successfully.
LastFailureAt
date-time		Last time this expectation closed with a failure result.
LastResult
string		Most recent terminal result for this expectation.
Possible values: success, late, missing, invalid
CreatedAt
date-time		Creation time.
UpdatedAt
date-time		Last update time.