- Who can: a member of the brand whose role allows it on that data model, in the “Entities” group of the role: “Read” to find and read records, “Create”, “Update” and “Delete”, and the operation “Link records”.
- Where in Cargofy: Studio › Data models, and the interfaces built on them
What it is
Your data models, such as shipment requests, customers or rate tables, are open to the assistant like any other object. Each one is named dm: plus the model’s key, for example dm:demo-customer for “Demo: Customer”. The key does not always follow the name — “Demo: Shipment request” is dm:demo-zaiavka-na-perevezennia — so the assistant takes it from the list of objects. The assistant adds records, finds them by their fields, changes, deletes and links them, and tells you which workflows ran on a record.
Important
The assistant saves and deletes at once, without asking, and a deleted record cannot be restored through it. A new, changed or deleted record starts the workflows that run on that event: steps Cargofy runs on its own, which can give a person or a Digital Worker a task.
Start the chat with “Tell me what you will save or delete and wait for my yes.” Before a change, ask the assistant which workflows it starts, for example “Which workflows start when a request is added?” A member who only needs to look things up is safest with a role that allows “Read” only.
What it can do
A shipment request from start to finish
A dispatcher’s conversation with the assistant and Cargofy’s real answers, on the data models “Demo: Shipment request” and “Demo: Customer”. Each request belongs to one customer. The terms are in the Glossary. The tools behind each step are in the table at the end; you do not type their names, the assistant uses them. Dates on this page are examples.
1. Add the request for its customer
Add a request for Demo: Customer Lviv Steel: Demo: Kyiv → Uzhhorod, loading on November 27, 2026, 12 t, curtainsider.
Cargofy saves the request — route “Demo: Kyiv → Uzhhorod”, loading date 2026-11-27, 12,000 kg, body type “Curtainsider” — and links it to the customer in the same step. The weight field is in kilograms, so the assistant turns 12 t into 12,000. You name the body type as you see it in Cargofy, “Curtainsider”; the assistant sends the value Cargofy stores, tent.
2. See what the new request started
Which workflows ran on this request?
Two demo workflows started on the new request. “Demo: Process shipment request” gave a Digital Worker — an AI worker set up in Studio — the task “Demo: Check new shipment request”; its run shows “waiting” until the worker finishes. “Demo: Run that fails” ran too; its run ended with “completed”, the status of a finished run.
3. Find requests
Which requests load between November 24 and 30, 2026 and weigh at least 10 t?
The assistant lists every request that matches, with route, loading date, weight and body type, and says how many there are.
4. Change the request
Set the weight of Demo: Kyiv → Uzhhorod to 15,000 kg.
Cargofy changes only the weight. The route, the date, the body type and the customer stay as they were.
5. Delete the request
Delete the request Demo: Kyiv → Uzhhorod.
Cargofy deletes it.
| Step | Tool | What the assistant sends |
|---|---|---|
| 1 | entities-schema, entities-query, then entities-create | the schema of dm:demo-zaiavka-na-perevezennia (a model it does not know yet it finds with entities-list); the customer found by search; then fields — route, loading_date as YYYY-MM-DD, weight_kg as a number, body_type as tent — and links with the relationship id and the customer’s id |
| 2 | config-workflow-runs | the request’s id from step 1 as record_id |
| 3 | entities-query | filters loading_date between ["2026-11-24", "2026-11-30"] and weight_kg gte 10000 |
| 4 | entities-query, then entities-update | the request’s id and only weight_kg: 15000 |
| 5 | entities-query, then entities-delete | the request’s id |
Add a record
Add a customer: Demo: Customer Kraków Metal, Poland, Kraków, office at ulica Demo 1, Kraków.
The assistant reads the model’s fields first: which are required, which values a list field takes and which list depends on another. It sends the value of a list field, not its label: “Poland” is pl, “Kraków” is krakow. A missing or wrong field is refused with the field’s name, and nothing is saved; the assistant reads the answer and tells you what to fix.
- Required fields. A record without them is refused.
- Lists that depend on another field. “City” takes only the cities of the chosen “Country”: Warsaw and Kraków for Poland. Another city is refused.
- Dates. Give a date with the year; the assistant sends it as YYYY-MM-DD.
- Numbers. A number field takes a plain number in its unit: “15 t” in a kilogram field is sent as 15000.
- Text. Saved exactly as you write it.
- Addresses. For a location field, the assistant can send the address only, as an object:
{"address": "ulica Demo 1, Kraków"}. Cargofy adds the coordinates. - Fields the model does not have. Refused with the list of fields that can be written.
- Duplicates. Ask the assistant to find the record first, so you do not add the same customer twice.
The answer is the saved record. A new record starts the workflows that run on new records of that model, see Workflows on record changes.
Find records
Show reefer and isothermal requests. Which requests have no weight? Find the customers in Poland.
What you can ask depends on the field type:
| Field type | You can ask |
|---|---|
| Text | equals, one of a list, contains, is empty |
| Number | equals, one of a list, is empty, more or less than, at least, at most, between |
| Date | equals, is empty, after or before, on or after, on or before, between. The ends of a range are included |
| List (select) | equals, one of a list, is empty. You name the label; the assistant filters by the value |
| Yes / No, location, member | equals, is empty |
“Equals” on text matches capital letters exactly: “Demo: Customer Kyiv Foods” finds the customer, “demo: customer kyiv foods” does not. “Contains” and text search ignore capital letters. Text search looks in every text field of the model, for example the route of a request or the company of a customer. When you name several conditions, a record must match all of them.
The answer gives the number of records found. Up to 20 records come at once, up to 100 when you ask for more. Say “show the next ones” for the next page, or “send me the whole list as a file”. See How it works for pages and exporting to a file.
Change a record
Change the body type of Demo: Kyiv → Uzhhorod to isothermal and clear its weight.
The assistant finds the record, then sends only the fields you name. The others keep their values. A changed value starts the workflows that run on “updated”. A field that is not required can be cleared — the assistant sends it empty, as null; a required field cannot. When your words fit several records, ask the assistant to list them first. The same checks apply as when you add a record.
Delete a record
Delete the request Demo: Kyiv → Uzhhorod.
The assistant finds the record first; when your words fit several, ask it to list them before it deletes. Workflows that already started on the record are not stopped.
Link records
Link the request Demo: Kyiv → Lviv to Demo: Customer Kyiv Foods.
Two data models can be related, for example customers and their requests. The schema of each model lists its relationships: the ID, the model on the other side and how many records each side holds. The assistant links a new record in the same step that creates it, or links two existing records with the operation link of entities-run-operation.
In “one customer, many requests”, a request holds one customer: a request already linked to a customer cannot be linked to another one.
Workflows on record changes
Which workflows start when a request is added? Did anything run on Demo: Kyiv → Lviv?
Each data model has three events a workflow can start on: a record created, updated and deleted. “Updated” starts a workflow only when a value changes: saving the same value starts nothing. Each record starts its own runs: ten new requests start ten runs of each workflow. Only published workflows run; workflows are built and published in Studio, outside the assistant.
To answer which workflows start on an event, the assistant lists your workflows with config-surfaces-list and reads each published one started by an event with config-get: its trigger names the data model and the event.
For one record, the assistant reads its runs with config-workflow-runs: workflow, status, start and finish time, the step that failed. See Studio.
Glossary
The words of this page, what they mean in Cargofy and the name the assistant works with. The last column is for the assistant: paste this table into the chat or add it to your assistant’s project knowledge, and it reads your words the same way Cargofy does.
| Term | Meaning | The assistant sees |
|---|---|---|
| Data model | A record type you built in Studio, such as “Demo: Shipment request” | the object dm:<key>, for example dm:demo-customer; the key of each model in entities-list |
| Record | One entry of a data model, such as the request Kyiv → Lviv | id (a UUID), display_value, data |
| Main field | The field that names the record, such as the route | display_value |
| Field | One value every record of the model keeps | a key of data, for example data.route; the list in entities-schema |
| Required field | A field every record must have | required: true |
| List field | A field with fixed choices; the label is what you see, the value is what is stored | allowed_values; labels in config.options |
| Dependent list | A list whose choices depend on another field, such as the city on the country | config.depends_on; parent_values of each option |
| Body type | Demo model only. The list field of a request: “Curtainsider” (tent), “Reefer”, “Isothermal” | body_type: tent, reefer, isotherm |
| Loading date | Demo model only. The date field of a request | loading_date, YYYY-MM-DD |
| Weight | Demo model only. The weight of a request, in kilograms | weight_kg |
| Customer | Demo model only. The customer model; each request has one | dm:demo-customer; fields company, country, city, office_address, active |
| Location field | An address with map coordinates, such as the office of a customer | an object: address, and lat, lng, place_name once Cargofy adds them |
| Filter | A condition on one field | field, op: eq, in, contains, is_null, gt, gte, lt, lte, between |
| Text search | Words looked up in every text field | search |
| Relationship | A link type between two data models, with “one” or “many” on each side | relationships in entities-schema: id, source_cardinality, target_cardinality |
| Link | One record tied to another | links in entities-create, or the operation link with relationship_id and target_record_id |
| Record events | What a workflow can start on | “created”, “updated”, “deleted” in config-events-list |
| Workflow started by an event | A workflow bound to a record event | trigger_type: event and published in config-surfaces-list; trigger_config with type_slug (the model) and action (the event) in config-get |
| Workflow run | One time a workflow ran on a record | config-workflow-runs with record_id |
Limits
- Records cannot be sorted. Ask for a date range, or narrow the question by a field.
- File fields cannot be written.
- The assistant cannot change a model’s fields, list values or relationships; they are changed in Studio, outside the assistant. It can read them, see Studio.