Imported from gabrielmoreira/agent-skills-mirror (mirrors/repos/jeremylongshore@claude-code-plugins-plus-skills/skills/.curated/navan-migration-deep-dive/SKILL.md). Install upstream with npx skills add gabrielmoreira/agent-skills-mirror --skill navan-migration-deep-dive. Copyright stays with the author (MIT).

Navan Migration Deep Dive

Overview

End-to-end migration playbook for moving from SAP Concur or legacy travel management systems to Navan. Navan uses REST APIs with OAuth 2.0 — there is no SDK, no automated migration tool, and no sandbox for testing.

Prerequisites

• Admin access to both source system (SAP Concur, legacy TMC) and Navan
• Navan OAuth credentials from Admin > Travel admin > Settings > Integrations
• Data export from source system (expense reports, itineraries, user directory)
• SSO identity provider (Okta, Azure AD, Google Workspace) for user provisioning
• Executive sponsor and travel program manager identified

Instructions

Phase 1 — Discovery and Planning (Weeks 1-2)

Inventory current state:

Key decision: historical data strategy. Navan does not support importing historical booking or expense data. Export source system data to a data warehouse or archive storage for reference. Future Navan data starts fresh from migration day.

Phase 2 — User Provisioning (Weeks 2-3)

Option A — SCIM provisioning (recommended):

1. Configure SCIM connector in your IdP (Okta, Azure AD)
2. Map IdP groups to Navan roles: traveler, travel arranger, approver, admin
3. Enable provisioning — users are created in Navan automatically
4. Test with a pilot group (10-20 users) before full rollout

Option B — CSV bulk upload:

1. Export user directory from source system
2. Format per Navan's CSV template (available in Admin > User Management)
3. Upload via Navan admin console
4. Manually verify role assignments

Verify provisioned users via API:

TOKEN=$(curl -s -X POST "https://api.navan.com/ta-auth/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$NAVAN_CLIENT_ID&client_secret=$NAVAN_CLIENT_SECRET" \
  | jq -r '.access_token')

# Count provisioned users
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.navan.com/v1/users" \
  | jq '{total: (.data | length), sample: [.data[:3][] | {email, status}]}'

Phase 3 — Policy Recreation (Weeks 3-4)

Recreate travel policies in Navan admin console. Key policy areas:

1. Booking policies: Flight class limits (economy/business by route length), hotel rate caps by city, advance booking requirements
2. Approval workflows: Auto-approve under threshold, manager approval above, VP approval for international
3. Expense policies: Per diem rates, receipt requirements, out-of-policy flagging
4. Preferred vendors: Airline/hotel preferences, negotiated corporate rates, loyalty program linkage
5. Traveler profiles: Default seat preferences, meal requirements, loyalty numbers, passport info

SAP Concur policy mapping pitfalls:

• Concur's "travel rules" do not map 1:1 to Navan's policy engine — expect manual translation
• Concur custom fields require mapping to Navan's cost center / department / project structure
• Concur delegation rules differ from Navan's travel arranger model

Phase 4 — Parallel Running (Weeks 4-6)

Run both systems simultaneously to validate the migration:

# Monitor booking volume in Navan during parallel run
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.navan.com/v1/bookings?page=0&size=50&createdFrom=$(date -d '7 days ago' +%Y-%m-%d)" \
  | jq '{total_bookings: (.data | length)}'

Reconciliation checks:

• Compare booking counts between systems weekly
• Validate expense report totals match between systems
• Verify approval chains produce consistent outcomes
• Test edge cases: international travel, group bookings, last-minute changes

Phase 5 — Cutover (Week 6-7)

Go/no-go checklist (all must pass):

• All users provisioned and can log in via SSO
• Travel policies match source system intent (reviewed by travel manager)
• Pilot group has booked 20+ trips without issues
• Expense submission and approval tested end-to-end
• Corporate card feeds connected (if applicable)
• Navan API integration healthy (auth + data endpoints return 200)
• Fivetran/Airbyte data sync running for BOOKING and TRANSACTION tables
• Rollback procedure documented and tested
• User training materials distributed
• IT support team briefed on Navan admin and Ava AI assistant
• Source system read-only access preserved for historical lookups

Cutover steps:

1. Send company-wide communication (24 hours before)
2. Disable new bookings in source system
3. Enable Navan SSO for all users
4. Activate all Navan travel policies
5. Switch corporate card feeds to Navan
6. Verify first production bookings succeed
7. Monitor error rates for 48 hours

Phase 6 — Post-Migration (Weeks 7-10)

• Monitor Navan API health daily for first two weeks
• Track user adoption metrics (login rate, booking volume, Ava usage)
• Collect feedback from frequent travelers and approvers
• Maintain source system in read-only mode for 90 days (historical reference)
• Decommission source system after retention period

Output

• Migration project plan with phase timelines and owners
• Data mapping document (source fields to Navan structure)
• User provisioning report showing successful account creation
• Parallel running reconciliation results
• Go/no-go checklist with sign-offs
• Post-migration adoption metrics

Error Handling

Examples

Quick migration readiness assessment:

# Verify Navan API access and user count
echo "=== Migration Readiness Check ==="
TOKEN=$(curl -s -X POST "https://api.navan.com/ta-auth/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$NAVAN_CLIENT_ID&client_secret=$NAVAN_CLIENT_SECRET" \
  | jq -r '.access_token')

echo "API Auth: $([ -n "$TOKEN" ] && echo 'OK' || echo 'FAILED')"
USERS=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.navan.com/v1/users" | jq '.data | length')
echo "Provisioned users: $USERS"
BOOKINGS=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.navan.com/v1/bookings?page=0&size=50" | jq '.data | length')
echo "Total bookings: $BOOKINGS"

Resources

• Navan Help Center — Admin setup guides and migration support
• Navan Integrations — ERP and data connector options
• Navan Security — SOC 2, ISO 27001, GDPR compliance for vendor evaluation

Next Steps

• Use navan-install-auth to set up OAuth credentials for the migration
• Use navan-prod-checklist before cutover to validate production readiness
• Use navan-data-sync to configure Fivetran/Airbyte data pipelines