Skip to main content
Version: Current

File Reference

Overview​

A File Reference is a file handle that allows workflows to pass files between activities without storing file content directly in variables.

Activities that produce files return a File Reference. Activities that consume files can accept a File Reference as input.

At runtime, the platform uses the File Reference to access the underlying file through the connection or storage provider that produced it.

Benefits​

Using File References provides several advantages:

  • Avoids storing large file content as Base64 strings.
  • Allows files to be passed efficiently between workflow activities.
  • Supports files originating from multiple sources, including email attachments, cloud storage, and file management activities.
  • Enables AI, document processing, and file manipulation activities to work with the same file handle.

Single File vs FileReference[]​

Some activities accept a single file:

FileReference

Examples:

  • Azure AI Foundry Analyze Document
  • Microsoft Word activities
  • PDF activities
  • Excel activities

Other activities accept multiple files:

FileReference[]

Examples:

  • OpenAI Generate Response (Files)
  • OpenAI Generate Response (Image Files)

A FileReference[] is a collection of File References.

How to Use a File Reference​

Passing a Single File​

Many document-processing activities accept a single File Reference.

Typical flow:

Producer Activity → FileReference → Consumer Activity

Examples:

  • Email attachment → Analyze Document
  • Google Drive file → Read PDF
  • Download File → Word Activity

Passing Multiple Files​

Activities that accept multiple files require a FileReference[].

Typical flow:

  1. Create a FileReference[] field in Model Data.
  2. Add file references to the collection.
  3. Bind the collection to the target activity.

For example:

  1. Define a FileReference[] field in Model Data (for example, AttachmentFiles).
  2. Use Add To Collection to add file references to the collection.
  3. Bind the collection to the target activity input.

Common Workflow Patterns​

Email Attachment → OpenAI Generate Response​

  1. Read email attachments using Read IMAP Email.
  2. Add each attachment's File value to a FileReference[].
  3. Bind the collection to Files or Image Files on Generate Response.

See:

File → Azure AI Foundry Analyze Document​

  1. Obtain a File Reference from a previous activity.
  2. Bind the File Reference to Document File.
  3. Run Analyze Document.

See:

Example​

flowchart LR
  Email[Read IMAP Email]
  Collection[FileReference[]]
  OpenAI[Generate Response]

  Email --> Collection
  Collection --> OpenAI