Using Unqork’s Internal API

Estimated Reading Time:  15 minutes

Overview

In this article, we’ll go into more detail about using Unqork’s internal API. You’ll learn how you can use it to build applications in Unqork. We’ll also discuss some common API calls, how they’re configured, and how to troubleshoot errors.

What You'll Learn

After finishing this article, you’ll be able to:

• Feel comfortable using Unqork’s API calls for your application builds.

• Understand why you’re using certain calls.

• Explain how an API call should be set up.

• Troubleshoot an API error message.

Unqork’s API

The Unqork Designer Platform is built on top of an API. This API lets you access certain types of data from across the whole Unqork platform. Have you ever wondered how you can pass Unqork data back and forth between modules? It's done through the Unqork API.

Bringing in data from external applications (such as DocuSign and Salesforce) requires integration with an external API. We’ll get into using external APIs in the next article. But, for now, there’s a lot we can do with Unqork’s API.

A few examples include:

• Sending sensitive submission data directly to our clients, rather than storing that data on our server.

• Populating and exchanging data between modules in Unqork.

• Creating users, creating and updating submissions, executing modules, and even promoting modules.

You'll find a list of all Unqork’s API calls at developers.unqork.io. Or, you can click the Learn More button in the Plug-In's configuration window.

Making API Calls

Internal API calls are primarily made using the Plug-In component. To access these calls:

1.

Drag and drop a Plug-In component onto your canvas.

2.

Under Service Type, select the Unqork choice chip.

3.

Under the Internal Services drop-down, select which call to make.

Now, let’s look at some common Unqork API calls.

Get Module Submissions

Let's start with a simple API call: Get Module Submissions. Selecting Get Module Submissions from the Plug-In's Unqork Service drop-down populates the Data Source URL and Request Type.

You’ll see that the Data Source URL populates with /fbu/uapi/modules/{moduleId}/submissions. This is the resource URL used to make the Get Module Submissions call. All you need to do is replace {moduleId} with the module ID of the source module. This module is where you're pulling data.

Whenever you see Data Source URL settings in single brackets (like {moduleId}) you'll replace this setting with a value. That value can be dynamic, such as data.moduleId, or static, like 5ec574becd0af602152c24cb.

You’ll notice that Request Type auto-populates with GET. That’s because the Get Module Submissions call is a GET call. You are getting data from /fbu/uapi/modules/{{data.moduleId}}/submissions.

Testing the API Call

Let's test the Get Module Submissions call. To make it simple for you, use the following module as an example: https://trainingx.unqork.io/#/display/5ec574becd0af602152c24cb. This link takes you to Express View, where you can interact with the module browser.

You can inspect the API call using the DevTools Console. To do this:

1.

In Express View, right-click anywhere on the browser’s page.

2.

Click Inspect. The Inspect tab of the DevTools Console opens on the right side of the page.

3.

Click on the Network tab to see the API calls.

4.

In Express View, expand the module's Read panel.

5.

Click the Get Submissions button.

6.

You should see submissions under the Name column. You’ll also see the HTTP status in the Status column. If you see a 200 response, the call was successful.

7.

If you click on the API call, you’ll see the specific information about that call:

Troubleshooting a Failed Call

Now let’s try that same process, but for a failed call. This time you'll receive an error message instead of a success message. This example still uses the following module: https://trainingx.unqork.io/#/display/5ec574becd0af602152c24cb.

1.

Using Express View, right-click anywhere on the browser’s page.

2.

Click Inspect. The Inspect panel opens on the right side of the page.

3.

In Express View, expand the module's Error panel.

4.

Click the Get Submissions ERROR button. You’ll immediately see a 404 (Not Found) response.

5.

In the Inspect panel, click the Network tab.

6.

Click on the failed API call. The text shows in red.

7.

Since it’s a 404 Not Found response, it means the API could not find the resource at the link you provided. As you see in Inspect panel, the system couldn’t find the module.

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 command: angular.element('.unqorkio-form').scope().submission. This is the Unqork Angular command. Using this command lets you see the module’s data in a neat JSON format.

Let’s see what using the angular command looks like in practice. Use the following training module: https://trainingx.unqork.io/#/display/5ec574becd0af602152c24cb.

1.

In Express View, right-click anywhere on the browser’s page.

2.

Click Inspect. The Inspect panel opens on the right side of the page.

3.

Click the Console tab.

4.

In Express View, expand the Read panel.

5.

Click the Get Submissions button.

6.

Returning to the Console tab, enter the angular.element('.unqorkio-form').scope().submission command.

You’ll notice there’s a new nested array under the angular command. An array is a collection of ordered data sets. Arrays have a numbered index that starts at [0]. Since this is a nested array, you must drill down into the data set (as shown in the image below).

1.

Click data.

2.

Click the Property ID of the API’s Plug-In component. In this example, it’s pluginGetSubmissionCall.

3.

Select a submission. They're numbered starting at [0].

4.

Click data.

5.

Click rawData to see the submission data.

Summary of Get Module Submissions Call

It’s important to note that the Get Module Submissions returns 50 submissions. For more information on this call, refer to the API documentation (developers.unqork.io). You’ve now successfully and unsuccessfully run a Get Module Submissions call.

Let’s take a look at other common internal API calls.

List Submissions for Dashboard

The List Submissions for Dashboard call is similar to the Get Module Submissions call. You’ll use List Submissions for Dashboard call to bring submission data into dashboards. This call formats submission data to display in a ViewGrid component.

Again, use the following training module: https://trainingx.unqork.io/#/display/5ec574becd0af602152c24cb/

1.

In Express View, right-click anywhere on the browser's page.

2.

Click Inspect. The Inspect panel opens on the right side of the page.

3.

Click the Console tab.

4.

In Express View, expand the Read panel.

5.

Click the List Submissions for Dashboard button.

6.

Returning to the Console tab, enter the angular.element('.unqorkio-form').scope().submission command.

7.

Like you did with the Get Module Submissions example, drill down into 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]. However, when you drill into index 0, you’ll see all the call’s data. You don’t need to drill further into data the way you did for the Get Module Submissions call.

Unlike the Get Module Submissions call, the List Submissions for Dashboard call brings back more than 50 records. However, for this call to work, you must specify which submission data or metadata you want returned. These are the API call’s parameters.

You’ll notice this call’s Data Source URL (/fbu/uapi/system/getSubmissions) does not reference a module ID. With this call, you must enter the module ID in the Inputs table of the Plug-In component. See below for an example of a successful List Submissions for Dashboard Plug-In setup.

Summary of List Submissions for Dashboard Call

For more information about this call, refer to the List Submissions for Dashboard API documentation at training.unqork.io/fbu/uapi/docs/documentation.

NOTE  You must be logged in to the Training environment for this link to work.

Specify any conditional filtering of the submission data according to the api-query-params library (github.com/loris/api-query-params).

Create Module Submission(s)

Another common API call is Create a Module Submission(s). Why is this call necessary when clicking Save button automatically creates a submission. Well, it has to do with security. Our proxy module setup requires you to create a submission with this API call. It keeps submission data safe and everyone happy.

This call creates one (or more) new module submissions. The API auto-generates the submission IDs. You must provide a JSON object for any module submission data. To create multiple submissions, the Request Body must contain an array of the defined request body structure. You'll find this call’s request body structure in the API documentation at developers.unqork.io.

1.

Drag and drop a Plug-In component onto your canvas.

2.

Select Create Module Submission(s) from the Internal Services drop-down.

The Data Source URL populates with /fbu/uapi/modules/{moduleId}/submissions. This is the same resource URL as our earlier call, Get Module Submissions. The only difference here is that the Request Type is a POST.

With the module ID, you’ll need to specify data for this call. This way, the API knows what information to actually create.

3.

In the Inputs table, enter the following:

a.

Property ID: enter the Property Names of the source module that you want to include in the data of the new submission.

b.

Mapping: map these fields to the corresponding fields in the module where you're creating the submission.

The Inputs table of your Plug-In will look something like this:

Now take a look at the Create Module Submission(s) call in the practice module: https://trainingx.unqork.io/#/display/5ec574becd0af602152c24cb.

1.

In Express View, right-click anywhere on the browser's page.

2.

Click Inspect. The Inspect panel opens on the right side of the page.

3.

Click the Network tab.

4.

In Express View, expand the Create panel.

5.

Enter data in the First Name, Last Name, Joke Question, and Joke Answer fields.

6.

Click the Create Submission button.

7.

Look at the Network tab. If the submission creation was successful, you should see a 201 response under Status.

Summary of Create Module Submission(s) Call

Now you know how to use the Create Module Submission(s) call. This call will come in handy when you create proxy modules.

Tip: For more information on what you can do with this call, select the Create Module Submission(s) call from the Unqork Service drop-down. Then click the Learn More button.

Update Module Submission

This call functions like the Create Module Submission call. But, instead of a POST call, the Update Module Submission is a PUT call. A PUT call is used to update existing data.

The Update Module Submission call supports partial data updates. That is, data sent in the data object doesn’t need to include all the submission data. So, you can use the call to update certain fields.

By default, any fields sent in the API call can update that submission even if they are blank. But, if you mark fields as optional, the fields will only update submission data if they have values.

See the image below for an example:

Summary of Update Module Submission Call

This call also has additional functionality. You can delete a data key using the unsetData parameter. You can also replace the entire data set of a submission by using the replaceData parameter.

Tip: For more information on using this call and it’s counterpart, Update Multiple Module Submissions, see the API Documentation (developers.unqork.io).

Deletes Multiple Module Submissions

The Deletes Multiple Module Submissions call has the ability to "soft-delete" submissions based on the submission IDs provided. Soft-delete marks the submission as deleted, but doesn't remove it. The soft-deleted submissions won’t appear in query calls, but they could be restored. To restore a submission, use the Restore Deleted Module Submission call. This call's parameters are the module ID where the submissions live and the IDs of the submissions you want deleted. The maximum number of submissions you can delete at once is 25.

You can also “hard-delete” these submissions from the database. If you hard-delete a submission, it can’t be retrieved. To hard-delete a submission, add a query parameter for destroy. Destroy is a Boolean (meaning its value is either true or false). Setting destroy to a value of true hard-deletes the submission from the database.

Summary of Deletes Multiple Module Submissions

Go to the practice module: https://trainingx.unqork.io/#/display/5ec574becd0af602152c24cb

Use the List Submissions for Dashboard to view the module submissions. Copy a submission ID and use the Delete section of the module to delete the submission. Then try restoring the submission.

Tip: You can learn more about this call in the API documentation (developers.unqork.io).

Execute Module

Now for the most important and most frequently used API call: Execute Module.

You might have heard terms like server-side execution or remote execute. These are some of the configurations that rely on the Remote Execute API call. Normally, a module executes in the browser by loading the Express View. Instead, with the Execute Module call, the API executes the module behind the scenes. The module executes on the “server-side.” There are a few important reasons to execute a module by remote execute. Notably, having a module execute server-side is much more secure. That way, sensitive data isn’t passed in the browser. Additionally, a remote execute lets you modularize your application’s functionality.

Under the Modules tab in our API documentation you’ll see the call for Execute Module (developers.unqork.io). This call has some unique functionality worth mentioning:

Key	Description
Validate	This key is a Boolean, meaning you'll pass true or false as its value. The value sent determines whether the call validates submission data post-execution. Validating submission data means the system validates any fields where rules are set. For example, email and phone number formats. Setting Validate to true validates the submission data and returns any errors. Not validating, defaults the key to false.
Save	This key is also a Boolean. The Save key sets whether to save data in the existing submission or to create a new submission. The Save key defaults to false. Also, execution errors prevent data from saving.
saveOnValidationError	Another Boolean. Setting this key to true (along with Save and Validate), saves the submission data despite validation errors. This key defaults to false.
hydrateDataInitially	Always specify this key and set it to true. Setting this key to true populates the data object before the module executes. This is crucial in ensuring that your remote execute only fires when it has all the information it needs. Firing early would cause an unexpected result and response.

1.

To use these keys in the Plug-In component, set the following Inputs:

a.

Property ID: enter the value of the Boolean answer.

b.

Mapping: enter the key (such as hydrateDataInitially).

Summary of Execute Module

This API call, like all the others, has a parameter of the module ID of the module you want to execute. In the module you’re executing, you need an Initializer with a trigger type of New Submission or Edit Submission. This kicks off the chain of events leading to the remote execution.

Tip: Check out developers.unqork.io to learn more about this and other API calls.

Lab

To see how Unqork's API calls are configured, check out the practice module here: https://training.unqork.io/#/form/5edff945102265020e847a32/edit.