npm package: @partnersync/promapp-parser
Description: Minimal parsers for Nintex Process Manager (Promapp) XML exports
Author: Mark Wharton
Latest version: 0.2.0

# @partnersync/promapp-parser

[![npm version](https://img.shields.io/npm/v/@partnersync/promapp-parser.svg)](https://www.npmjs.com/package/@partnersync/promapp-parser)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@partnersync/promapp-parser.svg)](https://nodejs.org)

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

```bash
# 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

```typescript
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

```bash
# 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)

```typescript
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

```typescript
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

```typescript
// 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

```typescript
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
```typescript
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](./src/types/index.ts) 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](#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

```bash
# 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](https://www.conventionalcommits.org/). 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](CONTRIBUTING.md) for full guidelines.

## License

MIT - see [LICENSE](LICENSE) for details.