Skip to content

Home

Jump to bottom
Fuuz Documentation Team edited this page Jun 7, 2026 · 2 revisions

Confluence Data Model Documentation V1.0.0

Article Type: Concept / Integration Package Overview Audience: Application Designers, Solution Architects, Technical Writers, DevOps Engineers Module: Documentation / Confluence Applies to Versions: 2023.10.0+

1. Overview

The Confluence Data Model Documentation package enables automatic generation and synchronization of technical documentation from Fuuz data models directly into Atlassian Confluence. This package exemplifies the principle of self-documenting solutions — where the system itself generates and maintains its own documentation, ensuring accuracy and eliminating the manual burden of keeping documentation in sync with application changes.

By integrating Fuuz with Confluence, organizations can maintain a living documentation system that automatically reflects the current state of their industrial applications. Documentation is created under a structured hierarchy with a parent "Data Models" page, and each data model receives its own child page prefixed with "Data Model:" for consistent organization.

Note: This package requires an active Atlassian Confluence Cloud subscription and a configured Confluence connection in Fuuz. The integration uses the Confluence REST API to create and update pages programmatically.

Note: The original KB article includes the package attachment ConfluenceDataModelDocumentation1001.fuuz. Download it from the original article on support.fuuz.com; it must be re-attached or linked in this repo.

2. Architecture & Components

Key Definitions

  • Self-Documenting Solution: An application architecture pattern where the system automatically generates and maintains its own documentation based on metadata, configurations, and runtime information.
  • Confluence Space: A container in Atlassian Confluence for organizing related pages. Each Fuuz application typically maps to one Confluence space.
  • Space ID: A unique numeric identifier for a Confluence space, required for API operations.
  • Data Model: A Fuuz schema definition that describes the structure of data entities, including fields, types, relationships, and validation rules.
  • Application Configuration: A Fuuz component that stores configurable settings for integrations, allowing connection and space information to be managed without code changes.

Package Components

Component Type Count Description
Screens 1 Data Model Documenter interface for selecting models to document
Data Flows 2 Page retrieval and documentation generation flows
Module Group 1 Documentation module group for organizing related screens
Module 1 Confluence module for categorizing documentation features
Application Configuration 1 Settings for Confluence connection and space configuration

Data Flow Details

Data Flow Nodes Description
Get Pages in Confluence Space 8 Retrieves existing pages from Confluence space with pagination support
Generate Confluence Data Model Documentation 21 Main flow that queries data models and creates/updates Confluence pages

How It Works

  1. Query Data Models: The flow retrieves selected data model metadata from Fuuz including fields, types, relationships, and descriptions
  2. Check Existing Pages: The Get Pages flow retrieves current pages in the Confluence space to determine if pages need to be created or updated
  3. Create Parent Page: If the "Data Models" parent page doesn't exist, it is created as the container for all model documentation
  4. Format Documentation: Data model information is transformed into structured Confluence markup with tables, field descriptions, and relationship diagrams
  5. Create/Update Pages: Individual pages are created or updated for each data model using the Confluence REST API

3. Use Cases

Data Model Documentation

The primary use case is automatic generation of data model documentation. Each documented page includes field names, data types, descriptions, validation rules, and relationships to other models. This ensures developers and stakeholders always have access to current schema information without manual documentation maintenance.

Compliance & Audit Documentation

Manufacturing environments often require documented system specifications for regulatory compliance (FDA 21 CFR Part 11, ISO standards). Automated documentation generation provides traceable, versioned records of system configuration that can be referenced during audits. Schedule the documentation flow to run after deployments to capture configuration changes.

Onboarding & Training

New team members can quickly understand the application's data architecture by browsing the automatically generated Confluence pages. The structured hierarchy (Data Models → Individual Models) provides an intuitive navigation experience for learning the system.

Change Management

When data models are modified, running the documentation flow updates Confluence pages automatically. Combined with Confluence's built-in version history, this creates an audit trail of schema changes over time without any manual effort.

4. Self-Documenting Solutions Strategy

This package demonstrates a foundational pattern for self-documenting solutions. The same approach can be extended to document screens, data flows, integrations, and more. Below are strategies for building comprehensive self-documenting Fuuz applications.

Extending to Other Components

The pattern used for Data Models can be replicated for other Fuuz components:

Component Documentation Content Query Source
Screens Route paths, components, user permissions, linked data models Screen, ScreenVersion, Route
Data Flows Node sequences, triggers, integrations, business logic descriptions DataFlow, DataFlowVersion
Data Mappings Source/target systems, field mappings, transformation rules DataMapping, DataMappingVersion
Connections Connector types, endpoint configurations, credential references Connection, Connector
Roles & Permissions Access control policies, role definitions, screen/data access Role, AccessControlPolicy
Schedules Cron expressions, triggered flows, shift configurations Schedule, DataFlowSchedule

Recommended Documentation Hierarchy

Organize your Confluence space with a consistent structure for comprehensive solution documentation:

[Application Name] Space
├── Overview
│   ├── Application Description
│   ├── Architecture Diagram
│   └── Getting Started Guide
├── Data Models
│   ├── Data Model: Product
│   ├── Data Model: Workcenter
│   └── Data Model: ProductionRun
├── Screens
│   ├── Screen: Plant Dashboard
│   ├── Screen: Workcenter Control Panel
│   └── Screen: Production History
├── Data Flows
│   ├── Flow: Calculate OEE
│   ├── Flow: IOT Tag Handler
│   └── Flow: Record Production
├── Integrations
│   ├── Integration: Plex ODBC
│   ├── Integration: SAP RFC
│   └── Integration: OPC-UA Gateway
├── Work Instructions
│   ├── WI: Starting a Production Run
│   ├── WI: Recording Downtime
│   └── WI: Shift Handoff Procedure
├── Troubleshooting Guides
│   ├── TS: Connection Failures
│   ├── TS: Data Flow Errors
│   └── TS: Missing Production Data
└── Deployment Guide
    ├── Prerequisites
    ├── Installation Steps
    └── Configuration Checklist

5. Advanced Documentation with MCP & LLMs

For advanced documentation scenarios, Fuuz's integration capabilities can be combined with Model Context Protocol (MCP) servers and Large Language Models (LLMs) to generate intelligent, context-aware documentation that goes beyond simple metadata extraction.

MCP Integration Architecture

The Model Context Protocol (MCP) enables bidirectional communication between Fuuz and AI systems. Using MCP servers like the Atlassian MCP connector, you can create sophisticated documentation workflows:

  • Atlassian MCP Server: Direct integration with Confluence for page creation, search, and updates via AI assistants
  • Fuuz API Access: Query data models, screen definitions, and flow configurations programmatically
  • LLM Processing: Transform raw metadata into human-readable documentation with context and explanations

LLM-Powered Work Instructions

Generate comprehensive work instructions by combining screen metadata with LLM capabilities:

Example Workflow:

  1. Query Screen and Route metadata for a specific workflow (e.g., "Record Production")
  2. Extract form fields, actions, validations, and navigation paths
  3. Pass metadata to an LLM with a prompt template for work instruction generation
  4. LLM generates step-by-step instructions with field descriptions, expected values, and tips
  5. Publish to Confluence under "Work Instructions" hierarchy

Sample LLM Prompt Template:

Generate a work instruction document for the following Fuuz screen:

Screen Name: {{screenName}}
Route: {{routePath}}
Purpose: {{screenDescription}}

Form Fields:
{{#each formFields}}
- {{name}} ({{type}}): {{description}}
  Required: {{required}}
  Validation: {{validation}}
{{/each}}

Actions Available:
{{#each actions}}
- {{title}}: {{description}}
{{/each}}

Please create:
1. A brief overview of when to use this screen
2. Step-by-step instructions for completing the workflow
3. Field-by-field guidance with expected values
4. Common mistakes to avoid
5. Related screens or next steps

LLM-Powered Troubleshooting Guides

Generate intelligent troubleshooting documentation by analyzing data flow configurations and error patterns:

Example Workflow:

  1. Query DataFlow and DataFlowVersion for target flow (e.g., "Plex ODBC Import")
  2. Extract node types, integrations, error handling, and retry configurations
  3. Query DataFlowExecutionMetric and DataFlowDeploymentLog for common error patterns
  4. Pass configuration and error data to LLM for troubleshooting guide generation
  5. LLM generates issue/cause/resolution tables with step-by-step diagnostic procedures
  6. Publish to Confluence under "Troubleshooting Guides" hierarchy

Sample LLM Prompt Template:

Generate a troubleshooting guide for the following Fuuz data flow:

Flow Name: {{flowName}}
Type: {{flowType}}
Description: {{flowDescription}}

Integration Nodes:
{{#each integrationNodes}}
- {{name}}: Connects to {{connectionType}}
  Retry Config: {{retryConfig}}
  Error Handling: {{errorHandling}}
{{/each}}

Recent Error Patterns (from execution logs):
{{#each errorPatterns}}
- Error: {{errorMessage}}
  Frequency: {{count}} occurrences
  Last Seen: {{lastOccurrence}}
{{/each}}

Please create a troubleshooting guide with:
1. Common issues table (Issue | Possible Cause | Resolution)
2. Diagnostic steps for each integration point
3. Log locations and what to look for
4. Escalation procedures
5. Preventive measures and monitoring recommendations

LLM-Powered Deployment Guides

Generate deployment documentation by analyzing package contents and dependencies:

Example Workflow:

  1. Parse PackageDefinition and InstalledPackage metadata
  2. Extract dependencies, data models, screens, flows, and configurations
  3. Query Connection and Connector requirements
  4. Pass package manifest to LLM for deployment guide generation
  5. LLM generates prerequisites checklist, installation steps, post-install verification
  6. Publish to Confluence under "Deployment Guide" hierarchy

Sample LLM Prompt Template:

Generate a deployment guide for the following Fuuz package:

Package Name: {{packageName}}
Version: {{version}}
Platform Version Required: {{platformVersion}}

Components Included:
- Data Models: {{dataModelCount}} ({{dataModelNames}})
- Screens: {{screenCount}} ({{screenNames}})
- Data Flows: {{flowCount}} ({{flowNames}})
- Configurations: {{configCount}}

Dependencies:
{{#each dependencies}}
- {{packageName}}: {{versionRequired}}
{{/each}}

Required Connections:
{{#each requiredConnections}}
- {{connectorType}}: {{purpose}}
{{/each}}

Please create a deployment guide with:
1. Prerequisites checklist (platform version, dependencies, connections)
2. Pre-installation verification steps
3. Step-by-step installation procedure
4. Post-installation configuration (connections, application settings)
5. Verification/testing checklist
6. Rollback procedure

Implementation Options

Approach Implementation Best For
Fuuz Data Flow + OpenAI/Anthropic API Create a data flow with integrateV2 node calling LLM API, then Confluence API Scheduled batch documentation generation
Claude + Atlassian MCP Use Claude with connected Atlassian MCP server to query Fuuz and create Confluence pages Interactive documentation sessions, ad-hoc requests
Claude + Fuuz Project Knowledge Load Fuuz metadata files into Claude project, generate documentation on demand Development-time documentation, package KB articles
Hybrid: Fuuz Flow + Claude Artifacts Flow extracts metadata, Claude generates rich HTML, flow publishes to Confluence High-quality formatted documentation with diagrams

Important: When using LLMs for documentation generation, always review generated content before publishing. LLMs may hallucinate details not present in the source metadata. Establish a review workflow where generated documentation is validated by subject matter experts before becoming official.

6. Screen Details

Confluence Data Model Documenter

Route: /system/confluence/documentation/dataModels

Module: Documentation → Confluence

This screen provides an interface for selecting data models and triggering documentation generation. Users can filter by ID or Module to find specific models, select multiple models for batch documentation, and execute the generation flow.

Screen Components:

  • Filter Form: Search by Data Model ID or Module
  • Data Model Table: Displays available data models with selection capability
  • Flow Button: Triggers the Generate Confluence Data Model Documentation flow

Table Columns:

Column Description
ID Unique identifier of the data model
Name Display name of the data model
Description Brief description of the data model's purpose
Module The module group the data model belongs to

7. Technical Details

Application Configuration

The package includes an Application Configuration record (confluenceDocumentationIntegration) with the following configurable settings:

Setting Type Required Description
Confluence Connection Combobox Yes Select from configured Confluence connections
Space ID Integer Yes Numeric ID of the Confluence space for documentation
Application Description Markdown No Optional description included on the Data Models parent page

Confluence API Integration

The package uses the Confluence REST API v2 with the following operations:

  • GET /wiki/api/v2/pages: List pages in a space with pagination
  • POST /wiki/api/v2/pages: Create new documentation pages
  • PUT /wiki/api/v2/pages/{id}: Update existing pages with new content

Page Naming Convention

Confluence requires unique page names within a space. The package uses the following conventions:

  • Parent Page: "Data Models"
  • Child Pages: "Data Model: {ModelName}" (e.g., "Data Model: Product")

Integration Caveats

Important Limitations:

  • You cannot archive pages programmatically as there is no way to un-archive via the Confluence API. Delete pages you no longer want instead.
  • Each page must have a unique name within the space. The "Data Model:" prefix ensures uniqueness for model documentation.
  • Page updates increment the version number automatically. Confluence maintains version history for audit purposes.

8. Implementation Approach

Prerequisites

  • Atlassian Confluence Cloud subscription with API access
  • Confluence API token generated for authentication
  • Fuuz Confluence connector configured with valid credentials
  • A Confluence space created for application documentation
  • App Admin or Developer access type to install packages

Phase 1: Installation

  1. Open the Fuuz Package Manager
  2. Upload the Confluence Data Model Documentation package (.fuuz file)
  3. Complete the installation process
  4. Verify the Documentation module group and Confluence module appear in navigation

Phase 2: Connection Setup

  1. Open the Connections list in Fuuz administration
  2. Create a new Confluence connection using the Confluence connector
  3. Configure the connection with your Atlassian domain and API token
  4. Test the connection to verify authentication

Phase 3: Configuration

  1. Open the Application Configurations list
  2. Find the "Confluence Documentation Integration" configuration
  3. Select your Confluence connection from the dropdown
  4. Enter your Confluence Space ID (found in space settings or URL)
  5. Optionally add an Application Description for the parent page
  6. Save the configuration

Phase 4: Generate Documentation

  1. Open the Data Model Documenter screen (Documentation → Confluence)
  2. Filter data models by ID or Module if desired
  3. Select the data models to document (or select all)
  4. Click the Generate Documentation flow button
  5. Verify pages appear in your Confluence space

Phase 5: Schedule (Optional)

  1. Create a Data Flow Schedule for the Generate Confluence Data Model Documentation flow
  2. Configure timing (e.g., daily, weekly, or after deployments)
  3. Documentation will automatically stay in sync with data model changes

9. Extensibility

The Confluence Data Model Documentation package provides a foundation that can be significantly extended:

Documentation Extensions

  • Screen Documentation: Clone the flow pattern to document screens with route information, components, and permissions
  • Data Flow Documentation: Generate documentation for data flows including node diagrams and integration details
  • API Documentation: Document GraphQL queries and mutations available for each data model
  • Release Notes: Automatically generate release notes from package version changes
  • ERD Generation: Create entity-relationship diagrams from data model relationships

LLM Enhancement Extensions

  • Intelligent Descriptions: Use LLMs to generate human-readable field descriptions from technical names
  • Usage Examples: Generate sample queries and data examples for each model
  • Cross-Reference Analysis: Identify and document relationships between models automatically
  • Change Summaries: Generate natural language summaries of model changes between versions

Integration Extensions

  • SharePoint: Adapt the pattern for Microsoft SharePoint documentation
  • Notion: Create a Notion connector for modern documentation platforms
  • GitBook: Generate documentation in GitBook-compatible markdown
  • PDF Export: Combine with Document Designer to generate PDF documentation packages

10. Troubleshooting

Issue Possible Cause Resolution
No connections in configuration Confluence connection not created Create a Confluence connection in Connection management
Authentication error Invalid API token or expired credentials Generate a new API token in Atlassian account settings
Space not found error Incorrect Space ID configured Verify Space ID in Confluence space settings or API
Page name conflict Page with same name exists outside hierarchy Rename or delete conflicting pages in Confluence
No data models displayed Filter criteria too restrictive Clear filters or broaden search criteria
Flow execution timeout Too many models selected at once Process models in smaller batches or schedule flow
Permission denied API token lacks space edit permissions Verify API token user has edit access to target space

11. Resources

12. Revision History

Version Date Editor Description
1.0 2025-01-24 Fuuz Documentation Team Initial release documenting Confluence Data Model Documentation v1.0.0 with expanded self-documenting solutions guidance and MCP/LLM integration patterns

See Also

Source: support.fuuz.com

This article was moved from the Fuuz Platform Help wiki to live alongside its package.

Clone this wiki locally