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

# Creating Workflow Templates

> Learn how to build effective workflow templates for reproducible research

This guide covers the anatomy of workflow templates and best practices for creating effective, reusable research workflows.

## Template Anatomy

A workflow template consists of:

| Field            | Required | Description                               |
| ---------------- | -------- | ----------------------------------------- |
| `name`           | Yes      | Template name for identification          |
| `prompt`         | Yes      | Research prompt with Jinja2 placeholders  |
| `description`    | No       | Human-readable description                |
| `expected_input` | No       | Schema defining required inputs           |
| `content_filter` | No       | Restrictions on searchable content        |
| `research_plan`  | No       | Predefined steps for structured execution |

## Basic Template Structure

```json theme={null}
{
  "name": "Company Financial Analysis",
  "description": "Comprehensive financial analysis for any public company",
  "prompt": "Analyze {{ company_id }} from an investment perspective. Include financial metrics, competitive position, and growth outlook.",
  "expected_input": {
    "company_id": {
      "type": "rp_entity_id"
    }
  }
}
```

## Input Types

### `rp_entity_id`

Use for Bigdata entity identifiers (companies, ETFs, etc.):

```json theme={null}
{
  "expected_input": {
    "company_id": {"type": "rp_entity_id"},
    "competitor_id": {"type": "rp_entity_id"}
  }
}
```

Entity IDs can be found using the [Knowledge Graph API](/api-reference/companies/find-by-details).

### `string`

Use for free-form text input:

```json theme={null}
{
  "expected_input": {
    "topic": {"type": "string"},
    "region": {"type": "string"}
  }
}
```

Example prompt using string inputs:

```jinja2 theme={null}
Research {{ topic }} trends in the {{ region }} market.
Focus on key players, regulatory changes, and investment opportunities.
```

## Content Filters

Restrict which sources the research uses:

### Filter by Document Type

```json theme={null}
{
  "content_filter": {
    "any_of": [
      {
        "type": "DOCUMENT_TYPE",
        "document_types": [
          {"type": "TRANSCRIPT", "subtype": "Earnings Call"},
          {"type": "FILING"}
        ]
      }
    ]
  }
}
```

### Filter by Source

```json theme={null}
{
  "content_filter": {
    "any_of": [
      {
        "type": "SOURCE_TYPE",
        "sources_ids": ["ABC123", "DEF456"]
      }
    ]
  }
}
```

### Exclude Specific Content

```json theme={null}
{
  "content_filter": {
    "none_of": [
      {
        "type": "DOCUMENT_TYPE",
        "document_types": [
          {"type": "NEWS"}
        ]
      }
    ]
  }
}
```

### Available Document Types

| Type                      | Subtypes                                                               |
| ------------------------- | ---------------------------------------------------------------------- |
| `TRANSCRIPT`              | Earnings Call, General Conference Call, Investor Conference Call, etc. |
| `TRANSCRIPT-PRESENTATION` | Same subtypes as TRANSCRIPT                                            |
| `FILING`                  | RNS-SEC-10-K, RNS-SEC-10-Q, RNS-SEC-8-K, etc.                          |
| `NEWS`                    | (no subtypes)                                                          |

## Research Plans

Add a research plan for structured, step-by-step execution:

```json theme={null}
{
  "research_plan": {
    "title": "Comprehensive Credit Analysis",
    "steps": [
      {"description": "Gather company background and business model"},
      {"description": "Analyze recent financial statements and leverage metrics"},
      {"description": "Review credit ratings and analyst commentary"},
      {"description": "Assess key credit risks and mitigants"},
      {"description": "Evaluate liquidity and debt maturity profile"},
      {"description": "Formulate investment recommendation"}
    ]
  }
}
```

<Tip>
  When a `research_plan` is provided, the agent follows your predefined steps for structured, predictable output. Without a plan, the agent dynamically determines research steps based on your prompt.
</Tip>

## Complete Example

Here's a complete template for M\&A transaction analysis:

```json theme={null}
{
  "name": "M&A Transaction Analysis",
  "description": "Detailed analysis of merger or acquisition transactions",
  "prompt": "Analyze the {{ transaction_type }} involving {{ acquirer_id }} and {{ target_id }}. Include:\n\n1. Transaction overview and strategic rationale\n2. Financial terms and valuation analysis\n3. Synergy expectations and integration risks\n4. Regulatory considerations\n5. Market reaction and analyst views\n6. Impact on competitive landscape",
  "expected_input": {
    "acquirer_id": {"type": "rp_entity_id"},
    "target_id": {"type": "rp_entity_id"},
    "transaction_type": {"type": "string"}
  },
  "content_filter": {
    "any_of": [
      {
        "type": "DOCUMENT_TYPE",
        "document_types": [
          {"type": "NEWS"},
          {"type": "FILING"},
          {"type": "TRANSCRIPT", "subtype": "Special Situation, M&A and Other"}
        ]
      }
    ]
  },
  "research_plan": {
    "title": "M&A Analysis Framework",
    "steps": [
      {"description": "Research transaction details and timeline"},
      {"description": "Analyze deal terms and valuation metrics"},
      {"description": "Evaluate strategic fit and synergy potential"},
      {"description": "Review regulatory filings and antitrust considerations"},
      {"description": "Gather analyst reactions and market sentiment"},
      {"description": "Synthesize findings and outlook"}
    ]
  }
}
```

## Creating Templates via API

```python theme={null}
import requests
from dotenv import load_dotenv
import os

load_dotenv()
my_api_key = os.getenv('BIGDATA_API_KEY')

template = {
    "name": "Quarterly Earnings Preview",
    "description": "Pre-earnings analysis for upcoming quarterly reports",
    "prompt": """Prepare an earnings preview for {{ company_id }} ahead of their upcoming quarterly report.

Include:
1. Consensus estimates (revenue, EPS)
2. Key metrics to watch
3. Recent business developments
4. Management guidance and commentary
5. Analyst sentiment and price targets
6. Potential catalysts or risks""",
    "expected_input": {
        "company_id": {"type": "rp_entity_id"}
    },
    "content_filter": {
        "any_of": [
            {
                "type": "DOCUMENT_TYPE",
                "document_types": [
                    {"type": "TRANSCRIPT", "subtype": "Earnings Call"},
                    {"type": "NEWS"}
                ]
            }
        ]
    }
}

response = requests.post(
    "https://agents.bigdata.com/v1/workflow/templates",
    headers={
        "X-API-KEY": my_api_key,
        "Content-Type": "application/json"
    },
    json=template
)

created = response.json()
print(f"Created template: {created['id']}")
print(f"Name: {created['name']}")
```

## Best Practices

1. **Clear, specific prompts**: Include numbered sections or bullet points for structured output
2. **Appropriate input types**: Use `rp_entity_id` for entities to enable entity-aware search
3. **Content filters**: Restrict to relevant document types for focused research
4. **Research plans**: Add plans for complex, multi-step analyses
5. **Descriptive names**: Use clear template names for easy identification
6. **Documentation**: Add descriptions explaining the template's purpose

## Next Steps

<CardGroup cols={2}>
  <Card title="Research Plans" icon="play" href="/how-to-guides/workflows/execution_modes">
    Learn how research plans affect execution
  </Card>

  <Card title="Example Templates" icon="lightbulb" href="/how-to-guides/workflows/example_templates">
    Ready-to-use financial analysis templates
  </Card>
</CardGroup>