Examples of the External lookup field in a custom form

Last update: October 23, 2024

CREATED FOR:

Admin

An External lookup field in a custom form calls an external API and returns values as options in a dropdown field. Users who work with the object the custom form is attached to can select one or more of these options from the dropdown.

This article provides examples of using the External lookup field to call the same instance of Workfront or a public API. You can also use the External lookup to communicate with an external system such as Jira, Salesforce, or ServiceNow.

For more information about adding an External lookup field to a custom form and additional definitions of the external lookup components, see Create a custom form.

Set up an External lookup field for the same instance of Workfront

You can use the External lookup to bring data from your Workfront instance into the custom form.

Use native Workfront field values in the External lookup

This example shows how to call the Workfront API and bring data from the existing “Status Query” field into your External lookup field.

Open the custom form.
On the left side of the screen, find External lookup and drag it to a section on the canvas.
Enter the Label and Name for the field.
Select the Format for the field.
Enter the API call in the Base API URL field.
- To reference the same instance of Workfront that the custom form is in, use $$HOST for the URL.
- To filter the results based on querying a different field, add $$QUERY.
Example
$$HOST/attask/api/v15.0/project/search?status={DE:StatusQuery}&$$QUERY
Review the Dependencies for the fields that this lookup field is referencing in the API.

A dependency field can be any custom or native field existing in the object’s details page.

In this example, the {DE:StatusQuery} will be replaced with the value of the StatusQuery custom field.
Select the HTTP Method.

This will mostly likely be Get.
Enter the JSON Path to get the results from your API call.

Example
$.data[*].name

NOTE
Header information is not required for a call to the same Workfront instance.
Click Apply.

When the custom form is added to a Workfront object (in this example, a project), it looks similar to this.

Use custom field values in the External lookup

This example shows you to call the Workfront API and bring data from a custom field into your External lookup field. The example custom field is called “Custom Colors.”

Open the custom form.
On the left side of the screen, find External lookup and drag it to a section on the canvas.
Enter the Label and Name for the field.
Select the Format for the field.
Enter the API URL call in the Base API URL field.

Example
$$HOST/attask/api/v18.0/PORT/search?ID={portfolioID}&fields=parameterValues
Review the Dependencies for the fields that this lookup field is referencing in the API.

A dependency field can be any custom or native field existing in the object’s details page.
Select the HTTP Method.

This will mostly likely be Get.
Enter the JSON Path to get the results from your API call.

Example
$.data[*].parameterValues.["DE:Combo Colors"]
- “parameterValues” refers to any custom field in Workfront for the object you’re on.
- For this example, “DE:Combo Colors” is the specific custom field containing the values you want to retrieve.
NOTE
Header information is not required for a call to the same Workfront instance.
Click Apply.

When the custom form is added to a Workfront object, all of the values in the “Combo Colors” field appear in the External lookup field dropdown.

Set up an External lookup field for the Workfront Planning API

An endpoint is available in the Workfront Planning API to search records by record type ID through the Get method. You can use this endpoint to reference Planning records in External lookup fields.

Base API URL: $$HOST/maestro/api/v1/records/search?recordTypeId={recordTypeID}
HTTP Method: Get
JSON Path: $.records[*].data.{fieldID}

{fieldID} is the field to display in the External lookup search results on the custom form for end users.

For more information, see Workfront Planning API.

Set up an External lookup field for a public API

You can use the External lookup to call an external, public API and retrieve data.

This example shows how to call an API of countries (such as https://api.first.org/data/v1/countries) so that you don’t have to hard code all of the country names in the dropdown options.

Open the custom form.
On the left side of the screen, find External lookup and drag it to a section on the canvas.
Enter the Label and Name for the field.
Select the Format for the field.
Enter the API URL call in the Base API URL field.
- You can add $$QUERY to implement query filtering for your end users.
Examples
Lists all countries: https://api.first.org/data/v1/countries

Allows the user to search for any country in the dropdown field: https://api.first.org/data/v1/countries?q=$$QUERY

Allows the user to search for a country in a region: https://api.first.org/data/v1/countries?region={DE:Region}&q=$$QUERY
- The available regions are defined in a separate custom field in Workfront.
- When the user selects a region on the form, then the External lookup field shows only the countries in that region (which country is in which region is defined in the API). The user can also search for a country in the selected region.
Review the Dependencies for the fields that this lookup field is referencing in the API.

A dependency field can be any custom or native field existing in the object’s details page.

In this example, the {DE:Region} will be replaced with the value of the Region custom field.
Select the HTTP Method.

This will mostly likely be Get.
Enter the JSON Path to get the results from your API call.

This option allows extracting data from the JSON returned by the API URL. It serves as a way to select which values from inside the JSON will appear in the dropdown options.

Example
$.data[*].country
(Optional) Click Add Header, and type or paste the key-value pair required for authentication with the API.

NOTE
The Header fields are not a secure place to store credentials, and you should be careful of what you enter and save.
(Optional) Select Multi-Select Dropdown to allow the user to select more than one value in the dropdown.
Click Apply.

When the custom form is added to a Workfront object (in this example, a project), it looks similar to this.

Additional use cases for External lookup fields

There are many other use cases for creating an External lookup.

Use case: Replace typeahead fields, because they can cause problems with reporting.
Solution: Use an API call to existing objects in the system.

Example Base API URL for templates, to replace a typeahead field:
$$HOST/attask/api/v17.0/tmpl/search?isActive=true&name_Sort=asc

Use case: Create dropdown fields with more features (for example, there is line wrap in the External eookup field).
Solution: Use an API call to existing objects in the system, or create a new object and use an API call to this object.

Use case: Define a way for users to maintain their own fields outside of the custom forms area. Set up the External lookup field and you can give users to the objects that comprise the field. This option is good for high maintenance fields and teams.
Solution: Create a new object and use an API call to this object.

Use case: Integration with objects outside of Workfront. For example, accessing another system to get the name of every user, rather than being restricted in a typeahead field.
Solution: Webhook/Fusion automation to connect to other systems.

recommendation-more-help