TABLE OF CONTENTS

• Creating a New External Data Source 
• Adding a Data Set for an External Data Source
• Exporting and Importing an External Data Source
  • Exporting an External Data Source
  • Importing an External Data Source

The External data sources page allows you to create, configure, and manage external data sources. 

When your application needs to interact with an external API endpoint from another system, configuring an External Data Source is required. An External Data Source provides your app with the necessary definitions to use the API, and the CafeX platform handles connection establishment, security, and authentication. Additionally, it can supply your application with a schema for the API endpoint you are using.

Important: The External Data Source feature enables you to configure various aspects of a RESTful API. Before configuring an External Data Source, it's essential to be familiar with RESTful services.

 To configure an External Data Source, you need to complete the following steps:

1. Create a new External Data Source.
2. Add a data set for an External Data Source.

Creating a New External Data Source 

To create a new External Data Source:

1. Go to App Studio > External data sources (). Alternatively, go to Configure > External data sources. The External data sources page opens.
2. Click Add new data source.
3. In the Data Source pop-up, specify the Name, Group, and select recommended Configuration version for the data source.
4. Under Request > Configuration, there is a JSON definition for the endpoint that your App uses to access the API.
   
   Data Source configuration can include the following attributes:

   Attribute	Description
   URL	The URL of the endpoint. Define URL fields using parameters enclosed in {{}}.
   method	The request method to use. Typically, RESTful services use the following request methods: GET (idempotent, no change): Retrieves data. POST (non-idempotent): Creates new objects. PUT (idempotent): Updates existing objects. PATCH (idempotent): Partially updates existing objects.
   urlParameters	An array of URL parameters.
   auth	An authentication header, an OAuth token.
   payload	JSON payloads for POST, PUT, and PATCH requests.

5. Under Response > Schema, there is a JSON definition of the information your App uses. As this is a GET request, use Extract Schema to test the endpoint and automatically generate the schema for your App to use. Click Extract Schema and enter values for the REST API inputs to have CafeX call the endpoint and parse the data object.
6. Click Send Request. The response schema provides the App Studio with a definition of response objects that your App references. If necessary, you can manually update the schema.
7. Click Accept to accept the schema.
8. Click Update to update the data source.
9. A newly added data source appears in the list.
    

Alternatively, you can import an external file with pre-configured API settings and schemas. For details on how to do it, check the Importing the External Data Source section.

Adding a Data Set for an External Data Source

To perform operations on an External Data Source, you need to collect parameters and use them to evaluate a Data Set in your app. The Data Set provides your app with a consistent way to interact with data.

To add a Data Set to search on:

1. In App Studio, go to Explorer > App.
2. On the Appearance and Configuration panel, click Configuration.
3. In the Data sets section, click Add data set.
4.  Complete the form and select the appropriate Data 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 ("").
5. Click Add.

Now the Components in your App can make use of the added Data Set.

Exporting and Importing an External Data Source

App Studio provides options for exporting and importing External Data Source configurations.

Exporting an External Data Source

Exporting an External Data Source enables you to save the API configurations and schemas from your app into a JSON file. This can be useful if you want to reuse the configuration in other projects or have a backup.

To export an External Data Source:

1. From the External data sources page, click Export in the top right-hand corner of the screen.
2. Adjust the Only export filtered data sources toggle based on your needs.
3. Click Export. The file will be downloaded automatically.

Importing an External Data Source

Importing an External Data Source allows you to bring in pre-configured API settings and schemas from an external file into your app. This can be useful if you want to quickly set up your app to interact with previously defined APIs. 

To import an External Data Source:

1. From the External data sources page, click Import in the top right-hand corner of the screen.
2. Select the file and click Open.
3. Adjust the Replace existing data sources toggle based on your needs. If enabled, any matching data sources will be replaced by the new version being imported.
4. Click Import. The list of the External Data Sources will be updated accordingly.