ShowMgr provides an application API for product operations and a separate external API for integrations. The interfaces use different models and authentication handling. Integration requests should use the external interface and its defined field names.
Booking identity fields
The internal booking model identifies a booking with booking_id. The external booking payload uses id. Both also provide relationship fields for the order and element.
| Concept | Internal application property | External booking property |
|---|---|---|
| Booking identity | booking_id |
id |
| Order identity | order_id |
order_id |
| Displayed order number | order_num |
order_num |
| Element identity | element_id |
element_id |
| Generic requirement | generic_element_id |
generic_element_id |
| Specific assignment | specific_element_id |
specific_element_id |
Use the payload definition for the requested operation. A field returned for display is not automatically a writable field in every operation.
Preserve identity and environment context
Keep instance and client context with integration mappings. Internal IDs, displayed numbers and external-system references have different meanings.
Map records by the appropriate identity rather than their displayed names. Keep project IDs and associated order IDs as separate fields. Maintain separate mappings for test and production environments; do not carry one environment's record IDs into another.
Date filters answer different questions
External booking time filters use UTC. Their purpose differs by field:
| Filter | Purpose |
|---|---|
start_time |
Selects bookings by their start time |
end_time |
Selects bookings by their end time |
last_modified_date |
Selects bookings by when they changed |
date_range |
Selects bookings overlapping a time interval |
A booking modified today can concern work scheduled for another date. Use change timestamps for change detection and scheduled timestamps for schedule selection. Keep the full date and UTC context when exchanging timestamps.
Map related records before applying changes
An integration mapping should identify the owning system for each field, how parent and related record IDs are resolved, and the permitted classes and statuses. Booking, actual and invoice updates are separate operations even when they concern the same production work.
After a change, reconcile the returned or retrieved record using its identity and relationship fields. Follow the endpoint's paging and filtering rules when retrieving sets of records, and account for deletion handling when maintaining a synchronized dataset.
Define the integration's responsibilities
| Area | Integration responsibility |
|---|---|
| Authentication | Use the credentials and method assigned to the external interface |
| Identity mapping | Keep ShowMgr IDs, external IDs and environment context distinct |
| Field ownership | Define which system supplies each value and how conflicts are resolved |
| Relationships | Resolve the order, booking, element and other references required by the operation |
| Synchronization | Handle paging, retries and duplicate prevention according to the endpoint contract |
| Reconciliation | Compare saved identities, relationships, statuses and values |
This separation keeps integration behavior aligned with the records and workflows it is intended to manage.