Reports with Parameters

Creating Reports with Parameters

To use parameterized reports, it is important to follow some strict guidelines:

1. Begin the section with params.add().
2. List the name of the parameter. The first argument in each parameter must always be the name. Naming conventions require the name to be within quotes, begin with a lowercase letter, and separate additional words with either an underscore or an uppercase letter.

   params.add('my_name')

   OR

   params.add('myName')

3. Add the type of data for the parameter. Each parameter can only have one type, but each must have a data type.

   Use quotation marks around each type as it is entered into the code:

   params.add('myName', type='str')

4. Add the optionsfor that parameter within the parentheses. Each item in the parameter must be separated by a comma.

   Use quotation marks around the information provided for each option with the exception of True/False, integers and floats:

   params.add('facility_name', type = 'list', choices=['North', 'South', 'Mountain', 'Desert'], default='North')

5. End the parameters section of the report's code with params.end().
6. Assign the value of the parameter to a variable that can be used elsewhere in the compound report if desired. For example: mode = params.parameters['parameter_name'].value. Mode can be any name desired, and parameter_name can be any parameter desired. However, params.parameters and .value are constants and cannot be changed.
7. Finish writing the compound report script.
8. Press Run below the compound report window.

If the type of parameter entered is bool it displays as a checkbox in the Parameters section of Report Builder.

When choices is used, only values specified are valid, any other will fail validation.

Types

• bool: Boolean; the value is either true or false
• date: date; date format (year, month, date), see details below
• dict: dictionary; key:value pair This currently has no visual representation and is only used for validating.
• float: number with decimal places
• int: integer
• list: list; choices can be provided, if not, enter a comma separated list after Run has been clicked
• str: string; choices can be provided, if not, provide information after Run has been clicked

Options

• choices: renders a drop-down list when an array of choices is entered, works for all types of data but Boolean and dates
• description: displays a description for the parameter, shows up as tooltip
• default: sets the default value for the field, works for all types of data
• display_name: displays the name of parameter in the parameters section
• hidden = True: hides the parameter from showing in the parameter section
• min: sets the minimum value of a field, works with integers, floats, and dates
• max: sets the maximum value of a field, works with integers, floats, and dates
• parent: controls the choices available in the child option
• child: links to the parent option, choices change depending on which parent is chosen
• optional = True: allows a null value to pass validation in a parameter, a value must still be entered in the parameter section
• precision: provides the number of decimal places a float will use, ignored by all data types but float

Formatting Date Parameters

Date parameters must use a date object for all options used. To do this, add datetime.date(yyyy, m, d) to each option. The year must contain four characters; the month and the date may contain either one or two characters depending on need. For example, the minimum value option would read min=datetime.date(2015, 1, 1). A print function will automatically convert the date to a format the server understands, 2015-01-01.

If any of the options below are used in a date parameter, they must contain the date object:

• default
• min
• max

When using a date parameter, the report must enter import datetime at the beginning of the report in the setup section of the code.

Formatting Parent-Child Parameters

Parameters can be set with parent and child options. When these options are used, two parameters are linked. The values of the second parameter change depending on the choice of the first parameter.

To create the parent-child relationship use the steps below:

1. Create the lists to be used in the parent and child parameters. Though the example below does not show it, it is possible to create the lists by querying the search server.

   facilities = ["Practice A", "Practice B", "Practice C", "Practice D"]
   providersList = ["Doctor A", "Doctor B", "Doctor C", "Doctor Q", "Doctor X", "Doctor Y", "Doctor Z"]
   
   practicesList = ["All"] + sorted(facilities) #Make a new list of the sorted facilities with "All" at the top of the list
   providersList = ["All"] + sorted(providersList)

2. Add the parent parameter. These choices control the values displayed in the child parameter. To link to the child parameter, add child = ["child_parameter_name"]to the parameter. Use a comma separated list to link to more than one child.

   # the providers parameter is driven by the practices
   params.add("practices", type="list", choices=practicesList, default='Practice B', display_name="Practices", child = ['providers'])

3. Add the child parameter. These values change depending on the selection of the parent parameter. Link the child parameter to the parent parameter by entering parent = {. Assign the correct values to each option available in the parent parameter.

   params.add("providers", type="list", choices=providersList, default=providersList[0], display_name="Providers", parent = {  
       "name": "practices",
       "values": {
           "All": {
               "choices": ["Doctor A", "Doctor B", "Doctor C", "Doctor X", "Doctor Y", "Doctor Z"],
               "default": ["Doctor C"]
           },
           "Practice A": {
               "choices": ["Doctor A", "Doctor B", "Doctor C"],
               "default": ["Doctor B"]
           ...#List the rest of the practices
   
           },
           "default": ["Doctor Z"]
           }
       }
       #If no value for practices revert to normal choices and default
       #On selects, multiselects or unselects recalculate, union of choices, first default encountered
   )

4. End the parameters section with params.end().

It is possible to pull data from the server to provide the values for the parents and children by writing queries and calculating the lists from the queries.