e-automate lookups
Read the dealer's own e-automate records: accounts, machines, contracts, meters, open calls, orders and items.
For a workspace connected to a dealer's e-automate system, these tools let an assistant look up who is calling, which account a ticket belongs to, what machines the account has, whether a machine is under contract, what its meters read, what is already open or on order, and which supplies it takes. Every one only reads. To file something, see e-automate filing.
| Tool | What it does | Role needed | Changes data? |
|---|---|---|---|
esn_enabled | Whether e-automate is available here, what it may do, and why not | viewer | read-only |
esn_status | What this ticket has already produced in e-automate | viewer | read-only |
esn_account | The e-automate account this ticket belongs to | viewer | read-only |
esn_search | Searches customers, contacts, equipment, serials and items | viewer | read-only |
esn_identify_caller | A phone number in, a person and an account out | viewer | read-only |
esn_customer_detail | An account's record, by its e-automate number | viewer | read-only |
esn_customer_equipment | Every machine at an account, with its key operator | viewer | read-only |
esn_fleet_makes | The make of each machine at an account | viewer | read-only |
esn_contracts | Every contract on an account, in summary | viewer | read-only |
esn_sales_orders | An account's orders, with their lines | viewer | read-only |
esn_asset | A machine and the account that owns it, from one number | viewer | read-only |
esn_contract | The contract covering one machine, and its meters | viewer | read-only |
esn_meters | The current reading on each of a machine's meters | viewer | read-only |
esn_meters_due | The meter readings e-automate expects on a machine | viewer | read-only |
esn_open_calls | Service calls already open on a machine | viewer | read-only |
esn_open_orders | Supply orders still open on a machine | viewer | read-only |
esn_related_items | The supplies a machine takes, for this account | viewer | read-only |
esn_ticket_service_calls | The service calls in e-automate for this ticket's customer | viewer | read-only |
esn_item_lookup | Turns the number on a box into the dealer's own item | viewer | read-only |
esn_item | One dealer item, by the dealer's own number | viewer | read-only |
esn_call_types | The dealer's service-call types | viewer | read-only |
esn_unassigned_technician | Where a call with no engineer assigned lands | viewer | read-only |
Source: the esn_* entries in _TOOLS and their handlers in
services/runtime/src/runtime/mcp/tools.py. Each tool calls the HTTP route
named in its handler, in services/runtime/src/runtime/api/esn.py or
services/runtime/src/runtime/api/esn_reads.py.
These tools send the client no read-only hint. Each one reads and only reads.
How these tools are described
Each tool's description is the first paragraph of its HTTP route's own
documentation, and its input schema is generated from the route's own request
model. So the tool and the route cannot disagree about what is accepted, and a
field the route does not know is refused by name. Some descriptions name the
e-automate operation behind them, such as GetCustomerEquip.
Source: _esn_read_spec, _esn_schema, _esn_body and _first_paragraph in
services/runtime/src/runtime/mcp/tools.py.
What they need
- A connected dealer. A workspace that holds no e-automate credential is
refused with
esn_not_connected. - To be in the connection's audience. An admin can limit a connection to
certain teams or people. Anyone outside is refused with
esn_not_permitted, andesn_enabledtells them e-automate is not available. - When e-automate declines or does not answer, the refusal is an identifier and whether it is worth retrying. e-automate's own error text is logged, never returned.
Source: the module notes and refusals in
services/runtime/src/runtime/api/esn_reads.py.
Inputs
All inputs are short strings, at most 64 characters, unless noted.
| Tool | Required | Optional |
|---|---|---|
esn_enabled | none | none |
esn_status | ticket_id | none |
esn_account | ticket_id | asset_ref |
esn_search | query (1 to 128 characters) | none |
esn_identify_caller | phone (3 to 64 characters) | include_local (default false) |
esn_customer_detail, esn_customer_equipment, esn_fleet_makes, esn_contracts | customer_number | none |
esn_sales_orders | customer_number | order_number, order_type |
esn_asset | identifier | none |
esn_contract, esn_related_items, esn_open_orders, esn_meters_due | equipment_number, customer_number | none |
esn_meters | none | equipment_number, serial, make, model |
esn_open_calls | equipment_number | none |
esn_ticket_service_calls | ticket_id | none |
esn_item_lookup | number | none |
esn_item | item_number | none |
esn_call_types, esn_unassigned_technician | none | none |
Source: the request models named in each _esn_read_spec call in
services/runtime/src/runtime/mcp/tools.py.
Per-tool notes
esn_enabledis answered per person, not just per workspace, and costs no call to e-automate when the workspace has no connection. Over MCP it can return an answer cached for a short time.esn_statusanswers from the helpdesk's own records of what this ticket has filed, from every channel. It does not ask e-automate.esn_accountreturns the account the ticket is linked to. When the ticket text matches more than one account, the call is refused rather than guessing; pick one withesn_searchand record it withesn_pick_customer.esn_searchcovers what its name suggests: customers, contacts, equipment, serial numbers, and items by manufacturer number, barcode or serial. It stores nothing.completeis the only signal that the list is the whole answer, andsearchedandfailedsay which searches ran and which broke.esn_identify_callerignores seven-digit local numbers unlessinclude_localis true, because a local number can belong to another area code.- Stored answers.
esn_account,esn_customer_equipment,esn_contract,esn_contracts,esn_meters,esn_open_callsandesn_related_itemsanswer from the helpdesk's stored copy when it has one, and ask e-automate only when nothing is stored. Over MCP there is no way to force a fresh read; the answer says when it was fetched underread. esn_open_ordersshows supply orders on the machine wherever they were placed: this helpdesk, the dealer's own desk or a portal.
Source: the route docstrings for esn_enabled, esn_status, esn_account and
esn_search in services/runtime/src/runtime/api/esn.py, and
IdentifyRequest and the module notes in
services/runtime/src/runtime/api/esn_reads.py.
Sandbox mode
When the workspace is in sandbox mode (the practice setting), a lookup that finds nothing, such as a machine not on file or an unknown company, can be answered with the practice customer and one of its machines instead of a refusal, so a demo or training run works without real identifiers. A lookup that fails because e-automate is down is still reported as an outage.
Source: the module notes in services/runtime/src/runtime/esn/practice.py.