Unqork’s Internal API: Read APIs

Estimated Reading Time:  7 minutes

Overview

Most of Unqork's internal API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. (applications programming interface) calls use one of the create, read, update, and delete (CRUD CRUD refers to the four critical operations for creating and managing data elements in your applications. It stands for create, read, update, and delete.) operations. In this article, you'll explore two examples of read API services in Unqork. Here you'll explore the Get Module Submissions and List Submissions for Dashboard API calls.

What You'll Learn

In this article, you’ll learn about the Get Module Submissions and List Submissions for Dashboard API calls, how they're configured, and how to test them.

Get Module Submissions API

The Get Module Submissions API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. is the simplest of Unqork's internal API calls. It's purpose is to retrieve multiple module submissions. In combination with the List Submissions for Dashboard API, you can then populate those submissions in a dashboard.

TIP  To learn more about the Get Module Submissions API, view our Get Module Submissions documentation.

Review the Get Module Submissions API Configuration

To help explain how the Get Module Submissions API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. works, we've configured a module and Plug-In component that uses this API call. The following sections explore the configuration and lets you test the API. We will take a closer look at the List Submissions for Dashboard API later in this article.

WARNING  Feel free to use the configuration created here for your own builds. But, please do not reconfigure the modules. If you want to use the configuration, make a copy of the module and paste it in your application.

Review the initNewSubmission Initializer Component

First, let's open the preconfigured module and look at the Initializer component configuration.

1. Open the preconfigured module in the Module Builder by clicking the following link: https://training.unqork.io/#/form/64cbebaf9ee30a59c4322f0d/edit.
2. Hover over the initNewSubmission Radio Button component icon Initializer component.

A 5-button toolbar displays above the component on hover-over.

3. Using the toolbar, click the (Settings) button.

You can see the Trigger Type is set to New Submission, firing the Initializer on page load. In the Outputs table, the component outputs values from a schema module and stores them in the moduleId Hidden component.

A static image displaying the initNewSubmission Intializer component's configuration with the New Submission Trigger Type and outputs to the schema module.

Review the pluginGetSubmissions Plug-In Component

Let's take a closer look at the necessary Plug-In component configuration and settings to make the API work.

1. Hover over the pluginGetSubmissions Plugin Component Icon Plug-In component.

A 5-button toolbar displays above the component on hover-over.

2. Using the toolbar, click the (Settings) button.

Internal Services

From the Internal Services drop-down, you'll see that the Get Module Submissions API is selected. Once selected, the Data Source URL auto-populates with /fbu/uapi/modules/{moduleId}/submissions. As you can see, the {moduleId} placeholder text in the URL was modified to {{data.moduleId}}. That way, you can retrieve the specific data stored in the moduleId Hidden component.

TIP  To learn more about the Get Module Submissions API, click the Learn More button in the Plug-In component's configuration window.

A static image displaying the Get Module Submissons Internal Service selection in the Plug-In component.

Request Type

The Request Type is also set to GET. The GET type is used to retrieve data.

Inputs

Lastly, the Inputs table sorts by the created data field of the submission and specifies a descending sort order based on the date and time created.

TIP  To learn more about conditional filtering, see the api-query-params library documentation: github.com/loris/api-query-params.

A static image displaying the Get Request Type and sorting inputs of the Plug-In component.

Test the Get Module Submissions API

Now, let's preview the module and test the configuration.

1. Preview the preconfigured module in Express View Express View is how your end-user views you application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View..
2. In Express View, right-click anywhere on the page.
3. Click Inspect. The Inspect tab of the DevTools Console opens to the right of the page.
4. Click on the Network tab to see the API calls.
5. Click Get Submissions. This button triggers the pluginGetSubmissions Plugin Component Icon Plug-In component.

NOTE  Unqork data is managed in a MongoDB database, which is stored in Amazon Web Services (AWS) and Azure. By pulling in these submissions, you’re seeing what’s saved to MongoDB.

6. In the Name column, you'll see submissions?sortBy=created&sortOrder=-1. You’ll also see the HTTP status in the Status column. If you see a 200 response, the call was successful.

NOTE  You will also see additional filters after the word submissions. These are the sortBy and sortOrder filters set up in the pluginGetSubmissions Plug-In component.

A static image displaying a successful get module submission API call in the DevTools Console.

7. If you click on the API call, you’ll see the specific information about that call:
Inspector Tabs Description

Headers

Displays the call's general information. This information includes the request URL, request method, response headers, and request information (if any was sent). Use this tab to double-check the information that you’re sending in your request.

Payload

Displays the actual response payload received from the call, formatted using readable JSON JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data..

Preview

Displays the additional information about the call, formatted using readable JSON JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data..

A static image displaying the headers, payload, and preview tabs of the submission in the DevTools Console.

Use the Angular Command

You can also view API call data and responses in the Console tab. In a new line of the Console tab, enter the Angular Command The Angular command, or data command, is a tool that displays submission data in a browser's developer console. In Express View, enter the following command in the devtool console: angular.element('.unqorkio-form').scope().submission: angular.element('.unqorkio-form').scope().submission. This command lets you see the module’s data in a neat JSON JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data. format.

1. In Express View Express View is how your end-user views you application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View., right-click anywhere on the browser’s page.
2. Click Inspect. The Inspect panel opens to the right of the page.
3. Click the Console tab.
4. Click Get Submissions. This button triggers the pluginGetSubmissions Plugin Component Icon Plug-In component.
5. Returning to the Console tab, enter the angular.element('.unqorkio-form').scope().submission command.

You’ll notice a new nested array displays in the Console. An array is a collection of ordered data sets. Arrays have a numbered index that starts at [0]. Because this is a nested array, you must expand the data sets to view the submission details.

1. Expand the data: drop-down section.
2. Expand the data: drop-down section.
3. Click the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. of the API’s Plugin Component Icon Plug-In component. In this example, it’s pluginGetSubmissions.
4. Select a submission. They're numbered starting at [0].
5. Expand the data: drop-down section.
6. Expand the rawData: drop-down section to see the submission data Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections..

A static image displaying the submission data using the Angular Command in the DevTools Console.

List Submissions for Dashboard API

The List Submissions for Dashboard call is similar to the Get Module Submissions call. You’ll use it to retrieve submission data and display it in a dashboard.

Review the List Submissions for Dashboard API Configuration

To help explain how the List Submissions for Dashboard API works, we've configured a module and Plug-In component that uses this API call. The following sections explore the configuration and lets you test the API.

WARNING  Feel free to use the configuration created here for your own builds. But, please do not reconfigure the modules. If you want to use the configuration, make a copy of the module and paste it in your application.

Review the pluginGetSubmissionsForDashboard Plug-In Component

Let's take a closer look at the necessary Plug-In component configuration and settings to make the API work.

1. Hover over the pluginGetSubmissionsForDashboard Plugin Component Icon Plug-In component.

A 5-button toolbar displays above the component on hover-over.

2. Using the toolbar, click the (Settings) button.

Internal Services

From the Internal Services drop-down, you'll see that the List Submissions for Dashboard API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. is selected. Once selected, the Data Source URL auto-populates with /fbu/uapi/system/getSubmissions. You’ll notice this call’s Data Source URL does not reference a module ID. With this call, you must enter the module ID in the Inputs table of the Plug-In component.

TIP  To learn more about the List Submissions for Dashboard API, click the Learn More button in the Plug-In component's configuration window.

A static image displaying the List Submission for Dashboard Internal Service selection in the Plug-In component.

Request Type

The Request Type is also set to GET. The GET type is used to retrieve data.

Inputs

Lastly, the Inputs table inputs the stored submission data Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections. from the moduleId Hidden component. Then, it inputs the specific fields in the submission data and sorts by the created field. For this call to work, you must specify the submission data or metadata you want returned.

A static image displaying the Get Request Type and data field mapping of the Plug-In component.

Review the dwfOutput Data Workflow Component

The dwfOutput Data Workflow Icon Data Workflow contains a simple configuration. It inputs the pluginGetSubmissionsForDashboard Plugin Component Icon Plug-In component and outputs it into the listSubmissionsResponse Hidden component. That way, the ViewGrid component can retrieve the submission data from the Hidden component and display it.

A static image displaying the Input and Output operator configuration of the Data Workflow component.

Review the vgSubmissionsResponse ViewGrid Component

A ViewGrid component is a great way to display submission data in a dashboard. The vgSubmissionsResponse Dropdown Component Icon ViewGrid component inputs the submission data from the listSubmissionsResponse Hidden component and displays the specific data fields in a grid.

A static image displaying the ViewGrid configuration in the Module Builder.

Test the List Submissions for Dashboard API

Now, let's preview the module and test the configuration.

1. Preview the preconfigured module in Express View Express View is how your end-user views you application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View..
2. In Express View, right-click anywhere on the page.
3. Click Inspect. The Inspect panel opens to the right of the page.
4. Click the Console tab.
5. Click List Submissions for Dashboard. This button triggers the pluginGetSubmissionsForDashboard Plugin Component Icon Plug-In component.
6. Return to the Console tab and enter the angular.element('.unqorkio-form').scope().submission command.
7. Like you did with the Get Module Submissions example, expand the call’s data. You'll find the data for this call under pluginGetSubmissionsForDashboard.

You’ll notice that these submissions are also listed in an array that starts at index [0]. When you expand an index, you’ll see all the call’s data. You don’t need to expand further into the data like you did for the Get Module Submissions call.

A static image displaying the grid data and detailed submission data in the DevTools Console.

Resources