Create a custom form

• Single line text
• Paragraph
• Text with formatting
• Descriptive text

(Required)Type a descriptive label to display above the field. You can change the label at any time.

IMPORTANT: Avoid using special characters in this label. They don't display correctly in reports. For more information, see Notes on field names and labels.

• Single line text
• Paragraph
• Text with formatting

(Required) This name is how the system identifies the field. When you are configuring the widget for the first time and you type the label, the Name field populates automatically to match it. But the Label and Name fields are not synchronized—this gives you the freedom to change the label that your users see without having to change the name that the system sees.

For more information, see Notes on field names and labels.

• Single line text
• Paragraph
• Text with formatting
• Descriptive text

• Single line text
• Paragraph
• Text with formatting

Select the type of data that will be captured in the custom field.

NOTE:

• This field cannot be edited after the form is saved. If you intend to use your field in mathematical calculations, ensure that you select a Number or Currency format.
• When you select Number or Currency, the system automatically truncates numbers that start with 0.
• The character limit for Number fields is 16. You can also use a Text field to enter numbers and avoid the limit.

• Single line text
• Paragraph

• Single line text
• Paragraph

• Descriptive text

(Required) Type a descriptive label to display above the custom field. You can change the label at any time.

IMPORTANT:

Avoid using special characters in this label. They don't display correctly in reports. For more information, see Notes on field names and labels.

• Radio buttons
• Checkbox group
• Single-select dropdown
• Multi-select dropdown

(Required) This name is how the system identifies the field. When you are configuring the widget for the first time and you type the label, the Name field populates automatically to match it. But the Label and Name fields are not synchronized—this gives you the freedom to change the label that your users see without having to change the name that the system sees.

For more information, see Notes on field names and labels.

• Radio buttons
• Checkbox group
• Single-select dropdown
• Multi-select dropdown

Type any additional information about the custom field. When users fill out the custom form, they can hover over the question mark icon to view a tool tip containing the information you type here.

• Radio buttons
• Checkbox group
• Single-select dropdown
• Multi-select dropdown

Select the type of data that will be captured in the custom field.

NOTE:

• This field cannot be edited after the form is saved. If you intend to use your field in mathematical calculations, ensure that you select a Number or Currency format.
• When you select Number or Currency, the system automatically truncates numbers that start with 0.
• The character limit for Number fields is 16. You can also use a Text field to enter numbers and avoid the limit.

• Radio buttons
• Checkbox group
• Single-select dropdown
• Multi-select dropdown

• Radio buttons
• Checkbox group
• Single-select dropdown
• Multi-select dropdown

• Radio buttons
• Checkbox group
• Single-select dropdown
• Multi-select dropdown

1. Click Options, then enable any of the following:

   • Show Values: Shows the values of each choice in the field. The label of each choice shows by default.
   • Sort Choices A-Z: Sorts the choices you add alphabetically in the field.

2. For each choice you add for the user, click the gear icon , then select one of the following options:

   • Select by Default: Select the choice by default in the field.

   • Hide Choice: Hide the choice in the field. Hidden choices remain accessible in reports.

   • Remove Choice: Remove the choice from the field.

     WARNING: If you have current objects using this choice, do not remove it from the field. Removing it will cause historic data to be lost. Instead, select the option to hide it, which prevents users from selecting it in the future.

NOTE:

There is no limit for how many choices you can select.

• Radio buttons
• Checkbox group
• Single-select dropdown
• Multi-select dropdown

(Required) Type a descriptive label to display above the custom field. You can change the label at any time.

IMPORTANT: Avoid using special characters in this label. They don't display correctly in reports. For more information, see Notes on field names and labels.

• Typeahead
• Date

(Required) This name is how the system identifies the field. When you are configuring the widget for the first time and you type the label, the Name field populates automatically to match it. But the Label and Name fields are not synchronized—this gives you the freedom to change the label that your users see without having to change the name that the system sees.

For more information, see Notes on field names and labels.

• Typeahead
• Date

Type any additional information about the custom field. When users fill out the custom form, they can hover over the question mark icon to view a tool tip containing the information you type here.

• Typeahead
• Date

• Date

Select the object type that you want to associate with the field.

Once you have clicked Apply or Save+Close, you cannot change the object type for the field.

NOTE:

• If your Workfront administrator customized the name for Portfolios, Programs, or Projects in the Workfront user interface, the default Workfront name for the object appears in this dropdown list, not the customized name. See your Workfront administrator if you need help with this.
• The following object types are supported in the iOS and Android Workfront Mobile Apps: User, Company, Group, Job Role, Portfolio, Program, Project, and Template.

• Typeahead

Add a filter for an object type to limit the objects users can choose when they are using the field.

For example, you could limit a field so that user names can be selected only if they meet the following criteria:

• They belong to a group or groups that you specify
• They are associated with a role or job title you specify
• They belong to the same group as the person using the field

You must define the filter for the object type you selected using Text Mode syntax. For information about creating a filter using Text Mode, see Edit a filter using text mode.

NOTE:

• If you are editing an existing custom form, adding a filter to a Typeahead field does not remove any objects (outside the scope of the filter) that users have already added using the field.
• This filter is not available on mobile devices. If you use the filter for a Typeahead field, the field will appear on users' mobile devices unaffected by the filter.

• Typeahead

• Typeahead
• Date

(Required) Type a descriptive label to display above the custom field. You can change the label at any time.

IMPORTANT: Avoid using special characters in this label. They don't display correctly in reports. For more information, see Notes on field names and labels.

(Required) This name is how the system identifies the field. When you are configuring the widget for the first time and you type the label, the Name field populates automatically to match it. But the Label and Name fields are not synchronized—this gives you the freedom to change the label that your users see without having to change the name that the system sees.

For more information, see Notes on field names and labels.

Select the type of data that will be captured in the custom field.

NOTE:

• You can change the format type after the form is saved, with one limitation: All existing values on objects must be able to be converted to the new type. (For example, if the format type is Text, and an object is storing the value "abc," you cannot convert the field and will get an error that the system cannot convert "abc" to number/currency.) If you intend to use your field in mathematical calculations, ensure that you select a Number or Currency format.
• When you select Number or Currency, the system automatically truncates numbers that start with 0.
• The character limit for Number fields is 16. You can also use a Text field to enter numbers and avoid the limit.

Type or paste the URL for the API.

The API URL must return a JSON content of the options that you would like to show in the dropdown. You can use the JSON Path field to select the specific values from the returned JSON to be dropdown options.

When entering the API URL, you can optionally pass the following values in the URL:

• $$HOST - This represents the current Workfront host and can be used to make /search API calls to the Workfront API. When this wildcard is used, the authentication is handled and users don't need to send authentication headers. (For example, users can search tasks using the base URL $$HOST/attask/api/task/search and it will allow searching tasks and selecting values from a returned list of tasks.)

• $$QUERY - This represents the search text that the end user types in the field and allows you to implement query filtering for your end users. (The user will search for the value in the dropdown.)

  If the API you are referencing allows it, you can also include modifiers in your search query to identify how the search should work. For example, you can use the following as the Base API URL to allow people to search for any Workfront projects that contain specific text: $$HOST/attask/api/v15.0/proj/search?name=$$QUERY&name_Mod=contains.

  Learn more about the Workfront search modifiers in API Basics.

  NOTE: If you are not using $$QUERY and the user types text in the search box, it will narrow down the choices you already have. However, if you use $$QUERY and the user types anything, a new network call to your API is performed. Therefore, if you have more than 2000 values in your API, and the API supports querying, you can utilize $$QUERY to not only search from the existing 2000 values, but from the original API with the narrowed down options.

• {fieldName} - Where fieldName is any custom or native field in Workfront. This way you can implement cascading dropdown option filters, when you pass the value of an already selected field to the External lookup field to filter down options. (For example, the Region field already exists on the form and you are narrowing a list of countries from the API to those that are in a specific region.)

  For an external lookup field that has a dependency on other fields (using the {fieldName} syntax), the options returned from the API are limited to those that match any strings or values entered in the other fields. (This functionality is not supported in lists and reports.)

• {referenceObject}.{fieldName} – Where the field is part of an object. This syntax is similar to custom expressions. (For example, portfolioID={project}.{portfolioID})

NOTE: Review the documentation for the API you are working with for the specific queries you can define.

Type or paste the JSON path for the API.

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.

For example, if your API URL returns JSON in this format:

   {
    data: {
      { name: "USA"},
      { name: "Canada"}
    }
   }

then you can use "$.data[*].name" to select USA and Canada as dropdown options.

For more information about the JSON Path and ensuring you write the correct JSON Path, refer to https://jsonpath.com/.

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.

(Required) Type a descriptive label to display above the widget. You can change the label at any time.

IMPORTANT: Avoid using special characters in this label. They don't display correctly in reports. For more information, see Notes on field names and labels.

(Required) This name is how the system identifies the widget. When you are configuring the widget for the first time and you type the label, the Name field populates automatically to match it. But the Label and Name fields are not synchronized—this gives you the freedom to change the label that your users see without having to change the name that the system sees.

For more information, see Notes on field names and labels.

(Required) Type or paste the URL of the widget where it is stored on the internet.

If you are adding a video widget, currently you can do so by adding the following in the URL box:

• YouTube or Vimeo link

• Google Drive video link

• Link to video with MP4 and MOV extension

• Link to video already uploaded to the Documents area in your Workfront instance. For instructions, see Add a video widget to a custom form from the Documents area in this article.

(Required) Type a descriptive label to display above the field. You can change the label at any time.

IMPORTANT: Avoid using special characters in this label. They don't display correctly in reports. For more information, see Notes on field names and labels.

(Required) This name is how the system identifies the field. When you are configuring the field for the first time and you type the label, the Name field populates automatically to match it. But the Label and Name fields are not synchronized—this gives you the freedom to change the label that your users see without having to change the name that the system sees.

For more information, see Notes on field names and labels.

(Required) Select a Workfront native field.

Only native fields for the form's objects are available. For example, if the Object Types list at the top of the form designer shows Project, you will be able to select native fields for projects but not fields that are specific to tasks.

Add a filter for the reference field to limit the list of items users can choose from when they are using the field.

For example, you could limit a field so that user names can be selected only if they meet the following criteria:

• They belong to a group or groups that you specify
• They are associated with a role or job title you specify
• They belong to the same group as the person using the field

You must define the filter for the reference field you selected using Text Mode syntax. For information about creating a filter using Text Mode, see Edit a filter using text mode.

NOTE:

• The filter option is only available when you reference a native typeahead field, such as Portfolio, Company, or Owner.
• If you are editing an existing custom form, adding a filter to a native field does not remove any objects (outside the scope of the filter) that users have already added using the field.
• This filter is not available on mobile devices. If you use the filter for a native field, the field will appear on users' mobile devices unaffected by the filter.

(Required) Type a descriptive label to display above the widget. You can change the label at any time.

IMPORTANT: Avoid using special characters in this label. They don't display correctly in reports. For more information, see Notes on field names and labels.

(Required) This name is how the system identifies the widget. When you are configuring the widget for the first time and you type the label, the Name field populates automatically to match it. But the Label and Name fields are not synchronized—this gives you the freedom to change the label that your users see without having to change the name that the system sees.

For more information, see Notes on field names and labels.

(Required) Type or paste a valid XD prototype link.

Note: The Link Access setting on the Share tab in Adobe XD must be set to Anyone with the link. Otherwise, users will not be able to view the prototype.

(Required) Type a descriptive label to display above the field. You can change the label at any time.

IMPORTANT:

Avoid using special characters in this label.

We recommend that you choose a label by which you can easily identify where the Planning record is coming from. Add information like the name of the workspace or the name of the record type.

(Recommended) Type any additional information about the field. When users fill out the custom form, they can hover over the question mark icon to view a tool tip containing the information you type here.

Here, you can add explicit information about the record and the objects you are connecting.

(Required) Select a Workfront object type that is connected to a record type in Workfront Planning.

You may select from the following object types:

• Project
• Portfolio
• Program
• Company
• Group

Only Workfront object types for the form's object types are available.

For example, if the Object Types list at the top of the form designer shows Project, you can only select Project in this field, and you cannot select Portfolios, although portfolios can also be connected to record types.

(Required) Select the Planning workspace where the records you want to display in Workfront come from.

Only workspaces that are connected to the object types you selected in the Object type field display.

(Required) Select the Workfront Planning record type that has a connection with the Workfront object type.

Only record types that have connections to the object type you selected in the Object type field display.

(Required) Select the connection field between the selected Planning record type that you want to display on the Workfront objects and the Workfront object type.

NOTE

You can have multiple connection fields between the same object and record types, but you can select only one field.