Add a URL to Retrieve Data

Last updated 3/09/2025

The following will need to be added into the External URL Data Access application built in Five to enable you to retrieve data via a public URL:

• GetCustomers()
  function
• Get Customers process
• customers URL

GetCustomers Function

The example function is called

GetCustomers()

and selects the first name and last name of the customers from the Customer table and returns it as an array in a JSON formatted string.

The

executeQuery()

function is used on the

Five

object and is used to execute SQL statements on the Five server, and returns an array of results from the Customer table.

The

createError()

function is used on the

Five

object and will return an error if an error occurs.

A

Results

object is initialized called

resultsData

.

The records retrieved from the

executeQuery()

function are attached to the

resultsData

object using the key

customers

.

A

FiveError

object is created using the

success()

function on the

Five

object. The

resultsData

object is attached as JSON data to the

customerResult

object using the

setData()

function. The results are returned to the calling client.

Add the GetCustomers Function

1. Select Logic in the menu followed by Functions in the sub-menu.

Figure 1 - Functions menu item

2. Click the Add Item button and give your function an ID (GetCustomers) in the Function ID field.

3. Click in the Code field.

Figure 2 - Add GetCustomers function

4. Click the Copy button on the below code block.

Retrieve an array of customer names

function GetCustomers(five, context, result)  {

    ////////////////////////////////////////////////////////////////////////////////////////////////
    // query the data
    ////////////////////////////////////////////////////////////////////////////////////////////////
    const customerData = five.executeQuery('Select FirstName, LastName from Customer', -1);
    if (customerData.isOk() === false) {
        return five.createError(customerData, 'Error executing query');
    }

    ////////////////////////////////////////////////////////////////////////////////////////////////
    // create a resultsData object, which is where we will attach data to be returned
    ////////////////////////////////////////////////////////////////////////////////////////////////
    const resultsData = {};

    ////////////////////////////////////////////////////////////////////////////////////////////////
    // attach the records from the query results to the resultsData object,
    // and return the data by attaching the data to the FiveError object customerResult using setData
    ////////////////////////////////////////////////////////////////////////////////////////////////
    resultsData['customers'] = customerData.records;
    const customerResult = five.success();
    customerResult.setData(five.MIMETypeJSON, resultsData);
    return customerResult;
}

5. Paste the code block over the template in the Code Editor.

6. Click the Save button in the Code Editor app bar.

Figure 3 - Save button

7. Click the Save button in the form app bar.

Figure 4 - Save button

Get Customers Process

The process enables the

GetCustomers()

function to be executed on the Do Run event. The Do Run event is a server event and executes when the URL endpoint gets triggered by a request. For this example, the URL endpoint will be triggered when the URL has been submitted in the browser as no authorization token has been applied.

Add the Get Customers Process

1. Select Tasks in the menu followed by Processes in the sub-menu.

Figure 5 - Processes menu item

2. Click the Add Item button and give your process a title (Get Customers) in the Title field.

Figure 6 - Add Get Customers process

3. Click the Events tab.

Figure 7 - Events tab

4. Click the lookup icon in the Do Run field and select your function (GetCustomers).

Figure 8 - Do Run field

5. Click the Save button in the form app bar.

Figure 9 - Save button

customers URL

The URL references your process so that when the URL is submitted, your URL created in Five will be used to retrieve the data and display it in the browser. Ensure the host name is your Five's host name. Add

/action

to your URL to interact directly with the function attached to your process. Lastly, add the name of your url,

/<YOUR_URL_NAME>

, to complete your targeted endpoint.

Example
https://control-default-externalurldata.5au.dev/action/customers

Add the customers URL

1. Select Setup in the menu followed by URLs in the sub-menu.

Figure 10 - URLs menu item

2. Click the Add item button and give your URL a name (customers) in the URL field.

tip

Use lowercase for your URL name!

3. Click the lookup icon in the Action field and select your process (GetCustomers (Process)).

Figure 11 - Add customers URL

4. Click the Save button in the form app bar.

Figure 12 - Save button

Response Data

To see the data retrieved, you will need to have your application deployed to an environment and add

/action/<YOUR_URL_NAME>

to your application URL.

action

in the URL executes the Do Run event immediatley for the customers process and will display the retrieved data in the browser.

Example

/action/customers

https://control-default-externalurldata.5au.dev/action/customers

1. Click the Deploy to Development button.

note

You may already have you application deployed, in which case, you only need to add the extension to your URL.

Figure 13 - Deploy to Development button

2. Add

/action/<YOUR_URL_NAME>

to your url.

Figure 14 - URL

Returned is a string representation of a

FiveError

object containing information about the retrieval of the data, this can be parsed using a JSON parser and if the

errorCode

is

ErrErrorOk

the results will contain a string representing a JSON result.

Figure 15 - Response format