system.mes.inventory.operation.startInventoryOperation

Description

Starts an Inventory Operation. This function initiates the inventory operation and creates an inventory lot record with a specified start time but a null end time, indicating that the operation is currently in progress. The operation remains active until explicitly ended.

Permissions

This method requires the INVENTORY_OPERATION.EXECUTE permission.

Syntax

system.mes.inventory.operation.startInventoryOperation(inventoryOperationId, primaryLotIdOrName, secondaryLotIdOrName, materialIdOrPath, inventoryName, startDateMillis)

Parameters

Parameter	Type	Nullable	Description
inventoryOperationId	String (ULID)	False	The ID of the inventory operation to start.
primaryLotIdOrName	String	False	The ID or name of the primary lot to start.
secondaryLotIdOrName	String	True	The ID or name of the secondary lot to start. When omitted, the operation's configured Secondary Lot Resolution Strategy is used instead, see the note below.
materialIdOrPath	String	True	The ID or path of the material associated with the inventory operation.
inventoryName	String	True	The name of the inventory associated with the inventory operation.
startDateMillis	Long	True	The start date of the inventory operation (milliseconds since epoch).

Deriving the secondary lot

When secondaryLotIdOrName is left out, the inventory operation's configured Secondary Lot Resolution Strategy decides what is recorded:

• Auto Generate generates a lot code.
• Expression evaluates the operation's secondary lot code expression.
• Manual derives nothing, the caller is the source of the value by definition.
• From Location is not supported for secondary lots on this method. See the warning below, the call is rejected rather than quietly deriving nothing.

Whether the operation's Create Lot If Not Found setting has to be enabled for that derivation depends on the operation type:

Operation type	Derives a secondary lot
Consume, Produce, Receive and Consume	Only when Create Lot If Not Found is enabled. With it disabled nothing is derived and no lot genealogy is recorded, because a derived lot could not be created on these paths
Unconsume, Scrap, Scrap All, Return, Receive, Ship	Always, whatever Create Lot If Not Found says, because these paths create the secondary lot unconditionally

A value passed in secondaryLotIdOrName always wins, and is used regardless of the operation type, the strategy or that setting. The one exception is a Secondary Lot Resolution Strategy of From Location, which fails the call before the argument is looked at, as below.

From Location fails this call

An operation whose Secondary Lot Resolution Strategy is From Location cannot be started. The check runs before the secondary lot is resolved and raises:

IllegalArgumentException: Secondary lot resolution strategy 'FROM_LOCATION' is not supported for starting
inventory operations.

This happens whether or not secondaryLotIdOrName was supplied, because the strategy is rejected on its own, not the argument. Change the operation's strategy to Manual and pass the lot in the call, or to Auto Generate or Expression, before starting it.

executeInventoryOperation has no such check, so there From Location simply derives nothing.

Receive and Consume links its two lots both ways

A Receive and Consume operation writes two inventory lot records in one go, a receive and a consume, and both carry the same secondary lot. The two record types face opposite ways in track and trace: a receive reads as material arriving into the primary lot from the secondary lot, a consume as material leaving the primary lot into the secondary lot.

The trace graph therefore shows an edge in each direction between that one pair of lots. The secondary lot is both an ancestor and a descendant of the primary lot, and a trace that runs two levels or more comes back round to the lot it started from. This is expected for this operation type and is not corrupt data. No other operation type writes two records, so no other type does this.

Returns

Returns a JSON object of the inventory lot record of the inventory operation. The record will have a defined start time but a null end time, indicating the operation is currently active.

Example Usage

# Start the inventory operation
startedLotRecord = system.mes.inventory.operation.startInventoryOperation('01JPAND53P-BZ61RZHZ-V7C6EEHG', '01JPBC4H3V-J4X3FYKS-NRNVEKMM', None, None, None, None)

# Output the inventory lot record of the started inventory operation
print(startedLotRecord)