Add an External Data Widget
Before you begin
Create a Data Import connection whose data you can pull into the External Data widget. The external data widget can retrieve data from the following sources:
- CSV
- Google Sheet
- Microsoft Excel
- OneDrive Sheet
About this task
Use the External Data widget to import external data into your app. App users can then choose entries from that source and their choices are reported to the SOTI Snap server. It's particularly useful if you want to provide app users with a dynamic list whose data changes frequently.
Procedure
- In the Canvas, open the Widgets tab.
- Double-click or drag and drop the External Data widget onto the app canvas.
- In the External Data Properties panel, enter a name for the widget in the Name field. You can also enter a label for that will appear as the default option in the Display text field.
- Enable the Required check box if you want to force app users to select an entry before they can submit the form.
- Turn on the Allow multiple value selection check box to allow app users to select multiple entries from the data import source. Otherwise, they are limited to a single selection and if they choose a new selection, it replaces the existing value.
- Select an existing data import connection from the list of available options or click New to add a new data import connection.
-
Choose which columns of the data import that you want to appear in the search results to the app user. From the Display columns dropdown list, select up to three columns.
For example, if your external data source is a Microsoft Excel spreadsheet with the following three columns: 1. Name 2. Address 3. Phone number, the values for those three columns are shown in the search results.Note: Which columns are shown and which are searched are separate. You can configure the scope of the search later on.
-
Choose a Unique ID. Select a column in the external source to use as the Primary column (and unique ID).
A unique ID is the identifier that SOTI Snap stores in its database and uses to identify this data across records.
Make sure the primary column that you select does not contain any null values, such as empty cells in spreadsheets.
-
Specify which columns of the data source SOTI Snap should check when it runs searches. From the Search columns dropdown list, select the columns.
You can select all columns in the external source; they do not have to match the Display columns. This means that if you add a column to Search columns that's not a Display columns, app users will still get search results if the search term matches an entry in a search column but not a display column.
However, this also means that if you don't include all display columns as search columns, then some entries may not be returned, even if it looks like they should be.
Note: You must include at least one display column as a search column.When using the search function within the app, users can use multiple search terms separated by a space in the search field and receive the matching records. For any search team with multiple keywords, app users need to put them in quotes. For example:
Name / Country / Interest John Dew/ United States/ Skydiving Jane Dow/ Canada / Paragliding
Users can search John Dew’s record by entering multiple search terms, like John Skydiving. Users can get more specific results by entering the search terms as “John Dew” Skydiving.
-
Choose how the records for this widget should appear when
exported to reports or using data export connections. To let the external source
decide them automatically, leave Default selected. If you
want to customize how they appear, clear Default and
update the Data settings: Format field to your preferred
format.
-
Expand the dropdown icon above the right corner of the field to enter
macros that represent the data in each display column. Double percentage
signs encase macros:
%%macro%%
. You cannot manually enter a macro. - Enter text characters.
- Repeat to add more macros or text characters.
Do not leave the Data settings: Format field in the middle of creating your format. You could lose your work because the field reverts to the last valid format whenever you leave the field. -
Expand the dropdown icon above the right corner of the field to enter
macros that represent the data in each display column. Double percentage
signs encase macros:
-
Choose how you want to align your widget in the app.
- Align Left
- Center
- Align Right
- Optional:
Add a requirement rule to the widget.
Use requirement rules to specify whether the app user must configure this widget or can skip it.
- Select Requirement Rule to open the Set Requirement Rule dialog box.
- Select whether the requirement rule requires meeting all or any conditions.
- From the Field list, select an app field or variable and an operator. Enter the value required for the widget to be visible.
- Select Add Condition to add another condition.
- Select OK to save.
- Optional:
Add a visibility rule to the widget.
Use visibility rules to control when a widget is visible to the app user. For example, you can create a condition that a widget should only appear after the app user fills in a field or submits a form.
- Select Visibility Rule to open the Set Visibility Rule dialog box.
- Select whether the visibility rule requires meeting all or any conditions.
- Select an app field or variable and an operator from the Field list. Enter the value required for the widget to be visible.
- Select Add Condition to add another condition.
- Select Save.
-
Decide which name you want to appear in the widget report.
The Same as widget name setting is the default selection and automatically uses the widget name as the chart title. To choose your own chart title, clear the option and enter a new name.
You may use special characters except for
%
&
<
>
{
}
*
|
^
and double spaces. - Move to the Format tab to customize the widget's appearance.
-
Add events and actions to the widget.
Events are activities that you can set to trigger an Action. For example, you can configure a widget to navigate to a new section in the app when the user selects it.Important: Events and actions offer a wide range of combinations. The following steps are guidelines only. Replace the listed events and actions with ones that suit your app's needs and structure. Learn more about available events and actions at Events and Actions.
The Map Columns action is particularly useful for external data widgets. Read how at configure it at Map Columns.
-
Select Save in the SOTI Snap
banner to apply your changes.