@partnersync/promapp-parser

Minimal parser for Nintex Process Manager (Promapp) XML exports with a compact storage format.

Features

• 🎯 Focused Scope - Just parsing, serialization, and validation
• 📦 Small Package - Minimal dependencies (jsdom, commander)
• 🔧 Simple API - Clear, predictable methods
• 📄 Nintex Format - Compact, human-readable storage format
• 🔄 Round-trip Support - Parse XML → Nintex format → Parse back with perfect fidelity
• ✅ Content Validation - Detect and fix structural issues

Why Use This Package?

If you're working with Nintex Process Manager (Promapp) exports, this package helps you:

• Convert XML exports to human-readable formats
• Extract specific processes or activities programmatically
• Clean up formatting inconsistencies in exported content
• Build tools that analyze or transform process documentation

Unlike full Promapp API integrations, this package works with static exports and requires no authentication or API access.

Installation

# npm
npm install @partnersync/promapp-parser

# yarn
yarn add @partnersync/promapp-parser

# pnpm
pnpm add @partnersync/promapp-parser

Requirements: Node.js >= 16.0.0
Dependencies: jsdom (XML parsing), commander (CLI)

Quick Start

import { Parser } from '@partnersync/promapp-parser';

const parser = new Parser();

// Parse any Promapp XML file
const result = parser.parse(xmlString);

// Parse and convert to Nintex format
const nintexOutput = parser.parse(xmlString, { format: 'nintex' });

// Parse, validate, and fix issues
const cleaned = parser.parse(xmlString, { validate: true, fix: true });

Command Line Usage

# Quick conversion
npx @partnersync/promapp-parser process.xml --format nintex

# Install globally for repeated use
npm install -g @partnersync/promapp-parser
promapp-parser process.xml --format nintex

# Common operations
promapp-parser export.xml                    # View JSON structure
promapp-parser export.xml --format nintex    # Convert to Nintex format
promapp-parser export.xml --validate --fix   # Clean up formatting issues
promapp-parser structure.xml --no-content    # Structure only
promapp-parser procedures.xml --no-structure # Content only

# Help and version
promapp-parser --help                        # Show help message
promapp-parser --version                     # Show version number

Common Use Cases

Working with Process Groups (Full Exports)

import { Parser } from '@partnersync/promapp-parser';

const parser = new Parser();
const result = parser.parse(processGroupXml);

// Access structure
console.log(result.structure.rootGroup.name);
console.log(result.structure.totalProcesses);

// Access content by process ID
const processContent = result.content['process-123'];
console.log(processContent.activities);

Working with Individual Procedures

const result = parser.parse(proceduresXml);

// Direct access to activities
result.content.activities.forEach(activity => {
  console.log(activity.text);
  activity.children.forEach(element => {
    console.log(`${element.type}: ${element.text}`);
  });
});

Converting to Nintex Format

// Convert entire export
const nintexOutput = parser.parse(xmlString, { format: 'nintex' });

// Or use the serializer directly
import { NintexSerializer } from '@partnersync/promapp-parser';

const serializer = new NintexSerializer();
const nintexText = serializer.toNintex(parsedContent);

Validating and Fixing Content

import { ContentValidator } from '@partnersync/promapp-parser';

const validator = new ContentValidator();

// Check for issues
const result = validator.validate(content);
if (!result.isValid) {
  console.log('Issues found:', result.issues);
}

// Auto-fix common issues
const fixed = validator.fix(content);

Nintex Format

A compact, readable format for process documentation:

# Receive Purchase Order
## T.1: Validate PO details
## T.2: Check inventory levels
### N: Contact warehouse if stock is low
#### U: Email warehouse manager
#### U: Update inventory system
## T.3: Process order
### O[1]: Enter into system
### O[2]: Generate confirmation
### O[3]: Send to customer

Format Rules

• # = Activity (one per process step)
• ## = Element with type prefix (T=task, N=note, F=form, W=weblink)
• ###+ = Nested content with increasing depth
• Numbers after type indicate sequence (e.g., T.1, T.2)
• Lists: O[1.1] (ordered with original number), U (unordered)

API Reference

Main Parser

const parser = new Parser();
parser.parse(xml: string, options?: ParseOptions): any

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | format | 'json' | 'nintex' | 'json' | Output format | | validate | boolean | false | Run validation checks | | fix | boolean | false | Auto-fix validation issues | | structure | boolean | true | Parse document structure | | content | boolean | true | Parse document content |

Component APIs

For advanced usage, you can use components directly:

• StructureParser - Parse process hierarchy
• ContentParser - Parse procedures and activities
• NintexSerializer - Convert to/from Nintex format
• ContentValidator - Validate and fix content

See TypeScript definitions for detailed type information.

Formatting & Normalization

The parser applies consistent formatting rules to ensure clean, predictable output while preserving content meaning:

Whitespace Handling

• Trailing whitespace: Removed from all text content during XML parsing
• Leading whitespace: Preserved exactly as-is (important for indented content)
• Internal whitespace: Preserved within text content
• NBSP characters: Converted to regular spaces for consistency

Structural Transformations

• Element numbering: Cleaned automatically (e.g., "1.0.1" → "1.1")
• Note embedding: Notes immediately following tasks are embedded as attachments
• List detection: Numbered and bulleted lists are automatically detected and formatted with appropriate depth markers

Nintex Format Specifics

• Round-trip fidelity: All content and formatting can be perfectly reconstructed
• Spacing preservation: Exact spacing in element headers is maintained (e.g., ## N: Text with two spaces)
• Depth markers: List items and nested content use # symbols to indicate depth levels
• List formatting:
  • Ordered: O[1.1] preserves original numbering
  • Unordered: U for any bullet style (-, *, •, ·)

When to Use the Validator

The ContentValidator is designed to detect and fix structural issues that may arise from formatting:

• Orphaned indented content (content starting at deep indentation without parent headers)
• Invalid numbering sequences in lists
• Excessive indentation beyond configured maximum depth

These normalization rules ensure consistent output while maintaining the semantic meaning of your process documentation.

Philosophy

This package follows a "minimal but complete" approach - providing just the tools needed to parse, transform, and validate Promapp exports without unnecessary complexity.

The parser prioritizes content fidelity while normalizing formatting for consistency. See the Formatting & Normalization section for specific rules.

Contributing

We welcome contributions! This package is intentionally minimal - please discuss feature additions in an issue before submitting PRs.

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Clean
npm run clean

Commit Style

We use Conventional Commits. For consistency, we prefer lowercase descriptions:

✅ feat: add user authentication
✅ fix: resolve memory leak in parser
❌ feat: Add user authentication

However, we won't block PRs over capitalization - we focus on what matters:

• Valid type prefix (feat/fix/chore/etc.)
• Meaningful descriptions
• Proper scope when needed
• Breaking change indicators

See CONTRIBUTING.md for full guidelines.

License

MIT - see LICENSE for details.