integrations

---

sidebar_position: 29 title: "PPM Integrations" description: "Connect ProBeya to external project management systems including MS Project, Oracle Primavera P6, Jira, Azure DevOps, and SAP PS for bidirectional data synchronization."

PPM Integrations

The PPM Integrations module bridges ProBeya with the external project management tools that organizations already use. Teams can import project schedules from MS Project XML files or Oracle Primavera P6 XER files, push ProBeya project data back to those systems, and configure live bidirectional sync with connected systems such as Jira, Azure DevOps, and SAP Project System.

Overview

Most transformation programs operate alongside existing scheduling and ALM tools. ProBeya's integration layer allows PPM data to flow in both directions: schedules, WBS structures, milestones, resources, and cost entries can be imported from external systems, and ProBeya project data can be exported back. The integration hub page at /{workspaceSlug}/portfolio/integrations presents all configured integrations as a card grid and provides an entry point to the setup wizard for new connections.

Integrations are managed as configuration records that store connection parameters, sync direction, field mappings, and scheduling rules. Each integration has its own sync history and a dead letter queue for entities that fail to sync, enabling targeted retry and resolution without re-running the entire sync.

Getting Started

1. Navigate to Portfolio > Integrations in the sidebar.
2. Click Add Integration to launch the setup wizard.
3. Select the connector type (MS Project, Primavera P6, Jira, Azure DevOps, SAP PS, or Custom).
4. Provide the connection configuration (URL, credentials, API keys as required by the system).
5. Click Test Connection to verify the credentials before saving.
6. Configure field mappings to define how external fields map to ProBeya fields.
7. Activate the integration. It starts inactive by default.
8. Click Sync Now to trigger an immediate manual sync, or wait for the scheduled sync.

Key Concepts

Connector Types

ProBeya supports the following connector types:

Connector Type	Description
ms_project	Import/export via MS Project XML (.mpp exported as XML)
primavera_p6	Import/export via Oracle Primavera P6 XER files
jira	Live sync with Jira projects and issues
ado	Live sync with Azure DevOps work items and plans
sap_ps	Integration with SAP Project System
oracle_ebs	Integration with Oracle E-Business Suite
servicenow	Integration with ServiceNow project records
salesforce	Integration with Salesforce opportunity/project data
m365	Integration with Microsoft 365 planner data
hr_system	Integration with HR systems for resource data
custom	Generic custom connector using configurable adapter

Sync Direction

Each integration is configured with one of three sync directions:

• Inbound: pull data from the external system into ProBeya. External records become the source of truth.
• Outbound: push ProBeya data to the external system. ProBeya is the source of truth.
• Bidirectional: pull then push, with conflict resolution applied when both sides have changes.

Field Mappings

Field mappings define how external system fields translate to ProBeya fields. Mappings are ordered by sortOrder and applied sequentially during sync. The field mapper (packages/api/src/lib/connectors/field-mapper.ts) supports value transforms (renaming, type coercion, enum mapping) in addition to simple field-to-field copies.

Dead Letter Queue

When an entity fails to sync — due to a mapping error, a validation failure, or an external system error — it is placed in the dead letter queue (DLQ) rather than aborting the entire sync. The DLQ records the entity type, ID, failure reason, and retry count. Admins can inspect DLQ entries, correct the underlying issue, and retry or manually resolve each entry.

Activation Lifecycle

New integrations start with isActive = false. The admin must:

1. Configure field mappings.
2. Test the connection successfully.
3. Explicitly activate the integration.

This prevents incomplete or untested integrations from triggering scheduled syncs. Deactivating ("deleting") an integration performs a soft delete — it sets isActive = false and preserves all sync logs, field mappings, and DLQ entries for audit purposes.

How It Works

MS Project Import

The MS Project importer (packages/api/src/lib/importers/msp-xml-importer.ts) parses MS Project XML exports to extract:

• Tasks mapped to WBS elements with their hierarchy, dates, duration, and constraints.
• Resources and assignments mapped to ProBeya resource records.
• Task dependencies (finish-to-start, start-to-start, finish-to-finish, start-to-finish) mapped to WBS dependencies.
• Project calendars and calendar exceptions.
• Baselines for earned value comparison.

An import preview (generateImportPreview) is available before committing changes, showing what will be created, updated, or skipped.

Oracle Primavera P6 Import

The P6 XER importer (packages/api/src/lib/importers/p6-xer-importer.ts) parses the proprietary XER tabular format to extract activities, WBS, relationships, resources, calendars, and baseline data. Predecessor types are mapped from P6 codes to ProBeya dependency types. Calendar data is decoded from P6's internal representation to standard working-days-per-week configuration.

Live Sync Flow

For live connectors (Jira, ADO, SAP PS), the triggerSync procedure orchestrates the following steps:

1. Create a sync log entry with status running.
2. Load field mappings for the integration.
3. Instantiate the connector and connect to the external system.
4. Based on syncDirection: pull from external or push to external (or both for bidirectional).
5. For each entity: apply field mappings, validate, and persist or push.
6. Entities that fail are enqueued to the dead letter queue.
7. Update the sync log with final counts (entitiesProcessed, entitiesCreated, entitiesUpdated, entitiesFailed).
8. Update the integration config's lastSyncAt and lastSyncStatus.

Export

MS Project XML and P6 XER exports are also supported. The generateMspXml and generateXerFile functions in packages/api/src/lib/exporters/ produce output files uploaded to S3 storage. A pre-signed download URL is returned to the client for direct download.

Configuration

Setting	Location	Description
Connector type	Setup wizard	The external system to connect to
Connection config	Setup wizard	System-specific credentials and endpoint configuration
Sync direction	Setup wizard	Inbound, outbound, or bidirectional
Sync schedule	Setup wizard	Cron expression for automated syncs (optional)
Conflict resolution	Setup wizard	How conflicts are resolved in bidirectional sync
Field mappings	Integration > Mappings tab	Source-to-target field transform rules
Is active	Integration > Actions	Toggle to enable or disable scheduled syncs

Permissions

• View integrations: PPM admin or integration manager role.
• Create integration config: PPM admin role.
• Edit connection config and field mappings: PPM admin role.
• Test connection: PPM admin role.
• Activate/deactivate integration: PPM admin role.
• Trigger manual sync: PPM admin or project manager role.
• View sync logs: PPM admin or project manager role.
• Manage dead letter queue: PPM admin role.

Tips & Best Practices

• Always test the connection before activating: the Test Connection button verifies credentials and reachability without touching production data. Activating an untested integration can cause sync failures that fill the DLQ.
• Start with inbound sync: if you are migrating from an existing system, configure inbound-only sync first to populate ProBeya, then add outbound once the data structure looks correct.
• Use the import preview for large MS Project files: large schedules can have hundreds of tasks. The preview step shows exactly what will change before committing, reducing the risk of unintended overwrites.
• Monitor the DLQ after each sync: a healthy integration should have zero or near-zero DLQ entries. Persistent DLQ entries indicate field mapping issues or external system schema changes that need attention.
• Set conflict resolution policy explicitly: for bidirectional syncs, the conflictResolution setting determines what happens when both systems have changed the same field. Choose source_wins, target_wins, or manual_review based on your team's workflow.

Scheduled vs. manual sync

For integrations with time-sensitive data (Jira sprints, ADO work items), configure a sync schedule using a cron expression. For file-based imports (MS Project, P6), manual sync triggered after each export from the source tool is usually more appropriate.

Sensitive connection credentials

Connection configurations including API keys, passwords, and OAuth tokens are stored in the connectionConfig JSONB field. Encryption of sensitive fields is enforced at the persistence layer. Never share integration config records directly — use the UI to manage credentials.

Related Features

• WBS & Schedules -- WBS elements and dependencies populated by MS Project and P6 imports
• Baselines -- Baseline data imported from external scheduling tools
• Timesheets -- Timesheet data that may be synchronized from external HR systems
• Capacity Plans -- Resource data synced from external systems feeds capacity planning
• Governance Framework -- Compliance audit trail includes integration sync activity