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.

Folder References​

A Folder Reference identifies a directory managed by a storage provider. Obtain it from a folder-producing activity, such as FTP Create Folder or Google Drive Get Folder, and bind it to inputs that accept a folder reference, such as Write To CSV → Target Folder.

A folder reference is distinct from a file reference, a provider item ID, or a path string. Follow the target input's supported selection methods. IB Drive activities that expose By Id can also use the returned folder ItemId.

References and Base64 content​

Pass a file reference directly when the next activity accepts one. For an email attachment, use attachment.File. Use AttachmentReference with a mailbox attachment-retrieval activity when you specifically need its Base64 File Content output. A Base64 string contains encoded bytes; it cannot be bound directly to a file-reference input.

The storage item and its connection must remain accessible when a downstream activity reads or writes the reference.

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 Workflow Data, or in Agent Data when the collection is needed across workflows.
  2. Add file references to the collection.
  3. Bind the collection to the target activity.

For example:

  1. Define a FileReference[] field named AttachmentFiles in Workflow Data or Agent Data.
  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
Help improve this page