Work Order Approval

Overview

📤 Direction: Zudello → Zavanti
⚡ Sync Type: Real-time
🎯 Purpose: Update maintenance tasks with financial approval status and dates

Work order approval data flows from Zudello to Zavanti to update maintenance tasks with financial approval status and dates using real-time processing.

Approval Features

✅ Real-time Processing - Immediate approval status updates upon transaction approval
✅ Simple Payload - Minimal data update focusing on approval status
✅ Audit Trail - Clear approval timestamp for compliance
✅ Status Integration - Links Zudello approval workflow to Zavanti status

API Configuration

Endpoint: /api/data/v9.2/zav_maintenancetasks({external_id})
Method: PATCH
Authentication: Zavanti universal authentication

URL Structure

The endpoint uses the external_id from the original work order to target the specific maintenance task:

• Pattern: /api/data/v9.2/zav_maintenancetasks({external_id})
• Example: /api/data/v9.2/zav_maintenancetasks(12345678-1234-1234-1234-123456789012)

Field Mappings

Zavanti Field	Zudello Source	Data Type	Notes
zav_financesystemapproval	N/A	Boolean	Always true
zav_financesystemapprovaldate	Current date	Date	YYYY-MM-DD format

Processing Logic

Trigger Conditions

The approval process is activated when:

• Transaction Status Change: Zudello transaction status changes to approved
• External ID Present: Transaction has valid external_id reference
• Work Order Type: Transaction is classified as work order type

Processing Steps

1. Trigger Activation

Transaction Approval → Approval Workflow Triggered

2. External ID Extraction

• Source: Uses external_id field from Zudello transaction
• Validation: Ensures external_id exists and is valid GUID format
• Error Handling: Logs error and exits if external_id not found

3. Date Generation

• Method: Uses current date via moment().format("YYYY-MM-DD")
• Format: YYYY-MM-DD (ISO date format)
• Timezone: Uses system timezone for consistency

4. Update Request

• HTTP Method: PATCH request to specific maintenance task
• Payload: Minimal JSON with approval fields only
• Response: Validates successful update response

Payload Structure

The approval update sends a minimal payload:

{
  "zav_financesystemapproval": true,
  "zav_financesystemapprovaldate": "2024-01-15"
}

Real-time Processing

Immediate Execution

• Trigger: Executes immediately when transaction is approved in Zudello
• Latency: Minimal delay between approval and Zavanti update
• Reliability: Direct API call ensures immediate status synchronization

Processing Benefits

• Instant Feedback: Maintenance teams see approval status immediately
• Workflow Continuity: Enables immediate progression to next workflow stage
• Audit Compliance: Real-time approval timestamps for compliance requirements
• Status Consistency: Maintains consistent approval status across systems

Error Handling

Validation Errors

• Missing External ID: Logs error and marks transaction as failed if external_id not found
• Invalid GUID Format: Validates external_id is proper GUID format
• API Authentication: Handles authentication failures with detailed error messages
• Response Validation: Checks response success status for confirmation

Processing Failures

• API Failures: Uses Zudello's failIf method to mark transaction as failed
• Network Issues: Handles connectivity problems with retry logic
• Zavanti Errors: Processes Zavanti-specific error responses
• Timeout Handling: Manages API timeout scenarios gracefully

Failure Recovery

• Transaction Marking: Failed transactions marked appropriately in Zudello
• Error Logging: Comprehensive error logging with context
• Retry Logic: Intelligent retry for transient errors
• Manual Resolution: Provides information for manual issue resolution

Use Cases

Approval Workflow Integration

• Financial Approval: Mark maintenance tasks as financially approved
• Workflow Progression: Enable next stage of maintenance workflow
• Compliance Tracking: Maintain audit trail of approval dates
• Status Synchronization: Keep approval status consistent across systems

Operational Benefits

• Real-time Updates: Immediate visibility of approval status
• Process Automation: Eliminate manual approval status updates
• Audit Trail: Automated creation of approval audit trail
• Workflow Efficiency: Streamlined approval-to-execution workflow

Compliance and Reporting

• Audit Requirements: Meet compliance requirements for approval documentation
• Timestamp Accuracy: Precise approval timestamps for reporting
• Status Tracking: Track approval status across maintenance operations
• Regulatory Compliance: Support regulatory compliance requirements

Integration Benefits

Workflow Automation

• Seamless Integration: Automatic approval status updates without manual intervention
• Real-time Processing: Immediate status synchronization between systems
• Error Reduction: Eliminates manual approval status entry errors
• Process Efficiency: Streamlined approval workflow

Data Integrity

• Consistent Status: Maintains consistent approval status across systems
• Accurate Timestamps: Precise approval date recording
• Audit Trail: Complete approval audit trail maintenance
• Reliable Updates: Ensures approval status updates are reliable

Configuration Requirements

Approval Setup

For successful work order approval processing:

• Ensure Zavanti universal authentication is configured
• Verify external_id is properly set on work order transactions
• Configure Zudello approval workflow to trigger Zavanti updates
• Set up appropriate error handling for failed approval updates
• Ensure network connectivity between Zudello and Zavanti systems

Troubleshooting

Issue	Cause	Solution
Approval not updating	Missing external_id	Verify work order has valid external_id
Authentication failures	Invalid credentials	Check Zavanti universal authentication setup
API timeout errors	Network connectivity	Check network connection and API availability
Date format issues	Incorrect date formatting	Verify date format is YYYY-MM-DD
Maintenance task not found	Invalid external_id	Ensure external_id matches existing maintenance task
Approval already set	Duplicate approval attempts	Check if approval was already processed
Permission errors	Insufficient API permissions	Verify API user has update permissions on maintenance tasks

Related Documentation

• Work Order - Work order creation and master data mapping
• Invoice Creation - Invoice processing workflow
• Overview - Integration architecture overview