Core JSON-RPC API

TracePRO core API is a set of JSON-RPC endpoints registered on the api endpoint. All functions are called via JSON-RPC over HTTP POST to the /api/ URL.

The source code is in tracecar/views/api*.py.

Production Orders (api.py)

findorder(erp_ref)

Returns the order for a given ERP reference string.

param erp_ref:

The order’s ERP reference (e.g. "VP-12345").

returns:

The order object or None.

getorder(order_id)

Returns the order for a given internal order id.

param order_id:

The internal numeric order id.

getorderitemcounts(order_id)

Returns item counts for the order, mapping item type to counts of good/bad items.

makeorder(erp_ref, item, status, flags, amount)

Creates a new production order and returns it.

updateorder(order_id, properties, operations)

Updates the order’s parameters and operations.

param properties:

Dict with keys: status, flags, amount, params, mptp, mpcount, barcode_mp, barcode_pcb, customer, cat1-cat3, item_name, vd.

param operations:

List of operation dicts (op, act, name, desc, flags, params) or None.

queryorder(item, status_list)

Returns a list of orders filtered by item type and/or status list. If both are empty, defaults to status 1 (active).

getordercounts(order_id)

Returns the per-operation item counts done on the order.

Items (api.py)

getitembybarcode(barcode)

Searches for an item by barcode. Returns a list (may be empty).

getitembyitem(item_type, barcode)

Returns an existing item by item type and barcode.

getitem(order_id, barcode, tp)

Returns an existing item or creates a new one within the order.

param tp:

Item type (defs.ITEM_TP_*). If 0, the item is never auto-created.

getitemoperations(item_id)

Returns a list of operations performed on the item.

getitemslots(item_id)

Returns the slot values for the item.

getitemdetails(item_id)

Returns the item’s operations and related items with their operations.

getitemrel(item_id)

Returns a list of the item’s related items.

getorderitems(order_id)

Returns all items belonging to an order.

setitembarcode2(item_id, barcode2)

Sets the secondary barcode for the item.

setitembad(item_id, wp_id, workers, bad)

Marks the item as scrapped (bad=1).

setitemscrap(item_id, wp_id, workers, reason=““)

Marks the item as scrapped with an optional reason.

setitembadmark(item_id, wp_id, workers, reason=““)

Marks the item as discarded (bad mark) with an optional reason.

setitemrtflags(item_id, wp_id, workers, rt_flags)

Sets runtime flags on the item (bitwise OR).

clearitemrtflags(item_id, wp_id, workers, rt_flags)

Clears runtime flags on the item (bitwise AND NOT).

getitemextra(item)

Returns extra data for the item from modules (via event hook).

Operations (api.py)

addop(item_id, op, act, wp_id, workers, tm0, tm1, result, mat_auto, data)

Adds an operation to the item.

param op:

Operation number (or None).

param act:

Act number (or None).

param wp_id:

Workplace id (required).

param workers:

Worker ids – iterable or comma-separated string.

param tm0, tm1:

Start/end time (ISO format or empty for now).

param result:

0 = passed, non-zero = failed.

param mat_auto:

If set, material from the workplace is auto-added.

param data:

List of (tp, key, value) tuples.

returns:

{"op_id": <id>}

addopwithmat(item_id, op, act, wp_id, workers, tm0, tm1, result, mat_auto, data, mat)

Same as addop but also accepts a material list.

param mat:

List of (wfloormat_id, ref, amount, hole_no) tuples.

addncops(order_id, op_act_list, count, wp_id, workers, tm0, tm1)

Adds operations to non-charged (management) items.

param op_act_list:

List of (operation, act) pairs.

param count:

Number of operations to add.

addncopswithmat(order_id, op, act, count, wp_id, workers, tm0, tm1, mat_auto, mat)

Adds operations to non-charged items with optional auto-material.

addopdata(op_id, data_list)

Manually adds data to an existing operation.

param data_list:

List of (tp, key, value) tuples.

addopmat(op_id, mat_list)

Deprecated. Manually adds material to an operation.

canaddop(item_id, op_act_list, wp_id, workers)

Checks whether the operation(s) can be added to the item. Does not modify data (read-only check).

checkproc(order_id, op_act_list, wp_id, workers)

Verifies that the operation(s) can be done on this workplace by these workers. Checks workplace assignment if check_workplaces=True in parameters.ini. Also, emits an event and can get results from modules. They can be returned as the „op_info“ key of the response. Example:

{
    "op_info": {
        "20": {
            "_tp": "info-type".
            "_name": "Name of the record",
            "_status": "User-readable status"
        }
    }
}

reportoptime(order_id, op, act, wp_id, workers, seconds)

Reports time for an operation without actually adding it. Enqueues the time for ERP reporting.

stopwork(order_id, op_act_list, wp_id, workers)

Marks the work on the workplace as finished. Logs a WORK_END event.

batch_addop(item_ids, op, act, wp_id, workers, tm0, tm1, result, mat_auto, data, mat)

Adds the operation to multiple items. Rolls back on error (except for already-bad items which are skipped).

box_canaddop(box_id, op_act_list, wp_id, workers)

Checks if the operation can be added to all items in the box.

box_addop(box_id, op, act, wp_id, workers, tm0, tm1, result, mat_auto, data)

Adds the operation to all items in the box. Transactional – rolls back if any item fails.

checkfirstpiece(item, act, previous_op, workers, wp_id)

Checks that a „1st piece check“ has been done after the given operation.

Material (api.py)

getfloormat(mat_item, mat_lot, amount)

Finds or creates a floor material record. Returns {"wfloormat_id": <id>}.

getwpmat(wp_id)

Returns the material currently on the workplace.

setwpmat(wp_id, mat_item, mat_lot, amount, hole_no, decrement)

Sets material on the workplace at a given hole.

setwpmatbarcode(wp_id, mat_barcode, amount, hole_no, decrement)

Sets material on the workplace, parsing article and lot from a barcode.

setwpmatclamped(wp_id, mat_item, mat_lot, amount, hole_no, decrement)

Like setwpmat but clamps the amount to available floor material.

closewpmat(wp_id, mat_item, mat_lot, amount, hole_no)

Closes/finishes material on the workplace.

clearwpmat(wp_id)

Removes all material from the workplace.

setwpbom(wp_id, bom)

Sets the BOM for the workplace.

param bom:

List of (hole_no, mat_item, decrement) tuples.

getwpbom(wp_id)

Returns the BOM entries for the workplace.

Workers and Login (api.py)

login(id)

Performs worker login by worker id. Shortcut for loginwp(id, None).

loginwp(worker_id, wp_id)

Logs in the worker onto the workplace. Supports OTP login. May check ESD and ILUO.

Basic Data (api.py)

getbasicdata(name)

Returns a list of basic data entities (e.g. "Act", "Worker", "Workplace").

setbasicdata(name, id, key, value)

Sets a property of a basic data entity. Only ("Act", "desc") is currently allowed.

getsiteparams()

Returns the site configuration parameters.

Documents and Docs (api.py)

getstddocs()

Returns a mapping of standard document symbolic names (PI10, IL21, …) to their full paths.

getdocfile(full_path)

Returns the file at the given path (base64 encoded), if it is on an allowed path. Checks for path traversal.

Miscellaneous (api.py)

parsetoolbarcode(wp, barcode)

Parses a tool barcode and returns the material data.

getwplog(wp_id, seconds_back)

Returns recent operations done on the workplace(s) within the given time window.

param wp_id:

A single id or a list of ids.

getalerts(module, src, target, wp_id)

Returns all non-processed alerts matching the given filters.

mkalert(module, src, target, wp_id, severity, params, info)

Creates a new alert.

getalertfields(alert_id)

Returns the fields to be filled in when processing an alert.

processalert(alert_id, appstruct)

Validates and processes an alert.

getuserdata(name, clazz)

Returns public user data with the given name and class.

queryuserdata(clazz)

Returns the list of user data names for a given class.

getreportedwork(worker_id)

Returns reported work for the worker for the current shift.

Workplace Management (api_workplace.py)

getworkplace(wp_id)

Finds a workplace by its id.

findworkplace(name=““, erp_ref=““)

Finds a workplace by name or ERP reference.

blockworkplace(wp_id, reason)

Blocks the workplace with a reason text.

unblockworkplace(wp_id)

Unblocks the workplace(s). Accepts a single id or comma-separated list.

getwpblock(wp_list)

Checks whether any of the given workplaces is blocked.

param wp_list:

Comma-separated workplace ids.

addwlaction(worker_id, wp_id, action, info, order_id, op, param)

Adds a worker log action to the worker/workplace.

Line / Watcher (api_watcher.py)

setlineorder(line_name, order_id)

Sets the production order for the line.

setlinelogin(line_name, wp_ids, workers)

Logs workers onto the line (all machines or selected workplaces).

linegetinfo(line_name)

Returns info about the whole line. (Stub, not implemented.)

linegetenvironment(line_name, machine_name)

Returns the environment of a line + machine: workplace, workers, order, operation.

returns:

line_id, line_name, lineitem_id, lineitem_name, wp_id, worker_ids, workers, order_id, erp_ref, operation, act.

linecanaddop(machine_id, barcode, op, act)

Checks whether the operation can be done on the item at this machine. Read-only check.

lineaddop(machine_id, barcode, op, act, mat_auto, data)

Adds the operation to the item at this machine. Increments machine.counter0.

findlinedata(wp_id, clazz, key)

Finds a cached data entry from the line_cache table.

storelinedata(wp_id, clazz, key, value)

Stores a data entry into the line_cache table. The value is pickled.

SMD Carts (api_smdcart.py)

getcartsfororder(order_id, op)

Returns the list of SMD carts assigned to an order/operation.

setcartsfororder(order_id, op, program, cart_map)

Updates carts for the order/operation. Clears existing carts first.

param cart_map:

Maps cart name to a structure with machine, bank, and item_data (list of items with hole_no, mat_item, scanned_lot, wfloormat_id).

LS Line (api_lsline.py)

getlsline(line_name)

Returns the LSLine object and current history.

setlslineparam(line_name, name, value)

Sets a parameter on the LS line.

lslineoptonextboard(line_name, op, act, wp_id, workers, tm0, tm1, result, data)

Adds an operation to the next board produced on the line. Used for endpoints that do not scan barcodes (e.g. reflow ovens).

ESD and Worker Info (api_esd.py)

getworkerbycard(card)

Looks up a worker by their card number.

logworkeraction(worker_id, wp_id, wwl_action, info)

Adds a record to the worker log (e.g. bracelet measurement). No side-effects beyond logging.

param wwl_action:

One of defs.WWL_* constants.

setworkeresd(worker_id, wp_id, passed)

Sets the ESD test result for the worker. Sets esd_tm to now if passed, or clears it if not.

setworkercard(worker_id, card, worker_name=““)

Sets the card number for the worker. Creates the worker if not found.

Counters (api_counter.py)

getnext(clazz, name, count, start)

Returns the next number from a sequence and reserves count numbers. Creates the sequence with start if it does not exist.

getrangednext(name, count)

Returns the next number from a ranged counter. Returns error if the counter does not exist.

returns:

{"i0": <first>, "i1": <last>}

setrangednext(name, next_value)

Sets a new starting value for the ranged counter.

Boxes (api_box.py)

makebox(item, box_size=0, label=““)

Creates a new box for the given item type.

getbox(id)

Finds a box by its id.

getboxbylabel(label)

Finds a box by its label.

getboxbyitem(item_id)

Returns a list of boxes containing this item.

addboxitem(wbox_id, item_id)

Adds an item to a box. Checks that the item is not already in any box.

addboxbox(wbox_id, child_box_id)

Adds a child box into a parent box.

delfrombox(wbox_id, item_id)

Removes an item from the box.

clearbox(wbox_id)

Removes all items and child boxes from the box.

setboxlabel(box_id, label)

Sets the label for the box.

setboxparams(box_id, label=None, box_size=None, status=None, item=None)

Sets box parameters. Only non-None values are updated.

User Authentication (api_auth.py)

userauth(username, password)

Authenticates a user (not a worker) by username and password.

returns:

{"username": ..., "fullname": ..., "groups": [...]}