Create a Filtered User Lookup via Integration

If you want to create a User lookup that only limits the users available for selection, you can use our rest API and filter the list by available attributes.  

Note: This can be done with any type of API that allows filtering - it's not just limited to users!

For more information on how the APIs work and more details on available APIs, please see our Kuali API Documentation.

• Create the Integration
• Add it to the Form
• Adding the Selected User in Workflow

Create the Integration

When establishing the API integration, you will need to utilize the GET List Users call, which has filtering parameter options (i.e. based on Attributes, Fields, etc.).

For this example, we'll filter the entire User lookup by two specific email addresses of two users ([e-mail] and [e-mail]). To set that up, we'll need to point the integration to the endpoint with that filter applied to the end of the integration URL, for example:

/api/v1/users?email=[e-mail]&email=[e-mail].

You can create the new GET integration as pictured below - notice the configured Type of Integration, URL, ID Key, Label Key, and Outputs:

 

When you run a test with these settings, it should return only the two users that were specified in the filtered settings within the dropdown:

Once you select a user, it will also map any specified outputs (like id) which can be used later if you desire to setup routing based on the selection:

If you would like to provide a searchable lookup to narrow down results, you can add &?q to the end of your integration URL and then configure the query parameters as follows:

 

Add it to the Form

Once you have created the integration, you can then add the field to the form by using the 'Data Lookup (list)' Advanced Gadget, and then choosing the newly created integration as the Data Source, which will be listed under External.

If you would like to use this selection within workflow, then you would also click the 'Add linked auto-filled gadgets' option and drag over the id output into the form.

Adding the Selected User in Workflow

To use the user selected in the filtered list within the app workflow, you will need to add one additional integration and field to allow the selection.

Note:In the long term, we plan to streamline this through either a single integration or offer filtering in a new advanced gadget. This is currently on our list of possible future enhancement ideas, but in the meantime you can still achieve this with the below logic.

1. First, make sure you add the linked id field to the form so the associated id of the user selected is populated on the form.
   • Next, create another integration that will utilize this id field in a 'Get single data item' integration to then output the entire user record based on the input id.
   • The URL to use will be: /api/v1/users?fields=id,displayName. This call is using the User API again, and filters specifically by id (which is displayed as the displayName).
   • You can create the new GET integration as pictured below - notice the configured Type of Integration, URL, ID Key, Label Key, and Outputs:

     

     

2. Once that integration has been established, add another field in the form using the 'Data Lookup (single item)' gadget that points to that new integration, and select the input field as the linked id field for the user selected:

   

   This field can be set as a headless integration so it won't show on the form to the end user since it will only be used for integration/workflow.

3. Once that is added, you select the user within the workflow: