> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Foundry examples

> Real Foundry use cases teams build in Ravenna, with the prompts that generated each custom function and integration and notes on adapting them to your tools.

These are starting points, not copy-paste recipes. Your integrations and field names will differ. Each example shows the **prompt** you'd give Foundry, the **integration shape** it needs, and how teams typically use it. Adapt them to your stack.

<Callout icon="link" color="#6B7280">
  New to building functions? Walk through the [Building functions](/documentation/automate/foundry/actions) reference first, then come back for ideas.
</Callout>

***

## Enrich a ticket from your CRM

**What it does.** When a new ticket is created, look up the requester in your CRM by email and return their company name, account tier, and account owner. Used by a workflow to set ticket fields and route to the right queue.

**Integration shape.** Custom API integration to your CRM. API key or bearer token, depending on what the CRM uses.

**Prompt to Foundry:**

<Prompt description="Take an email as input. Call the CRM's contact search endpoint to find a contact with that email. Return the contact's company name, account tier (free, pro, or enterprise), and account owner's email. If no contact is found, return null for each field.">
  Take an email as input. Call the CRM's contact search endpoint to find a contact with that email. Return the contact's company name, account tier (free, pro, or enterprise), and account owner's email. If no contact is found, return null for each field.
</Prompt>

**How teams use it.** Wire the function's output into a workflow's **Update ticket** step. Set a custom field for `account_tier` and route the ticket to a different queue based on the tier.

***

## Send a DocuSign envelope for signature

**What it does.** Send a contract for signature from a saved DocuSign template. Used by agents and workflows when a request is approved and a document needs to go out.

**Integration shape.** Custom OAuth provider for DocuSign ([walkthrough here](/guides/how-to/foundry/setup-oauth/docusign)). Scopes: `signature extended`.

**Prompt to Foundry:**

<Prompt description="Take a template ID, a recipient email, and a recipient name as input. Fetch the user's default account ID and base URI from /oauth/userinfo, then create an envelope from the template with that recipient as the signer. Send the envelope and return the envelope ID and status.">
  Take a template ID, a recipient email, and a recipient name as input. Fetch the user's default account ID and base URI from /oauth/userinfo, then create an envelope from the template with that recipient as the signer. Send the envelope and return the envelope ID and status.
</Prompt>

**How teams use it.** Reference the published function in an agent rule:

<Prompt description="When a user's NDA request is approved, use @Send DocuSign envelope with the standard NDA template ID. Use the requester's email and name. Share the envelope status with the user once it's sent.">
  When a user's NDA request is approved, use @Send DocuSign envelope with the standard NDA template ID. Use the requester's email and name. Share the envelope status with the user once it's sent.
</Prompt>

***

## "Where's my package?" lookup

**What it does.** Look up an order by ID in your e-commerce platform and return the current shipping status and tracking URL.

**Integration shape.** Custom API integration to Shopify, BigCommerce, or your own order system.

**Prompt to Foundry:**

<Prompt description="Take an order ID. Call the orders endpoint to fetch the order. Return the current fulfilment status, the carrier name, the tracking number, and the carrier's tracking URL. If the order has no fulfilments yet, return status: not_shipped and null for the other fields.">
  Take an order ID. Call the orders endpoint to fetch the order. Return the current fulfilment status, the carrier name, the tracking number, and the carrier's tracking URL. If the order has no fulfilments yet, return status: "not\_shipped" and null for the other fields.
</Prompt>

**How teams use it.** Agents call it when a customer asks about an order. The agent reads the status and replies in plain language.

***

## Find a meeting on the user's calendar

**What it does.** Find the next event on the requester's Google Calendar that matches a topic. Used by agents to help users reschedule or share meeting details.

**Integration shape.** Custom OAuth provider for Google ([walkthrough here](/guides/how-to/foundry/setup-oauth/google-cloud)). Scope: `https://www.googleapis.com/auth/calendar.readonly`.

**Prompt to Foundry:**

<Prompt description="Take a search query and a number of days as input. Call the Calendar events.list endpoint for the user's primary calendar, filter to events in the next N days whose title or description contains the query, and return the first match with its title, start time, end time, and meeting link.">
  Take a search query and a number of days as input. Call the Calendar events.list endpoint for the user's primary calendar, filter to events in the next N days whose title or description contains the query, and return the first match with its title, start time, end time, and meeting link.
</Prompt>

**How teams use it.** Plug into an agent rule for the scheduling assistant.

***

## Send a Slack DM with a custom payload

**What it does.** Build a custom-formatted Slack message (with blocks, buttons, or fields your built-in Slack actions don't expose) and send it to a user.

**Integration shape.** Select your Slack integration on the Integrations tab so the action can call the Slack Web API. Your workspace's bot token is attached automatically, so the code passes Slack arguments only, never a workspace or team id. A direct message needs the Slack member ID: open a DM channel with `conversations.open`, then post with `chat.postMessage`.

**Prompt to Foundry:**

<Prompt description="Take a Slack member ID and a list of { label, value } pairs as input. Format the pairs as Slack blocks with bold labels. Call conversations.open with the member ID to get a DM channel, then call chat.postMessage to send the message. Check the ok field on each Slack response and throw on error. Return the message ts.">
  Take a Slack member ID and a list of { label, value } pairs as input. Format the pairs as Slack blocks with bold labels. Call conversations.open with the member ID to get a DM channel, then call chat.postMessage to send the message. Check the ok field on each Slack response and throw on error. Return the message ts.
</Prompt>

**How teams use it.** As a notification step at the end of a workflow.

***

## Combine two systems in one function

**What it does.** Look up a customer in your CRM, then immediately create a Linear issue tagged with their account tier. One function, two integrations.

**Integration shape.** Two custom API integrations on the same function: CRM (primary) and Linear.

**Prompt to Foundry:**

<Prompt description="Take a customer email and an issue title as input. Look up the customer in the CRM by email to get their company and account tier. Create a Linear issue with the given title, prepend [Tier: tier] to the title, and add the company name to the description. Return the Linear issue URL.">
  Take a customer email and an issue title as input. Look up the customer in the CRM by email to get their company and account tier. Create a Linear issue with the given title, prepend \[Tier: tier] to the title, and add the company name to the description. Return the Linear issue URL.
</Prompt>

**How teams use it.** A single workflow step replaces what used to be two steps with manual mapping in between.

<Callout icon="link" color="#6B7280">
  Multi-integration functions: the function uses `ctx.integrations.<slug>` to choose which tool each call hits. See [Building functions → Advanced](/documentation/automate/foundry/actions) for the SDK details.
</Callout>

***

## Patterns worth copying

* **Always return a stable shape.** Decide what your function returns up front (`{ id, url, status }`) and tell Foundry. It makes workflows easier to wire.
* **Handle the "not found" case explicitly.** "If no result is found, return `null` for each field" produces much better code than letting Foundry guess.
* **Mention pagination if it matters.** "Fetch every page until there are no more results" or "stop after 50 results". Both are clearer than silence.
* **Use the chat to add behaviour incrementally.** Get the happy path working first, then ask "now retry on 429 up to three times" or "now also include the account owner."

<CardGroup cols={2}>
  <Card title="Tips & troubleshooting" icon="life-ring" href="/guides/how-to/foundry/tips-and-troubleshooting">
    Get more out of Foundry, and fix the most common issues.
  </Card>

  <Card title="Using functions" icon="zap" href="/documentation/automate/foundry/using-actions">
    How published functions show up in workflows and agents.
  </Card>
</CardGroup>