> 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/applets/prepare-your-data-structure.md).

# Prepare Your Data Structure

After planning the Applet’s workflow, confirm that the required data structure is available.

This does not mean every value used by the Applet must be stored in a database. Some information must persist in tables, while other information is needed only temporarily and can be managed within the Applet.

The objective is to determine:

* Which information must be stored permanently.
* Which existing tables the Applet will use.
* Whether any new tables or fields are required.
* Which information can remain local to the Applet.
* How records will be identified and retrieved.

### Review the data requirements

Begin with the information identified in the Applet plan.

For each value, consider whether the Applet must:

* Retrieve it from existing data.
* Display it without changing it.
* Add it as part of a new table record.
* Update it in an existing table record.
* Use it temporarily while the Applet is running.
* Use it to make a workflow decision.
* Include it in a collection of multiple items.

This review helps separate stored business data from temporary Applet data.

### Decide what must be stored in a table

Information should generally be stored in a table when it must:

* Remain available after the Applet closes.
* Be retrieved during a future session.
* Be shared with other Applets or users.
* Represent the current state of an item or process.
* Be included in reports or exports.
* Be accessed through an API connection.
* Be maintained as part of an ongoing business record.

For example, an item’s identifier, current status, location, and assignment may need to remain available after a transaction is completed. Those values would normally belong in a table.

### Identify temporary Applet data

Not every value requires a table field.

Information can remain local to the Applet when it is needed only to:

* Hold temporary user input.
* Control navigation.
* Track a selection or workflow state.
* Store an intermediate calculation.
* Build a value before it is saved.
* Display a temporary message or result.
* Maintain a working collection during the current process.

DC Works can manage this information through:

| Applet data option | General purpose                                                    |
| ------------------ | ------------------------------------------------------------------ |
| Local record       | Holds a group of related values used within the Applet             |
| List record        | Holds multiple entries that the Applet can process as a collection |
| Local variable     | Holds an individual temporary value                                |

These items are configured after the Applet is created. Detailed instructions are provided in **Records, Data, and Local Variables**.

{% hint style="info" %}
Use table-based data when information must persist or be shared. Use local records and variables when information is needed only while the Applet is operating.
{% endhint %}

### Review existing databases and tables

Before creating anything new, review the databases and tables already available in DC Works.

Determine whether an existing table:

* Stores the correct type of record.
* Contains the fields the Applet requires.
* Uses terminology consistent with the planned workflow.
* Can be accessed by the appropriate users.
* Is already used by another Applet or integration.
* Contains the records the Applet needs to retrieve or update.

Reusing an appropriate table keeps information centralized and reduces unnecessary duplication.

Do not use an existing table merely because it contains some similar fields. Confirm that one record in the table represents the same type of item or activity required by the Applet.

### Confirm what one table record represents

Each table used by the Applet should have a clear record definition.

Complete the following statement:

> One record in this table represents one \_\_\_\_\_\_\_\_\_\_.

Examples might include:

* One physical item.
* One employee.
* One work request.
* One inspection.
* One valid status.
* One transaction.

All user-created fields in the table should describe that same type of record.

If a table combines fields describing unrelated types of records, review whether the structure should be simplified or separated before using it in the Applet.

### Review the required fields

Confirm that each table contains the fields needed by the planned workflow.

For each field, verify:

* The field name clearly describes the stored value.
* The data type matches the information.
* The field belongs in that table.
* The value must persist after the Applet closes.
* The Applet needs to retrieve, add, or update it.
* The field is not an unnecessary duplicate of another value.

Also identify any required information that should remain local to the Applet rather than being added to the table.

Detailed instructions for adding or modifying table fields are provided in **Define and Manage Table Fields**.

### Confirm the primary field

Review the table’s primary field and confirm that it provides a useful way to identify or display its records.

Typical primary fields include:

* Item ID.
* Serial Number.
* Request Number.
* Employee Name.
* Location Name.
* Status.

The primary field is different from the system-generated **Row Key**. The Row Key uniquely identifies the record internally, while the primary field provides the principal user-facing reference.

{% hint style="info" %}
A primary field does not automatically require every value to be unique. Choose the field that most clearly represents the record to users and Applets.
{% endhint %}

### Identify how records will be found

Consider how the Applet will retrieve the correct table record.

A record might be found using:

* A scanned barcode.
* A serial number.
* An item ID.
* A request number.
* A selected status.
* A user-entered search value.
* A value received from another page or record.

Confirm that the value used for retrieval:

* Exists in the table.
* Uses a consistent format.
* Can be collected or provided by the Applet.
* Reliably identifies the intended record or group of records.

For example, if an Applet scans an identifier formatted as `EQ-1001`, the table should store that identifier in the same format.

### Prepare reusable selection values

Some Applets require consistent selections such as:

* Statuses.
* Categories.
* Locations.
* Departments.
* Operators.
* Reason codes.

These values may be stored in a separate table when they need to be reused, centrally maintained, or retrieved dynamically.

A separate table may not be necessary for every short or fixed selection. Use one when it provides a practical benefit to the Applet or the broader process.

Detailed configuration can be introduced when these values are connected to Applet fields.

### Create or update the required structure

If the necessary structure does not already exist, use the **Databases and Tables** chapter to:

* Create a database.
* Create a table.
* Define its fields.
* Select its primary field.
* Add or import initial records.
* Assign table permissions.

The Applets chapter assumes that any required persistent table structure is available before table-based records are configured.

{% hint style="warning" %}
Review existing Applets and integrations before changing an established table. Renaming or deleting fields may affect anything that currently uses them.
{% endhint %}

### Add sample data for testing

When practical, add a small number of representative records before building the Applet.

Include enough variety to test:

* A normal record.
* Different statuses or categories.
* Missing optional information.
* A record that should follow an alternate workflow path.
* Values that may produce validation or retrieval errors.

Sample records make it easier to test record retrieval, field binding, conditions, and updates while the Applet is being developed.

Avoid using sensitive or production-critical information solely for testing.

### Prepare a data map

Before creating Applet records, summarize how the planned information will be handled.

| Information                  | Needed from               | Persists after use? | Planned Applet handling             |
| ---------------------------- | ------------------------- | ------------------- | ----------------------------------- |
| Existing stored value        | Table                     | Yes                 | Table-based record                  |
| New or updated business data | Applet input and table    | Yes                 | Table-based record and table action |
| Group of temporary values    | Applet                    | No                  | Local record                        |
| Multiple working entries     | Applet or table retrieval | As required         | List record                         |
| Individual temporary value   | Applet                    | No                  | Local variable                      |

The exact Applet records and variables will be created later, but this map provides a clear starting point.

{% hint style="info" %}
Connecting an Applet record to a table does not by itself write information to that table. Table data is written through the appropriate record actions, such as adding or appending a record.
{% endhint %}

### Data-readiness checklist

Before continuing, confirm that:

* The information that must persist has been identified.
* Temporary Applet data has been separated from stored data.
* The required databases and tables exist.
* Each table has a clear record purpose.
* The necessary fields and data types are available.
* The primary field provides a useful reference.
* The Applet has a reliable way to find the required records.
* Initial selection values or reference records are available where needed.
* Table permissions allow the intended users to perform the required operations.
* Representative records are available for testing.

The structure does not need to anticipate every future feature. It needs to support the Applet’s current workflow clearly and reliably.

### Next

Continue to **Applet Editor Overview** for an introduction to the workspace used to create and configure Applets.


---

# 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/applets/prepare-your-data-structure.md?ask=<question>&goal=<endgoal>
```

`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.