How to create and configure an auxiliary table

Creating an auxiliary table has two steps: first you give the table a name and choose how it will be fed; then you define the fields, that is, the columns each record will have. Records can only be registered after the fields exist.

Who can create

You need the Manage auxiliary tables permission. To create a Company table, you also need to be a company manager. Learn more...

1. Create the table

1. Go to Auxiliary tables from the Main Menu;
2. In the list of tables, click the + button (New table);
3. In the New auxiliary table window, fill in:
   • Table name: the name that will appear in the list and in the question configuration, for example "Collaborators";
   • Description: an optional text explaining what the table is for;
   • Icon (optional): an icon to identify the table in the list;
4. Under How the table will be fed, choose an option:
   • Manual input: "Type the items in or import an Excel spreadsheet. You define the table attributes.";
   • Via API: "The data is sent by an external system through an HTTP POST request." Use this option when the list already exists in another system of your company (HR, ERP etc.) and the IT team will keep it up to date automatically;
5. If you are a company manager, also choose the Scope: Workspace or Company — Learn more about the difference;
6. Click Create.

The table appears in the list already selected, ready to receive its fields.

Creating a workspace auxiliary table, with manual input

Table shared between workspaces

To create a Company table, with filters per workspace, see the step by step in Company Tables.

2. Define the fields

With the table selected, the Fields block shows the table columns. "Each field has a title (shown to the user), a name (internal identifier) and a data type."

1. Click Add field;

2. Fill in the Title, for example "Employee ID". The Internal name is suggested automatically from the title, for example employee_id, and can be adjusted;

3. Choose the field Type:

   Type	When to use	Example
   Text	Any free text.	Name, job title, address
   Number	Numeric values, which can be compared (greater than, less than) in filters.	Capacity, numeric code, amount
   Selection	Text with a few values that repeat. In filters, the values already registered appear in a list for you to choose from, instead of typing them.	Department, state, category

4. Check the Key option on the field that identifies each record without repetition, such as the employee ID or the code;

5. Repeat for the other fields. Use the Move up and Move down arrows to change the order;

6. Click Save fields.

If you change your mind before saving, Discard changes returns the table to its saved state.

Defining the table fields and choosing the key

Field rules

• The key should not repeat. The key is how the system recognizes each record: when importing a spreadsheet or receiving data through the API, a row with the key of an existing record updates that record instead of creating another one. Keeping the key unique is the responsibility of whoever feeds the table;
• The Internal name cannot be changed once the table is in use (records, questions, filters or API). The Title can be changed at any time.

The Internal name is used in several places

The Internal name is what appears between braces in the display template of questions (for example {employee_id}), in the headers of the import spreadsheet and in the data sent through the API. Choose short, clear names from the start.

3. Changing the structure of a table in use

Some field changes force the system to reprocess every record already stored:

• changing a field Type (for example, from Text to Number);
• changing which field is the Key;
• removing a field, along with every value stored in it.

When you click Save fields after one of these changes, the Confirm structure change window appears. It shows how many records will be reprocessed and warns about possible problems, such as records that will end up with no key or with a duplicate key.

When the change is a Type change and some values cannot be converted (for example, the text "ABC" in a field that will become Number), choose what to do:

Option	What happens
Discard the incompatible values	The change is applied and values that cannot be converted are deleted. They cannot be recovered afterwards.
Cancel the change	If any value cannot be converted, nothing changes: the type and the records stay as they are.

If the change affects filters of questions that use the table, the window also lists those questions: the filters that depended on the changed field will be removed, and those questions will start offering more records.

Reprocessing happens in the background. Until it finishes, the table does not accept other changes. At the end, you receive the "Reprocessing completed" notification, which opens the table when clicked.

Check before confirming

Structure changes can delete data. In large tables, the numbers in the window are an estimate based on a sample of the records. If in doubt, keep a copy of the original spreadsheet before confirming.

4. Editing and deleting a table

Hover over the table in the list and click the More options... button to see:

• Edit: opens the Edit auxiliary table window, where you change the name, description, icon, feeding mode and scope. The icon can also be changed by clicking it, next to the table name;
• Delete: opens the Delete auxiliary table window.

Before deleting, the window shows the impact: which forms and how many questions use the table, or how many records will be deleted. When there are questions or records, the system asks for a security check (a small sum to answer) before enabling the Delete table button.

After deletion, "the affected questions will be flagged with a warning and will need to be reconfigured": in the form editor, they show the message "This question references an auxiliary table that was deleted. Configure a new table for this question."

Change that is not allowed

A Company table cannot go back to being a Workspace table.

When changing from Via API to Manual input

The change is allowed, but the integration token is discarded. If the table goes back to Via API, a new token must be generated. Learn more...

5. Common problems

What you see	What to do
The Auxiliary tables item does not appear in the Main Menu	The Manage auxiliary tables permission is missing; ask the workspace administrator.
"Feature not available in your plan"	The workspace plan does not include Auxiliary Tables. Use the "Contact support" link.
"Define the table fields before adding records."	The table has no saved fields yet. Define them and click Save fields.
The Internal name cannot be edited	The table is already in use (records, questions, filters or API). Adjust only the Title.
The Scope option does not appear in the window	You are not a manager of any company; the table will be created in the workspace.
I cannot edit the fields of a company table	Only company managers can change it. For everyone else, it is available for reference only.
A notice says the table has "inconsistent data"	A structure change failed and could not be undone. The table is not synced to the app until it is fixed. Try to fix it manually or contact support.

Next steps

• Learn more about how to register the records;
• Learn more about company tables;
• Learn more about how to use the table in a form.