Work Order Integration Overview

  • Updated

The Work Order Integration allows you to push work order details from an external project management or maintenance system directly into Unimarket. This ensures that only authorized users can purchase against specific work orders, and that spend is tracked against the correct project identifiers.

 

Key Data Fields

When creating or updating a Work Order via XML, the following character limits and constraints apply:

  • Work Order Name: Up to 255 characters.

  • Work Order Description: Up to 2000 characters.

  • Dates: Used by the system to automatically toggle the Work Order between Pending (before start date) and Active (within start/end date).

  • State: Valid values are PENDING, ACTIVE, CANCELLED, or EXPIRED.

  • Members: Defines which Unimarket users are permitted to purchase against the Work Order. Each member's identity must be a valid Unimarket username.

 

Create Work Order Request

Use the create-work-order-request to initialize a new Work Order. The work-order-number attribute in the header serves as the unique identifier for all future updates.

XML Request Example

<?xml version="1.0" encoding="UTF-8"?>
<create-work-order-request xmlns="http://www.unimarket.com/schema/unimarket-ws-1.1" work-order-number="WO0033">
    <name>Infrastructure Upgrade - Phase 1</name>
    <description>Materials and labor for the Q1 infrastructure project.</description>
    <start-date>2025-01-01T09:00:00Z</start-date>
    <end-date>2025-12-31T17:00:00Z</end-date>
    <state>ACTIVE</state>
    <owner-ref identity="project_lead_01" domain="UNIMARKET_USERNAME_DOMAIN"/>
    <members>
        <member-ref identity="buyer_team_A" domain="UNIMARKET_USERNAME_DOMAIN"/>
        <member-ref identity="buyer_team_B" domain="UNIMARKET_USERNAME_DOMAIN"/>
    </members>
</create-work-order-request>

 

Expected Response

A successful submission will return an OK response code.

<?xml version="1.0" encoding="UTF-8"?>
<create-work-order-response xmlns="http://www.unimarket.com/schema/unimarket-ws-1.1">
    <response code="OK"/>
</create-work-order-response>

 

Update Work Order Request

If the scope, dates, or permitted buyers change in your external system, use the update-work-order-request. This message replaces existing data for that specific work-order-number.

XML Update Example

<?xml version="1.0" encoding="UTF-8"?>
<update-work-order-request xmlns="http://www.unimarket.com/schema/unimarket-ws-1.1" work-order-number="WO0033">
    <name>Infrastructure Upgrade - Phase 1 (REVISED)</name>
    <description>Scope updated to include electrical wiring.</description>
    <start-date>2025-01-01T09:00:00Z</start-date>
    <end-date>2026-06-30T17:00:00Z</end-date>
    <state>ACTIVE</state>
    <owner-ref identity="project_lead_01" domain="UNIMARKET_USERNAME_DOMAIN"/>
    <members>
        <member-ref identity="buyer_team_A" domain="UNIMARKET_USERNAME_DOMAIN"/>
        <member-ref identity="new_vendor_manager" domain="UNIMARKET_USERNAME_DOMAIN"/>
    </members>
</update-work-order-request>

 

 

Implementation Notes

  • Sequential Updates: Ensure that updates are sent in the correct chronological order to avoid overwriting newer data with older project states.

  • Member Validation: If a member-ref identity does not match a user in Unimarket, the integration may fail or exclude that specific user from the Work Order.

  • Timezone Formatting: Dates should be provided in ISO 8601 format (e.g., YYYY-MM-DD'T'hh:mm:ssZ).