# Run Agentic Task
Source: https://docs.shieldbase.ai/api-reference/endpoint/external/agents-run

post /external/agents/run
Execute an agentic task and block until completion



# Create New Conversation
Source: https://docs.shieldbase.ai/api-reference/endpoint/external/conversations

post /external/conversations
Start a new AI conversation and stream the response via Server-Sent Events



# Continue Conversation
Source: https://docs.shieldbase.ai/api-reference/endpoint/external/conversations-continue

post /external/conversations/{conversation_id}
Send a follow-up message to an existing conversation



# List Library Files
Source: https://docs.shieldbase.ai/api-reference/endpoint/external/libraries

get /external/libraries
Browse files in your library with pagination, filtering, and sorting



# Models
Source: https://docs.shieldbase.ai/api-reference/endpoint/external/models

get /external/models



# Semantic + Keyword Search
Source: https://docs.shieldbase.ai/api-reference/endpoint/external/search

post /external/search
Perform hybrid BM25 + semantic vector search across all indexed content



# Upload
Source: https://docs.shieldbase.ai/api-reference/endpoint/external/upload

post /external/upload



# External API
Source: https://docs.shieldbase.ai/api-reference/external-api

Complete guide to Shieldbase External API for headless AI integration

## Overview

The Shieldbase External API provides a comprehensive set of endpoints for integrating AI capabilities into your applications. This API supports:

* **Models Management** - List available AI models
* **File Upload & Indexing** - Upload documents for semantic search
* **Library Management** - Browse and manage uploaded files
* **Semantic Search** - Hybrid BM25 + vector search across your content
* **Chat Streaming** - Real-time AI conversations via SSE
* **Headless Agents** - Blocking agentic task execution

<Note>
  All endpoints are mounted at `/external-docs` and require API key authentication.
  Interactive documentation is available at `/external-docs/docs` (Scalar UI).
</Note>

***

## Authentication

All API endpoints (except `/external/keys/*`) require three headers:

```bash theme={null}
X-Client-ID: your-client-id
X-API-Key: your-api-key  
X-Secret: your-secret
```

### Getting API Keys

1. Login to your Shieldbase account at [https://app.sbai.cloud/](https://app.sbai.cloud/)
2. Navigate to **Settings → API**
3. Click **"Generate"** to create your API credentials
4. **Save them securely** - the API key is only shown once!

<Warning>
  Keep your API credentials secure. Never commit them to version control or expose them in client-side code.
</Warning>

***

## Base URLs

<CodeGroup>
  ```bash Production theme={null}
  https://api.shieldbase.ai
  ```

  ```bash Development theme={null}
  http://localhost:8000
  ```
</CodeGroup>

***

## Quick Start

### 1. Set Environment Variables

```bash theme={null}
export SBAI_CLIENT_ID="sbai_client_xxx"
export SBAI_API_KEY="sbai_sk_xxx"
export SBAI_SECRET="sbai_secret_xxx"
export SBAI_BASE_URL="https://api.shieldbase.ai"
```

### 2. Test Connection

```bash theme={null}
curl -X GET "${SBAI_BASE_URL}/external/models" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}"
```

***

## Endpoints

### Models

#### List Available Models

**GET /external/models**

Returns all AI models available in the system with real-time availability status.

**Example Request:**

```bash theme={null}
curl -X GET "${SBAI_BASE_URL}/external/models" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}"
```

**Example Response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "gpt-5.1",
      "name": "GPT-5.1",
      "image": "openai-logo.png",
      "group_name": "OpenAI",
      "is_available": true
    },
    {
      "id": "gemini-2.5-pro",
      "name": "Gemini 2.5 Pro",
      "image": "google-logo.png",
      "group_name": "Google",
      "is_available": true
    }
  ]
}
```

***

### Upload

#### Upload Files to Library

**POST /external/upload**

Upload files asynchronously. Files are queued for indexing and become searchable once processing completes.

**Supported file types:**\
`pdf`, `doc`, `docx`, `xls`, `xlsx`, `csv`, `json`, `txt`, `html`, `ppt`, `pptx`, `zip`, `md`, `sql`, `yml`, `yaml`, `png`, `jpg`, `jpeg`, `gif`, `webp`

**Max file size:** 1 GB per file

**Example Request:**

```bash theme={null}
curl -X POST "${SBAI_BASE_URL}/external/upload" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -F "files=@report.pdf" \
  -F "files=@data.csv" \
  -F "folder_paths=reports/2024"
```

**Example Response:**

```json theme={null}
{
  "message": "Uploaded content is being processed",
  "data": [
    {
      "id": "abc123",
      "file_name": "report.pdf",
      "state": "loading",
      "provider": "file"
    },
    {
      "id": "def456",
      "file_name": "data.csv",
      "state": "loading",
      "provider": "file"
    }
  ]
}
```

***

### Libraries

#### List Library Files

**GET /external/libraries**

Retrieve paginated list of library files with advanced filtering options.

**Query Parameters:**

| Parameter      | Type   | Default | Description                                       |
| -------------- | ------ | ------- | ------------------------------------------------- |
| `page`         | int    | 1       | Page number (starts at 1)                         |
| `page_size`    | int    | 40      | Items per page (max 100)                          |
| `search`       | string | -       | Search by file name or folder path                |
| `provider`     | string | -       | Filter by provider (e.g. `file`, `google_drive`)  |
| `folder_paths` | string | -       | Filter by folder path                             |
| `file_types`   | string | -       | Comma-separated file extensions (e.g. `pdf,docx`) |
| `sort_by`      | string | -       | Field to sort by (e.g. `created_at`, `file_name`) |
| `sort_order`   | string | desc    | Sort direction: `asc` or `desc`                   |

**Example Request:**

```bash theme={null}
curl -X GET "${SBAI_BASE_URL}/external/libraries?page=1&page_size=40&sort_order=desc" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}"
```

**Example Response:**

```json theme={null}
{
  "total_items": 120,
  "providers": { "file": 80, "google_drive": 40 },
  "page": 1,
  "page_size": 40,
  "total_pages": 3,
  "items": [
    {
      "id": "abc123",
      "file_name": "report.pdf",
      "provider": "file",
      "mime_type": "application/pdf",
      "state": "success",
      "download_link": "https://cdn.shieldbase.ai/...",
      "created_at": "2024-06-22T10:00:00",
      "folder_path": ["reports", "2024"],
      "is_shared": false
    }
  ]
}
```

***

### Search

#### Semantic + Keyword Search

**POST /external/search**

Combine keyword matching (BM25) with semantic similarity (vector search) for best results.

**Payload Fields:**

| Field                | Type      | Default      | Description                                        |
| -------------------- | --------- | ------------ | -------------------------------------------------- |
| `keyword` or `query` | string    | **required** | Search query                                       |
| `limit` or `top_k`   | int       | 20           | Max results (max 100)                              |
| `group_by_file`      | bool      | false        | Merge chunks from same file                        |
| `types`              | string\[] | -            | Filter by type: `file`, `workflow`, `conversation` |
| `use_bm25`           | bool      | true         | Enable BM25 keyword search                         |
| `use_vector`         | bool      | true         | Enable semantic vector search                      |
| `bm25_weight`        | float     | 0.7          | BM25 score weight (0–1)                            |
| `vector_weight`      | float     | 0.3          | Vector score weight (0–1)                          |
| `relative_threshold` | float     | 0.7          | Min score as % of top result                       |

**Example Request:**

```bash theme={null}
curl -X POST "${SBAI_BASE_URL}/external/search" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "quarterly revenue",
    "limit": 40,
    "group_by_file": true
  }'
```

**Advanced Search Example:**

```bash theme={null}
curl -X POST "${SBAI_BASE_URL}/external/search" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue report",
    "top_k": 20,
    "types": ["file", "workflow"],
    "use_bm25": true,
    "use_vector": true,
    "bm25_weight": 0.7,
    "vector_weight": 0.3,
    "relative_threshold": 0.7,
    "group_by_file": true
  }'
```

**Example Response:**

```json theme={null}
{
  "success": true,
  "results": [
    {
      "id": "local-user##report.pdf",
      "title": "Q1 Revenue Report 2024.pdf",
      "content": "The quarterly revenue increased by...",
      "type": "library",
      "provider": "file",
      "score": 0.95
    }
  ]
}
```

***

### Chat (Streaming)

#### Create New Conversation

**POST /external/conversations**

Create a new conversation and receive real-time AI responses via SSE streaming.

**Payload Fields:**

| Field                 | Type      | Default      | Description                                 |
| --------------------- | --------- | ------------ | ------------------------------------------- |
| `content`             | string    | **required** | The user message                            |
| `model`               | string    | gpt-5.1      | AI model ID (see `/external/models`)        |
| `document_ids`        | string\[] | -            | Library file IDs to include as context      |
| `file_ids`            | string\[] | -            | Uploaded file IDs (from `/external/upload`) |
| `user_timezone`       | string    | UTC          | IANA timezone (e.g. `Asia/Jakarta`)         |
| `quoted_text`         | string    | -            | Text to quote/reply to                      |
| `additional_metadata` | object    | -            | Extended options (see below)                |

**`additional_metadata` Options:**

| Field          | Type      | Default | Description                                  |
| -------------- | --------- | ------- | -------------------------------------------- |
| `web_search`   | bool      | true    | Enable web search                            |
| `think`        | bool      | false   | Extended thinking mode                       |
| `agentic_mode` | bool      | false   | Agentic multi-step mode                      |
| `agent_id`     | string    | -       | Specific agent ID                            |
| `preferences`  | object    | -       | `{language, output_style, tones, character}` |
| `side_by_side` | bool      | false   | Run two models in parallel                   |
| `models`       | string\[] | -       | `[modelA, modelB]` for side-by-side          |

**Example Request:**

```bash theme={null}
curl -N -X POST "${SBAI_BASE_URL}/external/conversations" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What is machine learning?",
    "model": "gpt-5.1",
    "additional_metadata": {
      "web_search": true
    }
  }'
```

**SSE Event Types:**

| Event                  | Payload                               | Notes                                  |
| ---------------------- | ------------------------------------- | -------------------------------------- |
| `stream_meta`          | `{run_id, conversation_id}`           | First event; persist `conversation_id` |
| `conversation_created` | `{conversation_id}`                   | New-conversation endpoint only         |
| `message_start`        | `{message_id, user_message_id}`       | AI reply started                       |
| `content`              | `{content: "…chunk…"}`                | Stream text chunk                      |
| `thinking`             | `{content: "…"}`                      | Extended-thinking mode only            |
| `done`                 | `{conversation_id, message_id, …}`    | Stream complete                        |
| `error`                | `{content: "stream_error", error_id}` | Fatal error                            |

#### Continue Existing Conversation

**POST /external/conversations/**

Send a follow-up message to an existing conversation and stream the AI reply.

**Example Request:**

```bash theme={null}
curl -N -X POST "${SBAI_BASE_URL}/external/conversations/{conversation_id}" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Can you explain that in more detail?",
    "model": "gpt-5.1"
  }'
```

<Note>
  Use the `conversation_id` from the `conversation_created` event to continue the thread.
</Note>

***

### Agents (Headless Execution)

#### Run Agentic Task

**POST /external/agents/run**

Headless agentic execution - perfect for automation, scripts, and webhooks.

**Payload Fields:**

| Field                 | Type      | Default      | Description                                 |
| --------------------- | --------- | ------------ | ------------------------------------------- |
| `prompt`              | string    | **required** | The task / instruction to execute           |
| `agent_id`            | string    | -            | Specific agent ID to use                    |
| `model`               | string    | -            | AI model override (see `/external/models`)  |
| `document_ids`        | string\[] | -            | Library file IDs to include as context      |
| `file_ids`            | string\[] | -            | Uploaded file IDs (from `/external/upload`) |
| `user_timezone`       | string    | UTC          | IANA timezone                               |
| `timeout_seconds`     | int       | 600          | Max wait time (max 1800)                    |
| `additional_metadata` | object    | -            | Extra options passed through to the model   |

**Example Request:**

```bash theme={null}
curl -X POST "${SBAI_BASE_URL}/external/agents/run" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Analyze the Q1 sales data and generate a summary report with charts",
    "document_ids": ["local-user##q1_sales.xlsx"],
    "timeout_seconds": 300
  }'
```

**Example Response:**

```json theme={null}
{
  "conversation_id": "8e5245f6-...",
  "output": "## Q1 Sales Summary\n\nKey highlights: ...",
  "generated_files": [
    {
      "url": "https://cdn.shieldbase.ai/...",
      "filename": "q1_summary.pdf",
      "size": 204800
    }
  ],
  "success": true,
  "error": null
}
```

**When to use `/external/agents/run` vs `/external/conversations`:**

|                   | `/external/agents/run`                 | `/external/conversations`                   |
| ----------------- | -------------------------------------- | ------------------------------------------- |
| Response          | Blocking JSON                          | SSE stream                                  |
| Best for          | Headless automation, scripts, webhooks | Real-time UI, progress display              |
| `generated_files` | Included directly in response          | Requires fetching conversation after `done` |

<Warning>
  **Timeout:** Default 10 minutes, max 30 minutes. Returns HTTP 408 if exceeded.
</Warning>

***

## Privacy & Data Redaction

### Redacting Sensitive Information

To protect sensitive data in prompts and responses, you can enable automatic redaction of:

* **PII (Personally Identifiable Information):** Names, emails, phone numbers, addresses
* **Financial Data:** Credit card numbers, bank account numbers
* **Credentials:** API keys, passwords, tokens
* **Custom Patterns:** Define your own regex patterns for domain-specific data

**Example configuration (backend):**

```python theme={null}
# backend/sbai/config.py or environment variables
ENABLE_PII_REDACTION = True
REDACTION_PATTERNS = {
    "email": r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b",
    "phone": r"\b\d{3}[-.]?\d{3}[-.]?\d{4}\b",
    "credit_card": r"\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b",
}
```

**Example usage in API request:**

```bash theme={null}
curl -X POST "${SBAI_BASE_URL}/external/conversations" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Process this customer data: John Doe, john@example.com, 555-1234",
    "model": "gpt-5.1",
    "additional_metadata": {
      "redact_pii": true
    }
  }'
```

The system will automatically redact sensitive information:

* Input: `"John Doe, john@example.com, 555-1234"`
* Processed: `"[REDACTED_NAME], [REDACTED_EMAIL], [REDACTED_PHONE]"`

***

## Rate Limits

<Info>
  **100 requests per minute** per API key
</Info>

Rate limit headers are included in responses:

* `X-RateLimit-Limit`: Total requests allowed per minute
* `X-RateLimit-Remaining`: Requests remaining in current window
* `X-RateLimit-Reset`: Unix timestamp when the limit resets

***

## Error Handling

All errors follow this format:

```json theme={null}
{
  "error": "error_code",
  "message": "Human readable error message"
}
```

**Common error codes:**

| Code                  | HTTP Status | Description             |
| --------------------- | ----------- | ----------------------- |
| `invalid_credentials` | 403         | Invalid API credentials |
| `invalid_model`       | 400         | Model not found         |
| `not_found`           | 404         | Resource not found      |
| `rate_limit_exceeded` | 429         | Too many requests       |
| `internal_error`      | 500         | Server error            |

***

## Testing Script

Save this as `test-external-api.sh`:

```bash theme={null}
#!/bin/bash

# Configuration
export SBAI_CLIENT_ID="sbai_client_xxx"
export SBAI_API_KEY="sbai_sk_xxx"
export SBAI_SECRET="sbai_secret_xxx"
export SBAI_BASE_URL="http://localhost:8000"

echo "🧪 Testing Shieldbase External API"
echo "=================================="

# Test 1: List Models
echo -e "\n1️⃣  Testing GET /external/models"
curl -s -X GET "${SBAI_BASE_URL}/external/models" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" | jq '.'

# Test 2: Upload File
echo -e "\n2️⃣  Testing POST /external/upload"
echo "Sample content for testing" > test-file.txt
curl -s -X POST "${SBAI_BASE_URL}/external/upload" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -F "files=@test-file.txt" \
  -F "folder_paths=test" | jq '.'
rm test-file.txt

# Test 3: List Libraries
echo -e "\n3️⃣  Testing GET /external/libraries"
curl -s -X GET "${SBAI_BASE_URL}/external/libraries?page=1&page_size=10" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" | jq '.'

# Test 4: Search
echo -e "\n4️⃣  Testing POST /external/search"
curl -s -X POST "${SBAI_BASE_URL}/external/search" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "test",
    "limit": 10,
    "group_by_file": true
  }' | jq '.'

# Test 5: Chat (New Conversation)
echo -e "\n5️⃣  Testing POST /external/conversations (SSE stream)"
curl -N -X POST "${SBAI_BASE_URL}/external/conversations" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello! What is 2+2?",
    "model": "gpt-5.1"
  }' 2>&1 | head -n 20

# Test 6: Agents Run
echo -e "\n6️⃣  Testing POST /external/agents/run"
curl -s -X POST "${SBAI_BASE_URL}/external/agents/run" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Calculate 5 + 3 and explain the result",
    "timeout_seconds": 60
  }' | jq '.'

echo -e "\n✅ All tests completed!"
```

Make it executable and run:

```bash theme={null}
chmod +x test-external-api.sh
./test-external-api.sh
```

***

## Additional Resources

* **[Interactive API Docs](/external-docs/docs)** - Explore the API with Scalar UI (dark mode, modern layout)
* **[OpenAPI Spec](/external-docs/openapi.json)** - Download the OpenAPI specification
* **[Support](mailto:support@shieldbase.ai)** - Contact our support team
* **[Status Page](https://status.shieldbase.ai)** - Check API status and uptime

***

## Coming Soon

* Python SDK
* JavaScript/TypeScript SDK
* Go SDK
* Webhook support for async notifications
* GraphQL endpoint
* Batch processing API


# Introduction
Source: https://docs.shieldbase.ai/api-reference/introduction

Explore the API workflows designed for seamless document uploading, powerful semantic search, and efficient conversation management

## Welcome

Welcome to our Shieldbase AI API documentation site! Our API provides intuitive endpoints to seamlessly upload documents, execute advanced semantic searches, and manage dynamic conversations. Dive into the two primary workflows below to harness these powerful features effectively.

### Authentication

Before you get started, ensure that all your API requests include the following three headers. These headers are mandatory for all requests to authenticate and authorize your access to the system:

* **client-id**: Your unique client identifier.
* **private-key**: A private key to authenticate your API calls.
* **secret**: A secret key that provides an additional layer of security.

<Note>
  To obtain your `client-id`, `private-key`, and `secret`, please visit
  [https://app.sbai.cloud/](https://app.sbai.cloud/) and sign in to your
  account or email us to [support@shieldbase.ai](mailto:support@shieldbase.ai). Once you have these credentials, you can start making authenticated
  requests.
</Note>

These headers need to be included in every request you send to the API.

***

## Models API

Retrieve available models for tasks like semantic search and conversation management via the `GET /external/models` endpoint. The response delivers an array of models, each with a `label` and `value` for easy reference.

### Endpoint

**GET** `/external/models`

### Headers

Make sure to include the following headers in your request to authenticate:

* **client-id**: Your unique client identifier.
* **private-key**: A private key used for authenticating your API calls.
* **secret**: A secret key that provides additional security for your requests.

### Response

Upon a successful request, the response will include an array of available models, each represented as an object with the following properties:

* **label**: The human-readable name of the model.
* **value**: The model's identifier, used when specifying which model to use.

### Response Example

```json theme={null}
[
  {
    "label": "GPT-3.5",
    "value": "gpt-3.5"
  },
  {
    "label": "GPT4o",
    "value": "gpt4o"
  }
]
```

***

### Workflow 1: Upload and Semantic Search

This workflow allows you to upload documents and perform a semantic search across the uploaded files. It’s a two-step process: First, you upload your documents, and then you use the semantic search endpoint to retrieve all the relevant contents.

#### Step 1: Upload Documents

<Card title="Upload Documents" icon="file" href="/api-reference/endpoint/public/upload-document">
  Start by uploading one or more documents using our document upload API
  endpoint. This is the first step in the process and requires you to send the
  files as part of a `multipart/form-data` request. Make sure that you include
  all required headers like `client-id`, `private-key`, and `secret`.
</Card>

To upload a document or a set of documents, use the `PUT /external/upload` endpoint. This allows you to upload files in various formats. You need to include the files as binary data within a form data, and the server will process them enabling semantic search and other features afterwards. Upon successful upload, the server will return a confirmation message.

#### Step 2: Perform a Semantic Search

<Card title="Semantic Search" icon="magnifying-glass" href="/api-reference/endpoint/public/search-index">
  After uploading documents, you can retrieve them and their content semantically using keywords
  or context through our semantic search endpoint. This helps you find documents
  based on their content and similarity, making retrieval easier and efficient.
</Card>

Once your documents have been uploaded, you can use the `POST /external/semantic-search` endpoint to retrieve content based on specified keywords or query. You’ll also be able to narrow down your search by providing a context ID if needed. This endpoint will return the most relevant documents, giving you easy access to the information you need.

***

### Workflow 2: Conversation Management

Our conversation management API enables you to start, continue, and manage conversations programmatically. The conversation flow starts with initiating a new conversation, sending messages to it, and continuing the conversation when needed.

#### Step 1: Start a New Conversation

<Card title="Start a Conversation" icon="comments" href="/api-reference/endpoint/public/start-conversation-public">
  Begin a new conversation by sending an initial message to the conversation
  API. This endpoint will create a new conversation ID that will be used for
  tracking the conversation.
</Card>

To initiate a new conversation, use the `POST /external/start-conversation` endpoint. You’ll need to provide the message you want to start the conversation with. The server will respond with a `conversation_id` and `model` along with the initial conversation details, such as the messages, ner count, and timestamp.

### Example Response for Start Conversation

```json theme={null}
{
  "conversation_id": "<string>",
  "title": "<string>",
  "messages": {
    "id": "<string>",
    "text": "<string>",
    "redacted": "<string>",
    "synthetic": "<string>",
    "ner_count": 123,
    "response": "<string>",
    "ner_items": [],
    "timestamp": "2023-11-07T05:31:56Z"
  }
}
```

#### Step 2: Send a Message in the Conversation

<Card title="Send a Message" icon="paper-plane" href="/api-reference/endpoint/public/send-conversation-public">
  Once the conversation has started, you can send additional messages to
  continue the dialogue. This helps in extending the conversation with new
  information.
</Card>

To continue the dialogue, use the `POST /external/send` endpoint. Include the `conversation_id` received from the `start-conversation` endpoint and your new message in the body of the request. This keeps the conversation flow intact, ensuring that each message is properly linked to its conversation.

### Example Response for Send Conversation

```json theme={null}
{
  "conversation_id": "<string>",
  "sender": "ai | sender",
  "message_text": "<string>",
  "redacted_text": "<string>",
  "syntactic_text": "<string>",
  "model": "gpt-4o",
  "related_questions": ["<string>"],
  "id": "<string>",
  "typing_completed": true,
  "created_at": "2023-11-07T05:31:56Z"
}
```

#### Step 3: Continue the Conversation

<Card title="Continue a Conversation" icon="arrow-right" href="/api-reference/endpoint/public/continue-conversation-public">
  Use this endpoint to continue the ongoing conversation by adding new responses
  to it. This ensures that the conversation can evolve over time.
</Card>

If you want to further extend the conversation, you will need to use the `POST /external/continue` endpoint, providing the `conversation_id` and `model` and any additional information required to keep the conversation going. After calling `continue-conversation`, you can return to the `send-conversation` endpoint to send new messages within the same conversation context.

### Example Response for Continue Conversation

```json theme={null}
{
  "conversation_id": "d0c73687-cc8d-4628-be2d-01050d32dfb6",
  "sender": "user",
  "message_text": "<string>",
  "redacted_text": "<string>",
  "syntactic_text": "<string>",
  "typing_completed": true,
  "created_at": "2024-08-16T09:24:07.865867",
  "ner_items": [],
  "ner_count": 123,
  "title": "Dropbox: A Popular File Sharing Service",
  "id": "ac3ca0a0-69ee-49c3-a6a5-86ee9b9f4c0e"
}
```


# Release Notes
Source: https://docs.shieldbase.ai/changelog/changelog

Detailed release notes for each version of Shieldbase AI

## v1.2.0

<Info>Released on February 12, 2026</Info>

#### New Features

* **Translate Document Action**: A new specialized agent and action type for automated document translation within workflows.
* **GitLab Integration**: Seamlessly connect GitLab repositories to automate development cycles and data synchronization.
* **Enhanced Workflow Designer**: New productivity tools including import, export, multi-select, right-click actions, and copy-paste functionality for faster design.
* **French Localization (i18n)**: Full platform support for French, enabling better accessibility for international teams.
* **Homepage Task Management**: Improved Task Notification system and optimized lists to focus specifically on "Pending" and "Overdue" items.
* **Workflow Portability**: Added the ability to import and export workflows to facilitate easy sharing and migration between environments.

#### Fixes & Enhancements

* **Dataset Upsert Logic**: Optimized the "Store in Dataset" action to refresh or replace data within the same run, preventing duplicate rows.
* **System Stability**: Resolved critical hanging issues in Parent-Child and Conversational workflows and fixed email attachment failures.
* **Chatbot Fixes**: Fixed high-priority bugs regarding data hallucinations and language detection errors.
* **Reporting & UI**: Fixed dashboard crashes, improved chart responsiveness, and corrected "code-style" text formatting bugs in forms.

***

## v1.1.0

<Info>Released on January 28, 2026</Info>

#### New Features

* **Interactive Dashboards & Reporting**: Introduced clickable links within charts and tables and added the ability to adjust chart panel dimensions for a more customizable visualization experience.
* **Workflow Search & History Enhancements**: Implementation of a dedicated Workflow Search page and added execution duration metrics for both individual steps and overall workflows.
* **Advanced Attachment Handling**: Users can now attach "Source" PDF documents from parent workflows to emails, ensuring better UI formatting and comprehensive summaries.
* **Workflow Type Change**: Users can modify the workflow type after creating them.

#### Fixes & Enhancements

* **Chatbot & AI Accuracy**: Fixed system prompt failures, corrected citation numbering, and addressed the "Related Follow-Ups" trigger issue to ensure more accurate AI responses.
* **Performance Optimization**: Significantly improved data processing speeds for "Store into Dataset" actions and file uploads within folders.
* **UI/UX Polishing**: Fixed layout issues where menus and charts were being cut off in the Dashboard and Reporting views.
* **Integration Stability**: Resolve Magento API data sync issues.
* **Local Time Formatting**: Fixed reporting timestamps to display in the user's local time instead of UTC.

***

## v1.0.2

<Info>Released on January 15, 2026</Info>

#### New Features

* **Global Search**: Upgraded the search tool to help you find files, workflows, and specific results much faster across the entire platform.
* **Custom Branding**: Workspace owners can now add their own company logos and branding for a more personalized experience, for emails, generated documents, and External Workflows.
* **Improved Emailing**: Sending emails is now easier; the system can automatically pull recipient addresses from previous steps and any action types in your workflow.
* **Auto-Save Reports**: Any reports generated from your workflows are now automatically saved directly to your Reporting library for easy access.
* **One-Click Previews**: Added a "Preview" button so you can instantly view files and documents without having to download them first.
* **Advanced Parent Workflows**: You can now print results from a "parent" workflow directly within the related task, making it easier to keep all your data connected.
* **Enhanced Reporting Details**: Reports now include a "View Details" button whenever a specific execution ID is present, giving you instant access to the full history of a task.

#### Fixes & Enhancements

* **Smoother Login**: The system now remembers you by default so you don't have to log in every time you open a new tab.
* **Reliable File Uploads**: Fixed an issue where the "Upload File" button was occasionally disabled, ensuring you can always submit your documents.
* **Better Document Formatting**: Documents and PDFs generated by the system now have consistent, professional formatting that is easier to read.
* **Stability Upgrades**: Resolved various errors in the chat and workflow sections to provide a faster and more stable performance.


# AI Assistant
Source: https://docs.shieldbase.ai/how-to-use/ai-assistant

Master the AI Assistant with natural language interactions and multimodal capabilities

## Overview

Shieldbase AI Assistant uses natural language to interpret user prompts, access multiple AI models, select the most suitable one for the task, and then perform actions or provide information to the user.

### Video Tutorial

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

<Info>
  The AI Assistant is accessible at the Home screen and offers various ways to enrich your experience in generating responses.
</Info>

## Core Features

<CardGroup>
  <Card title="Internal Search" icon="magnifying-glass">
    Search your Knowledge Base
  </Card>

  <Card title="Agentic Mode" icon="robot">
    Autonomous, goal-driven tasks
  </Card>

  <Card title="Research" icon="microscope">
    Deep analysis with sources
  </Card>

  <Card title="Think" icon="brain">
    Customize responses
  </Card>

  <Card title="Web" icon="globe">
    Access web information
  </Card>

  <Card title="Image" icon="image">
    Generate images
  </Card>

  <Card title="Video" icon="video">
    Create videos
  </Card>

  <Card title="Smart Routing" icon="route">
    Automatic model selection
  </Card>

  <Card title="Side-by-Side" icon="table">
    Compare AI models
  </Card>
</CardGroup>

## Feature Details

### Internal Search

Retrieve specific information from your organization’s centralized **Knowledge Base**. Only data that is indexed in the **Library** or **Integrations** is searchable. Tap into all data that has been indexed and stored within your Library or through various data integrations. Internal search works automatically, indexing and retrieving information from both integrated apps and uploaded files without manual intervention.

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

<Note>
  Use Internal Search to find internal data from your connected sources and uploaded documents.
</Note>

### Agentic Mode

**Agentic Mode** is a dynamic, goal-driven AI mode where an intelligent agent can autonomously decide how to execute a task, which tools to use, and in what order. Unlike fixed, deterministic actions, Agentic Mode is designed for open-ended, complex work where the path to the answer is not predefined.

<Info>
  In Agentic Mode:

  * The AI agent can run multiple actions and tools in sequence or in parallel as needed.
  * Outputs are often non-deterministic: the same input might yield slightly different (but still valid) results, as the agent explores different solution paths.
  * It is best suited for complex, ambiguous, or multi-step tasks that cannot be fully expressed as a single action type or a rigid workflow step.
</Info>

<Tip>
  **Use Agentic Mode when:**

  * The task requires reasoning, exploration, or creativity (e.g., drafting strategies, comparing alternatives, synthesizing long documents).
  * The task may involve multiple unknown steps, where the agent must figure out how to reach the goal.
</Tip>

### Research

The **Research** mode is an advanced AI capability that goes beyond standard question-answering to provide in-depth, well-researched, and detailed responses. It is designed to act as a research assistant by autonomously searching for, analyzing, and synthesizing information from multiple sources on the web.

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

<Tip>
  Use Research Mode to generate longer, detailed responses with citations and references.
</Tip>

### Think - Customize Your Responses

Adjust responses to your preferred language, tone, character and style:

<Tabs>
  <Tab title="Language">
    Select a language for the AI model to generate responses in:

    * English
    * Spanish
    * French
    * German
    * Japanese
    * And many more...
  </Tab>

  <Tab title="Output Style">
    Specify the format of the responses:

    * Table
    * FAQ
    * User Guide
    * Summary
    * Bullet Points
    * Technical Documentation
  </Tab>

  <Tab title="Tone">
    Specify the tone the responses will be written in:

    * Professional
    * Casual
    * Friendly
    * Technical
    * Educational
  </Tab>

  <Tab title="Character">
    Roleplay a character that influences generated responses:

    * Expert Consultant
    * Teacher
    * Business Analyst
    * Technical Writer
    * Creative Director
  </Tab>
</Tabs>

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

### Web Search

Include context from the web in your prompt. Use web search to generate external responses from the web.

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

<Info>
  Web search automatically pulls from multiple search engines including Google, DuckDuckGo, and Bing.
</Info>

### Image Generation

Generate images from your prompt. You can specify the Size and Style of the image to be generated.

<Steps>
  <Step title="Enter Prompt">
    Describe the image you want to create
  </Step>

  <Step title="Select Size">
    Choose from standard sizes:

    * Square (1:1)
    * Landscape (16:9)
    * Portrait (9:16)
    * Custom dimensions
  </Step>

  <Step title="Choose Style">
    Select artistic style:

    * Photorealistic
    * Digital Art
    * Oil Painting
    * Watercolor
    * 3D Render
  </Step>

  <Step title="Generate">
    Click generate and wait for your image
  </Step>
</Steps>

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

### Video Generation

Generate videos from your prompt. You can specify if the video quality produced should be of normal quality or in high resolution and cinematic quality.

<Accordion title="Video Generation Options">
  * **Normal Quality**: Quick generation for draft or preview purposes
  * **High Resolution**: Professional quality with cinematic effects
  * **Duration**: Specify video length (up to 30 seconds)
  * **Aspect Ratio**: Choose format for different platforms
</Accordion>

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

### Smart Model Routing

**Smart Model Routing** automatically analyzes a user's request and routes it to the most suitable and efficient AI model available.

Because different models specialize in distinct areas, the 'best' model is subjective and depends entirely on the specific tasks. Think of it as a specialized team where each member has a unique skill set. Instead of using a one-size-fits-all approach, Shieldbase ensures that a relevant AI model is used for the task at hand.

**How it works:**

1. Analyzes your prompt
2. Identifies the task type
3. Selects the optimal AI model
4. Routes your request automatically

### Side-by-Side

Compare responses between two different AI models side-by-side. This allows you to compare and choose your preferred responses.

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

#### How to Compare Prompt Responses Side-by-Side

1. In the lower section of the **Chat** field, select **Side-by-Side** and click the arrow down (↓) symbol.
2. Select two different AI models from the menu list.
3. Insert your prompt and compare the responses of the two models.

### Use Prompt Template

Save a prompt to be used as a template in a new conversation thread.

Using a prompt template is helpful because:

* You don't have to repeat yourself when you frequently give the same set of instructions to the AI.
* It ensures consistency in how the AI responds across different chats and team members.
* It saves time for complex prompts (e.g., detailed roles, tone, structure) that you use regularly.
* It reduces errors or omissions that can happen when you manually retype or copy-paste long prompts.
* It makes it easier for teams to standardize best-practice prompts for common tasks (e.g., report writing, code review, policy drafting).

#### How to Save Prompt as Template

<Steps>
  <Step title="Generate a Response">
    Type your prompt in Chat and generate a response.
  </Step>

  <Step title="Save as Template">
    In the sidebar under **Chats**, hover over the chat message, click the kebab (three dots) icon, and select **Save as Prompt Template**. The prompt will be saved as a reusable template.
  </Step>

  <Step title="Use the Template">
    To use it, go to **Use Prompt Template** in the Chat function from Home or from any Chat thread, and select the saved template to start a new conversation with that prompt.
  </Step>
</Steps>

## Best Practices

<CardGroup>
  <Card title="Be Specific" icon="bullseye">
    Provide clear, detailed prompts for better results
  </Card>

  <Card title="Use Context" icon="file-lines">
    Reference specific documents or data from your Library
  </Card>

  <Card title="Iterate" icon="repeat">
    Refine your prompts based on initial responses
  </Card>

  <Card title="Combine Features" icon="layer-group">
    Use multiple features together for comprehensive results
  </Card>
</CardGroup>

## Common Use Cases

<Tabs>
  <Tab title="Content Creation">
    * Blog posts and articles
    * Social media content
    * Marketing copy
    * Documentation
  </Tab>

  <Tab title="Data Analysis">
    * Report generation
    * Trend analysis
    * Data summarization
    * Insight extraction
  </Tab>

  <Tab title="Visual Content">
    * Presentation graphics
    * Marketing visuals
    * Infographics
    * Video content
  </Tab>

  <Tab title="Research">
    * Market research
    * Competitive analysis
    * Industry trends
    * Academic research
  </Tab>
</Tabs>

## Pro Tips

<Tip>
  **Combine Internal and External Search**: Start with Internal Search for company data, then use Web search for external context and validation.
</Tip>

<Tip>
  **Use Research Mode for Reports**: When creating comprehensive reports, enable Research Mode to get detailed, well-sourced content.
</Tip>

<Tip>
  **Save Successful Prompts**: Keep a library of effective prompts that work well for your specific use cases.
</Tip>


# Chatbots
Source: https://docs.shieldbase.ai/how-to-use/chatbots

Build intelligent chatbots for automated interactions with users

## Overview

Automate interaction with users with natural language by responding to questions, performing tasks, and providing information.

## Types of Chatbots

<Tabs>
  <Tab title="Basic Chatbot">
    **Simple, Single-Source Chatbot**

    A basic chatbot that uses:

    * One source of information as Context
    * One-step Workflow
    * Unlimited open-ended conversations

    Perfect for:

    * FAQ bots
    * Simple customer support
    * Information retrieval
  </Tab>

  <Tab title="Advanced Chatbot">
    **Multi-Source, Multi-Step Chatbot**

    An advanced chatbot with:

    * Multiple sources of information as Context
    * Multiple steps specified in Workflow
    * Controlled conversation flow

    Perfect for:

    * Complex customer journeys
    * Lead qualification
    * Technical support
    * E-commerce assistance
  </Tab>
</Tabs>

## Build a Basic Chatbot

Build a basic chatbot that uses only one source of information as **Context**, and one-step **Workflow**. This chatbot is capable of interacting with users in unlimited open-ended conversations.

### Video Tutorial

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

### Step-by-Step Instructions

<Steps>
  <Step title="Create Workflow">
    1. Navigate to **Workflows**
    2. Click **New Workflow**
    3. You'll be in Build mode automatically
  </Step>

  <Step title="Configure Node">
    1. Click on the node to reveal details
    2. In the **Description** field, specify what will be shown to the user
    3. Click **Save Changes**
  </Step>

  <Step title="Create Chatbot">
    1. Click **Chatbot** in the sidebar
    2. A new chatbot setup will be automatically created
  </Step>

  <Step title="Configure Chatbot">
    1. Specify the **Name** of the chatbot
    2. Enter the **Title** that will appear at the top
    3. Select data from the **Context**
    4. Enable **Guardrails** to ensure responses come from selected data
    5. Click **Save**
  </Step>
</Steps>

## Build an Advanced Chatbot

Build an advanced chatbot with controlled conversation based on multiple sources of information as **Context**, and multiple steps specified in the **Workflow**.

### Video Tutorial

<Info>
  Advanced chatbots allow for complex, multi-step conversations with decision trees and conditional logic.
</Info>

### Step-by-Step Instructions

<Steps>
  <Step title="Create Workflow">
    1. Navigate to **Workflows**
    2. Click **New Workflow**
  </Step>

  <Step title="Configure First Node">
    1. Click on the node to reveal details
    2. Specify the initial user interaction in **Description**
    3. Click **Save Changes**
  </Step>

  <Step title="Add Multiple Steps">
    1. Click **Add Action** to add new steps
    2. Configure each step with specific actions
    3. Consider using the **Handle Conversation** action node to allow dynamic conversation routing
    4. Connect steps to create conversation flow
    5. Save changes for each step
  </Step>

  <Step title="Create Chatbot">
    1. Click **Chatbot** in the sidebar
    2. Configure name and title
    3. Select multiple data sources from **Context**
    4. Enable **Guardrails** for accuracy
    5. Click **Save**
  </Step>
</Steps>

## Share the Chatbot

Once your chatbot is configured, you can share it externally so users can interact with it without logging into Shieldbase. There are two primary ways to publish and share a chatbot:

### Method 1: Embed in a Website

Turn on public access to generate an embed code, then paste the code snippet into your website's HTML (typically in the `<head>` section or where your widget scripts are loaded). The chatbot will appear as an embedded widget on your site, allowing visitors to start a conversation directly from the page.

<Steps>
  <Step title="Enable Public Access">
    Turn on public access in the chatbot settings to generate an embed code.
  </Step>

  <Step title="Copy Embed Code">
    Copy the generated code snippet.
  </Step>

  <Step title="Add to Your Website">
    Paste the code snippet into your website's HTML (typically in the `<head>` section or where your widget scripts are loaded).
  </Step>
</Steps>

### Method 2: Share as a Standalone Experience

Enable public access by clicking **Make Chatbot Public**. Shieldbase will generate a shareable URL that you can send to anyone. Users can open this link in their browser to interact with the chatbot in a dedicated page, without requiring additional setup, embedding, or login.

<iframe />

<Steps>
  <Step title="Make Chatbot Public">
    Click **Make Chatbot Public** to enable public access.
  </Step>

  <Step title="Copy Shareable URL">
    Shieldbase generates a shareable URL.
  </Step>

  <Step title="Share the Link">
    Send the URL to anyone — they can interact with the chatbot in a dedicated page without logging in.
  </Step>
</Steps>

## Chatbot Configuration Options

### Context Settings

<Accordion title="Data Sources">
  Select one or more data sources that the chatbot will use:

  * Library documents
  * Integrated databases
  * API connections
  * Web resources
</Accordion>

<Accordion title="Guardrails">
  <Warning>
    **Always enable Guardrails** to ensure that the AI only sources information from the Context and avoids hallucination.
  </Warning>

  Guardrails ensure:

  * Accurate responses from selected sources
  * No fabricated information
  * Consistent answers
  * Data privacy compliance
</Accordion>

### Deployment Options

<Tabs>
  <Tab title="Internal Use">
    Deploy chatbots for internal team use:

    * Employee assistance
    * IT helpdesk
    * HR support
    * Knowledge management
  </Tab>

  <Tab title="Public Deployment">
    Make chatbots publicly accessible:

    1. Click the **Public** checkbox
    2. Copy the generated code snippet
    3. Embed on your website
    4. Customize appearance to match your brand

    ```html theme={null}
    <!-- Embed code example -->
    <script src="https://shieldbase.ai/embed/..."></script>
    ```
  </Tab>
</Tabs>

## Pro Tips

<CardGroup>
  <Card title="Define Purpose" icon="target">
    Clearly define what problem your chatbot will solve before building
  </Card>

  <Card title="Test Thoroughly" icon="flask">
    Test both expected and unexpected conversation flows
  </Card>

  <Card title="Brand Personality" icon="palette">
    Give your chatbot a personality that extends your brand
  </Card>

  <Card title="Regular Updates" icon="sync">
    Update context data regularly to keep responses current
  </Card>
</CardGroup>

## Use Case Examples

### Customer Support Bot

<Accordion title="Configuration">
  **Context**: Product documentation, FAQ database, support tickets

  **Workflow**:

  1. Greet customer
  2. Identify issue category
  3. Provide solution or escalate
  4. Collect feedback

  **Guardrails**: Enabled to ensure accurate product information
</Accordion>

### Lead Generation Bot

<Accordion title="Configuration">
  **Context**: Product catalog, pricing information, case studies

  **Workflow**:

  1. Welcome visitor
  2. Qualify interest
  3. Collect contact information
  4. Schedule demo or send resources

  **Guardrails**: Enabled for consistent pricing and features
</Accordion>

### HR Assistant Bot

<Accordion title="Configuration">
  **Context**: Employee handbook, benefits information, policies

  **Workflow**:

  1. Verify employee identity
  2. Categorize query
  3. Provide information or forms
  4. Log interaction for HR team

  **Guardrails**: Enabled for policy compliance
</Accordion>

## Best Practices

<Warning>
  **Never disable Guardrails** in production chatbots handling sensitive or critical information.
</Warning>

<Tip>
  **Start Simple**: Begin with a basic chatbot and add complexity as you understand user needs better.
</Tip>

<Info>
  **Monitor Performance**: Regularly review chat logs to identify areas for improvement and common user queries.
</Info>

## Troubleshooting

<Accordion title="Chatbot not responding correctly">
  * Check that Context data is properly indexed
  * Verify Guardrails are enabled
  * Review workflow configuration
  * Test with simpler prompts
</Accordion>

<Accordion title="Slow response times">
  * Reduce the amount of Context data
  * Optimize workflow steps
  * Check integration connections
  * Contact support if issue persists
</Accordion>

<Accordion title="Embedding issues">
  * Verify the Public checkbox is enabled
  * Check that embed code is properly formatted
  * Ensure your website allows external scripts
  * Test in different browsers
</Accordion>


# Dashboard
Source: https://docs.shieldbase.ai/how-to-use/dashboard

Build intelligent dashboards to monitor and visualize work progress

## Overview

Build intelligent dashboards to get visibility and monitor work progress without needing data scientists. Shieldbase Dashboards combine multiple reports into a unified view for comprehensive business intelligence.

<Info>
  Dashboards automatically update with the latest data from your Library and integrations.
</Info>

## Getting Started

### Video Tutorial

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

## Build Your First Dashboard

<Steps>
  <Step title="Add Reports">
    1. Click **Add Report** to see available reports
    2. Only reports not already added will be shown
    3. Select reports to include in your dashboard
  </Step>

  <Step title="Visualize Data">
    Selected reports appear as interactive visualizations
  </Step>

  <Step title="Organize Layout">
    Arrange reports for optimal viewing and analysis
  </Step>

  <Step title="Update Data">
    Click **Update Report** to refresh all data
  </Step>
</Steps>

## Organize with Tabs

Create a multi-tab dashboard for better organization:

### Method 1: Create Tab First

<Steps>
  <Step title="Create New Tab">
    Click to create a new tab with custom name
  </Step>

  <Step title="Add Reports">
    Select reports to add to the new tab
  </Step>

  <Step title="Repeat">
    Create additional tabs as needed
  </Step>
</Steps>

### Method 2: Move Reports to Tabs

<Steps>
  <Step title="Add to Default">
    Add reports to the Default tab initially
  </Step>

  <Step title="Create Tab">
    Create new tab or select existing one
  </Step>

  <Step title="Move Reports">
    Move reports from Default to specific tabs
  </Step>
</Steps>

## Dashboard Design Best Practices

### Layout Organization

<CardGroup>
  <Card title="Logical Grouping" icon="layer-group">
    Group related metrics together (e.g., sales, marketing, operations)
  </Card>

  <Card title="Visual Hierarchy" icon="eye">
    Place most important metrics at the top or center
  </Card>

  <Card title="Consistent Styling" icon="palette">
    Use consistent colors and chart types for similar data
  </Card>

  <Card title="Clear Labels" icon="tag">
    Use descriptive names for tabs and reports
  </Card>
</CardGroup>

### Tab Organization Examples

<Tabs>
  <Tab title="Executive Overview">
    **High-level metrics for leadership**

    * Revenue trends
    * Key performance indicators
    * Goal progress
    * Critical alerts
  </Tab>

  <Tab title="Sales Performance">
    **Detailed sales analytics**

    * Pipeline metrics
    * Team performance
    * Product sales
    * Regional breakdown
  </Tab>

  <Tab title="Operations">
    **Operational efficiency metrics**

    * Production stats
    * Quality metrics
    * Resource utilization
    * Process efficiency
  </Tab>

  <Tab title="Customer Insights">
    **Customer-focused analytics**

    * Satisfaction scores
    * Support metrics
    * User behavior
    * Retention rates
  </Tab>
</Tabs>

## Pro Tips

<Warning>
  **Display Actionable Metrics**: The numbers on your dashboard should prompt a question or an action. If a metric never changes or doesn't influence a decision, it probably shouldn't be on the Dashboard.
</Warning>

<Tip>
  **Update Regularly**: Click **Update Report** to refresh all reports in the Dashboard with the latest data from your Library.
</Tip>

<Info>
  **Organize by Topic**: Grouping reports by topic (e.g., sales, marketing, customer service) makes information easier to scan and digest.
</Info>

## Advanced Features

### Real-time Updates

Configure automatic data refreshes:

<Accordion title="Auto-refresh Settings">
  * Set refresh intervals
  * Configure data source polling
  * Enable real-time streaming
  * Set up alert notifications
</Accordion>

### Interactive Elements

Dashboards support interactive features:

<Accordion title="Interactive Capabilities">
  * Click-through drill-downs
  * Filter applications
  * Time range selections
  * Cross-report filtering
</Accordion>

### Sharing and Permissions

Control dashboard access:

<Steps>
  <Step title="Set Visibility">
    Configure public or private access
  </Step>

  <Step title="Assign Permissions">
    Control who can view or edit
  </Step>

  <Step title="Share Links">
    Generate shareable dashboard URLs
  </Step>

  <Step title="Embed Options">
    Embed dashboards in other applications
  </Step>
</Steps>

## Common Dashboard Types

### Operations Dashboard

<Accordion title="Components">
  **Purpose**: Monitor daily operations

  **Reports to Include**:

  * Production metrics
  * Quality indicators
  * Resource utilization
  * Issue tracking
  * Performance trends
</Accordion>

### Sales Dashboard

<Accordion title="Components">
  **Purpose**: Track sales performance

  **Reports to Include**:

  * Revenue trends
  * Pipeline status
  * Conversion rates
  * Team quotas
  * Product performance
</Accordion>

### Marketing Dashboard

<Accordion title="Components">
  **Purpose**: Measure marketing effectiveness

  **Reports to Include**:

  * Campaign performance
  * Lead generation
  * Channel analytics
  * ROI metrics
  * Engagement rates
</Accordion>

### Executive Dashboard

<Accordion title="Components">
  **Purpose**: Strategic overview

  **Reports to Include**:

  * Company KPIs
  * Financial summary
  * Department performance
  * Strategic goals
  * Risk indicators
</Accordion>

## Best Practices

<CardGroup>
  <Card title="Start Simple" icon="seedling">
    Begin with essential metrics, then expand based on needs
  </Card>

  <Card title="Test Performance" icon="gauge">
    Ensure dashboards load quickly with optimized queries
  </Card>

  <Card title="Mobile Friendly" icon="mobile">
    Design dashboards to work on all screen sizes
  </Card>

  <Card title="Document Purpose" icon="book">
    Include descriptions of what each metric means
  </Card>
</CardGroup>

## Integration with Other Features

### Use with Workflows

Automate dashboard updates:

* Schedule report regeneration
* Trigger alerts based on metrics
* Export dashboard snapshots
* Distribute via email

### Use with Chatbots

Enable conversational analytics:

* Ask questions about dashboard data
* Get explanations of metrics
* Request specific views
* Receive proactive alerts

### Use with Reporting

Enhance dashboard capabilities:

* Create custom reports for dashboards
* Combine multiple data sources
* Apply advanced analytics
* Generate predictive insights

## Troubleshooting

<Accordion title="Reports not updating">
  * Check data source connections
  * Verify report configurations
  * Click Update Report manually
  * Review integration settings
</Accordion>

<Accordion title="Performance issues">
  * Reduce number of reports per tab
  * Optimize underlying queries
  * Use data aggregation
  * Consider pagination
</Accordion>

<Accordion title="Layout problems">
  * Check screen resolution
  * Adjust report sizes
  * Reorganize tab structure
  * Test on different devices
</Accordion>

## Dashboard Checklist

Before publishing your dashboard, ensure:

<Steps>
  <Step title="Data Quality">
    ✅ All data sources are connected and current
  </Step>

  <Step title="Visual Design">
    ✅ Charts are readable and properly labeled
  </Step>

  <Step title="Organization">
    ✅ Reports are logically grouped in tabs
  </Step>

  <Step title="Performance">
    ✅ Dashboard loads within acceptable time
  </Step>

  <Step title="Permissions">
    ✅ Access rights are properly configured
  </Step>

  <Step title="Documentation">
    ✅ Metrics are clearly defined and understood
  </Step>
</Steps>


# Editor
Source: https://docs.shieldbase.ai/how-to-use/editor

Create content with AI in an intelligent canvas environment

## Overview

The Editor provides an intelligent canvas where you can write blogs, build reports, generate slides, and create images - all powered by AI. It's your creative workspace for content generation with minimal context switching.

<Info>
  The Canvas automatically uses all its content as context for new generations, allowing AI to consider existing images, slides, text, or articles to inform and enhance any new content you create.
</Info>

## Getting Started

### Video Tutorial

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

## Using the Editor

<Steps>
  <Step title="Open Editor">
    Click **Editor** to start with a blank canvas
  </Step>

  <Step title="Access AI Commands">
    Type **/** (forward slash) to reveal the AI command menu
  </Step>

  <Step title="Select Command">
    Choose from available AI generation options
  </Step>

  <Step title="Generate Content">
    AI creates content based on your selection and existing canvas context
  </Step>
</Steps>

## Available Commands

Type `/` to access these AI-powered features:

<Tabs>
  <Tab title="Text Generation">
    * **Article**: Generate full articles on any topic
    * **Blog Post**: Create engaging blog content
    * **Summary**: Summarize existing content
    * **Outline**: Create structured outlines
    * **Lists**: Generate bullet points or numbered lists
    * **FAQ**: Create frequently asked questions
  </Tab>

  <Tab title="Visual Content">
    * **Image**: Generate AI images
    * **Slides**: Create presentation slides
    * **Infographic**: Design data visualizations
    * **Diagram**: Create flowcharts and diagrams
    * **Chart**: Generate data charts
  </Tab>

  <Tab title="Business Documents">
    * **Report**: Generate business reports
    * **Proposal**: Create project proposals
    * **Email**: Draft professional emails
    * **Meeting Notes**: Structure meeting documentation
    * **Executive Summary**: Create concise overviews
  </Tab>

  <Tab title="Creative Content">
    * **Story**: Write creative narratives
    * **Script**: Generate video or podcast scripts
    * **Social Media**: Create social posts
    * **Marketing Copy**: Write promotional content
    * **Product Description**: Generate product details
  </Tab>
</Tabs>

## Key Features

### Contextual Generation

<Warning>
  The Canvas uses **all existing content as context** for new generations. This means:

  * New content builds on what's already there
  * AI understands the theme and style
  * Consistency is maintained across content
  * No need to re-explain context
</Warning>

### Multi-Modal Content

Create different content types in one workspace:

<CardGroup>
  <Card title="Text Content" icon="file-lines">
    Articles, blogs, reports, documentation
  </Card>

  <Card title="Visual Content" icon="image">
    Images, infographics, diagrams, charts
  </Card>

  <Card title="Presentations" icon="presentation">
    Slides, pitch decks, training materials
  </Card>

  <Card title="Data Visuals" icon="chart-bar">
    Charts, graphs, data visualizations
  </Card>
</CardGroup>

## Workflow Examples

### Blog Post Creation

<Steps>
  <Step title="Start with Outline">
    Type `/outline` to generate post structure
  </Step>

  <Step title="Expand Sections">
    Use `/article` to develop each section
  </Step>

  <Step title="Add Visuals">
    Insert images with `/image` command
  </Step>

  <Step title="Create Summary">
    Generate meta description with `/summary`
  </Step>
</Steps>

### Report Generation

<Steps>
  <Step title="Executive Summary">
    Begin with `/executive summary`
  </Step>

  <Step title="Data Analysis">
    Add charts with `/chart` command
  </Step>

  <Step title="Detailed Sections">
    Expand with `/report` for each section
  </Step>

  <Step title="Conclusions">
    Finalize with recommendations
  </Step>
</Steps>

### Presentation Creation

<Steps>
  <Step title="Title Slide">
    Start with `/slides` for opening
  </Step>

  <Step title="Content Slides">
    Add information slides progressively
  </Step>

  <Step title="Visual Slides">
    Include `/image` and `/chart` content
  </Step>

  <Step title="Summary Slide">
    Conclude with key takeaways
  </Step>
</Steps>

## Pro Tips

<Tip>
  **Maintain Flow State**: Use the Canvas when you want to continue working in a flow with minimal interruptions from switching tabs and apps.
</Tip>

<Tip>
  **Build Incrementally**: Start with an outline or structure, then expand each section using the existing context.
</Tip>

<Tip>
  **Mix Content Types**: Combine text, images, and data visualizations for more engaging content.
</Tip>

## Best Practices

### Content Organization

<CardGroup>
  <Card title="Structure First" icon="sitemap">
    Start with outlines before detailed content
  </Card>

  <Card title="Section Headers" icon="heading">
    Use clear headers to organize content
  </Card>

  <Card title="Visual Balance" icon="balance-scale">
    Mix text and visuals appropriately
  </Card>

  <Card title="Consistent Style" icon="paintbrush">
    Maintain tone and formatting throughout
  </Card>
</CardGroup>

### Productivity Tips

<Accordion title="Keyboard Shortcuts">
  * `/` - Open AI command menu
  * `Ctrl/Cmd + Z` - Undo
  * `Ctrl/Cmd + Y` - Redo
  * `Ctrl/Cmd + S` - Save
  * `Ctrl/Cmd + A` - Select all
</Accordion>

<Accordion title="Content Reuse">
  The canvas context feature means you can:

  * Reference earlier content automatically
  * Maintain consistency without repetition
  * Build complex documents incrementally
  * Create variations of existing content
</Accordion>

## Common Use Cases

### Marketing Content

<Tabs>
  <Tab title="Blog Series">
    Create interconnected blog posts with consistent voice and themes
  </Tab>

  <Tab title="Campaign Materials">
    Generate ads, social posts, and landing page copy in one workspace
  </Tab>

  <Tab title="Product Launch">
    Develop press releases, product descriptions, and promotional content
  </Tab>
</Tabs>

### Documentation

<Tabs>
  <Tab title="User Guides">
    Create comprehensive guides with text and visual instructions
  </Tab>

  <Tab title="API Documentation">
    Generate technical docs with code examples and diagrams
  </Tab>

  <Tab title="Training Materials">
    Develop courses with lessons, exercises, and visuals
  </Tab>
</Tabs>

### Business Documents

<Tabs>
  <Tab title="Proposals">
    Create client proposals with analysis, visuals, and recommendations
  </Tab>

  <Tab title="Reports">
    Generate quarterly reports with data, charts, and insights
  </Tab>

  <Tab title="Strategies">
    Develop strategic plans with goals, timelines, and visuals
  </Tab>
</Tabs>

## Advanced Features

### Template Creation

Save common structures as templates:

<Steps>
  <Step title="Create Structure">
    Build your ideal document structure
  </Step>

  <Step title="Save as Template">
    Save for future reuse
  </Step>

  <Step title="Apply Template">
    Start new documents from saved templates
  </Step>
</Steps>

### Collaborative Editing

Work with team members:

* Share canvas access
* Real-time collaboration
* Comment and review
* Version control

## Export Options

Export your content in various formats:

<CardGroup>
  <Card title="PDF" icon="file-pdf">
    Professional documents
  </Card>

  <Card title="Word" icon="file-word">
    Editable documents
  </Card>

  <Card title="HTML" icon="code">
    Web-ready content
  </Card>

  <Card title="Markdown" icon="markdown">
    Developer-friendly format
  </Card>

  <Card title="PowerPoint" icon="file-powerpoint">
    Presentation format
  </Card>

  <Card title="Image" icon="file-image">
    Visual exports
  </Card>
</CardGroup>

## Troubleshooting

<Accordion title="Commands not appearing">
  * Ensure you're typing `/` at the beginning of a new line
  * Check that you're in edit mode
  * Refresh the editor if needed
</Accordion>

<Accordion title="Content not generating">
  * Check your internet connection
  * Verify AI service availability
  * Try simpler prompts first
  * Clear canvas cache if needed
</Accordion>

<Accordion title="Formatting issues">
  * Use the format toolbar
  * Apply consistent styles
  * Check export settings
  * Preview before finalizing
</Accordion>


# Getting Started
Source: https://docs.shieldbase.ai/how-to-use/getting-started

Learn how to navigate Shieldbase and understand user roles

## Basic Navigation

The Shieldbase interface features a left sidebar with all the main features you need to get started. Here's what each section does:

<Accordion title="Navigation Menu Overview">
  <AccordionGroup>
    <Accordion title="New Chat" icon="message">
      Access the home page to start a new conversation with the AI Assistant
    </Accordion>

    <Accordion title="Home" icon="house">
      Access the home page, run existing workflows, and search across the platform
    </Accordion>

    <Accordion title="Chats" icon="comments">
      Interact with an AI assistant to perform actions or provide information
    </Accordion>

    <Accordion title="Editor" icon="edit">
      Write blogs, build reports, generate slides and images all in a canvas
    </Accordion>

    <Accordion title="Dashboard" icon="chart-line">
      Build an intelligent dashboard to get visibility and monitor work progress
    </Accordion>

    <Accordion title="Reporting" icon="chart-bar">
      Analyze data into insights and charts in a report
    </Accordion>

    <Accordion title="Workflows" icon="diagram-project">
      Turn manual, repetitive processes into automated workflows
    </Accordion>

    <Accordion title="Chatbots" icon="robot">
      Chat interface that responds to questions, performs tasks, and provides information
    </Accordion>

    <Accordion title="Meetings" icon="video">
      Record, transcribe, translate and analyze live meetings into notes
    </Accordion>

    <Accordion title="Library" icon="books">
      A repository of all information collected from data integration and manual upload
    </Accordion>

    <Accordion title="Integrations" icon="plug">
      Integrate data from various sources
    </Accordion>

    <Accordion title="Settings" icon="gear">
      Setup the settings based on your user roles
    </Accordion>

    <Accordion title="Help" icon="circle-question">
      Chatbot with a user guide on how to use Shieldbase
    </Accordion>

    <Accordion title="About" icon="circle-info">
      About Shieldbase, warning and compliance notes
    </Accordion>

    <Accordion title="What's New" icon="bullhorn">
      Changelog of all updates across different versions
    </Accordion>

    <Accordion title="Support" icon="life-ring">
      Send queries to the Shieldbase support team
    </Accordion>

    <Accordion title="Log Out" icon="sign-out">
      Log out of your account
    </Accordion>
  </AccordionGroup>
</Accordion>

<Info>
  **Quick actions** from the sidebar: use **New Chat** to access the home page, **Run Workflow** to swiftly access existing workflows, and **Search** to find anything within the Library and output generated from Chat, Workflows, Meetings, Reporting, Chatbot, and Editor.
</Info>

## User Roles

Shieldbase has four types of user roles with key distinctions and hierarchy:

<Info>
  **Role Hierarchy:** Root → Admin → Operator → Viewer
</Info>

<Tabs>
  <Tab title="Root">
    **Highest Level Access**

    Root users have complete control over the Shieldbase environment:

    * Change settings of the entire Shieldbase environment
    * Manage all system configurations
    * Access all features and data
    * Create and manage other user accounts
  </Tab>

  <Tab title="Admin">
    **Team Management**

    Admin users can manage teams and users:

    * Create teams and manage users
    * Configure team settings
    * Access most platform features
    * Cannot change environment settings
  </Tab>

  <Tab title="Operator">
    **Platform User**

    Operators are the primary users of the platform:

    * Use all Shieldbase platform features
    * Create workflows, chatbots, and reports
    * Access assigned data and integrations
    * Cannot manage users or teams
  </Tab>

  <Tab title="Viewer">
    **Limited Access**

    Viewers have read-only access:

    * View and run limited automation from public links
    * Access shared dashboards and reports
    * Cannot create or modify content
    * Restricted to viewing permissions only
  </Tab>
</Tabs>

## Knowledge Base

The Knowledge Base consists of **Integrations** and **Library**. Integrations connect with sources to ingest and index data inside the Library.

### Integrate Data from Third-Party Connectors

Shieldbase's connectors are pre-built tools that create a seamless link between **Knowledge Base** and various third-party applications and services.

These connectors use APIs (Application Programming Interfaces) to securely access and retrieve data from these external sources. APIs act as a set of rules and protocols that allow different software applications to communicate with each other.

Once a connection with the sources are established, any changes or new data from the external source will automatically be indexed and available for use in the Shieldbase suite of AI capabilities including **AI Assistant, Workflows, Chatbot**, and **Reporting**.

When data is integrated from various sources, it inherits the role-based access control (RBAC) of the original source. This ensures that the data's security settings are maintained even when it's made available in a new environment.

You can find the necessary API keys for each connector in its settings.

There are various ways to integrate data to the **Knowledge Base**:

• **APIs**: Integrate data from third-party systems

• **Import from ChatGPT**: Import threads from ChatGPT into Shieldbase.

• **Library Documents**: Upload new files directly into the **Library**.

• **Web Search**: Activate to enable external search from various search engines including Google Web Search, DuckDuck Go, and Bing.

• **Website & Resources**: Specify URLs from which to crawl and index data. Shieldbase automatically reads and indexes the content up to three levels deep from the initial URL.

• **Custom HTTP Requests**: Shieldbase will read and index the websites with custom parameters in the URL or even APIs.

## Quick Start Guide

<Steps>
  <Step title="Log In">
    Access Shieldbase with your credentials and select your workspace
  </Step>

  <Step title="Navigate to Home">
    Click on "New Chat" to access the home page and AI Assistant
  </Step>

  <Step title="Explore Features">
    Use the left sidebar to navigate between different features
  </Step>

  <Step title="Check Your Role">
    Go to Settings to verify your user role and permissions
  </Step>
</Steps>

## Best Practices

<CardGroup>
  <Card title="Start Simple" icon="lightbulb">
    Begin with basic features like the AI Assistant before moving to complex workflows
  </Card>

  <Card title="Organize Your Work" icon="folder">
    Use clear naming conventions for your workflows, chatbots, and reports
  </Card>

  <Card title="Test Before Deploying" icon="flask">
    Always test your automations in a safe environment before going live
  </Card>

  <Card title="Regular Updates" icon="sync">
    Keep your integrations and data sources updated regularly
  </Card>
</CardGroup>

## Next Steps

Now that you understand the basics, explore these key features:

<CardGroup>
  <Card title="Library" icon="books" href="/how-to-use/library">
    Learn how to integrate and manage your data
  </Card>

  <Card title="AI Assistant" icon="sparkles" href="/how-to-use/ai-assistant">
    Discover the power of AI-powered interactions
  </Card>

  <Card title="Workflows" icon="workflow" href="/how-to-use/workflows">
    Automate your repetitive tasks
  </Card>
</CardGroup>


# Introduction
Source: https://docs.shieldbase.ai/how-to-use/introduction

Learn about Shieldbase AI OS and its capabilities

## About Shieldbase

Shieldbase is an **AI operating system (Shieldbase AI OS)** built for the enterprise. Shieldbase AI OS unifies fragmented AI tools, databases, and legacy systems into streamlined automated workflows.

By leveraging multimodel AI with internal and external data sources, Shieldbase AI OS enables teams to:

* **Ingest data** from multiple sources
* **Produce multimodal responses** including text, images, and visualizations
* **Build and run agentic automations** without coding
* Ensure **enterprise-grade security, privacy and compliance**

Whether you're in banking, healthcare, or manufacturing, Shieldbase AI OS transforms data into analytics and automations - empowering teams to build and run AI-first operations without coding.

## Purpose and Scope

This living document serves as a comprehensive user guide to work with Shieldbase. It covers key capabilities on how to use Shieldbase AI OS.

## Key Benefits

<CardGroup>
  <Card title="No Code Required" icon="code">
    Build AI-powered workflows and automations without writing a single line of code
  </Card>

  <Card title="Enterprise Ready" icon="building">
    Built with enterprise-grade security, privacy, and compliance from the ground up
  </Card>

  <Card title="Unified Platform" icon="layer-group">
    Connect all your tools, databases, and systems in one unified platform
  </Card>

  <Card title="Multimodal AI" icon="brain">
    Leverage multiple AI models for text, images, videos, and data analysis
  </Card>
</CardGroup>

## Platform Architecture

Shieldbase AI OS is built on a modular architecture that consists of several key components:

<Steps>
  <Step title="Knowledge Base">
    Central repository that unifies fragmented data from various sources through Integrations and Library
  </Step>

  <Step title="AI Assistant">
    Natural language interface to interact with AI models and perform tasks
  </Step>

  <Step title="Automation Engine">
    Build and run workflows, chatbots, and automated processes
  </Step>

  <Step title="Analytics & Reporting">
    Generate insights, visualizations, and dashboards from your data
  </Step>
</Steps>

## Who Should Use This Guide

This guide is designed for:

* **Business Users** who want to automate their workflows without coding
* **Data Analysts** looking to generate insights and visualizations
* **IT Administrators** managing integrations and user access
* **Developers** building custom automations and integrations

## Getting Support

If you need help or have questions:

<CardGroup>
  <Card title="Email Support" icon="envelope" href="mailto:support@shieldbase.ai">
    Contact our support team at [support@shieldbase.ai](mailto:support@shieldbase.ai)
  </Card>

  <Card title="Documentation" icon="book" href="https://docs.shieldbase.ai">
    Browse our comprehensive documentation
  </Card>
</CardGroup>


# Knowledge Base
Source: https://docs.shieldbase.ai/how-to-use/library

Learn how to build and manage your centralized data repository

## Overview

Shieldbase Knowledge Base is a centralized repository that unifies fragmented data from various sources by storing, organizing, and enabling access to aggregated information. This serves as a single source of truth for company data.

The Knowledge Base consists of **Integrations** and **Library**.

Integrations connect with sources to ingest and index data inside the Library.

## Integrations

### Integrate Data from Third-Party Connectors

Shieldbase's connectors are pre-built tools that create a seamless link between Knowledge Base and various third-party applications and services.

These connectors use APIs (Application Programming Interfaces) to securely access and retrieve data from these external sources. APIs act as a set of rules and protocols that allow different software applications to communicate with each other.

Once a connection with the sources are established, any changes or new data from the external source will automatically be indexed and available for use in the Shieldbase suite of AI capabilities including AI Assistant, Workflows, Chatbot, and Reporting.

When data is integrated from various sources, it inherits the role-based access control (RBAC) of the original source. This ensures that the data's security settings are maintained even when it's made available in a new environment.

You can find the necessary API keys for each connector in its settings.

There are various ways to integrate data to the Knowledge Base:

• **APIs**: Integrate data from third-party systems

• **Import from ChatGPT**: Import threads from ChatGPT into Shieldbase.

• **Library Documents**: Upload new files directly into the Library.

• **Web Search**: Activate to enable external search from various search engines including Google Web Search, DuckDuck Go, and Bing.

• **Website & Resources**: Specify URLs from which to crawl and index data. Shieldbase automatically reads and indexes the content up to three levels deep from the initial URL.

• **Custom HTTP Requests**: Shieldbase will read and index the websites with custom parameters in the URL or even APIs.

## Library

The Library consists of all information collected from various connectors. Whether data is pulled through API integration or uploaded manually, they are ingested and indexed for it to be readable by AI.

### Data Integration

Data pulled and indexed from third-party sources is searchable and accessible within the **Library**.

The key distinction is that Shieldbase does not duplicate your data. Instead, it builds an index. Think of it like a search engine. Shieldbase scans your data (e.g., documents in Google Drive, records in a CRM) and creates a searchable index. This index contains metadata and a reference to the original data, but it does not store a complete, redundant copy of the files or information on its servers.

### Upload New Files

Upload files directly from the local drive into the Library. Uploaded files are automatically ingested and indexed to be readable by AI.

<Note>
  💡 **Tip**: You can adjust video playback speed using the gear icon (⚙️) in the video player controls.
</Note>

<iframe />

Currently, Shieldbase can index the following file formats:

* PDF (.pdf)
* CSV (.csv)
* ZIP (.zip)
* Excel (.xlsx)
* Word (.doc)
* Word (.docx)
* Powerpoint (.ppt)
* Powerpoint (.pptx)
* JPEG (.jpg)
* PNG (.png)
* Plain Text (.txt)
* Rich Text Format (.rtf)
* Markdown (.md)

## Pro Tips

<Tip>
  If you do not see a connector that you want to pull the data from, request a new connector to be added as a data source by contacting [support@shieldbase.ai](mailto:support@shieldbase.ai).
</Tip>

<Tip>
  If you need to index a file format that is not on this list, please send a request to [support@shieldbase.ai](mailto:support@shieldbase.ai). We are continuously working to expand our capabilities and will consider making the requested format available.
</Tip>

<Warning>
  A high-quality knowledge base is built on curated content, not just a data dump. To ensure its effectiveness, first cleanse and refine your data, as the quality of your input directly determines the quality of the AI output.
</Warning>

## Best Practices

<CardGroup>
  <Card title="Regular Updates" icon="sync">
    Keep your integrated data sources updated regularly for fresh information
  </Card>

  <Card title="Data Organization" icon="folder-tree">
    Organize your library with clear naming conventions and folder structures
  </Card>

  <Card title="Security First" icon="shield">
    Always use secure API keys and review access permissions
  </Card>

  <Card title="Quality Control" icon="check-circle">
    Regularly audit and clean your data to maintain accuracy
  </Card>
</CardGroup>

## Common Use Cases

<Accordion title="Sales Data Integration">
  Connect your CRM to automatically sync customer data, sales pipelines, and contact information for AI-powered sales insights.
</Accordion>

<Accordion title="Documentation Repository">
  Upload company policies, procedures, and documentation to create an AI-searchable knowledge base for employees.
</Accordion>

<Accordion title="Market Intelligence">
  Use web crawling to monitor competitor websites and industry news for automated market analysis.
</Accordion>

<Accordion title="Project Management">
  Integrate project management tools to track tasks, timelines, and team performance across all projects.
</Accordion>


# Meetings
Source: https://docs.shieldbase.ai/how-to-use/meetings

Record, transcribe, translate, and analyze live meetings into notes

## Overview

Meetings lets you send the **Shieldbase Notetaker** into a live online meeting so it can capture, analyze, and summarize the conversation for you. You can join any existing call by providing its meeting link.

<Info>
  The Shieldbase Notetaker joins your live call as a participant. Pre-scheduling via calendar is not supported yet — join an existing call by providing its meeting link.
</Info>

## What the Notetaker Generates

After the meeting ends, the agent automatically processes the call and generates:

<CardGroup>
  <Card title="Audio Recording" icon="waveform">
    Full recording available to replay and download
  </Card>

  <Card title="Summary" icon="list">
    Summary with the key topics discussed
  </Card>

  <Card title="Action Items" icon="square-check">
    Action items and key takeaways with owners and due dates when detectable
  </Card>

  <Card title="Attendees" icon="users">
    List of who joined the call
  </Card>

  <Card title="Speaker Analytics" icon="chart-pie">
    Who spoke, and roughly how much, as a percentage
  </Card>

  <Card title="Transcript" icon="file-lines">
    Full time-stamped transcript in the original meeting language
  </Card>

  <Card title="Translated Transcript" icon="language">
    Translated transcript when translation is enabled
  </Card>

  <Card title="Email Recap" icon="envelope">
    Recap that can be sent to specific recipients
  </Card>
</CardGroup>

## How to Send the Shieldbase Notetaker into a Meeting

<Steps>
  <Step title="Create the Meeting">
    Click **New Meeting** to configure the Shieldbase Notetaker.
  </Step>

  <Step title="Add a Title">
    Enter a clear and descriptive title that will be used to label the recording, summary, and recap emails.
  </Step>

  <Step title="Paste the Meeting URL">
    Paste the meeting URL for the Shieldbase Notetaker to join the live call (e.g., Microsoft Teams, Zoom, Google Meet). Ensure this is the full URL that participants use to join the meeting.
  </Step>

  <Step title="Choose Translation (optional)">
    Choose whether to translate into a different language. If enabled, the system will produce both the original transcript and a translated transcript.
  </Step>

  <Step title="Specify Recap Recipients">
    Specify the email(s) to send the meeting recap to. These addresses will receive the summary, key topics, attendees, and meeting summary.
  </Step>

  <Step title="Create Meeting">
    Click **Create Meeting** to send the agent. Make sure to admit the agent inside the meeting, as it will join the call as a participant.
  </Step>

  <Step title="Conduct Your Meeting">
    Conduct your meeting. The agent will capture audio, speakers, and content in the background.
  </Step>

  <Step title="Review the Results">
    Once the meeting ends and processing is complete, you will see the audio recording, summary, action items, attendees and speaker analytics, transcript, translation (if enabled), and recap delivery to the emails you specified.
  </Step>
</Steps>

## Meeting Outputs in Detail

<AccordionGroup>
  <Accordion title="Audio Recording" icon="waveform">
    A recording of the meeting that can be replayed and downloaded.
  </Accordion>

  <Accordion title="Summary" icon="list">
    A summary with the key topics discussed during the meeting.
  </Accordion>

  <Accordion title="Action Items" icon="square-check">
    Key takeaways of concrete follow-ups, owners (if detectable), and due dates (if mentioned), along with overall decisions and next steps.
  </Accordion>

  <Accordion title="Attendees" icon="users">
    The list of attendees, plus speaker analytics showing who spoke how much in percentage.
  </Accordion>

  <Accordion title="Transcript" icon="file-lines">
    Time-stamped text of the conversation in the original meeting language.
  </Accordion>

  <Accordion title="Translation" icon="language">
    The full translated transcript (if translation was enabled) in the target language selected.
  </Accordion>

  <Accordion title="Recap Delivery" icon="envelope">
    The recap is sent to the emails you specified.
  </Accordion>
</AccordionGroup>

## Pro Tips

<Tip>
  **Use clear, descriptive titles**: Give each meeting a specific title that includes topic and audience (e.g., "Customer X – Quarterly Business Review – May 2026") so recordings and summaries are easy to search and recognize later.
</Tip>

<Warning>
  **Verify the meeting URL before sending the agent**: Always double-check that the URL is a joinable link for participants. Incorrect URLs will prevent the Shieldbase Notetaker from joining.
</Warning>

<Info>
  **Inform participants about recording and the notetaker**: At the start of the call, briefly mention that a bot is present to record and summarize the meeting. This builds trust and helps with legal and compliance expectations.
</Info>

<Tip>
  **Choose translation only when needed**: Turn on translation when attendees or stakeholders need the content in another language. This reduces processing overhead and keeps your workspace tidy when translation isn't necessary.
</Tip>

<Tip>
  **Speak clearly and avoid heavy crosstalk**: Better audio quality and fewer overlapping voices lead to more accurate transcripts and reliable capture of who said how much — higher-quality summaries and action items.
</Tip>

<Tip>
  **Use names when assigning actions**: When you describe next steps, say them explicitly (e.g., "Alex will send the proposal by Friday") so the system can more accurately detect action items and potential owners.
</Tip>

<Tip>
  **Send or re-send recaps to stakeholders**: Keep absent stakeholders up to date, confirm decisions and responsibilities in writing, and share the translated transcript with multilingual teams.
</Tip>


# Reporting
Source: https://docs.shieldbase.ai/how-to-use/reporting

Analyze data into insights and charts in comprehensive reports

## Overview

Transform your data into actionable insights and visualizations. Shieldbase Reporting uses AI to analyze datasets and automatically generate relevant charts, graphs, and analytical insights.

<Info>
  Reporting works best with datasets in tabulated data format. The cleaner the dataset, the more accurate the analysis.
</Info>

## Getting Started

### Video Tutorial - Identify Insights

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

### Create Your First Report

<Steps>
  <Step title="Start New Report">
    Click **New Report** in the Reporting section
  </Step>

  <Step title="Select Data Sources">
    Choose one or multiple datasets from the Library to analyze
  </Step>

  <Step title="Generate Insights">
    Enter a prompt in **Analysis** to generate insights with relevant charts in **Visualization**
  </Step>

  <Step title="Review and Refine">
    Review the generated insights and refine your prompts for better results
  </Step>
</Steps>

## Pro Tip: Insight Discovery

Not sure what insights to generate? Use this powerful prompt:

```text theme={null}
Suggest what insights can be generated from this dataset. Generate the prompt to generate the insights and suggest the chart type to visualize the data. Generate a table for the response.

Column 1: Type of data (descriptive, diagnostic, predictive, prescriptive).
Column 2: Question to be asked in the form of a prompt.
Column 3: Chart type
```

### Video Tutorial - Insight Discovery

<Note>
  💡 **Tip**: Adjust video playback speed using the gear icon (⚙️) in the video player. We recommend 0.5x speed for detailed tutorials.
</Note>

<iframe />

## Types of Analysis

<Tabs>
  <Tab title="Descriptive">
    **What happened?**

    Summarize historical data to understand past performance:

    * Sales totals by quarter
    * Customer demographics
    * Product performance metrics
    * Regional distribution
  </Tab>

  <Tab title="Diagnostic">
    **Why did it happen?**

    Identify causes and correlations:

    * Root cause analysis
    * Performance drivers
    * Trend correlations
    * Anomaly detection
  </Tab>

  <Tab title="Predictive">
    **What will happen?**

    Forecast future outcomes:

    * Sales projections
    * Demand forecasting
    * Risk assessment
    * Growth predictions
  </Tab>

  <Tab title="Prescriptive">
    **What should we do?**

    Recommend optimal actions:

    * Resource allocation
    * Process optimization
    * Strategic recommendations
    * Action priorities
  </Tab>
</Tabs>

## Types of Data Visualization

Reporting allows you to transform structured data into insights and visualizations in a report. After selecting one or more datasets from the Library and generating an analysis, Shieldbase renders different chart types based on your data and prompt.

<Tip>
  Choosing the right visualization type for the right data is essential to quickly understand key insights. Data visualization may not show if the chart type is forced to pair with an incompatible dataset.
</Tip>

| Chart Type               | Best Used For                                                                                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Table**                | Display raw or aggregated data in rows and columns. Best for detailed views, reference tables, and drill-downs.                                                                                                                         |
| **Bar Chart**            | Compare values across categories (e.g., revenue by region, tickets by status). Supports vertical or horizontal bars.                                                                                                                    |
| **Stacked Bar Chart**    | Show the composition of each category (e.g., revenue by region broken down by product line) while still comparing totals across categories.                                                                                             |
| **Line Chart**           | Visualize trends over time (e.g., daily active users, monthly sales). Ideal for time-series data and monitoring changes.                                                                                                                |
| **Area Chart**           | Similar to line charts but with the area under the line filled. Useful for showing cumulative values and emphasizing volume over time.                                                                                                  |
| **Stacked Area Chart**   | Show how multiple series contribute to a total over time (e.g., traffic by channel over months).                                                                                                                                        |
| **Pie Chart**            | Show the proportion of each category as a percentage of a whole (e.g., market share, budget allocation).                                                                                                                                |
| **Donut Chart**          | A variation of the pie chart with a hollow center, often used to highlight a key metric in the middle while still showing category proportions.                                                                                         |
| **Column Chart**         | A vertical variation of the bar chart, often used interchangeably, to compare discrete categories or time buckets.                                                                                                                      |
| **Scatter Plot**         | Show the relationship between two numeric variables (e.g., marketing spend vs. revenue). Useful for detecting correlations and outliers.                                                                                                |
| **Bubble Chart**         | A scatter plot with an extra dimension represented by bubble size (e.g., x = revenue, y = profit margin, size = number of customers).                                                                                                   |
| **Histogram**            | Show the distribution of a single numeric variable by grouping values into bins (e.g., deal sizes, response times).                                                                                                                     |
| **Heatmap**              | Use color intensity to represent values in a matrix (e.g., performance by region and product, activity by hour and weekday).                                                                                                            |
| **Funnel Chart**         | Represent staged processes such as sales funnels or onboarding flows, illustrating drop-offs between stages.                                                                                                                            |
| **Radar (Spider) Chart** | Compare multiple metrics across different dimensions (e.g., feature scores, department KPIs) on a radial layout.                                                                                                                        |
| **Gauge Chart**          | Highlight a single key metric, often compared against a target or threshold (e.g., SLA adherence, utilization rate).                                                                                                                    |
| **Tornado Chart**        | A specialized bar chart with bars extending left and right from a central axis, typically used in sensitivity or scenario analysis to compare the relative impact of different variables on an outcome.                                 |
| **Gantt Chart**          | Visualize tasks or activities over time, showing start and end dates, durations, and overlaps. Ideal for project timelines, roadmap planning, and tracking dependencies.                                                                |
| **Control Chart**        | Plot a metric over time with upper and lower control limits to monitor process stability and variation. Useful in quality control to detect anomalies or trends that signal process changes.                                            |
| **Org Chart**            | Show hierarchical relationships between people, roles, or entities in a tree-like diagram. Helpful for visualizing organizational structure or ownership relationships.                                                                 |
| **Sankey Diagram**       | Visualize flows and their relative magnitudes between stages or categories (e.g., traffic sources to pages, budget allocations to spending categories). The width of each flow is proportional to its value.                            |
| **Checklist Matrix**     | Display items (e.g., features, requirements, tasks) against a set of categories or entities, indicating presence, completion, or status in a grid format. Useful for audits, feature comparisons, and tracking implementation coverage. |

## Best Practices

<Warning>
  **Data Quality is Critical**: The cleaner the dataset, the easier it is for AI to understand the context, and thus the more accurate the analysis.
</Warning>

### Data Preparation

<Steps>
  <Step title="Clean Your Data">
    Remove duplicates, fix inconsistencies, handle missing values
  </Step>

  <Step title="Structure Properly">
    Use consistent column names, proper data types, clear headers
  </Step>

  <Step title="Validate Accuracy">
    Verify data accuracy before analysis
  </Step>

  <Step title="Document Context">
    Include metadata about data sources and definitions
  </Step>
</Steps>

### Visualization Guidelines

<Tip>
  **Match Chart to Data**: Choosing the right visualization type for the right data is essential to quickly understand key insights. Data visualization may not show if the chart type is incompatible with the dataset.
</Tip>

<Accordion title="Chart Selection Guide">
  **Comparison**: Bar charts, column charts
  **Trends**: Line charts, area charts
  **Composition**: Pie charts, stacked bars
  **Distribution**: Histograms, box plots
  **Correlation**: Scatter plots, bubble charts
  **Geographic**: Maps, regional charts
</Accordion>

## Integration Options

<Info>
  Reporting can be used in **Dashboard**, **Chatbot**, and **Workflows** for comprehensive automation.
</Info>

### Use in Dashboards

<Steps>
  <Step title="Create Reports">
    Build individual reports for different metrics
  </Step>

  <Step title="Add to Dashboard">
    Combine multiple reports in a single dashboard view
  </Step>

  <Step title="Organize Tabs">
    Group related reports into logical sections
  </Step>

  <Step title="Share Access">
    Provide dashboard access to stakeholders
  </Step>
</Steps>

### Use in Workflows

Automate report generation:

* Schedule regular reports
* Trigger based on data updates
* Distribute via email
* Archive for compliance

### Use in Chatbots

Enable conversational analytics:

* Answer data questions
* Generate on-demand reports
* Provide insights interactively
* Explain trends and patterns

## Common Use Cases

<Tabs>
  <Tab title="Sales Analytics">
    * Revenue trends by product/region
    * Sales team performance
    * Customer acquisition costs
    * Pipeline conversion rates
    * Forecast accuracy
  </Tab>

  <Tab title="Marketing Reports">
    * Campaign performance metrics
    * ROI analysis
    * Channel effectiveness
    * Customer segmentation
    * Engagement trends
  </Tab>

  <Tab title="Operations Metrics">
    * Production efficiency
    * Quality control metrics
    * Inventory levels
    * Supply chain performance
    * Resource utilization
  </Tab>

  <Tab title="Financial Analysis">
    * P\&L statements
    * Cash flow analysis
    * Budget vs. actual
    * Cost center analysis
    * Financial ratios
  </Tab>
</Tabs>

## Advanced Features

### Multi-Dataset Analysis

Combine multiple data sources for comprehensive insights:

<Accordion title="Cross-Dataset Analysis">
  1. Select multiple datasets from the Library
  2. AI automatically identifies relationships
  3. Generate unified insights across sources
  4. Create consolidated visualizations
</Accordion>

### Custom Prompts

Examples of effective analysis prompts:

```text theme={null}
"Show me the top 10 performing products by revenue with monthly trend"
```

```text theme={null}
"Identify seasonal patterns in customer behavior and suggest optimal marketing periods"
```

```text theme={null}
"Compare this quarter's performance with the same quarter last year and highlight key differences"
```

## Troubleshooting

<Accordion title="No visualization appears">
  * Check data format compatibility
  * Verify chart type matches data structure
  * Ensure dataset has required columns
  * Try a different visualization type
</Accordion>

<Accordion title="Inaccurate insights">
  * Review data quality and completeness
  * Provide more specific prompts
  * Check for data inconsistencies
  * Verify date formats and ranges
</Accordion>

<Accordion title="Performance issues">
  * Reduce dataset size for initial analysis
  * Use data sampling for large datasets
  * Optimize queries before analysis
  * Consider data aggregation
</Accordion>

## Pro Tips

<CardGroup>
  <Card title="Start Broad" icon="expand">
    Begin with high-level insights, then drill down into specifics
  </Card>

  <Card title="Iterate Prompts" icon="repeat">
    Refine your prompts based on initial results for better insights
  </Card>

  <Card title="Combine Views" icon="layer-group">
    Use multiple chart types to tell a complete data story
  </Card>

  <Card title="Regular Updates" icon="clock">
    Schedule automated reports for consistent monitoring
  </Card>
</CardGroup>


# Workflows
Source: https://docs.shieldbase.ai/how-to-use/workflows

Turn manual, repetitive processes into automated workflows

## Overview

Turn manual, repetitive processes into automated workflows.

## Workflow Types

There are three types of workflows.

<Tabs>
  <Tab title="Internal Workflow">
    **Private workflow for internal usage with teams.**

    This workflow type is suitable for coordinating single or multiple user tasks, approvals and data operations across teams within a shared governed workflow. Intended for behind-the-scenes automation used by internal teams. Internal Workflow is suitable for:

    * Handling sensitive or operational data.
    * Requiring access to internal systems, integrations, or datasets that should not be exposed to external users.
    * Involving complex orchestration across multiple systems.
  </Tab>

  <Tab title="External Workflow">
    **Public workflow to capture input from external users.**

    This workflow is suitable for capturing structured data from external participants through secured, controlled entry points such as forms or links. Designed for use cases where an external user or system may trigger or interact with the workflow. Action nodes used here must:

    * Be safe to expose to users or systems outside your organization.
    * Avoid exposing internal-only data, configuration, or execution details.
    * Focus on controlled interactions such as collecting information.
    * Note: some internal-only actions are intentionally disabled in external workflows to prevent data leakage or unintended access.
  </Tab>

  <Tab title="Chatbot Workflow">
    **Private or public workflow built for conversations in chatbots.**

    This is suitable for executing workflows through conversational interfaces.
  </Tab>
</Tabs>

<Info>
  Unlike the Chatbot Workflow, both Internal Workflow and External Workflow consist of two modes: **Build** and **Run**. The Chatbot Workflow operates exclusively within the Chatbot interface.
</Info>

## Workflow Modes

<CardGroup>
  <Card title="Build Mode" icon="hammer">
    Design, configure, and sequence the steps in your workflows. Think of it as the blueprint and construction phase.
  </Card>

  <Card title="Run Mode" icon="play">
    Your built workflow actively executing or ready to execute in a live environment. This is where the workflow automation performs its intended tasks automatically.
  </Card>
</CardGroup>

There are two types of Run mode:

* **Run Live**: Automatically execute the workflow live. Process termination occurs if the browser session is closed or the URL changes.
* **Run in the Background**: Workflows run server-side and will continue to process even if the browser tab is closed or the device is powered off.

## Nodes Within a Workflow

There are two types of nodes within a workflow - **Action** and **Event**.

### Action Nodes

An Action is a specific task or operation that a workflow performs in response to a trigger:

<Tabs>
  <Tab title="Data Processing">
    * **Instruct**: Generate a response from a pre-filled prompt or previous step
    * **Agent**: Run an agentic task that can reason, execute code, and generate files
    * **Upload Files**: Ask the user to upload a file so it can be indexed and used in the workflow
    * **Process OCR**: Turn text inside images into editable, searchable text the AI can read
    * **Recognize Image**: Detect an image or part of an image with computer vision
    * **Contextualize From Library**: Pull context from your indexed knowledge sources
    * **Store Into a Dataset**: Save structured data from the workflow into a dataset
  </Tab>

  <Tab title="User Interaction">
    * **Input Text**: Ask the user for information during Run mode
    * **Fill In Form**: Show a custom form during Run mode for structured data collection
    * **Get Approval**: Request an approve or reject decision from a Shieldbase user
  </Tab>

  <Tab title="Communication">
    * **Send Email**: Send an email to one or more recipients with a subject and body
    * **Request Email Reply**: Send an email and wait for a reply to continue the workflow
    * **Download Document**: Turn workflow results into a downloadable document
  </Tab>

  <Tab title="Analytics & Reporting">
    * **Create a Report**: Analyze data and generate a visual report with charts and tables
  </Tab>

  <Tab title="Workflow Control">
    * **Start a Workflow**: Trigger another workflow from this step
    * **Refer to a Parent Workflow**: Use data or files from the workflow(s) that started this one
    * **Loop Action**: Loop over a list and run the same actions once for each item
    * **Pause Until**: Pause workflow execution until a specified condition is met
    * **Handle Conversation**: Route users to the correct conversation flow based on their query
  </Tab>

  <Tab title="Integrations & Templates">
    * **Pull Data from API**: Pull specific fields from third-party apps to be utilized as context
    * **Push Data to API**: Push data to third-party apps to be written
    * **Templatize**: Fill in a downloadable template with content while preserving its format
    * **Translate Document**: Translate documents from one language to another while preserving formatting and style
    * **Merge to PDF**: Merge multiple files (PDF, JPEG, JPG, PNG, XLSX, XLS, CSV) into a single consolidated document
  </Tab>
</Tabs>

### Event Nodes

An Event allows you to set the conditions when to trigger the workflow to run.

<Info>
  **Scheduled Execution**: Execute a workflow based on a schedule.
</Info>

### Action Node Availability by Workflow Type

Not all Action nodes can be used in every workflow type. Each workflow type is designed for different use cases, and certain actions are only available where they make sense functionally and securely.

| Action Node                | Internal Workflow | External Workflow | Chatbot Workflow |
| -------------------------- | ----------------- | ----------------- | ---------------- |
| Instruct                   | ✅                 | ✅                 | ✅                |
| Agent                      | ✅                 | ✅                 | ✅                |
| Upload Files               | ✅                 | ✅                 | ✅                |
| Process OCR                | ✅                 | ✅                 | ✅                |
| Input Text                 | ✅                 | ✅                 | ✅                |
| Download Document          | ✅                 | ✅                 | ✅                |
| Contextualize From Library | ✅                 | ✅                 | ✅                |
| Recognize Image            | ✅                 | ✅                 | ✅                |
| Send Email                 | ✅                 | ✅                 | ✅                |
| Request Email Reply        | ✅                 | ❌                 | ❌                |
| Fill In Form               | ✅                 | ✅                 | ✅                |
| Get Approval               | ✅                 | ❌                 | ❌                |
| Create a Report            | ✅                 | ✅                 | ✅                |
| Store Into a Dataset       | ✅                 | ✅                 | ✅                |
| Start a Workflow           | ✅                 | ✅                 | ❌                |
| Refer to a Parent Workflow | ✅                 | ❌                 | ❌                |
| Loop Action                | ✅                 | ✅                 | ❌                |
| Pause Until                | ✅                 | ❌                 | ❌                |
| Pull Data from API         | ✅                 | ✅                 | ✅                |
| Push Data to API           | ✅                 | ✅                 | ✅                |
| Templatize                 | ✅                 | ✅                 | ✅                |
| Translate Document         | ✅                 | ✅                 | ✅                |
| Merge to PDF               | ✅                 | ✅                 | ✅                |
| Handle Conversation        | ❌                 | ❌                 | ✅                |

## Action Node Details

### Instruct

Generate a response from a pre-filled prompt or previous step. Use this when you already know exactly what and how you want the AI to respond.

<Note>
  Adjust video playback speed using the gear icon in the video player.
</Note>

<iframe />

* Workflow automation frequently requires synthesizing data from multiple sources. For this reason, the Instruct node, which is designed to perform this synthesis, will likely be one of the most used nodes in any workflow.

* The Instruct node is the core of your workflow's logic. It takes in data and performs a specific action, such as synthesizing information, generating text, or making a decision.

* The more precise your instruction, the better the output will be. Instead of a general command like "summarize this," specify what kind of summary you want. For example: "Summarize this article into three key bullet points, focusing on the main arguments and conclusions. The tone should be concise and professional."

* For multi-step workflows, chain multiple Instruct nodes together. This breaks down a complex task into smaller, manageable parts. For instance, instead of one node trying to do everything, you could have the first node to summarize a long document. The second node to extract key facts from the summary. The third node to use those facts to draft an email.

* Tell the Instruct node exactly how you want the final output to be formatted. You can ask for a response in JSON, a list, a table, or simple text. For example, you can specify: "Provide the output as a JSON object with 'product\_name' and 'price' as keys." This is essential for ensuring the data can be used by subsequent nodes in your workflow.

### Agent

Run an agentic task that can reason, execute code, and generate files.

* Use the **Agent** node when a workflow requires flexible, multi-step reasoning, code execution, or file generation that goes beyond the fixed capabilities of other action types. Think of it as a "dynamic operator" that can adapt to complex tasks in real time.

* Unlike other action nodes that are too narrow or rigid to cover the full complexity of what you need, the **Agent** node is designed to be dynamic. It can decide what tools to use (reasoning, code, integrations, file generation) based on the goal you specify.

* Treat the **Agent** node as a general-purpose problem solver. You can use it to perform data analysis, transform or clean data, run calculations, simulate scenarios, or generate structured outputs (such as JSON, tables, and formatted text) within the same step.

* Because the **Agent** node can execute code, you can offload technical or repetitive logic into it — such as parsing complex inputs, reconciling data from multiple sources, or applying business rules — without building many separate workflow steps.

* Use the **Agent** node to generate files (for example, reports, summaries, or processed datasets) and hand them off to subsequent nodes.

* Use the **Agent** node when a process would otherwise require many Instruction steps chained together. The **Agent** can reason across multiple sub-tasks, decide intermediate actions, and produce a consolidated result, reducing workflow complexity.

<Tip>
  **For multi-step automations, pair the Agent node with other nodes:**

  * Use **Upload Files** or **Contextualize From Library** to supply source documents or datasets.
  * Use **Input Text** or **Fill In Form** to collect parameters or preferences from users.
  * Pass all of this as context into the Agent node so it can reason, compute, and generate the final outcome.
</Tip>

* Be explicit and precise in your instructions to the **Agent** node. Instead of a broad request like "analyze this," define the task clearly, including the objective, constraints, and format of the output. For example: "Clean this CSV data, remove duplicate rows, compute total revenue by month, and return a JSON object with 'month' and 'total\_revenue' fields."

* Clearly specify the expected output format (e.g., JSON, markdown table, plain text, or a file). This is crucial when the output will be used by downstream nodes, such as **Store into a Dataset**, **Create Report**, or another **Agent** node in a chained setup.

<Warning>
  For heavily regulated or sensitive use cases, scope and constrain what the **Agent** node can access and do. Provide it with clearly defined inputs (data, prompts, and rules) and combine it with guardrails from Library Integration or approval flows to avoid unwanted actions or hallucinations.
</Warning>

<Info>
  When designing enterprise workflows, treat the **Agent** node as your "advanced mode." Start with static, predictable nodes for straightforward tasks, and add an Agent node only where you truly need flexible reasoning, code execution, or dynamic file generation. This keeps workflows maintainable, auditable, and easier to troubleshoot.
</Info>

### Upload Files

Ask you or other users to upload a file so it can be indexed and used in the workflow (for example, a new report or document each run).

<iframe />

* Use Upload Files node for files that change with each use, like a new report or a daily log.

* This node treats the file as a variable, allowing you to handle different content each time the workflow runs.

* In contrast, if you need to access a fixed set of information repeatedly, use the Contextualize From Library node. This is ideal for consistently referencing static information, such as a company's product catalog or a list of standard operating procedures, because it treats the file as a persistent source of reference data.

### Process OCR

Understand text within the image.

<iframe />

* When a task involves extracting text from images, such as scanned documents or photos, use Process OCR. Optical character recognition (OCR) technology analyzes the image to recognize and convert the text into a machine-readable format. This is especially useful for digitizing physical documents, automating data entry, or making scanned content searchable.

<Warning>
  The Process OCR node is not a standalone node. It's usually amongst the first steps in a larger workflow. Although the purpose is to digitize text from images, the real value is in what you do with that text afterward. Think of OCR as a data extractor - it pulls the information, but it doesn't process or save it on its own.
</Warning>

### Input Text

Ask users to input information during Run mode.

<iframe />

* The Input Text node is designed to capture and store a user's input, which then acts as a variable. This node is not a standalone function; instead, it serves as a crucial component that connects to other nodes within a larger system.

<Tip>
  The Instruct node is particularly important because it can synthesize and process the data captured by the Input Text node. While Input Text gathers the raw information, the Instruct node uses that information to execute a task, generate a response, or perform some other action. Think of Input Text as the "question" and Instruct as the "answer."
</Tip>

### Download Document

Develop a downloadable report in either PDF, DOC, or XLSX formats.

<iframe />

* The Download Document node is suitable for converting synthesized data from an Instruct node into a downloadable report. This allows you to transform the processed information into a polished, shareable document.

* The Download Document node is most powerful when used as the final step in a process.

**Powerful Combinations:**

* Pair with **Instruct** node to turn text output into professional reports
* Use after **Process OCR** node to format extracted text into clean documents
* Combine with **Send Email** to automatically attach and distribute reports

<Info>
  If you need to download a file in a format that isn't currently available, please send a request to [support@shieldbase.ai](mailto:support@shieldbase.ai). Our team will consider your request and work to make the format available for you.
</Info>

### Contextualize From Library

Connect to a source for context.

<iframe />

* The Contextualize From Library node provides a centralized way to access all indexed data from various sources. Use this node when you need to select specific information as context for your automation tasks. It allows the user to access the institutional body of knowledge to inform or guide a workflow.

<Tip>
  **When to use Contextualize From Library vs Upload Files:**

  * **Contextualize From Library**: Static reference material used repeatedly (price lists, SOPs)
  * **Upload Files**: Variable files that change with each task (daily reports, new images)
</Tip>

<Warning>
  Before you integrate data into the Library, make sure the data within it is organized and easy to search. Use clear, descriptive headings and sections. For example, if your library is a document of standard operating procedures (SOPs), use a consistent format for each procedure, like "SOP-\[Number]: \[Procedure Name]."
</Warning>

* The information provided by this node is only as good as the data it contains. Regularly update your integrated documents or databases to ensure your workflows are using the most current and accurate information.

### Recognize Image

Detect an image or part of an image with computer vision.

<iframe />

* Use **Recognize Image** when a workflow needs to detect, interpret, or classify the content of an image, such as identifying objects, reading labels, or understanding scenes.

* Treat **Recognize Image** as the "eyes" of your workflow. It extracts visual context from images, similar to how OCR Document Processing extracts text, but focused on understanding what is shown rather than just what is written.

<Tip>
  **Powerful Combinations:**

  * Combine with **Templatize** to place an image in a predefined template (e.g., detect a product image, then insert it into a branded report, invoice, or slide layout).
  * Use together with **Upload Files** when image inputs change frequently (e.g., daily photos, scanned slips, uploaded screenshots). Upload Files collects the image; Recognize Image analyzes it; Instruct or Download Document turns the result into a usable output.
  * Use together with **Contextualize From Library** when you need to compare or match detected visual content against a known catalog (e.g., match a product from a photo to a product list, or map a detected logo to a company profile).
  * Chain with **Instruct** to summarize, validate, or generate a narrative from the detected visual details (e.g., "Create a quality check summary based on the detected defects in the image").
</Tip>

* Be explicit in your instructions. Instead of a general prompt like "analyze this image," specify what you want: "Identify all visible products and their colors," or "Detect whether this picture contains a signature and a company seal."

* When building automations that mix documents and visuals (e.g., reports with photos, inspection logs, or design reviews), use Recognize Image early in the workflow to structure what is seen (objects, labels, conditions), then pass these structured results to nodes like **Store into a Dataset** or **Create Report**.

<Warning>
  Always ensure the uploaded images are clear and of sufficient resolution. Blurry, low-contrast, or heavily compressed images may lead to incomplete or inaccurate recognition, reducing the quality of downstream analysis. For sensitive content, align Recognize Image usage with your organization's security and compliance policies.
</Warning>

### Send Email

Send an email to a specific email address with subject and body.

<iframe />

* Set up an email sender directly within your workflow. This feature allows you to input a subject line and a body, then send the email to one or multiple recipients. You also have the option to include CC recipients.

**Powerful Combinations:**

* Combine with **Scheduled Execution** to automatically send an email on a specific day and at a precise time (recurring or one-time)
* Combine with **Download Document** to download a report of the email sent

<Info>
  Send Email node does not allow email replies, while Request Email Reply node allows email recipients to reply.
</Info>

### Request Email Reply

Send the first email and reply to it to ensure the workflow continues.

<iframe />

* Request Email Reply node is used to send an email to the email recipient with the intention of getting replies in order for the workflow to continue.

* Since receiving email replies may take some time, find the workflow in the execution history at the right side of the screen.

<Tip>
  **Best Practices:**

  * Write concise subject lines and body text that explicitly state what is needed (e.g., "Approve Q3 Budget?"), how to respond (e.g., "Reply 'YES' to approve, 'NO' to reject"), and deadline (if applicable)
  * Enforce predictable responses by instructing users to reply with keywords such as APPROVE, REJECT, REVISE
  * Limit email recipients to essential stakeholders. Send to one decision-maker when possible. Use CC for visibility only, as replies from CC'd users are often ignored unless explicitly parsed. For group approvals, consider a shared form link instead
  * Ensure each Request Email Reply step logs the sent timestamp, recipient(s), reply timestamp and content, and outcome for compliance and debugging
</Tip>

### Fill In Form

Develop a custom form to be filled by users during Run mode.

<iframe />

* The Fill In Form node acts as a dynamic form builder that prompts users to fill in information based on the form.

* Before you start, identify the goal of your form. What data do you need to collect? What's the logical order for your questions?

* Use the right input fields. Matching the field type to the data you need is crucial for a good user experience.

* Use labels and placeholder text to guide the user. A clear label like "Enter your email address" is much better than a generic "Input."

* Mark any critical fields as Required. This prevents the workflow from failing due to missing data.

* Only ask for information you truly need. A long, complex form can lead to user fatigue and a higher drop-off rate.

#### Available Form Fields

<Tabs>
  <Tab title="Text Fields">
    * **Text Input**: Insert a single line of text, numbers, and symbols. Designed for short-form entries like a name, subject line, or product code.
    * **Text Area**: Input multiple lines of text, numbers, and symbols. Designed for longer content like descriptions or comments.
    * **Password**: Input sensitive information like a password. Characters are hidden from view.
  </Tab>

  <Tab title="Number & Date">
    * **Numeric**: Only accepts numbers. Used for values like quantity, price, or percentage.
    * **Date**: Select a specific date. Ideal for scheduling, setting deadlines, or logging events.
    * **Time**: Input the time. Useful for scheduling appointments or logging task completion.
    * **Date & Time**: Input both date and time. Useful for scheduling, logging events, or setting deadlines.
  </Tab>

  <Tab title="Selection">
    * **Dropdown**: Select a single item from a list of options. Great for saving space with clear choices like countries or sizes.
    * **Radio Button**: Select only one item displayed. Ideal for single selection like payment method or gender.
    * **Checkbox**: Tick a single checkbox. Use for yes/no responses like acknowledging terms of service.
    * **Multi-Select**: Select one or more options. Useful for multiple selections like categories or tags.
  </Tab>
</Tabs>

### Get Approval

Request approval from team members who are also Shieldbase users.

<iframe />

* The Get Approval node is a decision-node used to get a sign-off on a workflow's output.

* There are only two outcomes - approved and unapproved. Hence the Get Approval node is a decision that branches to two different paths.

* Since receiving approval from the approver may take some time, find the workflow in the Execution History at the right side of the screen.

<Tip>
  The approver should not have to hunt for information. Make sure the output from the previous nodes provides all the data they need to make an informed decision. Use the Instruct node to synthesize the data into a concise summary or report that is attached to the approval request.
</Tip>

### Create a Report

Analyze data into insights and generate visualization.

<iframe />

* The Create a Report node integrates data analysis and visualization directly into your workflow. It allows you to transform raw data into a structured, visual report, helping you make sense of complex information and share insights effectively.

* Before you even start, make sure the data you're feeding into the Create a Report node is clean and well-organized. Use a clear, consistent format, and label your data columns with descriptive names (e.g., Revenue\_2024, Region, Customer\_ID).

* Explicitly state the purpose in your instructions. For example, instead of just "develop a report," specify: "Create a sales performance report analyzing monthly revenue trends and showing top-performing regions. The report should include a line graph for revenue over time and a bar chart for regional sales."

* Use Create a Report node together with Input Text node, Fill In Form node or Contextualize From Library node to generate data analysis and visualization using the information as context for analysis.

### Store Into a Dataset

Extract text and store into a dataset.

<iframe />

* Before utilizing the Store Into a Dataset node, ensure that the previous steps in your workflow generate structured data.

* When creating the dataset, always define custom column names that reflect the data's purpose (e.g., "Customer\_ID," "Transaction\_Amount"). This improves readability and compatibility when integrating with tools like spreadsheets, databases, or reporting software.

* If your workflow deals with dynamic inputs (e.g., varying numbers of records), use conditional logic in prior steps to batch or filter data. This prevents overwhelming the dataset with irrelevant entries and keeps performance optimal.

* Be mindful of dataset size in enterprise environments, as large datasets can impact workflow speed. Set thresholds or use compression techniques if your platform supports them.

### Start a Workflow

Trigger to run another workflow as part of the step.

<iframe />

* Toggle the wait checklist to continue running the first workflow after the triggered workflow has completed.

* The Start a Workflow node is ideal to build a reactive, decoupled workflow capable of running by itself automatically in the background as the main workflow continues running.

### Refer to a Parent Workflow

Use data or files from specific steps in the workflow(s) that started this one. Useful for aggregating info from multiple parents.

* Name and label key steps in parent workflows clearly so it's easy to choose the right "Parent Step" when configuring this feature.

* When multiple parent workflows can trigger the same child, standardize output schemas (field names, types) to avoid mapping errors.

* Use this feature to aggregate results from parallel parent branches (e.g., multiple approvals) into a single consolidated summary step.

* Always validate that parent outputs exist before referencing them (e.g., add guards or conditional branches for missing/empty data).

* Log the parent workflow ID and triggering step in the child workflow for easier debugging and audit trails.

### Loop Action

Loop over a list and run the same actions once for each item (for example, send an email to every address in a list).

* Keep loops focused. Place only the actions that truly need to repeat inside the loop to avoid unnecessary processing time.

* For large lists, add safeguards such as item limits or batch sizes to prevent timeouts and rate-limit issues with downstream systems.

* When calling external APIs with Pull Data From API in a loop, implement throttling or short delays if you notice rate-limit or quota errors.

### Pause Until

Pause workflow execution until a specified condition is met.

* Use precise, machine-detectable conditions (status fields, timestamps, flags) instead of vague text values to avoid workflows pausing indefinitely.

* Set a maximum wait duration with a failover path (e.g., escalate, notify, or auto-close) to handle conditions that are never met.

* Prefer event-based triggers (webhooks, status updates) over long fixed delays to reduce latency and resource usage.

* Add clear logging messages when entering and exiting the pause so operators can understand where and why runs are waiting.

* When pausing for user input, send proactive notifications (email, chat, or in-app) that include a direct link to complete the required action.

### Pull Data from API

Pull specific fields from third-party apps to be utilized as context.

* The initial permission to pull data through API from third-party apps must be configured in Integrations.

* Start by pulling only the fields you truly need. Over-fetching unnecessary fields can slow down workflows and increase API costs.

* Normalize and validate API responses immediately after pulling (e.g., type-check, null-check) to prevent downstream failures.

* Log the raw response (or a sanitized version) for debugging, but mask or omit sensitive fields (tokens, PII) from logs.

### Push Data to API

Push data to third-party apps to be written.

* The initial permission to write data to third-party apps must be configured in Integrations.

* Map fields explicitly and document the mapping, especially when integrating with multiple APIs or versions of the same service.

* Validate and sanitize data before sending to prevent hard failures due to schema or format mismatches on the target side.

* Capture and store response IDs or confirmation tokens from the API for traceability and future updates or deletes.

### Templatize

Fill in a downloadable template with content while preserving its format.

<iframe />

* For the most accurate results in ensuring content is mapped to the template, use spreadsheets or structured text documents as the template.

* For optimal accuracy, use an empty, tabulated template. This structure ensures the system correctly maps each data field while preventing data errors.

* Design templates with clear placeholder markers (e.g., `{{field_name}}`) and maintain a mapping document for template authors and builders.

* Keep formatting logic (fonts, spacing, layout) in the template file and limit dynamic content to text and images where possible.

* Test template fills using edge-case values (very long strings, special characters, empty fields) to prevent broken layouts in real usage.

* Use conditional sections or fallback text for optional fields so templates still look polished when some data is missing.

* Version your templates and track which workflow version uses which template to avoid unexpected formatting changes in live flows.

### Translate Document

Translate documents from one language to another while preserving formatting and style.

<iframe />

* For domain-specific content (legal, medical, technical), provide glossaries or term lists if supported to improve translation consistency.

* Use translation primarily for content consumption. Run an additional human or specialized review step before using translations in legal or external-facing materials.

* Store both original and translated versions, and include metadata (language, translation date, workflow ID) for future reference and audits.

### Merge to PDF

Merge multiple files (PDF, JPEG, JPG, PNG, XLSX, XLS, CSV) into a single consolidated document.

<iframe />

* Use Merge to PDF when your workflow generates or collects multiple documents (e.g., reports, forms, attachments) that need to be consolidated into a single, shareable file for stakeholders.

* Standardize your output by always merging in a consistent order (e.g., cover page, summary, detailed analysis, appendix). This makes the final PDF easier to read and reference, especially in recurring workflows like weekly reports or client deliverables.

* Combine Merge to PDF with Process OCR when working with scanned documents or images. First convert images to machine-readable text, then merge them into a single, searchable PDF for better usability and archiving.

* When your process involves approvals or signatures, use Merge to PDF to consolidate all related materials (request, supporting evidence, decision logs) into a single file. This creates a clean audit trail that can be stored, emailed, or referenced later.

* Be mindful of file size. If you are merging many large documents (especially images or high-resolution reports), consider compressing inputs or limiting unnecessary pages before merging to keep the final PDF performant and easy to share.

### Handle Conversation

Route users to the correct conversation flow based on their specific query.

* Define clear routing criteria (intents, keywords, entities) and keep them mutually exclusive where possible to avoid ambiguous flows.

* Use a fallback or "unsure" route that gracefully handles queries that don't match any defined conversation path.

* Continuously review real user queries and conversation logs to refine routing rules and add new intents over time.

* Pass along context (user attributes, previous messages, channel) when handing off to downstream flows so they don't need to re-ask basic questions.

* Implement guardrails for high-risk topics (billing changes, privacy, security) by routing them to specialized flows or human agents.

## Scheduled Execution Node

Execute a workflow based on a schedule.

<iframe />

* The Scheduled Execution node allows you to run a workflow automatically at a specific date and time. This is perfect for automating routine tasks without any manual intervention.

* Use it to schedule daily, weekly, or monthly tasks. For example, you can set a workflow to generate a weekly sales report every Friday at 9 AM, or to send out a daily email reminder.

* You can also schedule a workflow to run just once at a future date. This is useful for things like sending a timed reminder or launching a campaign on a specific day.

* The Scheduled Execution node acts as a trigger for your entire workflow. Once the scheduled time arrives, the workflow automatically starts and runs to completion, pulling in data, processing it, and generating an output.

## How to Build a Workflow

### Build a Linear Workflow

A linear workflow runs in a straight sequence to produce an output. It is a simple, straightforward sequence from start to finish where each step is completed one after another without any loops, branches, or conditional logic. The output of one step becomes the input for the next, creating a clear, predictable chain of events.

<Note>
  Adjust video playback speed using the gear icon in the video player.
</Note>

<iframe />

<Steps>
  <Step title="Create Workflow">
    Click **New Workflow** - you'll automatically be in Build mode
  </Step>

  <Step title="Configure First Node">
    1. Click on the node to reveal node details
    2. Select the **Action Type** to select an action
    3. Insert the details specific to the Action Type
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to ensure the details are saved
  </Step>

  <Step title="Add Sequential Steps">
    Click **Add Action** to sequence the next steps. Repeat the configuration until the workflow sequence is complete.
  </Step>

  <Step title="Run Workflow">
    Click **Run** to run the workflow based on the sequence
  </Step>
</Steps>

### Build a Decision Workflow

A decision workflow allows you to make a choice from multiple options, guiding the workflow down a specific path based on certain conditions. This is more than just a simple "yes/no" process; it can present multiple options, evaluate different criteria, and then execute the appropriate next steps.

At its core, a decision workflow uses a decision node to evaluate a condition. For example, the workflow might ask: "Is the invoice amount greater than \$1,000?"

* **If Yes**: The workflow can be configured to automatically route the invoice to a manager for approval.
* **If No**: The workflow can send the invoice directly to the finance department for payment.

<Note>
  Adjust video playback speed using the gear icon in the video player.
</Note>

<iframe />

<Steps>
  <Step title="Open Workflow">
    Click **New Workflow** or any existing workflow
  </Step>

  <Step title="Add Decision Node">
    Click **Add Action** and select **Decision**
  </Step>

  <Step title="Configure Decision Condition">
    1. Select the Decision node to show and edit the node detail
    2. In the **Description**, make sure to specify under what condition the workflow will reach either option A or B
    3. Click **Save Changes**
  </Step>

  <Step title="Configure Option A">
    1. Select the node in option A and describe what happens if the workflow reaches this node
    2. Click **Save Changes**
  </Step>

  <Step title="Configure Option B">
    1. Select the node in option B and describe what happens if the workflow reaches this node
    2. Click **Save Changes**
  </Step>

  <Step title="Run Workflow">
    Click **Run** to run the workflow based on the sequence
  </Step>
</Steps>

### Schedule a Trigger to Run Workflow

To execute a workflow automatically at a specific date and time, you can schedule a trigger. This feature allows you to set up recurring tasks, such as generating a weekly report or sending a daily summary, without any manual intervention.

<Note>
  Adjust video playback speed using the gear icon in the video player.
</Note>

<iframe />

<Steps>
  <Step title="Open Workflow">
    Click **New Workflow** or any existing workflow
  </Step>

  <Step title="Add Event">
    Click **Add Event** to schedule a trigger when to activate this workflow
  </Step>

  <Step title="Configure Schedule">
    Describe in the Description under what conditions this workflow will trigger, along with scheduling the **Day of the Week**, **Hour**, **Minute**, and **Timezone**.
  </Step>

  <Step title="Save and Activate">
    Click **Save Changes** - the workflow will automatically run by itself based on the schedule set in the Scheduled Execution
  </Step>
</Steps>

## Edit a Workflow

A published workflow can be edited into new versions.

<Note>
  Adjust video playback speed using the gear icon in the video player.
</Note>

<iframe />

<Steps>
  <Step title="Open Existing Workflow">
    Click on an existing workflow
  </Step>

  <Step title="Create Draft">
    In Build mode, click **New Draft** to duplicate the previous version of the workflow that is editable
  </Step>

  <Step title="Make Changes">
    Edit the workflow
  </Step>

  <Step title="Publish">
    Once completed, click **Publish** as the latest version of the workflow
  </Step>
</Steps>

## Workflow Templates

Workflow templates are pre-built workflows designed to help you get started quickly with common automation tasks. They provide a solid foundation and best practices, saving you the time and effort of building a workflow from scratch.

<Info>
  Once you select a template and begin editing it, you are no longer working on the original template itself. Instead, you are creating a new, customized version of that workflow.
</Info>

## Prompt-to-Workflow

Workflow building can be initiated via Prompt-to-Workflow. Simply input the prompt with specific requirements to allow Shieldbase AI to draft an automated sequence, reducing the need for manual configuration.

<Tip>
  When using Prompt-to-Workflow, being descriptive in the prompt helps to build a workflow that is more precise in the sequences.
</Tip>

## Export and Import Workflow

Workflows can be both exported and imported, making it easy to reuse, back up, share, and migrate automations across environments, teams, or projects.

### Export Workflow

Use **Export** when you want to reuse, back up, or share a workflow configuration across environments or teams. Before exporting, give your workflow and its key steps clear names and descriptions so others can understand them more easily after import.

<Steps>
  <Step title="Open the Workflow">
    Open the workflow you want to export.
  </Step>

  <Step title="Click Export">
    Click **Export**.
  </Step>

  <Step title="Choose What to Include">
    Choose what to include in the export:

    * **Export workflow only**: Use this when you only need the workflow structure (nodes, connections, and configurations) without any attached files. Ideal for sharing logic patterns or templates that others will customize with their own files.
    * **Export with library files**: Use this when some workflow steps use files from the Library (e.g., reference documents, templates) that should travel with the workflow. This ensures the imported workflow can run without requiring the recipient to manually re-attach those files.
    * **Export with parent/child workflows**: Use this when the current workflow is connected to other workflows (for example, uses **Start a Workflow** or **Refer to a Parent Workflow**). This preserves relationships when moving an entire multi-workflow solution together. Verify that all referenced workflows are in a stable state (not drafts) to avoid broken references after import.
  </Step>

  <Step title="Confirm and Export">
    Confirm and export. A JSON file containing the workflow definition (and any included assets/links) will be created and downloaded.
  </Step>
</Steps>

### Import Workflow

Use **Import** when you want to bring in a prebuilt workflow (JSON file) from another environment, team, or project.

<Steps>
  <Step title="Create a New Workflow">
    Go to **Workflows** and create a new workflow.
  </Step>

  <Step title="Click Import">
    In the new workflow, click **Import**.
  </Step>

  <Step title="Select the JSON File">
    Select the JSON file you previously exported from your local drive. The platform will populate the workflow canvas using the definition in the JSON file.
  </Step>
</Steps>

<Info>
  On import:

  * The workflow structure (nodes, connections, and configurations) is recreated from the JSON file.
  * If the JSON includes library files, they are attached to the relevant steps (subject to access and environment rules).
  * If parent/child workflows were included, linked workflows are created and reconnected as defined in the package.
</Info>

<Tip>
  After importing a workflow, run it with sample data first to validate behavior before exposing it to end users.
</Tip>

## Pro Tips

<Tip>
  **Workflows can be used as a standalone or in a Chatbot** for more complex interactive experiences.
</Tip>

<Warning>
  **Don't automate a broken process**: Before automating a process, first understand and optimize the existing, manual workflow to ensure that it's effective. Automating an inefficient process will only make your problems faster and more widespread.
</Warning>

<Tip>
  **Keep workflows short and simple**: A shorter, simpler workflow is more resilient, easier to troubleshoot, and allows for rapid iteration. Effective workflows are defined by their efficiency, not their length. Complex, multi-step automation can be counterproductive, introducing more points of failure, making testing and auditing a nightmare, and slowing down future improvements.
</Tip>

<Info>
  **Ideal automation candidates**: Repetitive tasks, error-prone processes, time-consuming operations, tasks requiring fast scalability, and processes needing auditable execution across multiple systems and stakeholders.
</Info>

## Best Practices

<CardGroup>
  <Card title="Start Simple" icon="seedling">
    Begin with basic workflows and gradually add complexity
  </Card>

  <Card title="Test Thoroughly" icon="flask">
    Test each step individually before running the complete workflow
  </Card>

  <Card title="Document Purpose" icon="file-lines">
    Clearly document what each workflow does and why
  </Card>

  <Card title="Monitor Performance" icon="chart-line">
    Regularly review workflow execution logs and performance
  </Card>
</CardGroup>

## Common Use Cases

### Data Processing Pipeline

<Accordion title="Example Configuration">
  1. **Upload Files**: Receive CSV file
  2. **Process OCR**: Extract text from images
  3. **Instruct**: Clean and format data
  4. **Store Into a Dataset**: Update database
  5. **Create a Report**: Generate analytics dashboard
  6. **Send Email**: Notify stakeholders with report
</Accordion>

### Approval Workflow

<Accordion title="Example Configuration">
  1. **Fill In Form**: Employee submits request
  2. **Decision Node**: Route based on request type/amount
  3. **Get Approval**: Manager reviews request
  4. **Decision Node**: Approve or deny path
  5. **Download Document**: Generate decision letter
  6. **Send Email**: Notify employee of decision
  7. **Store Into a Dataset**: Log request in system
</Accordion>

### Scheduled Reporting

<Accordion title="Example Configuration">
  1. **Scheduled Execution**: Weekly at 9 AM
  2. **Contextualize From Library**: Pull latest data
  3. **Instruct**: Analyze trends and patterns
  4. **Create a Report**: Generate weekly metrics
  5. **Download Document**: Create PDF report
  6. **Send Email**: Distribute to team
</Accordion>

## When to Automate

### Good Candidates for Automation

<CardGroup>
  <Card title="Repetitive Tasks" icon="repeat">
    Tasks performed regularly with consistent steps
  </Card>

  <Card title="Error-Prone Processes" icon="triangle-exclamation">
    Processes where human error is common
  </Card>

  <Card title="Time-Consuming Operations" icon="clock">
    Manual tasks that take significant time
  </Card>

  <Card title="Scalable Execution" icon="expand">
    Processes needing to handle increasing volumes
  </Card>
</CardGroup>

## Troubleshooting

<Accordion title="Workflow fails to execute">
  * Check all required fields are filled
  * Verify data source connections
  * Review error logs in Run mode
  * Test each step individually
  * Ensure proper data formatting
</Accordion>

<Accordion title="Scheduled workflow not running">
  * Verify schedule configuration
  * Check timezone settings
  * Ensure workflow is published (not in draft)
  * Review system permissions
  * Check for conflicting schedules
</Accordion>

<Accordion title="Performance issues">
  * Break complex workflows into smaller ones
  * Optimize data queries in Contextualize From Library
  * Reduce unnecessary steps
  * Avoid processing large files in single steps
  * Contact [support@shieldbase.ai](mailto:support@shieldbase.ai) for optimization help
</Accordion>

<Accordion title="Form or approval not working">
  * Verify user permissions
  * Check that all required fields are configured
  * Test with different user roles
  * Ensure email notifications are configured
</Accordion>