TABLE OF CONTENTS

• Overview
• Adding a Data Set
• The types of Data Sets
  • External API
  • Data table
  • Workflow
  • Ruleset
  • Collector
  • Variable
  • Javascript
• Evaluating Data Sets
• Chaining Data Set Evaluation

Overview

Data Sets are essential tools for an App’s interface for interacting with data. As an App Builder, you can use Data Sets to interact with different types of data, such as local tables, external APIs, or workflows. 

In App Studio, you link interface Components to Data Sets by selecting the appropriate Data Set for each Component. Each Data Set is configured with specific parameters that define how to retrieve or modify data in its source. 

Before adding a Data Set to your App, ensure the underlying data source is properly configured. The data source defines the schema, which determines the structure of the data that the Data Set will handle. For example, when using an External API, the data source should include the URL endpoint, request types, and URL parameters so that the CafeX platform can call the external API.

Data Sets require a defined set of inputs, which are provided by the app interface. These inputs can come from the outputs of other Data Sets or from specific fields within the interface itself.

In the following example an App provides an interface field and a Variable to the Data Set definition. The Data Set is configured to connect to an External Data Source via a remote API. As the App Builder, you associate the Component fields and Data Set values as input fields of the Data Set. When the App evaluates the Data Set, it passes the parameters to the External Data Source. In this example, it maps interface fields to the API parameters.

Adding a Data Set

To add a Data Set:

1. In the Explorer tab of the Design Editor, select App.
2. On the right side of the page, go to Appearance and Configuration > Configuration.
3. Scroll to the Data sets section and click Add data set. 
4. Specify the Name and complete the rest of the form based on the type of the Data Set you are adding. Detailed instructions for each Data Set type are provided in the The types of Data Sets section below.
5. Enable the Evaluate automatically toggle if you want the data set to evaluate automatically once the relevant data becomes available.
6. Click Add.

The types of Data Sets

Data Sets come in various types, each serving a specific purpose:

External API

External APIs allow you to connect with external systems and pull in data using HTTP requests. 

Prerequisite: Ensure the External Data Source is configured prior to the Data Set creation. For details on how to add an External Data Source check Creating a New External Data Source.

Configuration: Select the appropriate Source. For each Input, specify the Location, which is a corresponding field or value from the interface that provides the values for the ruleset’s input fields, and Requirement which defines constraints on the input value to ensure it meets certain criteria. Possible values:

• Any Value: The input can have any value, including null or empty values.
• Not Null: The input must contain a value: it cannot be null, but it could be an empty string or zero depending on the data type.
• Not Empty: The input must have a value that is neither null nor an empty string ("").

Data table

Data Tables store private data within a workspace based on a predefined schema. 

Prerequisite: Ensure a Data Table is configured prior to the Data Set creation. For details on Data Tables, check the Data Tables article.

Configuration: Select the appropriate Source and select the Operation (AUTO, POST, PUT, DELETE).

Workflow

Workflows bring data into a component or execute actions across multiple applications.

Prerequisite: Ensure a Workflow is configured prior to the Data Set creation. For details on Workflows, check the Workflows article. 

Configuration: Select the Workflow. For each Input, specify the Location, which is a corresponding field or value from the interface that provides the values for the ruleset’s input fields, and Requirement which defines constraints on the input value to ensure it meets certain criteria. Possible values:

• Any Value: The input can have any value, including null or empty values.
• Not Null: The input must contain a value: it cannot be null, but it could be an empty string or zero depending on the data type.
• Not Empty: The input must have a value that is neither null nor an empty string ("").

Ruleset

Rulesets enable you to apply business rules in your app. For example, they can display warnings or tooltips based on specified conditions.

Prerequisite: Ensure a Ruleset is configured prior to the Data Set creation. For details on Rulesets, check the Rulesets article.

Configuration: Select the Ruleset. For each Input, specify the Location, which is a corresponding field or value from the interface that provides the values for the ruleset’s input fields, and Requirement which defines constraints on the input value to ensure it meets certain criteria. Possible values:

• Any Value: The input can have any value, including null or empty values.
• Not Null: The input must contain a value: it cannot be null, but it could be an empty string or zero depending on the data type.
• Not Empty: The input must have a value that is neither null nor an empty string ("").

Collector

The Collector Data Set stores an array of previous evaluations, allowing you to track and accumulate results over time. This can be especially useful for collecting and displaying items such as errors from a data source, allowing you to monitor and present them to users within the interface.

This is the recommended approach for collecting validation errors from forms. It can be useful if your App needs to present validation errors somewhere else or display errors from multiple forms when they are submitted together.
 

Configuration: Add Sources. For each source, specify the Data set, Data path, and enable the Collect errors toggle if you want to track errors on the interface and present them to the user.

Variable

Variables store values or expressions and are often used with Event Handlers to control the visibility of Components in App Studio or display specific data.

Configuration: Specify the Expression. Toggle the Persist value in client option if you want to write a value to the user's browser's local storage.

Javascript

JavaScript Data Sets allow for advanced operations by processing input Data Sets to produce new output Data Sets.

Configuration: For details on Javascript Data Sets and their configuration, check the Using a JavaScript Data Set article.

Evaluating Data Sets

As an App Builder, you can control when a Data Set is evaluated. CafeX evaluates a Data Set once all required inputs have values, and it re-evaluates whenever any of those input values change.   

The App ensures that all input values for a Data Set are provided before initiating the evaluation. You can use the Requirement option to specify that a Data Set should not be evaluated unless a particular parameter has a value.

 CafeX evaluates Data Sets under the following conditions:

• No Inputs Listed: The Data Set has no inputs defined, so it evaluates immediately.
• No Assigned Inputs: The Data Set has inputs, but they are not assigned to variables or interface values, so it will not evaluate until assignments are made.
• All Required Inputs Have Values: When all inputs, regardless of their requirements, are assigned and contain values, the Data Set will evaluate because the interface no longer needs to wait for additional input. The input values can be defined as:
  • Any Value: The input can have any value, including null or empty values.
  • Not Null: The input must contain a value: it cannot be null, but it could be an empty string or zero depending on the data type.
  • Not Empty: The input must have a value that is neither null nor an empty string ("").

In the following example, an App evaluates a Data Set and the result, or the output, is available on the original Data Set.

This output can then be accessed by other App Components, Data Sets, or through mustache expressions.

Chaining Data Set Evaluation

Chaining Data Set evaluations allows you to automatically use the output of one Data Set as the input for another, without needing to write any code to handle the parameters. This process is triggered whenever an input value of a Data Set changes, causing it to reevaluate.

This approach is especially useful when working with APIs that don't return all the necessary information in a single response. It also helps when a user action requires a second request, which may take longer to load. In this case, the result from the first Data Set automatically prompts the second Data Set to reevaluate.

Additionally, you can use Rulesets to validate user inputs and provide real-time feedback or instructions.

By chaining Data Set evaluations, you enable multiple Data Sets to update either sequentially or in parallel, ensuring the interface dynamically reflects the latest data without requiring direct user interaction.