e-automate filing

Record a ticket's e-automate account, and raise service calls, supply orders and meter readings in the dealer's system.

For a workspace connected to a dealer's e-automate system, these tools let an assistant record which e-automate account a ticket is about, and then raise a service call, place a supply order or post a meter reading in the dealer's own system. Every request goes through the same checks a request from the chat widget goes through.

Tool	What it does	Role needed	Changes data?
`esn_pick_customer`	Records which e-automate account a ticket is against	editor	destructive
`esn_file_service_call`	Raises a service call in e-automate	editor	adds
`esn_file_supply_order`	Places a supply order in e-automate	editor	adds
`esn_file_meter_read`	Posts a meter reading to e-automate	editor	adds

Source: the esn_pick_customer and esn_file_* entries in _TOOLS, and _esn_pick_customer, _esn_write_spec and _esn_file_request in services/runtime/src/runtime/mcp/tools.py.

These tools send the client no read-only or destructive hint. The last column describes what each one does. The three filing tools write into the dealer's live system unless the workspace is in sandbox mode.

Before you file

e-automate must be connected on the workspace. If it is not, the request is not refused: it is taken and handed to a person to file, and the answer says so with status: pending_approval.
The request type must be switched on. If the workspace has switched a type off for the AI, or the connection is not ready, the request is likewise handed to a person (pending_approval) rather than filed.
In both hand-over cases, missing details are still asked for first (needs_fields), because the person filing it needs them too.
You need editor. A viewer is refused.
Pick the account first when the ticket's account is not already known. Use esn_search to find it and esn_pick_customer to record it.

Source: _esn_file_request in services/runtime/src/runtime/mcp/tools.py and the module notes in services/runtime/src/runtime/api/esn_assistant.py.

`esn_pick_customer`

Inputs: ticket_id and customer_number (1 to 32 characters) are required. method is agent_pick (the default) or manual_entry.
Records the pick against the ticket, replacing any earlier pick. Who made the pick is taken from your sign-in, never from the request, because this record is the audit trail for a filing made against the wrong account.
Returns the account, read from e-automate.
A failed save is reported as a failure, never as success.

Source: _esn_pick_customer in services/runtime/src/runtime/mcp/tools.py and the esn_customer route in services/runtime/src/runtime/api/esn.py.

Filing a service call, supply order or meter reading

The three filing tools take the same inputs:

Input	Required	Notes
`ticket_id`	yes	The helpdesk ticket the request is filed on
`idempotency_key`	yes	8 to 200 characters: letters, digits and `. _ : @ = + -`
`fields`	no	The details, as named strings (below)

The fields each one reads:

Tool	`fields`
`esn_file_service_call`	`equipment`, `machine_description`, `customer`, `customer_location`, `contact_name`, `callback_phone`, `problem_description`
`esn_file_supply_order`	`supplies`, `equipment`, `machine_description`, `customer`, `customer_location`, `order_notes`
`esn_file_meter_read`	`reading`, `meter_type`, `equipment`, `machine_description`, `customer`, `customer_location`

Source: _esn_write_schema and _esn_fields_schema in services/runtime/src/runtime/mcp/tools.py, which read CHAT_FIELDS in services/runtime/src/runtime/esn/request_fields.py.

Retry with the same key

idempotency_key is your name for this attempt. If a call fails or times out, send it again with the same key: the first outcome recorded under that key comes back, and nothing reaches e-automate a second time. Use a new key only for a genuinely new request.

The ticket is checked, and the workspace's permission to file is decided, before the key is used. A request turned away at that point does not use up the key, so a corrected request can reuse it.

If an earlier attempt under the same key has not finished reporting, the call is refused: something may already exist in e-automate, and a person needs to check before anyone retries.

What comes back

An answer, not an error, for every outcome a person needs to hear about:

`status`	Meaning
`filed`	Done. `record_number` is e-automate's number for it
`needs_fields`	Something is missing. `missing_fields` and `fields` say what to ask for, in order; `options` lists the choices when the problem is which machine or meter
`pending_approval`	Taken, and waiting for a person: approval is required, the type is switched off, or e-automate is not connected
`failed`	Completed, and nothing was filed. Say so; do not retry

message is wording that can be said to a customer. reason is a stable code on failed and needs_fields.
e-automate's own error text never appears in the answer. It goes to the log and to an internal note on the ticket, where the person who can act on it reads it.
A meter reading that is filed also carries reading, meter_label, asset_id, serial and model.

Refusals are reserved for problems with the request itself: a ticket this workspace does not hold, a missing or malformed idempotency_key, a fields value that is not an object, and an unfinished earlier attempt under the same key.

Source: AssistantResponse and MeterReadResponse in services/runtime/src/runtime/api/esn_assistant.py, and _esn_file_request in services/runtime/src/runtime/mcp/tools.py.

Who filed it

The filing records MCP as the channel and you as the person, the same way a filing from the Studio panel records the person who clicked.

Source: _ESN_MCP_ORIGIN and _esn_file_request in services/runtime/src/runtime/mcp/tools.py.

Sandbox mode

A workspace in sandbox mode (the practice setting) is a safe place to try filing:

requests are filed against the practice customer, not the account on the ticket;
a machine that already has an open call does not block a new service call, because the practice machines are shared by every workspace in sandbox mode.

A workspace not in sandbox mode files into the dealer's live e-automate system. Check which mode the workspace is in before filing anything as a test.

Source: the practice handling in services/runtime/src/runtime/esn/assistant_requests.py and services/runtime/src/runtime/esn/practice.py.