Specification for the BI-Server Plugin Parameter-XML format

For every PRPT file (and in some respect for most artifacts in the BI-Server) a parameter entry UI can query the available parameters and their configuration, including the available values, from the server.

The client application calls a specific URL (the parameter service) with all relevant parameter values already entered by the user and gets back the updated parameter list. For cascading parameters the available values may change when user parameters change.

Note: the URL to call the parameter service is included in the @param-service-url attribute of <file> elements returned in the responses to calls to the getSolutionRepositoryDoc and getSolutionRepositoryFileDetails components of the SolutionRepositoryService. Some documentation regarding this service, it's components and the param-service-url attribute may be found at Solution Repository Webservices

Element: parameters

Each parameter document uses "parameters" as tag name of the root element. The document and all elements and attributes must belong to the namespace "http://reporting.pentaho.org/namespaces/parameters/1.0".

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema attributeFormDefault="unqualified"
           elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://reporting.pentaho.org/namespaces/parameters/1.0"
           targetNamespace="http://reporting.pentaho.org/namespaces/parameters/metadata/1.0">


 <xs:complexType name="parametersType">
    <xs:sequence>
      <xs:element type="parameterType" name="parameter" maxOccurs="unbounded" minOccurs="0"/>
      <xs:element type="errorsType" name="errors" maxOccurs="unbounded" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute type="xs:boolean" name="show-parameter-ui" use="optional"/>
    <xs:attribute type="xs:boolean" name="is-prompt-needed" use="optional"/>
    <xs:attribute type="xs:boolean" name="paginate" use="optional"/>
    <xs:attribute type="xs:boolean" name="subscribe" use="optional"/>
    <xs:attribute type="xs:string" name="layout" use="optional"/>
    <xs:attribute type="xs:int" name="accepted-page" use="optional"/>
    <xs:attribute type="xs:int" name="page-count" use="optional"/>
    <xs:attribute type="xs:boolean" name="autoSubmit" use="optional"/>
    <xs:attribute type="xs:boolean" name="autoSubmitUI" use="optional"/>
  </xs:complexType>

Element: parameter

The parameters element contains a list of parameter definitions and a map of error messages. Each parameter
has a unique name.

<xs:complexType name="parameterType">
    <xs:sequence>
      <xs:element type="attributeType" name="attribute" maxOccurs="1" minOccurs="0"/>
      <xs:element type="valuesType" name="values" maxOccurs="1" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute type="xs:string" name="name" use="required"/>
    <xs:attribute type="xs:string" name="type" use="required"/>
    <xs:attribute type="xs:string" name="timezone-hint" use="required"/>
    <xs:attribute type="xs:boolean" name="is-strict" use="optional"/> <!-- was is-strict -->
    <xs:attribute type="xs:boolean" name="is-multi-select" use="optional"/>
    <xs:attribute type="xs:boolean" name="is-mandatory" use="optional"/>
  </xs:complexType>

The parameter element has a unique name (within the document). The type attribute specifies the Java data type the parameter expects. The UI must respect the type specified here and must provide data in the correct format matching the type given. For web-environments, the web-UI must provide a string in a parsable format.

Type can be any of
"java.lang.String" (free form text),

"java.lang.Number", "java.lang.Double", "java.lang.Float", "java.lang.Short", "java.lang.Byte", "java.lang.Integer", "java.lang.Long", "java.math.BigDecimal" or "java.math.BigInteger"

The string representation consists of an optional sign, '+' ('\u002B') or '-' ('\u002D'), followed by a sequence of zero or more decimal digits ("the integer"), optionally followed by a fraction, optionally followed by an exponent.

The fraction consists of a decimal point followed by zero or more decimal digits. The string must contain at least one digit in either the integer or the fraction. The number formed by the sign, the integer and the fraction is referred to as the significand.

The exponent consists of the character 'e' ('\u0075') or 'E' ('\u0045') followed by one or more decimal digits. The value of the exponent must lie between -Integer.MAX_VALUE (Integer.MIN_VALUE+1) and Integer.MAX_VALUE, inclusive.

Valid examples are:

100
100.90
+50.45
-200.50
1E-10
1E+10
10E5

"java.util.Date", "java.sql.Date", "java.sql.Time", "java.sql.Timestamp"

The string representation for Dates constists of the standard ISO-8601 datetime format with or without timezone information. The format string used is "yyyy-MM-dd'T'HH:mm:ss.SSSZ" or "yyyy-MM-dd'T'HH:mm:ss.SSS".

Example: 2010-09-30T23:59:59.000+0500

"java.lang.Boolean"

The Boolean value of "true" is represented by the all-lower-case text "true". The value "false" is represented by the all-lower-case value of "false".

Additional types beyond the ones given in this specification can be supported if both the client and the server understand them and as long as these values are encoded in a way that makes them safe to use in internationalized environments.

Representing Null Values

The textual representation of a undefined value is an empty string. Therefore any empty string given by the user or in a parameter document must be normalized to a <null> value.

Element: attribute

Attributes define additional hints for the parameter-UI in respect to the particular parameter. Common hints are the render type, the parameter's label or a timezone (for date-parameter). At the moment, all defined parameter attributes use the namespace "core" (due to a limitation in the previous implementation). Commonly used attributes should be placed into this namespace - but in that case make sure that you update all projects that generate parameter information.

Attributes that only make sense for a particular implementation should be placed in a private namespace. If it turns out that this attribute is generally useful, it can be moved to the core namespace later on.

  <xs:complexType name="attributeType">
    <xs:attribute type="xs:string" name="namespace" use="required"
                  default="http://reporting.pentaho.org/namespaces/engine/parameter-attributes/core"/>
    <xs:attribute type="xs:string" name="name" use="required"/>
    <xs:attribute type="xs:string" name="value" use="required"/>
  </xs:complexType>

Namespace: Core

Attribute	Meaning
label	The display name that is shown in the parameter UI. If no label is given, the UI should show the raw name.
hidden	"true" or "false" stating whether the UI should render this parameter. Defaults to "true" unless specified otherwise.
layout	The layout mode of a list-parameter: "horizontal" or "vertical".
type	The display type defines what widget should be used for the parameter. If not given, a plain text input should be used. Valid values are "dropdown", "list", "radio", "checkbox", "togglebutton", "textbox", "datepicker"
parameter-visible-items	A positive integer or zero. The number of items to display in a list or the number of characters to display in a text-box. Zero means unlimited or a built-in default.
data-format	The number or date format used when to display the values.
role	The parameter role. "user", "system" or "schedule"
deprecated	"true" or "false" to state whether this parameter should no longer be used.
parameter-group	The parameter group. UIs may use this to group parameters into a titled box or so.
parameter-group-label	The label for the parameter group.
timezone	The timezone of a date parameter. Must be a valid timezone id. (see the JDK's timezones.properties file for all ids.

Element: values

A container element to contain all values.

  <xs:complexType name="valuesType">
    <xs:sequence>
      <xs:element type="valueType" name="value" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

Element: value

Contains a single available value for a parameter. For text fields only a single value element with "selected=true" will be given.

  <xs:complexType name="valueType">
    <xs:attribute type="xs:string" name="label" use="optional"/>
    <xs:attribute type="xs:string" name="type" use="required"/>
    <xs:attribute type="xs:string" name="value" use="required"/>
    <xs:attribute type="xs:boolean" name="selected" use="required"/>
  </xs:complexType>

Element: errors

The errors element is the container for both global and local errors.

  <xs:complexType name="errorsType">
    <xs:sequence>
      <xs:element type="errorType" name="error" maxOccurs="unbounded" minOccurs="0"/>
      <xs:element type="globalErrorType" name="global-error" maxOccurs="unbounded" minOccurs="0"/>
    </xs:sequence>

  </xs:complexType>

Element: error

The error element contains a single parameter specific error message issued during the parameter validation.
There can be multiple errors regarding the same parameter. The error should be displayed close to the parameter
input, or at least should state which parameter is affected by this error.

  <xs:complexType name="errorType">
    <xs:attribute type="xs:string" name="message" use="required"/>
    <xs:attribute type="xs:string" name="parameter" use="required"/>
  </xs:complexType>

Element global-error

A global error is a warning message that cannot be bound to a single parameter. Examples for such messages would be failures to start the parameter validation, or parse or database errors.

  <xs:complexType name="globalErrorType">
    <xs:attribute type="xs:string" name="message" use="required"/>
  </xs:complexType>
</xs:schema>