Proposal - Preproposal Forms (beta)

What it Does

This feature provides customers, who have Kuali Build and Proposal Development (PD), the ability to leverage Build Forms and Workflows from their Proposal Development application. Administrators can create a form in Build (complete with Workflow) that pulls in PD data (fields, questionnaires, and tables) and link the form to the PD module. The form will then be available for PD users to generate, so they can click on the corresponding tab in PD to start the form in Build and submit it to the Build workflow. Users will be able to see the completed form, as well as the current status and workflow step in both PD and Build. See the following demo of the Preproposal Forms. 

PLEASE NOTE: this feature is in early stages (beta release) so there could be undiscovered issues and we only support functionality/fields as described below.  We recommend initially linking your Kuali Build PRD environment to Kuali Research SBX environment for initial testing/confirmation before we then link to your Kuali Research PRD environment.  Also, this functionality is not available for proposals part of a Proposal Hierarchy.

DEMO

How to Activate Preproposal Forms

1. Submit a support ticket through our ticketing system or emailing us at [e-mail]  requesting to link your Build and PD environments
2. Create and publish the desired forms in Build.
3. Add Build form ID to proposalDevelopment.preproposalForms.applicationIds parameter in Research (see below section on Adding Build Form ID to Proposal Development). 

Adding Proposal Data to Build Form

To populate fields from a Kuali Research Proposal you’ll need to activate and add a unique JSON key to each field in the build form Design view. Specifically the 'Edit unique JSON key' needs to be completed with a reference to each field from the proposal with the correct format explained below (based on the area of the proposal the data is pulled and type of field in the Build form).

PLEASE NOTE:  When building the Preproposal form in Build the gadget type needs to match the data types you are pulling from the Proposal in Kuali Research.  For example, a Text gadget should be used for a string value field or a Date gadget used for a Date field.  Currently, Build forms do not support boolean format from Kuali Research (i.e. true/false - like the 'Has Subcontract?' checkbox field in proposal).  If the types do not match you will receive an error page on the Kuali Research side when you click the 'add form' button in the proposal of kualibuild.KualiBuildException: Form validation failed.  Confirmed gadget types in Build that work with the Preproposal form are Text and Date gadgets.

Pulling From Proposal Data

Each JSON key requires a “proposal.” before the specific variable from the proposal development record. For example to get the proposal number, you’d use “proposal.proposalNumber”. Click here to see available Proposal Development Variables.

Please note, every JSON key has to be unique in a Build form so you can only add a proposal field once to a form - if you list it more than once it will go to error when attempting to save the Preproposal Build form.

Pulling From Proposal Data Advanced

We also have a subset of data that can be pulled that is beyond the normal proposal variables mentioned above and the JSON format is listed below.

• Principal Investigator Name: principalInvestigator.fullName
• Principal Investigator Username: proposal.principalInvestigator.userName
• Proposal Type Name: proposal.proposalType.description
• Proposal Sponsor Name: proposal.Sponsor.sponsorName
• Proposal Prime Sponsor Name: proposal.primeSponsor.sponsorName
• Proposal Deadline Type: proposal.deadlineTypeRef.description
• Proposal URL link: proposal.url

Pulling From Proposal Questionnaire Data

To pull data from questionnaire responses in a proposal you will need to add json in the below format starting with questionnaire.byName.  It then requires the name of the Questionnaire and the Question ID (examples below in bold; quotes need to be included for the name of the questionnaire).

Question for single answers; including radio buttons (it will end in .answer):

• questionnaire.byName['Export Control Screening'].question[10112].answer

Questionnaire with multiple answers (it will end in .answers - note the s):

• questionnaire.byName['Feasibility Questionnaire'].question[10146].answers

Pulling From Proposal Supplemental Information

You can also pull data from a Supplemental Information tab in the proposal (aka Custom Data in the maintenance tables).  This needs to be in the below format and the value [] is specific to the order of the field in the UI of the proposal starting at 0.  This would also include if the questions flowed across multiple tabs within the Supplemental Information section; still be sequential across all.  For example, if you have 2 questions in the first tab/section and 1 in a section tab/section of Supplemental the values would be 0, 1, and 2 in order how they appear.

• proposal.customDataList[0].value (0 indicates first supplemental info field)
  

• proposal.customDataList[1].value (1 is second, etc.)

Please Note: If the order of supplemental info changes or new fields are inserted this will impact how this field logic works in the associated build form.

Adding Data from Proposal to Tables in the Build Form

If you’d like your research data to appear in table form, it requires the table gadget to have a JSON key along with each of the columns. For example, a table of non-employees on the proposal with their Full Name, Role, Country, and Organization would like this.

• The Table Gadget JSON would be: proposal.proposalPersons.?[nonEmployee]

• The JSON keys for each of the columns do not require the proposal. prefix, so they would be:

  • Name: fullName

  • Person Role: role.description

  • Country: rolodex.countryCode

  • Organization: rolodex.organization

Adding fields to Build form to Display in Proposal

You can also add field data from the Build form (specific to the proposal) that will then push back to the Proposal and display in the Submitted Data section.

Fields added in the Build form that have enabled 'Edit unique JSON key' and includes a JSON key will then push over to the Proposal in Kuali Research.  These would be values present also in the proposal so you could see if any values changed between what was entered on the proposal and what was entered in the preproposal build document. Anything that's different is then marked with an asterisk (*).

Adding Build Form ID to Proposal Development

1. The Build Form ID is found in the last section of the URL in the Build form (see below).
2. Log into Research, select “All Links” then search and select “Parameter" to open Parameter Lookup.
    
3. Search for the proposalDevelopment.preproposalForms.applicationIds parameter and click "Edit".
4. Complete the Description section.
5. Enter the Build Form ID in the Parameter Value section followed by a semicolon. If you want multiple Build forms to be available in PD, you should separate each Build Form ID with a semicolon and a space. This will open Parameter Lookup
6. Click “Save”. 

User Experience with Preproposal Forms

Users should now see “Preproposal Forms” in the left hand navigation of their proposal.

Click on “Preproposal Forms” and Click on “Add Form”

They can see the Name of the Build Form that you entered in the parameter.

Once they click “Add Form” on the form they would like to create, the form will automatically be created and open in a separate tab in Kuali Build. 

This will log the user into Build, populate the data in the JSON fields from PD to Build and allow the user to fill in additional information in the form. Once the user has completed the form they can submit the form for workflow.

After the user completes and submits the form, Build will create a document record with an “in progress” status. The form will now follow the designated workflow through Build and update the status in PD.

If the user clicks View Submission they will be directed to a read only version of the build form. Since it’s now in workflow changes cannot be made.

Toggle the view to status to see the workflow history and current step. If the user has the appropriate rights they can also resend notifications or even skip the workflow step.

Meanwhile, any user in PD will see an updated Pre Proposal Forms section where they can view submissions, status, and workflow stage. In addition, they can withdraw the form (or discard if the Build form hasn't yet been submitted).   The 'Reload from Build' option will re-sync information from the Build form to display to current data in the Submitted Dat section.

Please note, when you copy a proposal that contains a Preproposal form you will have the option to select the preproposal in the copy modal to copy into the new proposal.

Other Configuration Options

KRMS Function

We currently have a KRMS Function of 'Check if the preproposal app exists and is at a certain status (_)' that allows you to put in a validation around the status of a linked preproposal form in a proposal.  This would allow you to require the preproposal form be fully approved (complete) before they could submit the proposal into routing; otherwise it throws a validation.  For example, you could set up the KRMS rule as below to require the form to be a status of 'Complete':

Please note, the Application ID is the ID for the specific Preproposal form as explained previously in the article and you need to specify the desired Kuali Build form status (Complete, Denied, Withdrawn, In Progress, Draft, Error).  Also, to direct the 'fix it' link in the validation make sure to add the below Page/Section ID in the validation action section:

• Page ID: PropDev-PreproposalFormsPage
• Section ID: PropDev-PreproposalFormsPage-Section

Lastly, we have an option to limit the Prepoposal form options by the selected Proposal Type in a proposal.  We can create a new parameter by Application ID (related to the specific preproposal form) so you can specify the Proposal Type(s) you want to make it available in the Preproposal Forms tab when clicking on the 'Add Form' link.  For example, the parameter we created in a test environment for a specific Preproposal app (id 6441c2571b1ea159c0addb3e) to only be available if the Proposal Type is Renewal (Proposal Type ID 3):

If interested in this please reach out to us via support ticket and we can help you create a parameter for this use case.

Parameter to Control Preproposal Form by Proposal Type

You can also create a custom parameter for each Preproposal form in Build to control which specific Proposal Types would trigger/allow that Preproposal form to be added to the Proposal.  To do this you would create a new parameter with the Parameter Name being the below with your app ID (as explained above) appended to the end.  

proposalDevelopment.preproposalForms.proposalTypes.<insert app id>

For example, in the parameter pictured below for the app 'UCP Feasibility' form with an app ID (found in the build form url) of 6154bb7d9db3a62f1ff0d568 the Parameter Name should be proposalDevelopment.preproposalForms.proposalTypes.6154bb7d9db3a62f1ff0d56.  The rest of the attributes in the parameter create can match the below and then the Parameter Value should be the Proposal Type IDs that you want this Preproposal form to be available:

Build Document Created By/Submitter

When a Preproposal form is initiated from a Kuali Research proposal the Created By in Kuali Build will default as 'Kuali Service User'.  It will default to this generic Kuali user because the user accounts may not be consistent between your Kuali Research and Kuali Build instances.  The Submitter metadata will then be populated by the user at the institution that completes the form and submits.  Below outlines ways to provide additional user information on either the Build or SP Proposal side related to the proposal initiator and build document submitter to better clarify the users involved.

Pulling the Proposal Initiator into Build Form

If you desire to indicate in the Preproposal document the initiator of the proposal in Kuali Research (for possible notifications or other workflow actions) you can set up a series of integrations to populate that information in your Preproposal information - below outlines the steps required to pull the proposal creator into the form as the associated build user.

1. From the above instructions on pulling Proposal information into your Preproposal form make sure you include the Proposal Number as a field (proposal.proposalNumber).
2. Create an integration to retrieve the proposal creator (createUser) using our rest API to GET DEVELOPMENT PROPOSALS by key (the proposal.proposalNumber field):

   /propdev/api/v1/development-proposals/(key)

   Specifically you would add the below info in the Integration with the integration url being your own domain: https://<insert domain>greendale-tst.kuali.co/res/propdev/api/v1/development-proposals/{{proposalnumber}} 
   
   
3. Add a new field to pull in that information - in below example it's named 'Proposal Number (createUser integration)' but you can name it what you desire.  Then within this field point it to the new integration you just created and chose the Proposal Number field in the dropdown for 'Required data in this form'.  Once that's complete you can then enable the Add linked auto-filled gadgets option and drag over the 'createUser field into the form.  You can make both of these fields a headless integration so the field doesn't display to the end user and is only used for this integration.
   
   
4. Create a second integration that will use the username pulled into the form to then find the associated user profile in Kuali Build.  Specifically you would add the below info in the Integration:
   
   
   
5. Then in the form add one last field to pull in the associated Build user using this second integration - you can also make this a headless integration so it doesn't display to the end user in the form:
   
   
6. Then in the workflow if you want to add an Approval, Task, or Notification stop for this proposal creator you can select the Build User you're pulling into this field:
   
   

Mapping the Submitter of the Build form to the Proposal

As mentioned previously the Build document Created By will always be the 'Kuali Service User' but the user that actually submits the form will be an individual at your institution and populate the Submitter metadata. If you desire to display on the Proposal side who the submitter of the preproposal document in Kuali Build was then you can set up an integration to populate that information in the form and push over to your proposal - below outlines the steps required to pull the preproposal document submitter into the proposal.

FAQs

Roles and Permissions

• Who has access to the document that was created in Build?

• Outside of Build admins, the only people who have access to the doc created and submitted from PD are people who have access to the proposal.

• If a user can open a proposal they have permission to view and edit BEFORE workflow starts in Build, once in workflow they can only view.

• The permissions are granted in Build when the doc is created in PD

• The view permission is not removed in Build, if the user is removed from the proposal

• Currently once the Build form is fully routed with a status of COMPLETE only the App and System admins can open and view the form from the proposal 'View Submission' link.  Unless the user has view access due to Permission configuration in the Build app then they could also open.

• Do Research Administrators have Build access? 

• Not by default, you’ll need to give the users administrator access at the Build product level or for each app you would like them to be able administer.

• How does this relate to KRMS (Kuali Rules Management System)?

• These are specific rules for roles across the research suite and do not impact Build user roles or permissions.

• Can utilize the KRMS Function 'Check if the preproposal app exists and is at a certain status (_)' to check the preproposal form workflow status - see above Other Configuration Options section for more information.

• Can any user who has edit access to the proposal create a form?

• Yes

• Can a user who has view access to the proposal also view the build doc?

• Yes, see below

Build
Roles	Permissions
Administrator	Active Administer, design, and publish the app Create docs in the app Read docs in the app Updated docs in the app
All Authenticated Users	Each can be activated Administer, design, and publish the app Create docs in the app Read docs in the app Updated docs in the app
All Anonymous Users	Can be activated Create docs in the app
Configurable Role	Each can be activated Administer, design, and publish the app Create docs in the app Read docs in the app Updated docs in the app