> For the complete documentation index, see [llms.txt](https://docs.amltd.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amltd.com/dc-works/core-concepts/understanding-databases-tables-and-records.md). # Understanding Databases, Tables, and Records Databases and tables define how persistent information is structured and stored in DC Works. Applet records provide the working data used by fields, actions, and conditions. A record can hold one entry or a list of multiple entries, and its information is not necessarily stored in a table. ```mermaid flowchart TD T["Database Table"] <--> R["Applet Record"] R <--> F["Applet Fields"] A["Actions and Conditions"] --> R ``` ### Databases A **database** is a container used to organize related tables. For example, an asset-management solution might use one database containing tables for: * Assets * Employees * Locations * Asset transactions * Maintenance history Keeping related tables within the same database makes a solution easier to understand and manage. ### Tables A **table** stores persistent information. It contains table fields that define the information each stored entry may contain. For example: | Table | Information stored | | ------------------ | ------------------------------------ | | Assets | Items being tracked | | Employees | People using or receiving assets | | Locations | Places where assets are stored | | Asset Transactions | Check-ins, check-outs, and transfers | Each table should have a clear purpose. Avoid combining unrelated types of information in a single table. ### Table fields **Table fields** define the structure of the information stored in a table. They are similar to columns in a spreadsheet. An asset transaction table might include: * Asset number * Description * Location * Condition * Employee * Transaction date and time * Notes Each table field should use an appropriate data type. ### Applet fields An **Applet field** is a control or element placed on an Applet page. Depending on its type and configuration, it may display information, accept user input, initiate an action, or help control the workflow. An Applet field can be connected to a value within an Applet record. That record may: * Store a value locally within the Applet. * Receive a value set by an action. * Receive information retrieved from a table. * Provide information that will be added or appended to a table. * Hold information used by conditions or other actions. {% hint style="info" %} In DC Works, a table field defines stored data, while an Applet field is part of the user interface. An Applet field can be tied to a value in an Applet record, which may then interact with a table. {% endhint %} ### Understanding Applet records A **record** in an Applet is a working data object used by fields, actions, and conditions. It can contain a single set of values or a list containing multiple entries. A record may exist locally, receive information from a table, or provide information that an action later adds or applies to a table. A record can be: * **Local** — Its values exist within the Applet and are not necessarily stored in a table. * **Populated from a table** — Its values are retrieved from an existing table entry. * **Used to update table data** — Its values can be applied to an existing table entry. * **Appended to a table** — Its values can be added as a new entry in a table. This distinction is important: creating or changing a value in an Applet record does not automatically create or change an entry in a table. ### Single records and record lists An Applet record can hold: * A **single entry** containing one set of field values. * A **list of entries** containing multiple sets of field values. A single record might hold the information for one selected asset: | Asset Number | Description | Location | | ------------ | --------------- | --------- | | LT-1042 | Shipping Laptop | Receiving | A record list can hold several assets: | Asset Number | Description | Location | | ------------ | --------------- | --------- | | LT-1042 | Shipping Laptop | Receiving | | SC-2081 | Barcode Scanner | Warehouse | | TB-3015 | Rugged Tablet | Shipping | Record lists are useful for: * Displaying multiple table entries. * Showing search or filtered results. * Allowing a user to select an entry. * Passing the selected entry to another page or record. * Processing multiple entries within a workflow. ```mermaid flowchart LR T["Table"] --> Q["Retrieve or Filter"] Q --> L["Record List"] L --> S["Selected Entry"] S --> F["Applet Fields"] ``` A record list does not necessarily mean that the entries are stored locally or newly added to a table. The list may contain information retrieved from a table or values assembled within the Applet. {% hint style="info" %} A record can contain one entry or a list of multiple entries. Actions determine whether information is retrieved, selected, added, appended, or updated in a table. {% endhint %} ### Local records A **local record** holds working information within the Applet. For example, an Applet may use a local record to hold: * A scanned asset number. * A temporary status. * A calculated value. * A user’s selection. * A value used to evaluate a condition. * Information collected across several pages. Actions can set values within the local record, and conditions can evaluate those values to determine what happens next. ```mermaid flowchart LR U["User input"] --> F["Applet Field"] F --> R["Local Record"] R --> C["Condition"] C --> A["Next Action"] ``` The information remains local unless an action explicitly uses it to add, append, or update information in a table. ### Records connected to tables An Applet record may also retrieve information from a table. For example: 1. A user scans an asset number. 2. The scanned value is placed in a local record. 3. An action searches a table for the corresponding asset. 4. The table information is retrieved into an Applet record. 5. Applet fields display the retrieved values. 6. The user may then view or modify that information. Retrieving information allows the Applet to work with table data, but it does not by itself add a new entry to the table. ### Adding or appending a record Information becomes a new stored table entry when an **Add** or **Append Record** action is performed. A typical data-capture workflow is: ```mermaid flowchart TD I["Enter or scan data"] --> L["Store values in Applet Record"] L --> V["Validate with Conditions"] V --> P["Add or Append Record"] P --> T["New Table Entry"] ``` Until the Add or Append action occurs, the values may exist only within the Applet record. {% hint style="info" %} Setting a record value does not automatically save it to a table. The workflow must include the appropriate action to add, append, or update the table data. {% endhint %} ### Updating an existing table entry Adding a new entry and updating an existing entry are different operations. * **Add or Append** creates a new entry in the table. * **Update** changes an entry that already exists. * **Retrieve** obtains information from an existing table entry. * **Set** assigns a value within an Applet record. The exact action should match the intended workflow. Otherwise, an Applet might create duplicate entries, overwrite unintended information, or leave data only in a local record. ### Example: Asset Check-In In the Getting Started solution, the Applet can collect asset information in an Applet record before it is stored. A simplified workflow is: 1. The user enters or scans the asset information. 2. Applet fields place the values into an Applet record. 3. Actions and conditions may validate or modify those values. 4. An Add or Append action records the check-in as a new table entry. 5. The stored entry can later be retrieved, displayed, or updated. ```mermaid flowchart LR F["Applet Fields"] --> R["Applet Record"] R --> A["Append Action"] A --> T["Asset Check-In Table"] ``` ### Plan the data structure first Before building the Applet, consider: * What information must be stored permanently? * What information is needed only temporarily? * Which values should use local records? * Which records must retrieve information from tables? * When should a new table entry be added? * When should an existing entry be updated? * Which conditions must be satisfied before information is saved? * Will several Applets need to use the same stored information? Separating temporary Applet data from persistent table data helps prevent unnecessary entries and makes workflows easier to manage. ### Use clear names Use names that identify both the purpose and role of the information. Examples include: * `New Asset Check-In` * `Current Asset` * `Selected Transaction` * `Scanned Asset Number` * `Destination Location` Clear record and field names make actions, conditions, and data connections easier to understand. ### Key distinction Remember the following: | Element | Purpose | | --------------------- | -------------------------------------------------------------------------------- | | Database | Organizes related tables | | Table | Stores persistent entries | | Table field | Defines the information stored in a table | | Applet field | Displays, collects, or controls information | | Applet record | Holds values used by Applet fields, actions, and conditions | | Local record | Holds working data that is not necessarily stored | | Retrieved record | Holds information obtained from a table | | Add or Append action | Creates a new entry in a table | | Update action | Changes an existing table entry | | Single record | Holds one set of related values | | Record list | Holds multiple entries within one Applet record | | Selected record entry | One entry selected from a record list for viewing, editing, or use in a workflow | ### Next Continue to **Understanding Applets** to learn how Applet pages, fields, records, actions, and conditions work together. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amltd.com/dc-works/core-concepts/understanding-databases-tables-and-records.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.