Create Related Record – adding a related record to the current record¶
The command "Create Related Record" creates a record on the other side of a relationship and links it to the current record – a position for an order, a note for a ticket. Unlike Create Entity Record, the current record stays the same. This page is for administrators who build actions that add data to an existing record.
1. At a glance¶
| Purpose | Create a related record without leaving the current record |
| Typical use | "Add note", "Add position", copying entries from one record to another |
| Where in the editor | Toolbar menu "Data" → "Create Related Record" |
| Needs a user interface | Only for "Show Form" |
| Needs a current record | Yes |
| Changes the current record | No |
| Related | Create Entity Record, Update Related Record, For Each Related Record |
2. Settings¶
The settings are on the tab "General", below "Display Name", "Description" and "Execution Condition" (see Actions), and on the tab "Set Fields".
| Setting | Meaning | Default / Required |
|---|---|---|
| "Relationship" | A relationship of the current record's entity. The current record is its parent side; the new record is of its child entity. | Required |
| "Show Form" | Opens the new record in a form for the user to complete | Off |
| "Save" | Saves the current record right away, together with the new related record. If the save is rejected, the action ends with an error. Ignored while "Show Form" opens a form. | Off |
| "Form ID" | Expression for the id of the form to open, evaluated against the current record. Only active with "Show Form". | Empty: the default form of the child entity |
The tab "Set Fields" works like in Create Entity Record: one entry per field of the child entity, with "Clear Value" / "Set Value" and a "Value" expression. "Append" adds the value to the end of what the field of the new record already holds – for example its default value – as text.
3. Behaviour¶
- Without a current record, without "Relationship", or if the relationship or its child entity no longer exists, the action ends (without an error).
- All value expressions are evaluated against the current record – that is how the note gets the number of the ticket.
- The related record is created and linked to the current record. The add limits of the user's roles apply.
- The fields of the new record are set; business rules that react on changed fields run.
- With "Show Form" and a user interface, the form of the new record opens and the action continues once it is loaded. If "Form ID" does not result in a form id, the action ends.
- Otherwise, with "Save" on, the current record is saved together with the new record. If the save is rejected, a user in the browser sees the reasons and the action ends with an error (see Save).
- Forms that are open are drawn again, so a related items grid shows the new record.
The current record does not change. Following commands still work on the order, not on the new position.
4. Examples¶
Add a note. Action on "Ticket", started by an app bar item "Add note":
| Setting | Value |
|---|---|
| "Relationship" | Ticket → Notes |
| "Show Form" | On |
| "Set Fields" | "Author" = current user, "Created" = now |
The user sees the form of the new note with author and date filled in.
Status history in the background. A background business rule on "Ticket" starts an action when the status changes. Its only command is Create Related Record with "Relationship" "Ticket → Status history", "Save" on, and the fields "Status" = status of the ticket and "Changed at" = now. Every status change leaves one entry.
5. Limitations¶
- "Append" joins texts. For numbers, compute the value in the value expression instead.
- "Show Form" does not ask about unsaved changes of the current record before the form opens.
- With "Show Form", the user sees the new record, while the following commands of the action still work on the current record.