Skip to main content

Send pictures to Maersk AEMS (API)

AEMS (Automated Estimate Management System) is Maersk’s maintenance-order platform. In ConPDS Checker, an EDI destination whose protocol is API sends case pictures into AEMS by:

  1. Finding the right maintenance order for the container (equipment).
  2. Uploading image files to Maersk’s blob service.
  3. Updating the maintenance order JSON so those files appear as attached images (same rules as the legacy DepotMaster integration).

This page is the user-facing workflow. For implementation references (source files, tests), see the companion file in the main repository: docs/workflows/aems-api-picture-send.md.

What you configure (administrator)​

Administrators define an EDI destination with:

FieldUsed for AEMS as
ProtocolAPI
SenderMaersk shop code, or several shop codes separated by commas (sent as maintenanceShopCodes) — see Several shop codes on one destination
UsernameOAuth client id
PasswordOAuth client secret
ParamsSee below (PARAMS text, one KEY=value per line)

Params (PARAMS)​

KeyMeaning
TEST_MODE=1Use Maersk stage hosts (api-stage.maersk.com). Omit or 0 for production.
MAERSK_MODERepair mode filter sent to AEMS as maintenanceRepairModes (see repair mode codes). Use (all) to not filter by mode (ConPDS omits the parameter).
ORDER_STATUSNumeric maintenance order status type sent as maintenanceOrderStatusTypes when listing orders. Default in software is 200,330 if omitted. This controls which orders are returned for the container (for example open / pending work — exact meaning is defined by Maersk for your shop).
DRY_RUN=1Preview only: real sign-in and order lookup, but no picture upload and no order update. Useful for validating credentials and filters.
AEMS_WAIT_FOR_ORDER=1Let an unattended mailbox send wait up to 24 hours for an estimate (see below). Default / omitted / 0 = fail immediately.
SEND_DELAYMinutes to wait before the worker runs (same as other EDI destinations).
Multiple equipment types

Each request sends one MAERSK_MODE value. If you routinely send box vs reefer with different codes, configure separate destinations (e.g. “AEMS Box”, “AEMS Reefer”) with the appropriate MAERSK_MODE on each.

MAERSK_MODE repair mode codes​

These codes are passed through to Maersk as the maintenance repair mode filter (MAERSK_MODE in PARAMS). Use the value that matches how the estimate is registered in AEMS for your operation.

Dry container (“box”) — common codes

MAERSK_MODEEquipment / context
02Box (dry)
03Box (dry)
04Box (dry)
05Box (dry)

Reefer unit — common codes

MAERSK_MODEEquipment / context
26Reefer unit
41Reefer unit
43Reefer unit
45Reefer unit

Set exactly one of these per destination (unless you use (all) to disable the filter).

Several shop codes on one destination​

Sender may hold one shop code (1VK) or a comma-separated list (1VK,9FX,9WE,87V). The list is used in three places:

  • Finding orders: AEMS is asked for maintenance orders belonging to any of those shops.
  • Checking the chosen order: the order must be for this container and for one of the listed shops. An order from a shop that is not on the list is refused with order not found, and nothing is uploaded.
  • Uploading the pictures: the picture files are uploaded under the one shop the chosen order belongs to — the list is never sent as the upload shop.

Spacing and letter case do not matter (1vk, 9fx works). An empty Sender, or an order with no shop code, is always refused.

Multi-shop destinations upload to the order's own shop

A comma-separated Sender finds and checks orders across all listed shops, and the pictures are then uploaded to Maersk under the single shop code of the estimate that was matched. If no listed shop matches the estimate, the send is refused with order not found and nothing is uploaded.

ORDER_STATUS and several open orders​

With the default ORDER_STATUS=200,330 (or whatever your admin configured), AEMS may return more than one maintenance order for the same container — for example multiple pending estimates that all match the query.

ConPDS does not guess which order to use. The app loads the list and asks you to choose a maintenanceOrderNumber before pictures are uploaded (see Choosing an estimate when several match).

Choosing an estimate when several match​

What you do in the Send modal​

  1. Open Send for the case (all pictures or a selection).
  2. Choose your AEMS / API destination.
  3. Click Send (or complete any extra fields that destination requires).

The app calls the backend without a pre-selected order id. The backend runs an AEMS preflight job: OAuth token + list maintenance orders for this container, shop, status (ORDER_STATUS), and optional repair mode (MAERSK_MODE).

If exactly one order matches, the client continues automatically with that order.

If no order matches, the overlay shows the lookup criteria with Close and Wait for order (24h). Waiting enrols a live send job (even if you reached the overlay via DRY_RUN lookup): the system polls AEMS hourly for up to 24 hours. Exactly one match uploads; more than one fails the wait (choose manually); timeout fails with a clear Send Log message. Cancel from Send Log while waiting.

Waiting for an order on automatic sends​

The Wait for order (24h) button above is a manual choice in the Send modal. A send started by a mailbox rule or a mailbox spreadsheet/file has nobody to click it, so by default it fails the moment AEMS returns no matching order.

Set AEMS_WAIT_FOR_ORDER=1 in the destination PARAMS to let those automatic sends wait instead:

  • Applies to mailbox rule and mailbox file sends only. Gallery, Retry, mobile, cross-tenant and auto-destination sends are unchanged.
  • The send keeps its existing Send Log entry: the running row becomes Waiting for AEMS order, and no failure row is written. The mail processing log shows the row as skipped with reason aems_wait_enrolled.
  • AEMS is re-checked hourly for up to 24 hours. Exactly one match uploads the same pictures this run would have sent; more than one fails the wait (choose manually); timeout fails with a clear Send Log message. Cancel from Send Log while waiting.
  • Not used when the destination or the platform is in DRY_RUN, when an order was found but rejected (wrong container or a shop outside Sender), or when the destination already has many waits outstanding. Those keep failing immediately.
Turn it on only after an upgrade is fully rolled out

AEMS_WAIT_FOR_ORDER is a new key. An older app version rejects it as an unknown PARAMS key when you save the destination, and an older send worker ignores it (that send fails immediately instead of waiting). Enable it once the web app and the send workers are both upgraded. If the feature is rolled back, the key becomes inert — remove it before editing the destination through an older app version. Waits already enrolled finish normally.

If more than one order matches, the Send modal shows an extra control:

  • Section label: AEMS estimate (uppercase styling in the UI), inside a highlighted choice panel.
  • Selectable rows for each matching order: maintenanceOrderNumber is prominent; optional metadata (status, repair mode, shop, date) appears when the backend includes those fields.
  • Helper / callout text: “Multiple estimates found for this container. Select one, then click Send to upload pictures to that order.”

You select the right estimate (select-only — choosing a row does not upload), then press Send again. The second request includes the selected aems_order_id, so uploads go to that maintenance order only.

Wireframe (layout)​

+--------------------------------------------------+
|  Send To                                    [x]  |
|  Terminal / Container / Case date …             |
|                                                  |
|  DESTINATION                                     |
|  Pictures will be sent via AEMS.                 |
|  [ Change destination ]                          |
|                                                  |
|  ┌─ AEMS ESTIMATE ─────────────────────────────┐ |
|  │  Multiple estimates found… Select one, then │ |
|  │  click Send…                                │ |
|  │  ┌───────────────────────────────────────┐  │ |
|  │  │ # MO-2025-004411                      │  │ |
|  │  │ Status 200 · Mode 26                  │  │ |
|  │  └───────────────────────────────────────┘  │ |
|  │  ┌───────────────────────────────────────┐  │ |
|  │  │ # MO-2025-004412   (selected)         │  │ |
|  │  │ Status 200 · Mode 41                  │  │ |
|  │  └───────────────────────────────────────┘  │ |
|  └─────────────────────────────────────────────┘ |
|                                                  |
|                        [ Send ]    [ Cancel ]     |
+--------------------------------------------------+

API workflow — how pictures are attached (live send)​

After an order is chosen, the worker (Celery) runs the real integration:

Important behavior:

  • Capacity / fill: DepotMaster parity — fill the header first (up to 5), then each existing repair line in order (up to 5 each). Pack earlier lists before later empty ones. Never invent lines; never replace existing photos. Line 0999 is included when present but is not the only attach target.
  • When Send shows Sent: this attempt’s placed filenames must appear somewhere on the estimate (header or any line). Photos already on the estimate are skipped (no_upload_needed) without rewriting EDI_SENT. If every slot is full and names are still missing → Failed (order_slots_full).
  • Journey proof vs Sent chip: Open Send journey to see which lines hold pre-existing vs this send photos (including 0999 marked as the line Maersk reviews). The list Sent chip only means this attempt’s placed names were confirmed on the estimate.
  • Video: .MP4 files are skipped for AEMS in the current handler.
  • Dry run (DRY_RUN=1): the sequence stops after OAuth + listing orders (and preview data for the modal). No GET full order by id for attach planning, no upload, no PUT, no EDI_SENT updates — see the technical doc for details.

Dry run vs live send (summary)​

Dry run (DRY_RUN=1 or env EDI_DRY_RUN=1)Live send
OAuthYesYes
List / resolve ordersYesYes
Upload blobsNoYes
Update maintenance orderNoYes
Mark pictures sent in DBNoYes
Send log rowPreview path does not enqueue like a normal job; see technical docNormal queued / scheduled send + log entry

Duplicate-send guards​

Before a Gallery or Retry send starts, ConPDS binds the chosen AEMS order to this container and shop, then checks whether those pictures are already visible anywhere on the estimate (header or any line), or whether another send for that container/destination is already in progress. A previous Firebird “success” with names missing from the live GET does not block Retry.

  • Already visible on the order union — nothing is sent again (same 422 as before)
  • Names missing from the union — send proceeds (including Retry)
  • Order id does not match this container/shop — treated as order not found
  • Send already running — wait for it to finish, then retry if needed
  • Duplicate check unavailable — send is blocked until the check works again

Failed sends that recorded attempted picture IDs can still be retried from the Send Log; successful picture sets are not re-uploaded by a blind retry.

See also the operator runbook for attachment verify/repair on the ops docs site when Send Log says success but Maersk cannot show the files.

Glossary​

TermMeaning
maintenanceOrderNumberThe AEMS estimate / maintenance order id you select in the UI.
PreflightBackground step that lists matching orders when you have not yet chosen an order.
Hot / live sendNormal send: upload + order update.