⚙️ Exercise 2.1: Ingest Knowledge Using the API

🎯 Exercise Overview

Go beyond manual upload! In this exercise, you'll use a ready-to-use API to automatically ingest Jira issues into your Dify knowledge base. This approach gives you structured documents with rich metadata—much more powerful than plain text files.

✨ This is the foundation for automated knowledge ingestion. Perfect for teams that want to integrate Jira data into their AI assistants!

🚀 What You'll Build

• Connect to the deployed Jira ingestion API
• Explore available Jira projects using Swagger UI
• Ingest structured Jira issues into your Dify knowledge base
• Compare manual vs. API-based ingestion results

Release baseline: Follow this API ingestion exercise against the Dify 1.16.1 workshop default. Use the Dify base URL shown in your assigned environment; the examples below intentionally use a synthetic placeholder.

---

📋 Step-by-Step Checklist changed

🎯 Exercise Checklist

• Step 1: Get Dify API credentials
• Step 2: Explore available projects
• Step 3: Ingest Jira issues via API

• Step 4: Verify ingestion in Dify
• Step 5: Add Summary Index
• Step 6: Benchmark retrieval
• Step 7: Compare knowledge bases

⏱️ Estimated Time: 20-25 minutes | 🎯 Goal: API-ingested knowledge base with structured metadata and measured retrieval

---

🚀 Why Use the API?

Manually uploading .txt files gives you a starting point, but API ingestion offers superpowers:

• 🧠 Rich documents with metadata (issue keys, project info, etc.)
• 🤖 Bulk upload multiple issues at once
• ✅ Structured data - each document linked to an issue_key
• 🧰 Automation ready - perfect for pipelines or daily ingestion

💡 Use this API if you want to:

• Experiment with JSON ingestion instead of raw .txt
• See how metadata improves search quality
• Reuse this approach at work with real Jira projects

API Ingestion Example

---

🛠️ Step 1: Get Your Dify Configuration

📋 Configuration Steps

You'll need your Dify instance details to connect the API. Follow these steps:

1.1: Access Your Dify API Settings

1. In your Dify instance, navigate to Knowledge section

2. Find and copy your API Server URL

3. Click the API Key button and create a dedicated, short-lived key for this ingestion

Credential safety: Use this key only for the workshop ingestion, never include it in screenshots or saved command files, and revoke it after the verification steps below.

Step 1: Access API settings in Knowledge section (click to expand)

Step 2: Create API key for datasets (click to expand)

🧠 Pro Tip: Keep your API Server URL and API key handy - you'll need them in the next steps!

---

🔍 Step 2: Explore Available Projects

Before sending any Dify credentials, open the service /health and /projects endpoints. Continue only when the service reports version 2.1.0 and lists REST_JiraEcosystem_issues.

📋 Exploration Steps

Before ingesting data, let's see what Jira projects are available using the interactive Swagger UI.

2.1: Open the API Documentation

📚 Interactive API Documentation

Explore available Jira projects and test API endpoints directly in your browser

🔗 Open Swagger UI →

The Swagger UI provides an interactive interface where you can:

• 📖 Browse all available endpoints
• 🧪 Test API calls directly in your browser
• 👀 See request/response examples
• 🔍 View available projects interactively

Swagger UI interface (click to expand)

💡 Tip: The Swagger UI is especially helpful if you're new to APIs. You can click "Try it out" on any endpoint to test it without writing curl commands!

---

📤 Step 3: Ingest Jira Issues

🔧 Ingestion Steps

Use the POST /jira/ingest endpoint to ingest specific projects. Leave the dataset_id empty and fill in your Dify configuration.

3.1: Using Command Line (curl)

Run this command to ingest a project:

curl -X 'POST' \
  'https://dify-jira.testingfantasy.com/jira/ingest?advanced_ingestion=false' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "request": {
    "project": "REST_JiraEcosystem_issues"
  },
  "dify_config": {
    "dify_base_url": "{your_dify_base_url}/v1",
    "dify_api_key": "{your_dify_api_key}",
    "dataset_id": "" 
  }
}'

📝 Replace these values:

• {your_dify_base_url} → Your Dify instance base URL (from Step 1)
• {your_dify_api_key} → Your Dify API key (from Step 1)
• REST_JiraEcosystem_issues → The project you want to ingest (use /projects endpoint to see all available projects)

3.2: Using Swagger UI (Recommended)

You can also use the Swagger UI to test the endpoint interactively:

1. Navigate to the POST /jira/ingest endpoint in Swagger UI
2. Click "Try it out"
3. Use this payload:

{
  "request": {
    "project": "REST_JiraEcosystem_issues"
  },
  "dify_config": {
    "dify_base_url": "{your_dify_base_url}/v1",
    "dify_api_key": "{your_dify_api_key}",
    "dataset_id": "" 
  }
}

4. Click "Execute" to run the ingestion

Swagger UI ingest endpoint (click to expand)

---

✅ Step 4: Verify Ingestion in Dify changed

🔍 Verification Steps

After running the ingestion command, verify that your data was successfully uploaded to Dify.

4.1: Check the API Response

The API will return a response showing the ingestion status:

{
  "success": true,
  "dify_instance": "{your_dify_base_url}/v1",
  "files_processed": 1,
  "files_failed": 0,
  "results": [
    {
      "file": "REST_JiraEcosystem_issues",
      "result": ["... Dify document and metadata responses ..."],
      "issues_ingested": 23
    }
  ],
  "errors": []
}

The exact Dify response objects inside results[0].result vary by server version. Treat the request as successful only when success is true, files_processed is 1, files_failed is 0, and errors is empty.

4.2: Verify in Dify Knowledge Base

Navigate to your Dify instance and check the Knowledge section. You should see your newly created knowledge base!

Confirm that:

• the Jira_API_Basic_* knowledge base exists and all 23 documents finish indexing;
• built-in metadata is enabled and the custom issue_key field is attached to issue documents; and
• the descriptive smoke query REST-266 Default Jackson configuration unknown properties returns REST-266 at rank 1.

Do not accept the API response as proof that indexing finished. This API currently creates one dataset per run and submits the documents, but it does not poll every document to a terminal indexing state or make reruns idempotent. Verify all 23 document states in Dify and avoid repeating the ingestion call unless you intentionally want another dataset.

Knowledge base created via API (click to expand)

Dataset configuration (click to expand)

🎉 Success! Your Knowledge Base is Ready

Your Jira issues have been successfully ingested with structured metadata!

After the knowledge-base and retrieval checks pass, return to Dify's Knowledge API settings and revoke the short-lived key. Do not retain the key in workshop notes, terminal history, screenshots, or source control. The verified 1.16.1 run returned success: true, processed one file with no failures, created 23 issue documents, and revoked the key immediately after verification.

---

🧠 Step 5: Add Summary Index new

Dify 1.12 introduced Summary Index. It generates a compact LLM summary for each chunk and embeds that summary as another retrieval surface. This can make requirements, risks, and test implications easier to find when the original Jira wording differs from the learner's question.

1. Open the API-ingested knowledge base and go to Settings.
2. Keep High Quality indexing and enable Summary Auto-Gen.
3. Select gpt-35-turbo-16k.
4. Instruct the model to preserve the Jira key, summary, status, requirements, risks, acceptance criteria, test implications, and constraints without inventing facts.
5. Save the settings. Summary Auto-Gen applies to newly indexed content; for the 23 existing documents, select all documents and choose Generate summary.

Inspect at least one generated summary before trusting it. For REST-266, confirm that the backward-compatibility constraint remains explicit. Generated test implications are useful retrieval hints, but they are model output, not new Jira requirements.

---

🎛️ Step 6: Tune and Benchmark Retrieval changed

Configure Hybrid Search with weighted retrieval:

• semantic weight: 0.3;
• keyword weight: 0.7;
• Top K: 10; and
• score threshold: 0.05.

Run this fixed acceptance suite in Retrieval Testing before tuning further:

Query	Expected evidence
REST-266 Default Jackson configuration unknown properties	REST-266 at rank 1
Which issue creates a backward-compatibility risk when unknown JSON properties are accepted?	REST-266 at rank 1
Which Jira work has important test implications for REST API compatibility?	REST-266 in the top 3
Why is the sky blue?	No retrieved chunks

Hybrid search does not replace metadata filtering. Conceptual Jira questions benefit from summaries and semantic retrieval, while exact identifiers such as REST-265 should be extracted and applied as an issue_key filter. Exercise 3 establishes the grounded baseline; Exercise 4 adds the extractor and exact-key retrieval paths.

---

📚 Step 7: Compare Knowledge Base Approaches changed

🔬 Understanding the Differences

In this exercise, you will work with three knowledge bases in Dify:

📄 Manual Ingestion

Created by uploading .txt files manually. Simple but limited structure and no metadata.

🔧 Basic API Ingestion

API-based knowledge base with structured data. Useful for simple lookups and basic retrieval.

🚀 Advanced API Ingestion

Enhanced with query seeding and aliases. Better understanding of user intents and synonyms.

💡 Key Differences:

• Manual: Raw text files, limited structure, no metadata
• Basic API: Structured data with metadata (issue keys, project info)
• Advanced API: Query seeding + aliases for better retrieval and understanding

🧪 Test These Queries on All Three Knowledge Bases:

• 👉 What is this issue about: Jira Issue: REST-259?
• 👉 Give a test plan for REST-266
• 👉 Who is the assignee for REST-266?
• 👉 Summarize the technical documentation for the REST module.

Record rank, source, score, and no-match behavior rather than judging only how plausible a result looks.

Comparing query results (click to expand)

Advanced query comparison (click to expand)

🧠 Pro Tip: After uploading, go to Retrieval testing in Dify and try the queries above. Compare the answers you get from each knowledge base. Structured data and advanced techniques enable smarter, more accurate answers!

---

🔍 What Happens Behind the Scenes?

🔬 Technical Details

When you ingest Jira issues via the API, here's what happens:

• Each issue is converted into a descriptive document with summary, description, project, type, etc.
• Smart chunking ensures readable chunks with overlap for better search coverage
• Metadata (like issue_key) is attached to each chunk, improving traceability
• Documents are vectorized and indexed in your Dify knowledge base

---

⏱️ Why We Do Not Add a Trigger Yet new

Dify 1.10 added schedule and webhook triggers for Workflow applications. They could eventually synchronize Jira automatically, but the deployed ingestion API creates a new random dataset on every run, does not update by stable source identity, and does not wait for indexing to finish. Scheduling that behavior would create silent duplicates faster.

Adopt a trigger only after the ingestion owner adds idempotent create/update behavior, terminal indexing checks, bounded retries, and observable partial failures. Until then, the deliberate one-shot call in this exercise is safer and easier to audit.

---

🔧 Advanced: Deploy Your Own API (Optional)

🚀 Deploy Your Own API Instance

If you want to deploy your own version of the API or understand how it works under the hood:

1. Visit https://github.com/bassagap/dify_jira and create a Codespace on the main branch
2. Follow the setup instructions to deploy your own instance
3. This gives you full control over the API and allows customization

Note: This is optional and only needed if you want to customize the API or understand the implementation details.

---

🎯 Exercise Complete! What's Next? changed

🎉 Congratulations!

You've successfully ingested Jira issues using the API!

✅ What You've Accomplished:

• ✅ Connected to the Jira ingestion API
• ✅ Explored available projects using Swagger UI
• ✅ Ingested structured Jira issues with metadata
• ✅ Compared different knowledge base approaches
• ✅ Generated and reviewed Summary Index content
• ✅ Passed a fixed positive and no-match retrieval benchmark

🚀 Ready for the Next Challenge?

This deployed API is a great next step if you want to:

• 🤖 Automate ingestion in your organization
• 🔗 Connect to real Jira projects
• 🧪 Test richer search results with structured metadata
• 📊 Compare manual vs. API-based knowledge bases