POST Report Definitions (v2)
The POST /Reports/Definitions operation creates a new report definition for the newer report system. A report definition includes the report ID, title, and description, as well as a layout that defines the report parameters and widgets. The layout lists all parameters required by the widgets included in the report and provides the configuration details for each widget, including references to the predefined widgets used in the report. On success, the operation returns HTTP 200 OK with details of the reports.
Note: This operation is available only in Version 2 and does not have a Version 1 equivalent.
Table 702: POST Reports Definitions Input Parameters
| Title |
Body |
Required. A string containing the user-defined title of the report. |
| Description |
Body |
Required. A string containing the user-defined description of the report. |
| Layout |
Body |
Required. The layout of a report definition contains a list of widgets (referencing predefined widgets) and their report parameters.
Note: The description and name of the parameters used by the widgets can be customized to meet your specific user needs. Customizing the parameter name allows you to use the same parameter type (for example, certificate collection) multiple times on the same report in different widgets and reference different values. For more information, see Customize Report Parameters.
 Show report layout details.
| ReportParameters |
Required. An array of objects defining all the widget parameters for the report. Show report parameter details.
| Name |
Required. A string indicating the widget parameter name. This value reflects the effective parameter name—either the user-defined name (if configured) or the default name.
Report parameter names may contain only alphanumeric characters, spaces, tildes (~), hyphens (-), and underscores (_).
|
| Description |
A string indicating the optional, user-defined description of the widget parameter. |
| ParameterTypeId |
Required. A string indicating the Keyfactor Command reference GUID of the report parameter.
If custom parameters are used, the ParameterTypeId is used to determine the parameter to widget links. This allows for the use of, for example, more than one certificate collection per report.
|
|
| Widgets |
An array of objects that indicate a list of widgets and their linked report parameters that make up the report.
Show report definition widget details.
| Id |
Required. A string indicating the Keyfactor Command reference GUID of the widget.
Use the GET Reports Widgets (v2) operation to determine the widget ID.
|
| Title |
A string indicating the name of the widget in this report. This is a system-defined, read-only value. |
| Description |
A string indicating any description that may be associated with the widget. This is a system-defined, read-only value. |
| X |
An integer indicating the starting horizontal (X) position of the widget on the report page. The first widget added to a page takes position 0 (zero). Each additional widget is positioned according to the grid space occupied by the widgets beside it. See Table 12: Available Widgets for the dimensions of each widget. |
| Y |
An integer indicating the starting vertical (Y) position of the widget on the report page. The first widget added to a page takes position 0 (zero). Each additional widget is positioned according to the grid space occupied by the widgets above it. See Table 12: Available Widgets for the dimensions of each widget.
Tip: For example, the first widget added would be at X:0 Y:0. If that widget is a 2 x 2, the next widget added would be at either X:3 or Y:3 depending on its size, and so forth.
|
| Static |
Required. A Boolean indicating whether the widget is static (True or False). A widget is considered static if its X/Y position has been locked For more information, see Editing a Report Lock, Unlock, or Move Widgets. |
| Parameters |
Required. An array of objects defining the parameters in use for the report. Show parameter details.
| Name |
A string indicating the predefined name of the report parameter associated with this widget. |
| ReportParameter |
Required. A string indicating the user-defined name of the report parameter associated with this widget. |
| ParameterTypeId |
Required. A string indicating the Keyfactor Command reference GUID of the parameter type ID. This is used to link the widget to the parameter. |
| ParameterDataType |
A string indicating the data type of the parameter. Possible values include:
- Bool
- DateTime
- Guid
- Int
- ListOfInts
- String
|
|
| Text |
A string containing the text provided in the user-defined Text Entry widget. This text only displays if the widget is a text-based widget. If any text is added to a non-text widgets it will get cleared upon saving. Show as Null if empty. |
|
|
Table 703: POST Report Definitions Response Data
| Title |
A string containing the user-defined title of the report. |
| Description |
A string containing the user-defined description of the report. |
| Layout |
The layout of a report definition contains a list of widgets (referencing predefined widgets) and their report parameters.
Note: The description and name of the parameters used by the widgets can be customized to meet your specific user needs. Customizing the parameter name allows you to use the same parameter type (for example, certificate collection) multiple times on the same report in different widgets and reference different values. For more information, see Customize Report Parameters.
| ReportParameters |
An array of objects defining all the widget parameters for the report.
| Name |
A string indicating the widget parameter name. This value reflects the effective parameter name—either the user-defined name (if configured) or the default name.
|
| Description |
A string indicating the optional, user-defined description of the widget parameter. |
| ParameterTypeId |
A string indicating the Keyfactor Command reference GUID of the report parameter.
If custom parameters are used, the ParameterTypeId is used to determine the parameter to widget links. This allows for the use of, for example, more than one certificate collection per report.
|
|
| Widgets |
An array of objects that indicate a list of widgets and their linked report parameters that make up the report.
| Id |
A string indicating the Keyfactor Command reference GUID of the widget.
|
| X |
An integer indicating the starting horizontal (X) position of the widget on the report page. The first widget added to a page takes position 0 (zero). Each additional widget is positioned according to the grid space occupied by the widgets beside it. See Table 1: Available Widgets for the dimensions of each widget. |
| Y |
An integer indicating the starting vertical (Y) position of the widget on the report page. The first widget added to a page takes position 0 (zero). Each additional widget is positioned according to the grid space occupied by the widgets above it. See Table 1: Available Widgets for the dimensions of each widget.
Tip: For example, the first widget added would be at X:0 Y:0. If that widget is a 2 x 2, the next widget added would be at either X:3 or Y:3 depending on its size, and so forth.
|
| Static |
A Boolean indicating whether the widget is static (True or False). A widget is considered static if its X/Y position has been locked For more information, see Editing a Report Lock, Unlock, or Move Widgets. |
| Parameters |
An array of objects defining the parameters in use for the report.
| Name |
A string indicating the predefined name of the report parameter associated with this widget. |
| ReportParameter |
A string indicating the user-defined name of the report parameter associated with this widget. |
| ParameterTypeId |
A string indicating the Keyfactor Command reference GUID of the parameter type ID. This is used to link the widget to the parameter. |
| ParameterDataType |
A string indicating the data type of the parameter. Possible values include:
- Bool
- DateTime
- Guid
- Int
- ListOfInts
- String
|
|
| Text |
A string containing the text provided in the user-defined Text Entry widget. This text only displays if the widget is a text-based widget. If any text is added to a non-text widgets it will get cleared upon saving. Show as Null if empty. |
|
|
Tip: See the
Keyfactor Reference and Utility, which allows you to call API operations and view results. It is primarily intended for validation, testing, and development, and also serves as an interactive supplement to this API documentation. You can access it from the help menu (
) in the
Management Portal.
