Create Entity Record – creating a record and working on it¶
The command "Create Entity Record" creates a new record of an entity, optionally fills fields, links it to the current record and opens it in a form. The new record becomes the current record of the following commands. This page is for administrators who build actions that create data.
1. At a glance¶
| Purpose | Create a record and continue the action on it |
| Typical use | "Create invoice" from an order, "New ticket" from a dashboard, creating a record from a received mail |
| Where in the editor | Toolbar menu "Data" → "Create Entity Record" |
| Needs a user interface | Only for "Show Form" |
| Needs a current record | Only for "Relationship" |
| Changes the current record | Yes – to the new record |
| Related | Create Related Record, Update Entity Record, Save, Change Context |
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 |
|---|---|---|
| "Entity" | The entity of the new record | Required |
| "Relationship" | Optional relationship of the current record's entity. The new record is linked to the current record through it. The current record has to be on the parent side, the new record's entity on the child side. | Empty: not linked |
| "Show Form" | Opens the new record in a form for the user to complete | Off |
| "Save" | Saves the new record right away. 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 new record. Only active with "Show Form". | Empty: the default form of the entity |
On the tab "Set Fields", every entry ("Value Templates") sets one field of the new record:
| Part | Meaning |
|---|---|
| "Field" | A field of the selected entity |
| "Clear Value" / "Set Value" | Leave the field empty, or set it to the value |
| "Value" | Expression for the value. For fields with a list of valid values, the editor offers them as quick values. |
| "Append" | Adds the value to the end of what the field of the new record already holds – for example its default value – as text, instead of replacing it |
3. Behaviour¶
- If "Show Form" is on and a user is working with the action, the user is first asked what to do with unsaved changes of the current record ("Save", "Discard", "Cancel"). "Cancel" ends the action.
- Without "Entity", or if the entity no longer exists, the action ends (without an error).
- All value expressions are evaluated against the record that is current before the new record exists. That is how a value is copied from the order to the new invoice.
- The record is created. The add limits of the user's roles are checked at this moment; if they do not allow it, the command fails. Business rules that run on load and default values are applied as for a record created by hand.
- If "Relationship" is set and there is a current record, the new record is linked to it.
- The new record becomes the current record.
- The fields are set one after another. Business rules that react on changed fields run as if a user had typed the values. Fields that do not belong to the entity are skipped. With "Append", the value is added to what the field holds after the default values.
- With "Show Form" and a user interface, the form opens and the action continues once it is loaded. Saving is left to the user; "Save" is ignored. If "Form ID" does not result in a form id, the action ends.
- Otherwise, with "Save" on, the new record is saved. Without a user interface, "Show Form" is ignored and "Save" applies. If the save is rejected, a user in the browser sees the reasons and the action ends with an error (see Save).
Without "Save" and without a later Save, the record is not stored. In a background run it is lost when the action ends.
4. Examples¶
Invoice from an order. Action on "Order":
| Setting | Value |
|---|---|
| "Entity" | Invoice |
| "Relationship" | Order → Invoices |
| "Save" | Off |
| "Set Fields" | "Amount" = field "Total" of the order; "Due date" = today plus 30 days |
Followed by Update Entity Record for further fields of the invoice, then Save, then Change Context back to the order.
New ticket in a form. A dashboard button runs an action without entity: Create Entity Record "Ticket" with "Show Form" on and "Priority" = "Normal". The user sees the new ticket in its form and saves it.
5. Limitations¶
- "Append" joins texts. For numbers, compute the value in the value expression instead.
- "Relationship" only offers relationships of the current record's entity. If the action has no current record at that point, the new record is created without a link.