Forms - API Integration

Summary A form dropdown can fill itself automatically with data from PaT, through an API endpoint. The form API cheat sheet lists the available endpoints and what each returns, such as staff names, job titles, customers or sites. You copy the endpoint you need, add a dropdown to the form, switch on Fetch options from API endpoint, and paste the endpoint in.

Steps

Introduction. API integrations make forms more powerful by letting users pull in relevant data automatically. Instead of typing in information like names, departments or job titles by hand, users simply select or filter data from existing records in other systems. That makes the form faster, more accurate and easier to use, and reduces the risk of errors. With API integrations, forms become smarter and more efficient, and users get the information they need without extra steps.

Opening the form API cheat sheet

Step 1

You need an external data source to pull the data from: in practice, an API cheat sheet. Keep the cheat sheet somewhere that's easily accessible to everyone. A good spot is your intranet, under Shared Links. To open the intranet, click the globe icon at the top left of the screen, to the left of Task Wall. The Intranet panel opens on the left.

Step 2

Click Shared Links, the second item in the Intranet panel, to expand it.

Step 3

Click the link to the cheat sheet, such as Form APIs. The cheat sheet opens in a new tab.

Reading the cheat sheet

Step 4

At the top left of the sheet, the Key explains the codes the sheet uses: DD = Dropdown, FNLN = First name plus last name, ALL = all sites and departments, SITE = Site, DEPT = Department, and a code for your tenancy name.

Step 5

Below the key is a list of your department names, the department options.

Step 6

To the right of the department names is a list of your site names, the site options.

Step 7

The table to the right of the key outlines the key components of each API integration: the Form Element, the Data value and the Scope.

Step 8

The first row is a Dropdown (DD) form element that pulls the data values of First and Last name (FNLN) from all sites and departments (ALL) within your tenancy.

Step 9

The second row is also a dropdown, pulling the first and last name data values from a specific site (SITE) within your tenancy. You specify the site name in the endpoint, as Step 17 explains.

Step 10

The third row is a dropdown that retrieves the first and last name data values from a specific department (DEPT) within your tenancy. You specify the department name in the endpoint.

Step 11

The fourth row is a dropdown that retrieves the job title (JOBTITLE) data value from all sites and departments within your tenancy.

Step 12

The fifth row is a dropdown that retrieves the job title data value from a specific department within your tenancy.

Step 13

The sixth row is a dropdown that retrieves the customer (CUSTOMER) data value from all sites and departments within your tenancy.

Step 14

The seventh row is a dropdown that retrieves the site name (SITENAME) data value from all sites and departments within your tenancy.

Step 15

The eighth row is a dropdown that retrieves the first and last name data values from a specific site and department within your tenancy.

Step 16

To the right of the table, the endpoint URL column has the endpoint for each of those APIs, on the same row. These endpoints retrieve the data each row specifies, turning the different API configurations into requests that PaT can act on.

Step 17

In the endpoints for a specific site or department, a site name or department name is already in the URL, to show exactly where it goes in the endpoint URL. Put your own site or department name in its place: it sets how the information is filtered, and so which data is retrieved.

Step 18

Choose the row that matches the data you want. For example, to send a form to all staff and ask, at the start, who is filling it in, use the first row. It pulls the first and last names of all staff from every site and department, so the form can present a list of everyone for the user to select from.

Step 19

Find the endpoint on that row, in the endpoint URL column, and copy the endpoint URL.

Adding the dropdown to your form

Step 20

Open your form in the SD Form Builder. In the Controls panel on the left, under Common, click and hold Dropdown (Single selection), drag it onto the Canvas and let go.

Step 21

The dropdown appears on the canvas. Click its edit button, the pencil in the row of small buttons at its top right. The Edit form field (Single-Select Dropdown) box opens.

Step 22

On the General tab, change the dropdown's Title to your question, for example "Who are you?".

Step 23

Scroll down to Fetch options from API endpoint.

Step 24

Click its switch so that it shows YES. An Endpoint box appears below Advance mode.

Step 25

Paste the endpoint URL you copied into Endpoint. Then click Save & Close Single-Select Dropdown, at the bottom right of the box.

Result. With the first row's endpoint, when someone clicks the dropdown, it automatically fills with the names of the staff from all sites and departments in your tenancy, and the user selects from the available options.