Live Data allows Admins and Designers to supply users completing submissions with real-time data from external systems using APIs.

Table of Contents

Create Live Data Credentials

Create and configure a Live Data Source

Test and Publish a Live Data Source

Use Live Data in the Form Builders

Live Data for Users

View Live Data Request Logs

Live Data

Create Live Data Credentials

Credentials tell GoCanvas how to authenticate to your external API. To add new Credentials, follow the steps below:

1. In the left navigation, expand Data Sources and select Live Data. 

2. Click Manage Credentials.

   

3. Click Add Credentials.

   

4. Complete the required fields (i.e. Name, Base URL, and Auth Type) and optional field, Headers, if needed.

5. Select an Auth Type that matches your API (e.g. BasicAuthCredential, APIKeyAuthCredential, or OauthCredential) or No Authentication.

   

6. Fill in the required fields based on your API's documentation (e.g. Username and Password, API Key, Grant Type, etc.).
7. Click Create.

Create and configure a Live Data Source

Once you have Credentials, you can create a Live Data Source to define how GoCanvas calls your API:

1. In the left navigation, expand Data Sources and select Live Data.

2. Click Add Live Data.

   

3. Enter a Name and Description for your Live Data Source (e.g. "Weather Report API").

   

4. Expand Authorization and select the Credentials you previously created.
5. Expand HTTP Method and select the appropriate option (e.g. GET or POST). 
6. In Endpoint URL, enter the base URL and path for your API endpoint (e.g. https://api.example.com/v1/weather). The Endpoint URL can be further customized using optional Path Parameters, instructions below.

Configure Parameters

Parameters are used to customize API requests. They can be used in one or both of two ways:

1. Query Parameters: Automatically append to your URL. This is default behavior. (e.g. /api/projects?status=active&limit=10)
2. Path Parameters: Include directly in your Endpoint URL using curly braces (e.g. /api/projects/{project_id}/data).

Parameter Types:

• Static Parameters: Fixed values that remain the same for every API call.
• Dynamic Parameters: Values that can change based on form field input from users.

Static Parameters

Static Parameters are query parameters that always get sent on the request and do not change based on user input (e.g. pagination or fixed filters). To add Static Parameters, follow the steps below:

1. In the middle of the New or Edit Live Data page, click Add Static Parameter.
2. Enter a Key.
3. Enter a Value.
4. Repeat for any additional Static Parameters.

Dynamic Parameters

Dynamic Parameters send values from your form to your API at runtime. This is how you filter results based on what users enter in the form. To add Dynamic Parameters, follow the steps below:

1. In the middle of the New or Edit Live Data page, click add Dynamic Parameter.
2. Configure the fields:
   • Enabled: Select this if you want the Parameter to be available when mapping fields in the Builders and included in API calls.
   • Display Name: A user-friendly label that builders will see (e.g. "Country Code").
   • Required: Choose whether the user must provide a value before an API call is made.
   • Sample Value: A sample input used when you Test Connection (e.g. "US")
   • Wildcard Before/After: Add characters like * or % before or after the user's input for partial matches, based on your API's requirements.

Path Parameters

Path Parameters are placeholders in the Endpoint URL that get replaced with values fro the form when the API call is made e.g. Path: /data/2.5/weather?zip={zip},{country_code}&appid={API key}).

In this example, {zip} and {country_code} will be filled with a value from the form, and {API Key} is set by the Admin or Designer. To add Path Parameters, follow the steps below:

1. In the New or Edit Live Data page, scroll up to Endpoint URL.
2. Review the placeholders in your path (e.g. {zip} and {country_code}).
3. Configure each placeholder so that it can be mapped to a field in the Builders.
4. Use the Preview to confirm how the final URL will look once Path Parameters are resolved.

Map fields with JSONPath

Field Mappings transform your API's JSON response into columns that GoCanvas can use like Reference Data. To add Field Mappings, follow the steps below:

1. Near the bottom of the New or Edit Live Data page, scroll to the Field Mappings section.
2. Click + Add a new Field Mapping.
3. For each field your want to expose:
   • Enter a Field Name (this will appear as a Column in the Builders, e.g. "weather_description").
   • Enter the JSON Path that points to the values in your API response (e.g. $.weather[*].description).
4. Repeat for each field you need (e.g. coordinates, weather, etc.).
5. If you have already run a successful test, you may see suggested Mappings that you can edit or extend.

Test and Publish a Live Data Source

Test Connection

Use Test Connection to verify that your configuration, Credentials, and Mappings are correction before you use the source in a form:

1. In middle of the New or Edit Live Data page, confirm that your Dynamic Parameters have Sample Values.
2. Below Dynamic Parameters, click Test Connection.
3. Review the results:
   • Verify that the test is successful.
   • Confirm that the data shown matches your expectations for each mapped field.
4. If necessary, adjust your Parameters or JSON Path Field Mappings and test again.

Draft vs. Published Live Data Sources

Live Data Sources have two states:

• Draft:
  • Used while you are still configuring and testing the source.
  • Cannot be select or used in the Builders.
  • You can freely change Parameters, Mappings, and Credentials.
• Published:
  • Ready to be used in forms.
  • Appears as a selectable option in either Builder's Reference Data menu.
  • Forms always use the most recent Published version of the Source.

Publish a Live Data Source

Once you have tested your Parameter, and Field Mappings, you can Publish your Live Data Source. Follow the steps below, depending on if your Live Data Source is New, saved as a Draft, or previously Published.

Use Live Data in the Form Builders

A Live Data Source is mapped to fields in a form similarly to how fields are mapped to Reference Data, with one major difference: fields do not use the Screen and Field dropdowns to reference other field values to populate.

Live Data for Users

From a user's perspective, forms that use Live Data work much like forms that use Reference Data, with several key differences:

• Data is fetched in real time.
• The user will need to provide the Dynamic Parameters for every field that is mapped to the Live Data Source using the dialogue that opens when a field is selected. In the Web Client, users will click the arrow to open the dialogue.

View Live Data Request Logs

Request Logs help you troubleshoot issues and understand how your Live Data Sources are being used. To view Request Logs, follow the steps below:

1. In the left navigation, expand Data Sources and select Live Data.
2. On the right side of the page, under the Action column, click the third icon to the right of Copy and Trash.

Use these Request Logs to investigate missing results, errors, or performance concerns.