Data Grid Portal Pages make it easy for Portal users to interact with said AirData App Objects in various pre-approved ways. One of the most powerful ways Portal viewers can interact with data in a Data Grid is by running Data Flows on select App Object instances. This document discusses how this can be done.
- Prerequisites: An App Object and a Data Grid Portal Page
- Step 1: Build out your Data Flow
- Step 2: Add the Data Flow to the Portal Page
- Step 3: Publish and Test
Prerequisites: An App Object and a Data Grid Portal Page
In order to run a Data Flow on App Objects displayed in a Data Grid Portal Page, you must first have access to both an App Object and a Data Grid Portal Page that displays said App Object.
Creating an App Object
App Objects are defined in the Data Builder. There are no constraints to the type of App Object you need to create here: they can have any number of properties, which themselves might be any primitive type or even other App Objects. Once the structure of an App Object has been fully described, make sure to save your application so that the rest of the application will have access to the App Object you just defined.
For a deeper dive into how to create App Objects and how they might connect to they rest of your application, check out AK101.
Creating a Data Grid Portal Page
A Data Grid Portal Page displays a table of data stored in AirData; each Data Grid must be associated with a particular App Object. You can select which App Object you want your Data Grid to display from a dropdown menu in the Inspector. Select the App Object you intend to display and run Data Flows on.
For more on how to create a Data Grid Portal Page that displays a particular App Object, check out the documentation on Portal Builder.
Step 1: Build out your Data Flow
There are only two constraints to keep in mind while constructing Data Flows intended run from a Data Grid.
Firstly, when a Data Flow is run from a Data Grid, there is no designated place for resulting output to be displayed. Data Flows that are run from a Data Grid are intended to take actions – send emails, update a database, activate Chat Bots – not return output. While the Portal Builder does not forbid incorporating a Data Flow that returns some output, it must be understood that whatever output it returns will not, in practice, be accessible. If you want to run a Data Flow that displays new information within a Data Grid, it is necessary to build a place for that desired information within the displayed App Object and then run an Airdata query as part of the incorporated Data Flow.
Secondly, the input required by the Data Flow must be structured appropriately. Once a Data Flow is built into a Portal Page, it can only be fed input in the form of selected App Object instances, and the structure of the Data Flow being run must reflect that.
This means that the Data Flow can only accept input structured in two ways:
- The App Object that is being displayed in the Data Grid
- A List of said App Objects
Brief Tangent: How Data Flows incorporated into a Data Grid parse input
The above section specified that a Data Flow created to run from a Data Grid Portal Page can accept input in two forms: a singular App Object, or a singular List of App Objects (when, in both cases, all pertinent App Objects match the App Object being displayed in the Data Grid). In both cases, here is how input is given to a Data Flow from a Data Grid. Note that App Object instances are selected by clicking on the check box to immediate left of the row that displays the desired instance:
However, while input is given in the same way, how it is parsed depends on the format of input accepted by the Data Flow.
When a Data Flow accepts a a single App Object as input, it will run on every selected App Object instance individually. That is, it will run the Data Flow repeatedly: once for every app object instance selected. For instance, let's say that the Data Flow in the above example (ostensibly one that sends a follow up email) functions this way. It accepts a single App Object (or a "Feedback Object") as input, and runs twice: first it runs and sends an email to firstname.lastname@example.org, and then it runs again and sends another email to email@example.com.
When a Data Flow accepts a List of App Objects as input, it will run only once, on a List generated from every selected App Object Instance. If we now assume that the above example functions this way, the input given into the Data Flow would look as follows:
"Feedback": "It's okay.",
"Notes": "Need to follow up",
"Feedback": "It's great!",
"Notes": "Need to follow up",
Data Flows that accept input in this way ought to be used exclusively in cases where the Data Flow requires multiple App Object instances in order to function as intended, such as in cases where properties of App Object instances need to be directly compared. While it is possibly to craft a Data Operation that repeatedly loop through a list of App Object instances and does the same thing to each of them, this introduces an extra layer of complication that ought to be avoided when possible.
Step 2: Add the Data Flow to the Portal Page
Once you've built out a Data Flow that meets the constraints given above, save your application and toggle over to the Portal Builder. (Saving your application ensures Portal Builder will have access to the Data Flow you just created.) Access your Data Grid and click on the "Add Data Flow" button in the Inspector, nested under Data Flow. From there, you can select which Data Flow you want from a dropdown menu of relevant Data Flows (that is, Data Flows that accept input in one of the required formats):
After selecting a Data Flow to associate with the Data Grid, label the button that will run the Data Flow from the Data Grid. Multiple Data Flows can be added to a single Data Grid, so it's important to give each button a unique name that tells Portal users important information regarding the Data Flow that the button will trigger:
Step 3: Publish and Test
Most components of an app build can be fully emulated by Previewing the app, but this is not the case with Portals, because Portals aren't part of an app proper; they're a tool for internal (though non-developer) users as opposed to app users.
In order to test and confirm that a Data Flow built into a Data Grid is running as intended, you'll need to publish your app and the access the Portal by then accessing the URL associated with the Portal in Configuration Builder. For more on how to associate URLs with your organization, check out Connecting your Domain to Airkit, and for more on how to access a published Portal Page, check out Accessing Portal Pages.
Upon accessing the Data Grid Portal Page in question, you should see the button associated with Data Flow in the upper right corner. Note that the label on the button matches the label you gave it in the Portal Builder Inspector:
When multiple Data Flows are associated with a single Data Grid, the buttons will be arranged as follows:
Now you can run your Data Flows on any number of your saved App Objects! Simply select them by clicking on the check box to the left of the relevant object or objects, and then click on the button indicating the Data Flow you want to run: