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 Data Protocol (OData) Version 2 and Version 4. OData is an ISO/IEC approved OASIS standard. For more information, see the OData web site (https://www.odata.org/)

  • 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:

    • OData and

    • OpenAPI (Swagger).

  • 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:

OData

OpenAPI (Swagger)

Limited support only is provided for oData, Version 4. Support is limited to:

  • Adding models and properties. Additional features are not currently offered.

  • Using the first metadata schema encountered as the basis for the remote data source.

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:

  • Freeform data, also known as ‘object’. Example: “data” is an object {“data”: {“test”: 123}}.

  • An array of types. Example: “data” is an array with text properties {“data”: [“test”, “another”]}.

  • Multiple types on one property. Example: “test” can be a text or a number property {test: 1},{test: “testing”}.

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:

https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BILL_OF_MATERIAL_SRV;v=0002/$metadata

API key for verifying access to the remote data source:

Retrieve your personal API key via: https://api.sap.com/

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:

  • Name of the data source - for example, SAP Hana* (A)

  • Url location for obtaining the schema description (metadata) based on the data source*. (B)

*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.


Note: If you are a business user, you may need support for obtaining the required details from your IT department. The information here is based on an example only and needs to be qualified with details for the specific remote data you require for your application.

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:

  • Models list view button to open a table containing a list view.

  • Models schema overview button to open the schema view.

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:

  • A: The details for the selected Action are displayed.

  • B: Betty Blocks predefined steps are available in the sidebar. These steps are individual workflow events that you can use to automate a workflow. Additional custom steps can be created and published for use in your application.

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.

Also, keep in mind that custom action steps need to be enabled by the support. If you want to use them within your Betty Blocks application, click on the button in the bottom right corner to contact our support.

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)

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:

  • Name

  • Params

  • Response

Use the Variables button (x) to open the Variables selector for assigning the required variable.

  • A: Specify name to navigate to the variable.

  • B: Select the variable.

  • C: Press the Select button to insert the selected variable in the option field.

6. Add the details for the PARAMS variable. Click on the Select variable button to open the Variables selector.

  • A: Specify params in the Search field to display the available variables.

  • B: Select the params input variable from the list.

  • C: Press Select.

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.

➝ Next article: Updating a remote data source

Did this answer your question?