---
title: "Reports with Parameters"
slug: "reports-with-parameters"
updated: 2026-10-19T23:43:47Z
published: 2026-10-19T23:43:47Z
canonical: "docs.imat.io/reports-with-parameters"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.imat.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports with Parameters

Parameterized reports help the user more easily use compound reports. By entering parameters within the report code, it becomes possible to use the same compound report for multiple similar reports. For example, you can enter all the date parameters at one time instead of writing nearly the same report multiple times or altering the code of the same report multiple times to change a date range.

---

![](https://cdn.document360.io/5bf5f14a-9e3f-48aa-a2b9-2be6d9100091/Images/Documentation/params-section(1).png)Click on image to zoom

## Create 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 (1) quotes around the name, (2) names begin with a lowercase letter, and (3) additional words separated with either an underscore or an uppercase letter.

```python
params.add('my_name')
```

OR

```python
params.add('myName')
```
3. Add the parameter’s data [type](/reports-with-parameters#types). Each parameter can only have one type, but each must have a type.

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

```python
params.add('myName', type='str')
```
4. Add the [options](/reports-with-parameters#options) for that parameter within the parentheses. Separate each item by a comma.

Use quotation marks around the information provided for each option except for `True`/`False`, integers, and floats:

```python
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* should be the name of one of your previously-defined parameters. 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 specified values are valid; any other value fails validation.

event_note Note:

The hash marks surrounding the parameters section in the report example are not required; however, they can help quickly identify the parameters section later.

---

  

### Types

- **bool**: Boolean; the value is either `True` or `False`
- **date**: date; date format (year, month, date); [see date formats](/v1/docs/reports-with-parameters#format-date-parameters)
- **dict**: dictionary; key:value pair. *This currently has no visual representation and is only used for validation.*
- **float**: number with decimal places; required unless you also use `required=False` *and* `optional=True`
- **int**: integer; required unless you also use `required=False` *and* `optional=True`
- **list**: list; choices can be provided; if not, enter a comma-separated list after **Run** has been clicked; required unless you also use `required=False`
- **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. The report writer cannot leave the field blank.
- **description**: displays a description for the parameter; shows up as a tooltip
- **default**: sets the default value for the field; works for all types of data
- **display_name**: displays the name of the 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; works with integers and floats
- **required = True/False:** gives immediate feedback to decide if a parameter can be blank or not; works with lists, integers, and floats
- **precision**: provides the number of decimal places a float will use; ignored by all data types but float
- **description:** provides a tooltip when hovered over

event_note Note:

Advanced users can use an advanced option, **validation**. However, this option is intended only for advanced users because, if used incorrectly, it may cause the report writer to leave proper integer and string notation. See [Custom Validation](/custom-validation-for-reports-with-parameters) for more details.

---

![](https://cdn.document360.io/5bf5f14a-9e3f-48aa-a2b9-2be6d9100091/Images/Documentation/params-date(1).png)Click on image to zoom

## Format 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 include `import datetime` at the beginning of the report in the setup section of the code.

---

![](https://cdn.document360.io/5bf5f14a-9e3f-48aa-a2b9-2be6d9100091/Images/Documentation/parent-child(1).png)Click on image to zoom

## Format 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.

```python
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.

```python
# 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.

```python
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
    }
    #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.

---

![](https://cdn.document360.io/5bf5f14a-9e3f-48aa-a2b9-2be6d9100091/Images/Documentation/run-with-defaults(1).png)Click on image to zoom

## Use run_with_defaults

It is possible to write a parameterized report that will automatically run the defaults without requiring the person who is executing the report to enter any additional input. By setting run_with_defaults to True the report will run with the default value and will not require the user to enter any input in the parameters unless the default values do not exist or do not pass validation. Some guidelines to using run_with_defaults are below:

1. Write a report including the entire scope of information that will be required in the parameters.
2. Within the `params.add` line, call the report into that parameter with `choices = report_name`.
3. Within the `params.add` line, set a default.
4. End the parameter section with `params.end(run_with_defaults=True)`.

Below, the sample report is named *insomnia*. The choices are sorted by age, the server returns only unique values, the values have been converted from the dataframe into a list.

Python

```python
insomnia=get_hits('()insomnia n.age:[20 TO 60]', fields = 'extract.patient_sex, extract.age, extract.patient_id, extract.patient_full_name, extract.patient_date_of_birth')

params.add('gender', type = 'str', choices = ['male', 'female'], default = 'male')
params.add('insomnia_age', type = 'int', default = 55, min = 20, max = 100, choices = sorted(insomnia["extract.age"].unique().tolist()))

params.end(run_with_defaults=True)

print(params.insomnia_age)
```

In order for run_with_defaults to work, the default must pass validation, and all parameters must contain defaults. If any of the defaults fail validation, the user will be provided with the parameters and asked to enter input for each parameter that failed.

---

![](https://cdn.document360.io/5bf5f14a-9e3f-48aa-a2b9-2be6d9100091/Images/Documentation/running-parameterized-report(1).png)Click on image to zoom

## Run a Report with Parameters

If the report has a parameters section, fields are displayed for additional input for those parameters before results are returned:

1. Provide values for each parameter.
2. Press **Run with parameters**.

To change the choices of the parameters after results have been viewed, make the changes in the **Parameters** section and click **Run with parameters** again.

---

![](https://cdn.document360.io/5bf5f14a-9e3f-48aa-a2b9-2be6d9100091/Images/Documentation/params-error(1).png)Click on image to zoom

## Fix Parameter Errors

The search appliance validates that the parameters are of the correct type and within the ranges specified in the report. All fields provided are required. However, it does not return an error if a checkbox is not checked or if a string field is empty (an empty string is still a string). If the middleware encounters errors with any parameters, the field will be highlighted in red, and an exclamation point will appear next to the field. Hover the mouse over the exclamation point to view the reason for the failed validation. Fix the error and resubmit.