Applying a Recipe to a Machine

Last updated

License feature: Recipe Management

Applying writes every parameter of a recipe to its tag, one after another. Activating a work order with Download recipe on start ticked does the same thing — see Work Orders.

Procedure

1. On Recipes, click the blue play icon, Apply to device.
2. Apply Recipe: {name} opens. Choose Target Device ("— Select Device —").
3. Choose For Work Order. The active order on that device is picked for you; "— None —" leaves the history row unlinked. The list is hidden when Work Orders is switched off.
4. Click Apply. There is no second confirmation — unless an admin has made Download a recipe to a device a signed action, in which case you re-enter your password (and a reason, if required) first. See Electronic signatures.
5. Read the result. "All parameters written successfully!" means every write was accepted; "Some parameters failed to write:" is followed by one tagPath: error line per failure. Under it, the read-back: "All N values read back and matched", or "N of M values read back different" with a "Label: sent X, read Y" line for each.
6. Click Done.

What happens, exactly

Step	Behavior
Checks	The recipe must exist, be Enabled, have at least one parameter, and have every value within its Min/Max. One out of limits refuses the whole download (400, naming the parameter).
Which device	A parameter's own Device is used. Target Device is used only for parameters whose Device was left at "— Select —".
Order	Parameters are written in the order listed, one at a time. Each waits for the driver's answer before the next.
Local tags	Written directly to the local tag.
Simulator devices	Written to the simulator.
Other drivers	Sent to the driver; values are converted back to raw units if the tag has scaling.
Failure	A failed write is reported and the remaining writes still run. Nothing is rolled back.
Verification	After the writes, every accepted parameter is read back and compared with what was sent. Local and simulator tags are read from their live value; other drivers are asked for the tag again after a 0.75 s pause, and scaled values are converted to engineering units first. Numbers match within the rounding a PLC REAL adds (12.3 reads back as 12.300000190734863); true/on equal 1 and false/off equal 0; text compares exactly, ignoring spaces at the ends. Nothing is rewritten or rolled back on a mismatch — it is reported.
Permissions	Editor or admin. Each tag's write security level is checked for you, as on any tag write; a refused tag is a failed parameter ("You do not have permission to write to this tag.") and the rest still run. Admins are never refused.
History	One row is added, with the status the writes earned: applied (all accepted and matched), mismatch (all accepted, some read back different), partial (some) or failed (none), and the read-back. Its Device is the Target Device and its Work Order is the one you chose.
Audit	Applied recipe "{name}" v{n} to device #{id} ({status}), with ", N read back different" when some did

Warning: Because a partial failure leaves the machine with a mix of old and new setpoints, read the result every time. If any write failed, fix the cause and apply again before running.

A safe way to test a new recipe is a simulator or local device — both accept writes.

Order your parameters deliberately

Put interlocked values in the order the PLC expects: for example, write the fill volume and time before the line speed, and put any "recipe loaded" or "start changeover" bit last so it is only set when the others were accepted — though it will still be written if an earlier write failed. If that matters, have the PLC check the values itself.

Using the API

POST /api/recipes/5/apply
Authorization: Bearer <editor JWT>
Content-Type: application/json

{ "deviceId": 3, "workOrderId": 12 }

Response:

{
  "success": true,
  "data": {
    "recipeId": 5, "version": 3, "deviceId": 3,
    "status": "partial",
    "allParametersWritten": false,
    "writeResults": [
      { "tagPath": "Filler.FillVolume_SP", "success": true },
      { "tagPath": "Capper.Torque_SP", "success": false, "error": "Write failed" }
    ],
    "verification": {
      "checked": 1, "matched": 1, "mismatches": []
    }
  }
}

success is true whenever the request ran; check status and allParametersWritten. verification lists each mismatch as { tagPath, label, expected, actual, error? } (actual is null when nothing could be read); it is null when nothing was written. Passing workOrderId fills the Work Order column in History. With signatures on for recipe downloads, add "signature": { "password": "…", "reason": "…" } to the body.

To apply a recipe when a work order starts, set downloadRecipeOnStart on the work order and activate it — POST /api/work-orders/:id/activate then answers with a recipeDownload summary:

{ "success": true, "recipeDownload": { "status": "partial", "written": 4, "total": 5, "failures": [{ "tagPath": "Capper.Torque_SP", "error": "Write failed" }] } }

status is applied, mismatch, partial, failed, or recorded when nothing was sent, and a verification object like the one above is included after a download. The field is absent when the order had no recipe or no download flag. Tags are written with the activating user's security levels. A workflow can also write setpoints with Set Tag nodes from a recipe kept in a data table, but workflows cannot read the built-in recipes.

REST endpoints

Method	Path	Purpose	Role
GET	/api/recipes	List; partNumber, enabled, search	viewer
GET	/api/recipes/history	History; recipeId, deviceId, workOrderId, limit, offset	viewer
GET	/api/recipes/:id	One recipe	viewer
POST	/api/recipes	Create (400 when a value is outside its Min/Max)	editor
PUT	/api/recipes/:id	Update (version bumps when parameters or steps change)	editor
DELETE	/api/recipes/:id	Delete	editor
POST	/api/recipes/:id/apply	Write parameters and read them back: deviceId required, workOrderId optional	editor
GET	/api/recipes/:id/versions	Every kept version, newest first	viewer
POST	/api/recipes/:id/versions/:version/restore	Make a version current again, as a new version	editor
GET	/api/recipes/by-part/:partNumber	The enabled recipe a part number selects, or null	viewer
GET	/api/recipes/part-selectors	Part number tags and what they last selected	viewer
POST	/api/recipes/part-selectors	Set a device's partNumberTag, autoDownload, enabled	editor
DELETE	/api/recipes/part-selectors/:deviceId	Remove a device's part number tag	editor

Troubleshooting

Message or symptom	Cause	Fix
"deviceId is required"	No Target Device chosen	Choose one.
"Recipe is disabled"	Enabled unticked	Edit the recipe and tick Enabled.
"Recipe has no parameters or parameters_json is corrupt"	No parameter rows	Add parameters.
"Recipe not found"	Deleted	Refresh.
Device #N not found for a line	The parameter's device was deleted	Edit the row's Device.
"You do not have permission to write to this tag." for a line	The tag has a write security level you don't hold	Ask an admin to grant the level, or to apply the recipe.
"Write failed" or a driver error	Device offline, tag read-only, wrong tag path, value the PLC rejects	Check the device connection and tag on its detail page; try writing the value there.
403 Insufficient permissions	Operator or viewer	Editor or admin required.
History says Recorded only	The row is a work order activation that was not set to download anything	Nothing was sent. Apply the recipe, or tick Download recipe on start on the work order.
"Speed: 1800 is above the maximum of 1500" (or below the minimum)	A value outside the parameter's limits	Fix the value, or the limit, in the recipe. Nothing was sent.
Status Mismatch	The device accepted a write but holds a different value	Look at "sent X, read Y": the PLC may clamp the setpoint, overwrite it from its own logic, or the tag's type may not hold the value (12.3 into an INT reads 12).
Read-back says "nothing (could not read)"	The driver could not read the tag back (offline, read error, bad quality)	Check the device; the write itself may still have landed.

See also

• Recipes: Creating, Versions and History
• Work Orders
• Input / Output Nodes
• Custom Pages