Promapp XML Parsers

TypeScript-based parsers for extracting and processing structured data from Nintex Process Manager (Promapp) XML exports. The toolkit provides comprehensive parsing and formatting capabilities for Promapp XML files.

🎯 Overview

This repository contains three specialized components:

1. Core Structure Parser - Extracts hierarchical organization, metadata, and process relationships
2. Text Content Parser - Processes activity text and attachments with |~| delimiter support
3. Activity Content Formatter - Transforms parsed content into formatted output with multiple renderers

Together, they provide comprehensive parsing and formatting of Promapp XML exports.

📦 Installation

npm install @partnersync/promapp-xml-parsers

Or clone and build locally:

git clone [email protected]:PartnerSync/promapp-xml-parsers.git
cd promapp-xml-parsers
npm install
npm run build

🚀 Usage

Core Structure Parser

Extracts the hierarchical structure and metadata from Promapp exports:

# Display hierarchical tree structure
npx promapp-parse-structure "Test Group.xml"

# Output as JSON
npx promapp-parse-structure "Test Group.xml" --json

Output includes:

• Process hierarchy with groups and subgroups
• Process metadata (ownership, state, version)
• Export configuration detection
• Activity counts

Text Content Parser

Parses the detailed text content within activities:

# Parse and display formatted text
npx promapp-parse-text "Test Group.xml"

# Output as JSON with parsed structure
npx promapp-parse-text "Test Group.xml" --json

# Parse individual ProcessProcedures fragment
npx promapp-parse-text --procedures procedures.xml

Features:

• Parses |~| delimited text into structured arrays
• Handles nested bullets, numbering, and indentation
• Preserves formatting including non-breaking spaces
• Supports Tasks, Notes, Forms, and WebLinks

Activity Content Formatter

Formats parsed content with intelligent structuring and multiple output options:

# Parse and format with different renderers
npx ts-node examples/parse-xml-file.ts "Test Group.xml"                    # Text output (default)
npx ts-node examples/parse-xml-file.ts "Test Group.xml" --format markdown  # Markdown output
npx ts-node examples/parse-xml-file.ts "Test Group.xml" --format html      # HTML output
npx ts-node examples/parse-xml-file.ts "Test Group.xml" --format json      # JSON output

Features:

• Contextual note embedding
• Automatic number cleaning (e.g., 1.0.1 → 1.1)
• List detection and formatting
• Depth management with configurable limits
• Multiple output formats

Programmatic Usage

import {
    PromappCoreStructureParser,
    PromappTextContentParser,
    formatActivityContent,
    renderAsText,
    renderAsMarkdown,
    renderAsHtml,
    renderAsJson
} from '@partnersync/promapp-xml-parsers';
import { JSDOM } from 'jsdom';

// Parse structure
const structureParser = new PromappCoreStructureParser();
const structure = structureParser.parse(xmlDocument);

// Parse text content
const textParser = new PromappTextContentParser();
const content = textParser.parse(processProceduresElement);

// Format and render
const formatted = formatActivityContent(content.activities);
const text = renderAsText(formatted);
const markdown = renderAsMarkdown(formatted);
const html = renderAsHtml(formatted);
const json = renderAsJson(formatted);

🛠 Architecture

Component Separation

The three components work together but maintain clear separation:

• Core Structure Parser: Focuses on XML hierarchy, counts, and metadata
• Text Content Parser: Handles the complex text formatting within activities
• Activity Content Formatter: Transforms parsed content into display-ready formats

This separation allows for:

• Clean, focused code
• Independent testing and maintenance
• Flexible integration options
• Multiple output formats

Key Design Principles

1. Modular architecture - Separate parsing, formatting, and rendering
2. Type safety - Full TypeScript with strict typing and discriminated unions
3. Const assertion patterns - For type-safe enums
4. Graceful degradation - Handle missing elements safely
5. Format once, render many - Efficient formatting with multiple outputs

📋 Features

Supported XML Structures

• Simple: Direct processes under root group
• Complex: Nested groups with process/group links
• Variable: Handles different export configurations

Export Types Detected

• Stub - Structure only, no content
• OneLevel - Single level with content
• Full - Complete recursive export

Text Formatting Support

• Line breaks via |~| delimiters
• Bullets: -, *, •
• Numbering: 1., 1.1, 2.
• Indentation preservation
• Non-breaking space handling

Output Formats

• Text: Clean, indented text output
• Markdown: GitHub-flavored markdown
• HTML: Semantic HTML with CSS classes
• JSON: Structured data format

🧪 Testing

Run tests for all components:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

🔗 Combined Usage

For complete XML processing, see the examples directory:

# Parse and display in different formats
npx ts-node examples/parse-xml-file.ts "Test Group.xml" --format text
npx ts-node examples/parse-xml-file.ts "Test Group.xml" --format markdown

# Run the combined parser example
npx ts-node examples/combined-parser.ts "Test Group.xml"

This provides:

• Hierarchical process group structure
• Process metadata (ownership, state, version)
• Detailed activity content with formatted text
• Multiple output format options

The complete pipeline:

1. Uses the core structure parser to build the hierarchy
2. Applies the text parser to extract content
3. Formats the content with the activity formatter
4. Renders in the desired output format

📚 Documentation

• Core Structure Parser - Detailed structure parser documentation
• Text Content Parser - Text parsing implementation details
• Activity Content Formatter - Formatting and rendering guide

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure all tests pass and follow the established patterns for new components.

📄 License

MIT - see LICENSE for details.

🙏 Acknowledgments

Built for parsing Nintex Process Manager (Promapp) XML exports. Nintex and Promapp are trademarks of Nintex Ltd.