Technical - PDF Forms Setup for Award and Subaward

Overview

Institutions often have business processes related to their awards and subawards that require the preparation of forms such as FDP agreements, or financial account setup forms. To help streamline these processes Kuali has a tool that allows institutions to automatically populate data from the award and subaward modules to pdf forms.

PDF Mapping File

When the Kuali system populates a pdf form with data from the system it sends the pdf form, and a mapping file, along with appropriate document data to the pdf service. The mapping file is made up of a series of json objects with the following attributes.

• key: This is the field Name defined in the PDF form.
• action: This is always setValue
• expression: A springLanguage expression that defines what data should populate the field listed in the key attribute.

Here is an example of what this looks like in the json mapping file.

{
"key": "Sponsor Award",
"action": "setValue",
"expression": "#award.sponsorAwardNumber"
},

PDF Mapping Tool

To help create a pdf mapping file for the PDF Forms system Kuali provides a pdf mapping tool.  To use the tool navigate to the following URL:

https://{customerdomain}.kuali.co/pdf

Example: https://miskatonic.kuali.co/pdf

Once you load the pdf tool the first step is to import your pdf.  You must host your pdf on a website locally and provide a direct link to the document (document sharing link won't work).  To do this click on +Add a PDF and enter the direct link to your pdf file.

Note: This file must be hosted directly on a web server where you can directly link to the document.  Download links from most file sharing services like Google Drive will not work since those links do not directly link to the pdf file, and instead connect with a more involved file sharing service.

Once the pdf form populates the next step is to load in a set of sample data to complete your mapping. To do that click on the +Add Sample Data button on the right hand side of the screen.

A modal will appear allowing you to enter json sample data. The sample data for your configurations can be retrieved by sending a sample document to the following APIs (content type for GET must be json format):

Award: https://{Customer domain}{Environment lane}.kuali.co/res/award/api/v2/awards?awardNumber={Award Number}&includeBudgets=false&activeVersionOnly=true

Example: https://miskatonic-sbx.kuali.co/res/award/api/v2/awards?awardNumber=010880-00001&includeBudgets=false&activeVersionOnly=true

Subaward: https://{Customer domain}{Environment lane}.kuali.co/res/subaward/api/v1/subaward-documents/{Document Number}?includeFundingSourceDetails=true&subAwardFundingSourceId=1&calculateAmountInfo=true

Example: https://miskatonic-stg.kuali.co/res/subaward/api/v1/subaward-documents/17730?includeFundingSourceDetails=true&subAwardFundingSourceId=1&calculateAmountInfo=true

The API calls above should be copied and pasted into the mapping document, and then embedded within a json object named "award" if you are mapping an award form, and "subAward" if you are mapping a subaward form.

Example Format

{
"award":
{
"documentNumber": "17730",
"documentDescription": null,
"subAwardId": 94,
ETC. . .
}
}

Examples of full sample data for Award and Subaward.

You can confirm that the sample data has loaded properly by checking that the document structure loads into the Data to Map panel on the left hand side of the screen.

In order to link a field in your pdf to one of the data elements in the Data to Map section first click on the field in the form, then click on the field you want to link it to in the Data to Map section.  The appropriate linkage will then display in the Value box in the upper left hand corner of the screen. This will also display the variable name of the field you have selected underneath the link expression. As you are navigating the pdf whenever you click on a field it will show the expression associated with that field so you can make updates.

The mappings from the sample data to your pdf using a simplified version of the Spring Expression Language. Most spring expression documentation assumes you are working in a full application development framework, and so may not apply to the pdf mapping tool.  To help navigate this limitation here are a number of common mappings used in Kuali documents.

Direct Reference of the fixed value in a list

If you want to have a section of your pdf that lists out several entries that appear in a list, such as every term, or every report listed on your award you would use the structure below. This example will show the fullName of the first personnel in the document, if you listed [1] instead of [0] then it will display the second entry in the list. You could increase this number further if you needed to display additional entries from a given list. The count starting with 0 is a standard array sorting pattern. 

• #award.projectPersons.[0].fullName

Pulling the last value from a list

If you want to pull the last entry in a list, such as listing the most recent entry on the Award Direct F&A Distribution list, instead of counting from the start of a list use the pattern below.  The $ pulls the last entry in this list, and true tells the mapping tool to check all values in the list instead of a specific filtered result.

• #award.awardDirectFandADistributions.$[true].startDate

Dynamic Reference of the first value in a list that matches a filter

If you want to pull in a specific entry in a list, such as the name of the person entry that has the role of PI use the pattern below. The section inside the brackets shows the logic which defines which entry data should be pulled from. The value at the end of the expression indicates which field in that entry data should display in the mapping. I have listed a few common uses of this pattern.

• PI Full Name: #award.projectPersons.^[roleCode == 'PI']?.fullName
• A Custom Data Field #award.awardCustomDataList.^[customAttributeId == 31]?.value
  • Note that the search in this doesn't have quotation marks. Custom Attribute IDs are returned as numbers so if you include quotation marks around the customAttributeId this will not work.
• #award.awardComments.^[commentTypeCode == '9']?.comments
  • Note that this search in this does have quotation marks. Comment IDs are returned as strings so if you do not include quotation marks around the commentTypeCode this will not work.

Pulling Multiple Values from a List Based on a Filter

If you need to list multiple lines that show many values from a list that match a filter, such as listing reports, but only the ones in the Financial Report class then you can include both a filter bracket, and the Array ID in a second set of brackets. The example below will show the description from the first report in report class 3. If you replaced the [0] with [1] it would display the description of the second report in report class 3. You could increase this number further if you needed to display additional entries from a given list.

• #award.awardReportTerms.?[reportClassCode == '3'][0].report.description

Display Multiple Values in a Single Field

To concatenate values use the + operand on string fields. You can also add hard coded strings for the purposes of formatting.  Such as populating the start and end date in a single period of performance field. The example below would display in the following format in your form output (2020-11-01 - 2021-10-31)

• #award.beginDate+" - "+#award.projectEndDate

Adding Values Together in a Single Field

To add values numeric values such as currency fields together use the + operand on number fields.

#award.anticipatedTotalDirect+#award.anticipatedTotalIndirect

Formatting number data as currency

(This will not work on custom data since those fields are always treated as text in the database.

• #formatCurrency(#award.obligatedTotalDirect, 'en-US')

Mapping values that aren’t human readable to human readable values

Sometimes the data stored in the database isn't optimized for read by an end user. You can wrap your field expression in a the#mapVals expression, and then include a comma separated list of the values that can display in this field, and what should show in the pdf if that value is present. You should alternate between database value, and pdf display value like this: ([dbValue1],[pdfDisplayValue1],[dbValue2],[pdfDisplayValue2]).

This will always result in an even number of comma separated values.  If you add one entry after your list of mapped values that will always display if the value in your document doesn't match the mapped list at all. This comma separated list will look like this: ([dbValue1],[pdfDisplayValue1],[dbValue2],[pdfDisplayValue2],[displayIfDbValueIsNotInMapping]).

This example below is for the on campus flag in rates, but this also works for other scenarios like checkboxes.

• #mapVals(#award.awardFandaRate[0].onCampusFlag,"N","On","F","Off")

To see the mapping output you have build with the PDF Mapping tool click on the Actions menu in the upper right hand corner of the screen and select Mapping Output.

This will display a modal that includes your mapping file as text.  You may occasionally want to come in here and make manual changes to the json mapping, and you can save those changes and see how the impact the mapping behavior. When you are ready to download your mapping copy and paste it into a text editor and save the file with a .json extension. You are now ready to upload your mapped pdf to the Kuali Research system.

PDF Forms Table

To review the PDF forms that are setup in the system, or you add new forms lookup go to the All Links page and lookup PDF Form. From here you can search to see the FDP templates that are available in the subaward module out of the box, or add new forms to the system.

To add a new PDF form to the system click the create new button in the upper right hand corner of the screen and complete the following fields on the maintenance document that displays.

• Description: Enter a description per your institution's naming standards.
• Form ID: This is a required field, but has no specific formatting requirements. You can use this field to put in a quick reporting name for your form. This can be a good way to keep track of different versions of the same basic form if you iterate on the form over time.
• Description: This is the name of the form that will display to award or subaward users who want to export this pdf with data from their documents.
• Module Code: This field controls if the form will be available in the Award or Subaward module.
• Template Type Code: This tracks if the form is an FDP template or a custom template that is unique to your institution.
• Active: Keep this checked for a new setup.  If you ever want to retire a form, but keep it in the system so you have a record of how it was mapped while it was still in use you can uncheck the Active flag on a form.
• PDF Form File: Upload the pdf that will be sent to the pdf service when a new form is exported from the Kuali Research system.
• Mapping File: Upload the json mapping file generated by the Kuali PDF Mapping tool.

Printing Forms in Award and Subaward

Once the forms are configured you can then access them in the Award Actions and Subaward Actions tab within the module. Below outlines how to print the forms in each module.

Award

In the Award Actions tab you will see a PDF Forms section within the Print panel once a PDF form is configured:

Once a form is selected you can use the 'print' option to generate a PDF or if you select 'send' it will create a notification with the PDF form attached.  Please note, if you do a multi-select to select more than one form it will download or attach as a zip file.  This will utilize the Award Notice notification template and attach this custom PDF form rather than the out of the box Award Notice PDF.

If you leave the Read Only option checked then the output will not be editable.  If you uncheck this then the output will retain it's editable form fields and when the pdf is opened it can be updated directly.

Subaward

In the Subaward Actions tab you will see the newly configured form as an option in the Print panel:

Please note, the ENABLE_FORM_PRINTING parameter must be enabled for the Print panel to be available in Subaward.  Also, additional information on form mapping related to FDP forms can be found in the Subaward FDP Forms article.