There are several use cases where an institution needs to add a field or question to a document with a limited set of valid entries beyond what it built into the Kuali Research Modules. In the Proposal Development, Institutional Proposal, Award, Subaward and Negotiation modules custom dropdown lists, or lookups can be built with the Argument Value Lookup table. Once a custom dataset is defined it can be linked to a Custom Data Field or a Questionnaire Question.
Creating an Argument Value Dataset
Navigate to the System Admin Portal > Maintenance > Shared > Argument Value Lookup link.
Click on the 'create new' button in the upper right hand corner of the screen and complete the following fields.
Note: If you are going to be creating several of these values, which is likely if you are populating a custom dropdown you can ctrl+click the 'create new' button and the document will open in a new tab. You can then open as many new tabs as you want without leaving the ArgValue lookup screen. This will avoid having to navigate back to this screen before creating each new entry in your dataset.
- Description (Document Overview): Enter a description per your institution's naming standards.
- Argument Name: This is what associates a series of values in the ArgValue table. A dropdown will display all entries that share the same Argument Name. The Argument Name can only consist of letters and numbers.
- Value: This is the value that will be saved in database if a user selects this option on any fields linked with this Argument Value dataset. Depending on how you configure the fields that use this dataset this may or may not display for the end user.
- Description (Arg Value Lookup): Depending on how you configure the fields that use this dataset the description can display instead of the value that is stored in the database.
- Active: Check this box. If you edit an ArgValueLookup value after it's been used in documents and mark it as inactive it will be preserved on existing documents, but will not be available on new documents.
When you have filled out all of the fields press the submit button at the bottom of the screen. Complete these steps for every value in your dataset.
Examples Use Cases for Having a Different Value and Description:
- There is a field in PD that pulls forward to IP that captures the individual in OSP who is assigned to the proposal. The institution wants to limit options in this field to current staff in the OSP office. The value is used to capture the usernames of the current staff. The description has additional information bout the staff members in the format First Name Last Name | Email | Phone Number. This provides rapid contact information to end users, but the username is stored in the database which is easier to leverage for workload reports.
- An institution's home state has a special reporting requirement for when a project might impact a local protected ecosystem. There are codes assigned by the state corresponding to a variety of classes of potential impact. The institution sets up the codes in the value fields for a series of ArgValue Lookup entries, and the state impact descriptions in the Description fields.
Linking your Dataset to a Custom Data Field
To link your dataset to a Custom Data field follow the instructions in the Cross Module Functionality - Custom Data Fields article. When you create your Custom Attribute you will enter the following values in the Lookup fields.
- Lookup Class: Arg Value Lookup
- Lookup Return: The Argument you entered above for your dataset
Custom Data fields linked to Argument Value datasets will populate Proposal Development as a dropdown list. How this data displays depends on the configuration of the ARG_VALUE_VALUES_FINDER_PREFER_DESCRIPTION parameter. When set to the values below the behavior of the dropdown list will behave accordingly.
Custom Data fields in IP, Award, Subaward, and Negotiation will display as dropdowns and respect the ARG_VALUE_VALUES_FINDER_PREFER_DESCRIPTION parameter if the Display_KNS_Arg_Value_Lookups_As_Dropdowns parameter is set to true. They will display as a lookup if the Display_KNS_Arg_Value_Lookups_As_Dropdowns parameter is set to false.
- DESCRIPTION: The dropdown list will display the Description from the ArgValueLookup entries, but store the Value in the database.
- VALUE: The dropdown list will display the Value from the ArgValueLookup and store the Value in the database.
- BOTH: The dropdown list will display both the Value and the Description from the ArgValueLookup entries, but store the Value in the database.
Linking your Dataset to a Questionnaire Question
To link your dataset to a Questionnaire Question you will create your question and select the following values in the Response Section
- Type: Lookup
- The user will be presented with the ability to search for: Arg Value Lookup
- The field to return is: The Argument you entered above for your dataset
Your question will render as a dropdown list that displays the Description, but stores the Value. If no description is entered for a given entry then the dropdown list entry will display the Value.