Rest Data Mapping Picklist

Pick work item values from any REST API, with instant search, multiple values, paging and the option to copy more data from the chosen item into other fields.

Works with the ServiceNow Table API, Microsoft Graph and other OData APIs, GitHub, Azure DevOps REST APIs, or any HTTPS endpoint that returns JSON.

What it does

• Loads only when needed. Nothing is requested until someone opens the list, so forms open fast. You can choose to load the list when the work item opens instead.
• Search as you type. Matches any part of a value or its second line, ignoring case and accents, with the best matches first and highlighted. Lists with thousands of items stay smooth.
• Cascading lists. Use $(Field.ReferenceName) in the URL or parameters. The list reloads when that field changes.
• Copy to other fields. Properties of the picked item, like an ID or email, go into other work item fields. Clearing the field empties them again.
• Clear field states. A red outline and “(required)” when a required field is empty, and a blue outline and dot for a change that isn't saved yet. Fields made required by work item rules are detected automatically.
• Light, dark and high contrast themes, keyboard and screen reader support, and touch-friendly sizing on phones.

What's new in 3.0

3.0 is a major update from 1.x. Everything under "What it does" is new or rebuilt, and so is the following:

• Sign-in methods. Choose None, Basic, Bearer token or API key. The API key goes in the x-api-key header unless you set another one. Controls set up with earlier versions keep working.
• Multiple values. Pick several items. They're stored in the field as A; B; C.
• Second line. Show another property, like an email address, in smaller text under each value. It's searched too, and it tells apart items with the same name.
• Paging. Lists that the API returns page by page load in full: next links (in the body or a Link header), page numbers, offsets and cursors. The first page shows right away while the rest loads.
• Smart detection. Leave JSON path to the list empty and the list is found in the response. Leave Value property empty and the most name-like text property is used. The setup page shows ranked suggestions, with the reason for each, and a Detect button.
• Saved configurations. Save one control's settings and reuse them by name in other controls of the same process. The new Saved configurations tab lists them, loads them for testing, removes them, and exports and imports them as JSON.
• Organization security policy. Limit which hosts controls may call and which sign-in methods they may use, block private network addresses, and cap pages, items and waiting time.
• A clearer setup page. Three tabs: Build and test, Saved configurations and Security policy. The basics are always open, and each optional feature is a collapsible section with a one-line summary of its settings. Import and Export move settings as JSON files, never with passwords or tokens.
• One more permission. The security policy is kept in the extension's data, so 3.0 asks for the extension data scope. An administrator must approve it before the update is installed. See Permissions below.

Updating from 1.x

• Lists load when they're opened. Forms open faster because nothing is requested until someone opens the list. To load it with the form, as 1.x did, check Load the list when the work item opens.
• "Hide native Field label" is gone. It had no effect; set the label on the control's Layout tab instead.
• Clearing a value empties the fields filled from it, instead of leaving the old copied values behind.
• Approve the new permission. Azure DevOps keeps 1.x until an administrator approves the extension data scope in Organization settings › Extensions.
• Your existing settings, including sign-in with Bearer in the user name, keep working without changes.

Set it up

1. Open Organization settings › REST Picklist. On Build and test, enter the endpoint, choose the values and run a test. The preview is the real control. The Add it to your process card lists every Options value, ready to copy. This step is optional, but it's the fastest way to get the settings right.
2. Open Organization settings › Boards › Process, then your inherited process and the work item type. Custom controls can only be added to inherited processes.
3. Choose Add custom control and pick Rest Data Mapping Picklist. On the Options tab, choose the Field to fill in and paste the settings. On the Layout tab, give the control a label.

The test request runs in your browser under your organization's security policy, just like the control on the form. A password, token or API key you enter on the setup page is only used for the test. It's never saved, copied or exported, so type it into the Options tab yourself.

Settings

These are the settings on the control's Options tab, in order. Each label on the Options tab starts with the words below, followed by an example or a hint.

Controls set up with earlier versions keep working. When Sign-in is empty, or None while a user name or password is filled in, the older rules apply: Bearer in User name means a bearer token (the token goes in the password setting), any other user name or password means Basic, and neither means None.

For example, for this response:

{
  "data": [
    { "id": 7, "email": "michael.lawson@example.com", "first_name": "Michael" },
    { "id": 8, "email": "lindsay.ferguson@example.com", "first_name": "Lindsay" }
  ]
}

use JSON path to the list data, Value property email, Second line first_name and Copy to other fields { "Custom.ExternalUserId": "id", "Custom.FirstName": "first_name" }. If you leave both paths empty, the list at data is still found, but the value is picked for you: here first_name, because it looks like a name and is unique in every item.

Advanced settings (JSON)

Everything here is optional. Leave out a key to keep its default. The setup page builds this JSON from its API key header, Paging, Multiple values and Behavior settings, so you rarely need to write it by hand.

Numbers outside their range are brought into it. The organization's security policy can lower maxItems, maxPages and timeoutSeconds further. If the JSON isn't valid, the control shows what to fix instead of loading the list.

Example with several settings:

{
  "paging": { "type": "nextLink", "nextLink": "@odata.nextLink", "maxPages": 20 },
  "apiKeyHeader": "Ocp-Apim-Subscription-Key",
  "copyMode": "first",
  "maxItems": 20000,
  "timeoutSeconds": 60
}

Paging

Every paging type takes maxPages: the most pages to load, from 1 to 100 (default 10).

Every type also stops at an empty page, at a page it already loaded, and at maxPages or maxItems. When a limit cuts the list short, the list says “Showing the first N items”. Each page uses the same sign-in, and next links must stay on the endpoint's own site (see Security below).

OData and Microsoft Graph: the next page's URL is in @odata.nextLink.

{ "paging": { "type": "nextLink", "nextLink": "@odata.nextLink" } }

GitHub: the next page's URL is in the Link header. Add { "per_page": "100" } to URL parameters for fewer requests.

{ "paging": { "type": "nextLink" } }

Page number and size, for an API that takes ?page=2&per_page=100:

{ "paging": { "type": "page", "pageParam": "page", "sizeParam": "per_page", "size": 100 } }

ServiceNow Table API: offset and limit, with JSON path to the list result.

{
  "paging": {
    "type": "offset",
    "offsetParam": "sysparm_offset",
    "limitParam": "sysparm_limit",
    "limit": 1000
  }
}

Cursor, for a response like { "items": [ … ], "meta": { "next_cursor": "c2Vjb25k" } } that expects ?cursor=c2Vjb25k for the next page:

{ "paging": { "type": "cursor", "cursorPath": "meta.next_cursor", "cursorParam": "cursor" } }

Multiple values

Check Allow multiple values to pick several items. Picked values show as chips in the field, and the list stays open after each pick. To take a value off, use its chip's remove button, pick the checked item again, or press Backspace in the empty search box.

• Storage. The field holds the values separated by a semicolon and a space: Contoso; Fabrikam; Northwind. Each value appears once. A value that contains a semicolon can't be picked in this mode.
• Field types. Use a text field. Text (single line) holds 255 characters, so when the next value wouldn't fit, the control says so and doesn't add it. Text (multiple lines) has no such limit, so use it for long lists. Multi-line fields store HTML: the control reads their text and writes values as plain text, never as markup. Other field types, and picklist fields, show a configuration error on the form.
• Copy to other fields. With several picks, each mapped field gets the values of every picked item, joined with ; ("copyMode": "all", the default), or only the first picked item's values ("copyMode": "first"). Removing the last value, or clearing the field, empties the mapped fields.

Saved configurations

A saved configuration lets several controls in a process share one set of settings, so you set up an API once.

To save one, open a control's Options tab, check Save as a reusable configuration for this process, and optionally enter a Reusable configuration name. Without a name, the control's label is used (or the field's reference name when the control has no label). Names must be unique in the process: if two controls save the same name, controls that use it show an error until one is renamed.

To use one, enter its name in Use a saved configuration on another control in the same process. Case doesn't matter. Any setting you fill in on that control overrides the saved one; Advanced settings (JSON) are combined key by key.

• What's shared: the endpoint URL, URL parameters, sign-in method, JSON path to the list, value property, second line, copy to other fields, the not-in-list message and advanced settings.
• Sign-in. The sign-in method is shared: leave Sign-in empty or None on the control that uses the configuration to inherit it, or choose another method to override it. The user name and the password, token or API key are never shared, so fill them in on each control that uses a configuration that signs in.
• What stays per control: the user name, the password, token or API key, the field, Allow multiple values, Load the list when the work item opens and Mark as required when empty.
• Same process only. A control looks up the name in the process of its work item's project. To reuse settings in another process, export them (below).
• Saved configurations are part of the process layout, so only people who can edit the process can create or change them. The security policy can turn them off.
• Changing a saved configuration changes every control that uses it, including where those controls send their own password, token or API key. That's no more than a process editor could already do by editing each control, but it's easy to miss. Keep the Edit process permission to people you trust with those credentials, and use Allowed hosts in the security policy to limit which APIs any control can reach.

The Saved configurations tab in Organization settings › REST Picklist lists the saved configurations in a process (system processes can't have custom controls, so they aren't listed): name, the control that saves it (work item type › label, and field), endpoint host and how many controls use it. For each one you can:

• Load it into Build and test to try it or change it.
• Export it, or Export all, as a JSON file with the shared settings. Credentials are never included.
• Remove it. This unchecks Save as a reusable configuration for this process on the control that saves it. That control stays on the form with its settings; controls that use the name stop working until they're changed. You need the Edit process permission. A control that signs in to its API can't be changed from this page, because sending its settings back to Azure DevOps could replace its password. For those, How to remove tells you where to uncheck the option in the process editor.

To copy settings to another process (or organization), export them, then choose Import on the setup page there. One configuration loads into Build and test; a file with several asks which one to load. Test it, then add a control with those values to the target process and check Save as a reusable configuration for this process. Importing doesn't change any process by itself.

Security policy

Organization settings › REST Picklist › Security policy sets rules for every REST Picklist control in the organization and for the setup page's tests. The policy can only tighten the protections built into the control, never loosen them.

• Controls pick up a saved policy within five minutes. The page shows who changed it last, and when.
• When Allowed hosts or Block private network addresses are on, requests don't follow redirects, because the browser would contact a redirect's target before it can be checked. Requests that sign in never follow redirects either. In both cases, endpoints must use their final address.
• The private network block checks the host name or address written in the URL. A public host name that resolves to a private address (through DNS) can't be detected in the browser. To limit controls to known APIs, use Allowed hosts.
• If the policy can't be read, the built-in rules apply.

What the policy is, and isn't. The policy is stored in this extension's data for the organization. Azure DevOps lets any member of the organization write extension data through its REST API, so the policy is a guard rail that keeps process editors to the endpoints and sign-in methods you allow, not a hard security boundary. The built-in protections below always apply, whatever the policy says.

Security

• The endpoint is called from the browser of the person using the form, so anyone who can open the work item can see the password, token or API key. Use a read-only token limited to this API, never a personal access token with broad rights.
• Anyone who can edit a process can change where its controls send their credentials: by editing a control's endpoint, or the saved configuration it uses. Treat the Edit process permission as access to those credentials, and use Allowed hosts to limit the endpoints.

These protections are built in and always apply:

• Only HTTPS endpoints are called. http://localhost works only when the security policy allows it for testing.
• Cookies are never sent to the endpoint.
• Work item values can go in the path or query string but can't change the endpoint's host. A user name or password written in the URL is refused; use the sign-in settings.
• Requests don't follow redirects when they sign in (so credentials are never forwarded to another address) or when the policy restricts hosts (allowed hosts or private network blocking). Endpoints must then use their final address. Other requests may only be redirected within the same site.
• Next-page links must stay on the endpoint's own site (the same scheme, host and port) and pass the security policy. Otherwise paging stops, the items loaded so far are shown, and nothing is sent to the link.
• Responses are shown as plain text and are never interpreted as HTML. Values written to multi-line (HTML) fields are escaped.
• Saved configurations and exported files never contain user names, passwords, tokens or API keys.
• Every request has a time limit, and every list has an item limit.

CORS

The endpoint is called from the browser, so the service must allow requests from the extension's origin (https://oscararguedasbarboza.gallerycdn.vsassets.io). When the control signs in, the browser first sends a preflight (OPTIONS) request, so the service must also allow the Authorization header, or the API key header, in Access-Control-Allow-Headers. For paging with a Link header, the service must also list Link in Access-Control-Expose-Headers, or the browser hides it. Cookies are never sent, so Access-Control-Allow-Credentials isn't needed. The setup page shows the exact origin if a test request is blocked. This isn't needed for Azure DevOps REST APIs.

Permissions

The extension asks for these scopes. Every call runs as the signed-in person, so it can never do more than their own Azure DevOps permissions allow.

Updating from an earlier version: because 3.0 adds a scope, Azure DevOps doesn't install the update until an administrator approves the new scope in Organization settings › Extensions. Until then, the organization keeps the version it has.

None of these scopes are high-privilege scopes in Azure DevOps' list.

Support, privacy and license

• Support: open an issue at https://github.com/OscarArguedas/RestDataMappingPicklist/issues. The support policy says what to include and what's supported.
• Security: report vulnerabilities privately as described in the security policy.
• Privacy: the extension collects no telemetry and sends nothing to the publisher. See the privacy policy.
• License: MIT. Rest Data Mapping Picklist started as a fork of Dedac/RestDataMappingPicklist by Richard Goforth.