Guide
EZO Setup (API Builder)
This page covers the EZO-specific implementation pattern for API Builder. Use this as the reference for contract rows, mapping structure, and validation gates when targeting EZOfficeInventory endpoints.
When to Use Builder vs EZO Profile
Use EZO Profile When
- You want predefined EZO behavior and fast setup.
- You do not need custom endpoint, method, or body-format control.
- You want the profile to provide expected default mapping semantics.
Use API Builder When
- You need explicit control over API contract paths and HTTP methods.
- You need to choose request format (JSON/XML) per contract endpoint.
- You want to manually map destination fields from real destination samples.
EZO API Builder Contract Example (Successful Pattern)
Recommended Contract Inputs
| Contract Endpoint | Method | Formatter | Example Path | Notes |
|---|---|---|---|---|
| Computers - Required fetch API | GET | JSON | /assets.api?include_custom_fields=true&show_document_urls=true&show_image_urls=true&show_document_details=true |
Primary list lookup endpoint for serial matching and runtime indexing. |
| Computers - Required update API | PUT | JSON | /assets/{id}.api?format=json |
Update endpoint uses resolved destination asset ID. |
| Computers - Optional detail lookup API | GET | JSON | /assets/{id}.api?include_custom_fields=true&show_document_urls=true&show_image_urls=true&show_document_details=true |
Optional/collapsed detail endpoint for full payload hydration and lookup enrichment. |
| Mobile Devices - Required fetch API | GET | JSON | /assets.api?include_custom_fields=true&show_document_urls=true&show_image_urls=true&show_document_details=true |
EZO is asset-centric; reuse same fetch path for mobile scope. |
| Mobile Devices - Required update API | PUT | JSON | /assets/{id}.api?format=json |
EZO uses the same asset update path for both scopes. |
| Mobile Devices - Optional detail lookup API | GET | JSON | /assets/{id}.api?include_custom_fields=true&show_document_urls=true&show_image_urls=true&show_document_details=true |
Optional/collapsed detail endpoint for full payload hydration and lookup enrichment. |
Important Contract Notes
- EZO lookup is typically ID-based after serial reconciliation from list/detail responses.
- Detail endpoints improve lookup reliability and sample-field hydration when list rows are partial.
- If update returns 404/405/415/400, verify path, method, and formatter pairing before changing mappings.
EZO API Builder Mapping Example (Assets)
ABM Source to Destination Mapping Pattern
| ABM Field | Destination Field (Example) | Action | Formatter | Notes |
|---|---|---|---|---|
serialNumber |
Serial Number |
Key | String | Lookup key. Do not treat as a writable business field. |
orderNumber |
PO Number (if present) or custom field |
Update | String | Map only to fields supported by your EZO schema. |
orderDateTime |
PO Date or custom field |
Update | Date (yyyy-MM-dd) or Date (MM/dd/yyyy) | Use formatter that matches destination field expectation. |
purchaseSourceType |
Vendor or custom field |
Update | String | Map based on your EZO field availability. |
purchaseSourceId |
custom field | Update | String or Integer | Align formatter with destination type. |
appleCareId |
custom field | Update | String or Integer | Formatter should match target field type. |
warrantyDate |
Warranty (or equivalent EZO destination field) |
Update | Date (yyyy-MM-dd) or Date (MM/dd/yyyy) | Use date-only output expected by your EZO field configuration. |
lifeExpectancy |
custom field | Update | Integer | Use Integer when destination rejects decorated values like “6 Years”. |
Formatter Guidance
Builder formatters are explicit and important. Choose formatters based on destination expectations, not source display style. A date-time source may need date-only output, and a decorated numeric string may need Integer output.
Successful EZO API Builder Setup Checklist
End-to-End Validation Gates
| Stage | What to Confirm | Pass Condition | If It Fails |
|---|---|---|---|
| API-Key Validation | Connection test succeeds with current base URL and API key headers. | Wizard advances to contract and mapping. | Recheck host, API key token, header name, and any required prefix. |
| Contract Save | Contract rows are valid and persist after close and reopen. | Method, formatter, and endpoint path rehydrate exactly. | Reopen Update API Contract and verify each row, especially list/update/detail path parameters. |
| Mapping Save | Mapped destination fields and formatters persist after Save. | Update Mapping reopens with exact saved values. | Validate key field mapping and required field mappings are still set. |
| Single Dry Run | One target serial shows expected would-update and skip diagnostics. | No endpoint or media-type errors in diagnostics. | Check contract method/formatter pairing and mapped destination field names. |
| Single Live Run | One target serial applies expected updates in EZO destination. | Destination reflects mapped values. | Check response error details and verify mapped destination field names exactly match EZO-accepted fields. |
| Full Run | Jobs complete with expected update and skip counts across all records. | No unexpected destination-missing spikes or payload format failures. | Re-validate lookup/detail contract paths, serial visibility, and action rules. |