@partnersync/promapp-xml-parsers NPM

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:

Core Structure Parser - Extracts hierarchical organization, metadata, and process relationships
Text Content Parser - Processes activity text and attachments with |~| delimiter support
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 git@github.com: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

Modular architecture - Separate parsing, formatting, and rendering
Type safety - Full TypeScript with strict typing and discriminated unions
Const assertion patterns - For type-safe enums
Graceful degradation - Handle missing elements safely
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