Work Order

Overview

📥 Direction: Zavanti → Zudello
🔄 Sync Type: Incremental sync
📋 Entity: Maintenance tasks with line items and master data mapping

Maintenance task data flows from Zavanti to Zudello, creating purchase orders for work order management and approval processing. The integration includes comprehensive master data mapping and incremental synchronization.

Work Order Features

✅ Master Data Mapping - Intelligent mapping of suppliers, locations, and account codes
✅ Incremental Sync - Efficient processing using last modified timestamps
✅ Automatic Tax Calculation - 15% tax automatically calculated on work details
✅ Batch Processing - Sequential processing for data integrity

API Configuration

Primary Endpoint: /api/data/v9.2/zav_maintenancetasks
Lines Endpoint: /api/data/v9.2/zav_maintenancedetails
Method: GET
Authentication: Zavanti universal authentication

Query Parameters

Parameter	Source	Purpose
modifiedon	Metadata	Incremental sync timestamp filter
$filter	Configuration	Task status and DOA required filtering
$expand	API	Related entity expansion

Master Data Requirements

The integration fetches and maps the following master data from Zudello:

Master Data Type	Zavanti Source	Zudello Target	Mapping Method
Locations	zav_servicename	location.external_id	Service code lookup
Currencies	transactioncurrencyid.isocurrencycode	currency.code	ISO currency code
Suppliers	zav_Tradesperson.name	supplier.external_id	Name-based matching
Account Codes	zav_maintenancecode	account.external_id	Maintenance code lookup

Filtering Criteria

Only processes maintenance tasks meeting the following criteria:

Filter	Value	Purpose
zav_taskstatus	100000004	Specific task status filter
zav_doarequired	100000000	DOA required flag filter

Header Field Mappings

Zudello Field	Zavanti Field	Data Type	Notes
external_id	zav_maintenancetaskid	GUID	Maintenance task identifier
document_number	zav_maintenanceid	String	Maintenance task number
supplier.external_id	zav_Tradesperson mapping	String	Mapped from tradesperson name
company_name	zav_Tradesperson.name	String	Tradesperson name
reference	zav_name	String	Task name/reference
date_issued	createdon	Date	Task creation date (formatted)
currency.code	transactioncurrencyid.isocurrencycode	String	Currency code (defaults to NZD)
subtotal	zav_workdetailstotal	Decimal	Work details total
tax	Calculated	Decimal	15% of subtotal
total	Calculated	Decimal	Subtotal + tax (1.15 multiplier)
module	N/A	String	Always "PURCHASING"
submodule	N/A	String	Always "ORDER"
document_type	N/A	String	Always "WORK_ORDER"
status	N/A	String	Always "READY"

Line Item Field Mappings

Zudello Field	Zavanti Field	Data Type	Notes
external_id	zav_maintenancedetailid	GUID	Line item identifier
description	Composite	String	Location + Information Code + Comments
location.external_id	Service code mapping	String	Mapped from zav_servicename
account.external_id	Maintenance code mapping	String	Mapped from zav_maintenancecode
tax_rate.external_id	Fixed	String	Always "37623fa7-88f0-ee11-a1fd-00224894e175"
quantity	N/A	Integer	Always 1
unit_price	zav_amount	Decimal	Line amount
total	zav_amount	Decimal	Same as unit_price

Custom Fields

Zudello Field	Zavanti Field	Data Type	Notes
custom.raisedBy.email	owninguser.internalemailaddress	String	Task owner email

Processing Logic

Date Processing

Converts Zavanti date formats to YYYY-MM-DD format:

Supported Formats

• ISO 8601 Format: Extracts date portion from timestamp
• MM/DD/YYYY Format: Converts to YYYY-MM-DD
• Fallback: Uses JavaScript Date parsing for unknown formats

Description Construction

Line descriptions are built from multiple Zavanti fields:

Description Components

1. Location Name: zav_Location.zav_name
2. Information Code: zav_InformationCodeDetail.zav_name
3. Comments: zav_comments

Format Structure

{Location} {Information Code} - {Comments}

Tax Calculation

Automatic tax calculation on work details total:

• Tax Rate: 15% fixed rate
• Calculation: tax = subtotal * 0.15
• Total: total = subtotal * 1.15

Currency Handling

• Primary: Uses transactioncurrencyid.isocurrencycode
• Fallback: Defaults to "NZD" when currency not specified
• Validation: Ensures currency exists in Zudello master data

Incremental Synchronization

Last Modified Tracking

Uses lastModifiedDateTime metadata for efficient synchronization:

Process Flow

1. Retrieve Timestamp: Gets last processed timestamp from metadata
2. Filter API Calls: Uses modifiedon field for filtering
3. Process Records: Handles new and updated maintenance tasks
4. Update Timestamp: Stores new timestamp after successful processing

Performance Benefits

• Reduced Load: Only processes changed records
• Faster Sync: Eliminates unnecessary data transfer
• Resource Efficient: Minimizes API calls and processing time

Master Data Mapping

Supplier (Tradesperson) Mapping

Maps Zavanti tradespersons to Zudello suppliers:

Mapping Process

1. Name Extraction: Gets tradesperson name from Zavanti
2. Supplier Lookup: Searches Zudello suppliers by name
3. Caching: Caches successful lookups for performance
4. Fallback: Logs warning if mapping not found

Location (Service Code) Mapping

Maps Zavanti service names to Zudello locations:

Mapping Process

1. Service Name: Uses zav_servicename from maintenance details
2. Location Search: Finds matching location in Zudello
3. External ID: Uses location external_id for reference

Account Code Mapping

Maps Zavanti maintenance codes to Zudello accounts:

Mapping Process

1. Maintenance Code: Uses zav_maintenancecode from details
2. Account Lookup: Searches Zudello chart of accounts
3. Reference: Uses account external_id for GL coding

Error Handling

Data Quality Issues

• Missing Master Data: Logs warnings for unmapped references without failing
• Invalid Dates: Uses fallback date processing for malformed dates
• Empty Fields: Handles null or empty field values gracefully
• Currency Issues: Defaults to NZD for missing currency information

Processing Errors

• Partial Results: Continues processing remaining records on individual failures
• API Failures: Comprehensive error logging with context
• Master Data Validation: Non-blocking validation with warning logs
• Transaction Integrity: Ensures data consistency across related records

Batch Processing

• Sequential Processing: Processes one maintenance task at a time
• Data Integrity: Prevents concurrent modification issues
• Error Isolation: Isolates failures to individual records
• Performance Balance: Balances throughput with data reliability

Use Cases

Maintenance Management

• Work Order Creation: Convert maintenance tasks to purchase orders automatically
• Approval Workflows: Enable approval processing in Zudello
• Cost Tracking: Track maintenance costs by location and account
• Resource Planning: Plan maintenance resources and budgets

Financial Integration

• GL Integration: Proper account coding for maintenance expenses
• Tax Compliance: Automatic tax calculation for compliance
• Multi-currency: Support for international maintenance operations
• Budget Tracking: Track maintenance spending against budgets

Operational Efficiency

• Automated Processing: Eliminate manual work order creation
• Real-time Data: Current maintenance task information
• Error Reduction: Reduce manual data entry errors
• Streamlined Workflows: Seamless maintenance-to-payment workflow

Configuration Requirements

Work Order Setup

For successful work order integration:

• Configure Zavanti universal authentication
• Set up master data mappings for locations, suppliers, and accounts
• Verify task status filtering (zav_taskstatus eq 100000004)
• Configure DOA required flag (zav_doarequired eq 100000000)
• Set up fixed tax rate reference (37623fa7-88f0-ee11-a1fd-00224894e175)
• Configure incremental sync timestamp handling

Troubleshooting

Issue	Cause	Solution
Tasks not syncing	Task status filter mismatch	Check zav_taskstatus eq 100000004 filter
Missing supplier mapping	Tradesperson not found in Zudello	Create supplier with matching name in Zudello
Location mapping failures	Service code not mapped	Set up location mapping for zav_servicename
Account mapping issues	Maintenance code not found	Ensure maintenance codes exist in chart of accounts
Date format errors	Invalid date formats	Check date field formats in Zavanti
Tax calculation issues	Missing work details total	Verify zav_workdetailstotal field is populated
Incremental sync problems	Timestamp handling errors	Check lastModifiedDateTime metadata

Related Documentation

• Work Order Approval - Approval processing workflow
• Invoice Creation - Invoice processing with PO closure
• Overview - Integration architecture overview