About the data sources feature
This article describes how you use the Data sources feature for creating connections to data resources in external systems to an application you are building on the Betty Blocks platform. You are able to seamlessly integrate data to enrich the information in your application. Connections that enable systems to communicate are known as application programming interfaces (APIs). APIs are commonly used to update information in applications. For example, when you press a refresh button on a social media application, an API provides the connection to check for updates so that you receive the latest information.
Who should read this information
This article is of interest to you if you are building an application in which you want to include data sourced from both the Betty Blocks platform as well as from other external sources.
Which API protocols are supported
The following protocols are supported:
Open API/Swagger - a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. For more information, see please see the Swagger web site (https://swagger.io/)
What is required for connecting to remote sources
To use remote sources, you need:
an established API connection that can be integrated with Betty Blocks.
the Metadata endpoint for the API with which you want to connect. The OData or Swagger metadata endpoint that is used to fetch the API's schema and to install it in your Betty Blocks Application. For example, https://services.odata.org/OData/OData.svc/$metadata.
an API key that permits connection with the data source (if required).
Note: API's can require authorization on their API's metadata endpoint. In these cases, an API key is required that is used for identifying and authenticating access requests.
What you need to know already
This document assumes that you are familiar with working with the Betty Blocks Data model and that you are able to create models. You also need to know how to work with the Pages builder for incorporating data in your application's user interface.
If you are new to creating applications, please refer to the Betty Blocks resources (Courses, Tutorials, Documentation, and Forum) available from the Betty Blocks Dashboard to familiarize yourself with working with the platform.
Once connected, what do you need for working with remote data
You need to create custom Application Functions in the new Actions for working with remote data sources in your application. How to create custom Application Functions is detailed in: GitHub repository for Betty Blocks command-line interface (CLI)(https://github.com/bettyblocks/cli/wiki/functions).
What is and is not supported
The following details the restrictions around the usage of the remote data source models. The remote data source feature is primarily intended for loading and showing remote data on Page builder Pages. The following details what is/is not supported:
The Data Sources feature is compatible with the following protocols only:
Remote model data cannot be rendered or displayed in the Back office.
Remote model permissions: the remote data source manages data authorization.
Authentication is limited currently to API keys.
The following are outside the scope of support for this feature:
Creating associations between regular local models and/or remote models.
Creating an association between remote models.
Creating remote models that have files and images as properties.
The following details API specific limitations regarding support:
Limited support only is provided for oData, Version 4. Support is limited to:
While additional schemas inside a single metadata document are possible, these are not currently included in this feature.
The following return data is not supported:
Working with remote data sources
You can incorporate data from systems outside the Betty Blocks platform. In this way, you can ensure that you obtain the data required for your application. Data can be incorporated in your application to provide the details needed for supporting business needs. Once you have identified the data that is required, you can create a connection over an application programming interface that mirrors the specific information in your application. Within your application’s Data model, you can create one (or more?) models that are linked with your user interface via the Pages module.
In this way, you can build applications aligned with business needs, for example, a Bill of Materials required by the engineering design team that incorporates information located in an external system. In the following example, an application built in the Betty Blocks platform compiles a Bill of Materials (BOM) that incorporates data from an SAP HANA (High-performance ANalytic Appliance) database:
To build an application that incorporates both local and remote data, you need to:
Step 1. Create a data source entity that obtains a description of the remote data.
Step 2. Create one or more remote models for mapping to interface elements.
Step 3. Configure the remote model Action(s) that define the steps for connecting with the remote system for mirroring the results in your application.
Step 4. Design an interface in the Page builder for displaying the required information.
Step 5. Test that the information retrieved displays as required in your application.
Each of the above steps is explained in detail in the following sections. The example bill of materials shown here is used as an example for explaining how you can work with remote data for building business applications.
Step 1: Creating a data source
To create a data source you need:
Name of the data source.
Url location for obtaining the schema description (metadata) that details the remote data in terms of, for example, remote models and properties.
API key for verifying access to the remote data source.
How these are applied when creating a data source is described in the following based on creating the example bill of materials provided.
Note: If you are a business user, you may need support for obtaining the required details from your IT department. The following is based on an example only and needs to be adapted for your organization.
The following are used as an example in this article:
Name of the data source:
SAP Hana (Demo)
Url location for obtaining the schema description (metadata) that details the remote data in terms of, for example, remote models and properties:
API key for verifying access to the remote data source:
1. Click on the Data model button in the builder bar and select the Models overview (A) button in the quick menu. The Data model list is opened containing the Data sources feature (B).
2. Click on the New data source button to open the New Data Source dialog.
3. In the New Data Source dialog, enter the details:
*Adapt to reflect the data source and the url for the metadata for the specific data source you want to access.
4. Press Connect . An authorization step takes place that checks the details for setting up the connection to the remote data source. Once successful, an additional entry field is displayed for providing API key details. Specify the API key (C) for verifying access to the remote data source**
** Adapt to reflect the unique API key details for your organization.
5. Press Connect. When successful, a checkmark (✔) indicator confirms that the connection is successfully established. The host URL details (E) are also displayed as shown in the next example screen.
6. Where already available, you can select an application configuration so that the API key and the Host are dynamically configured.
7. Press Create Data Source. The Data model list view is displayed. The Data sources dialog now shows the remote data source that is now available for using to map the information that you require for your application.
In the next section, how you create one or more models for working with remote data is described. These models are called remote models to distinguish them from our standard Betty Blocks “local” models.
Step 2. Creating remote models
Now that you have created a connection to the data source, you can add one or more remote models to your Data model. Remote models and local models play the same role in mapping data to your application. The examples in this section continue our journey for building a Bill of Materials application based on the SAP Hana remote data source.
To start building a remote model
1. Click the New model button in the Data model window. The Create new model dialog is displayed.
2. Click SAP Hana to display the models in the remote source (A).
3. Click the Add (+) button to add each required model for use in your application. A checkmark (✔) indicates that the model is selected and the model name is displayed in the adjoining table (B).
3. Click the Add models button to add the selected model to your data model. The Data model list view is displayed.
Identifying remote sources
A. Remote models are included in both the list view and in the schema view. You can toggle between the views as required. Click on the:
How the information is displayed in each view is indicated in the following image:
B. The remote model icon helps you to quickly identify remote models in the different views.
C. An additional Data source column is provided in the Models list view. When you have added additional data sources, you can recognize the data source connected to a model.
D. You can click on the remote model to view Properties, Actions and Settings information for a model in separate tabs. You can view the property details as shown in the example.
E. The Actions tab opens the list of Actions connected with a data model. A series of default actions provided with a remote data source model is displayed.
F. In the Settings tab, you can add a detailed description for the model. This is useful, for example, for application maintenance purposes. You can also refresh the connection to the data model for ensuring that you have the most up-to-date instance using Data source settings.
Step 3. Configuring remote model actions
You can now create the action(s) required for mirroring the remote data source details to your application. In our example, we are creating an action to fetch all the Bill of Materials data from the remote source into the Betty Blocks application.
Remote model actions are designed to do the actual CRUD API requests. That’s why we are auto-generating these five actions for: Create, Read, Update and Delete.
Note: In the following example, a predefined SAP Hana action is used.
1. Open the Actions tab in the Data model and
2. Click on the Read all action. The Actions module is opened and the:
Note: Custom steps must be created before you specify the Action workflow as shown in the following. Please ensure that the custom steps you require have been defined and deployed for you to use in your Action.
A code example is available in the article: Example of an oData script for use with remote data sources.
Additional information on how you create Application Functions is detailed in
Note: Additional information on how you create Application Functions is detailed in:
GitHub repository for Betty Blocks command-line interface (CLI)- (https://github.com/bettyblocks/cli/wiki/functions).
3. From the components menu (A), drag and drop the SAP Data action step to the canvas. A drop indicator appears as you drag the action step between the Start and Finish steps.
4. Click on the action step to open the details pane. The name is displayed in the opened pane.
5. Map the auto-generated input variables (name and params) to the options available in the SAP Data step in the Options tab displayed. The SAP Data step contains the following options:
Use the Variables button (x) to open the Variables selector for assigning the required variable.
6. Add the details for the PARAMS variable. Click on the Select variable button to open the Variables selector.
Each of the option fields now contain the selected variable.
7. Specify a value in the Response text field, for example, response or results. This option becomes available later in the workflow.
8. Press Save to save the details you have added. A message is displayed that confirms that the Action step is successfully updated.
9. Click on the FINISH step in the workflow to add the response step from the workflow action.
10. Click on the Finish step to open the details pane.
11. Click on the Select variable button to open the Variables selector. (You can use Search if required (A) to locate the required variable.) Choose the variable (B) you created in step 7 as the return value for the Action. Press Select (C).
This configures your action to output the response from the SAP Hana data step when the action completes.
12. Press Save to save the details you have added.
13. To close the detail pane to return to the canvas, either press the Close or Cancel to close the pane.
You have now completed the Action configuration for workflow steps. You can now build the user interface as described in the next section for displaying information from the remote source.
Step 4. Designing an application page for displaying information
You can now design and build the user interface that you want to use for displaying information. This example continues the steps needed for creating a Bill of Materials based on the remote data source, SAP Hana.
1. Navigate to the Pages module in the Builder bar. The Pages quick menu is opened (A).
2. Click New page. The Choose a page template menu is displayed.
3. Click on the Blank page template.
4. Select Use. The Create new page dialog is displayed.
5. Specify the page name you want to use. In this example, we are using Bill of Materials.
6. Click on the Create page button.
7. Drag and drop the single column layout component to the canvas. The Column layout is displayed at the top of the canvas.
8. Specify data in the search field to quickly navigate to the DATA components. Drag and drop the Data Table component to the column component on the canvas. The Configure data table wizard is displayed.
9. Click on Select model to open the Models dialog. The remote data source icon supports identifying the required model.
10. Navigate to and select Bill of Material from the list displayed. Press Select to confirm that you want to select this model.
11. Click on Bill of Material. The detailed list of properties in the remote model is displayed.
12. Navigate to and press the Add (+) button for each property you want to include in your data table.
You can add and remove properties as required based on the information that you require for your business application. As shown in the example below, the following properties included in the example:
PlantName - Material - ID - IsVersionBillofMaterial
Note: Where you add a property that is not required, you can remove it by selecting the Trash button in the property row.
13. Click Save. The Configure data table wizard is closed. The canvas page now shows a series of columns based on the properties you selected. The order reflects the order in which the properties were added.
14. You can use the component options to specify, for example, the number of rows you want displayed.
Step 5. Testing your application
You can now test your application to both ensure that the design meets your requirements and that the data required is being mirrored from the remote data source.
1. Press the Play button
2. A new browser tab is opened that shows the end-result.
3. Close the tab to return to your application. You can continue building additional information as required.