Use table workspace variables to conveniently manage data that is best presented in tabular form. These variables enable simple visualization and presentation of tables, enhancing the clarity and accessibility of your data. Easily automate processes to respond to table updates or update data in tables, further streamlining your work and increasing efficiency.
Creating a Table: Setting the Table Schema
You can create tables both automatically and manually:
Automatically:
Use the Create a workspace variable step:
Give the table variable a meaningful name. The programmatic name will be derived from the pretty name by converting it to lowercase, removing special characters, and replacing spaces with underscores.
Select table as the data type.
Specify the table columns (see step 2 below).
Specify a Torq integration to execute the step.
Manually:
Navigate to the Workspace Variables Page: Go to Build > Workspace Variables.
Create a New Workspace Variable: Click the + icon in the Variables column and set the variable type to Table. Give the table variable a meaningful name.
Define the Table Schema: Set the table schema by specifying the table columns. The table is created with these default columns:
id: The row index.
created_by: Indicates who created the row.
created_at: Indicates when the row was created.
updated_by: Indicates who updated the row.
updated_at: Indicates when the row was updated.
Column names must begin with a letter (a-z) or an underscore (_). Subsequent characters can be letters, digits (0-9), or underscores.
Some names are reserved because they are SQL keywords.
Cells support long text, boolean, number, or JSON formats.
Table workspace variables have the following guardrails for optimal performance and stability.
Working with tables
You can perform actions on tables both manually and automatically.
Automatic Actions
Use steps to operate on tables automatically:
Insert Into Table: Add new data entries.
Update Table: Modify existing data.
Delete From Table: Remove data entries.
Query Table: Utilize the step optional parameters to retrieve specific columns, sort data, and filter cells based on specified conditions.
Update a workspace variable: Update the table schema.
To run these steps, you need a Torq integration.
Manual Actions
In the Workspace Variables page, at the top right of the table preview, you can:
Add Rows: Insert new data into the table.
Modify the Table Schema: Add columns to expand the table structure.
Delete Rows: Remove unwanted data.
Revert Unsaved Changes: Undo any modifications that haven't been saved.
Example: Add User Information to a Table
In this example, we aim to collect user responses to a survey in a table format. To start, we'll populate the table with the users we want to survey. In this case, these are users who have been locked out of Okta.
The table schema is automatically populated when you select the table name.
Triggering Workflows Upon Table Updates
Use the System Events > Variable updated trigger to automate a response to table updates.
The Variable Updated internal trigger applies only to table workspace variables and does not support the other variable types: text, JSON, number, or boolean.
Example: Trigger a Workflow When a New Row Is Added
Create a workflow that's triggered whenever a new row is added to the table:
Use the System Events > Variable updated trigger.
Add trigger conditions to specify the table name and the exact type of update that will activate the workflow.
In this example, the new row contains the email address of the user to be surveyed.
3. The workflow will automatically send survey questions to the user.
4. The answers are recorded directly in the same table row, streamlining the data collection process.
Query a Table
Use the Query Table step to extract table values.
Use the optional parameters in the Query Table step to make your query more specific. Otherwise, the entire table content will be returned.
Specify the table name from which you want to extract information.
Select optional parameters to narrow down your query:
Selected columns: Choose the specific columns to return values from.
Conditions: The filter criteria for the table. Specify the column values to return (see example below.)
Sort by column: Specify the column by which to sort the results.
Sort order: The order by which to sort the column values (ascending or descending).
Limit: Define the number of rows to return, useful for setting the page size in pagination.
Offset: Set the starting row for the query, which acts as the next page token for pagination.
(Optional) Specify a Torq integration for the workspace where you want to execute the step. If no integration is specified, the step will run in the current workspace.
Run the step to extract the data as an array of JSON objects, with each object representing a row in the table.
Extract Rows That Match a Condition
To return rows from the table that match a specified condition, use the Query Table step with the following optional parameters:
Selected columns: Select the table columns to return. To retrieve complete rows, omit this parameter.
Conditions: Specify the condition for the values to return. You can also add more conditions with OR and AND relations to create a more complex condition.
Comparison operators are available according to the column value type.
Extract a Specific Value from the Table
To extract a specific value from the table use the Query Table step with the following optional parameters:
Selected columns: specify the column of the value you wish to retrieve.
Limit: Enter the value 1. To retrieve a specific value you need to specify the specific column and row.
Offset: Specify the row of the value you want to retrieve. This can be the output of a previous step.
Create and Manage Table Schemas with Workspace Variables API
The Workspace Variables API allows you to manage table schemas, including retrieving the existing column titles, creating new tables, and updating column details.
The API does not support accessing the table data itself.
Create a table
To create a table, send an API request using the following format:
curl --request POST \
--url https://api.torq.io/public/v1alpha/workspace_variables \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{"pretty_name":"table_name","table":{"columns":[{"name":"col1","text":{}},{"name":"col2","boolean":{}}]}}'
Update a table
To update the table schema, send an API request using the following format:
curl --request PUT \
--url https://api.torq.io/public/v1alpha/workspace_variables/table_name \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{ "variable":{"name":"table_name","table":{"columns":[{"name":"col1","text":{}}]}}}'