Solution Repository Webservices

Content Repository Services

You can work with the solution repository through this service:

/pentaho/SolutionRepositoryService?component=<value>

This service is implemented by org.pentaho.platform.web.servlet.SolutionRepositoryService. Please refer to SolutionRepositoryService.java to keep this page updated.

Component parameter

Using the component parameter, you can specify what action to perform. The following values are valid for the component parameter:

getSolutionRepositoryDoc - describes all files and folders contained in the repostitory that are available within the context the current session
getSolutionRepositoryFileDetails - describes one particular file or folder in the repository, including its contents (but also within the context of the current session)
createNewFolder - create a new folder.
delete - delete an item.

All of these services can be accessed using the HTTP GET method (yes, that's not how it ought to be for creating and deleting objects, but that is how it works for some reason).

Additional parameters

The createNewFolder and delete services require extra parameters to identify the repository item to which the action is applied:

solution - the pentaho solution
path - the folder path within the solution
name - the name of the item found at the path within the solution.

In addition, the createNewFolder service accepts an additional desc parameter to set the description of the new folder.

The getSolutionRepositoryFileDetails also applies to a particular respository item, but in this case the item is identified by the fullPath parameter (and not by solution / path / name as I would expect)

Response

The delete and createNewFolder service return an XML document to indicate success or failure:

<result>*true</result>* is returned in case of success
<result>*false</result>* is returned in case of failure

The getSolutionRepositoryDoc returns and XML document representing the folders and items contained in the repository. The schema of this response is shown below:

<repository> - document element represents the entire solution repository (in so far its contents are accessible by the current user)
- @path - location of the solution repository directory
- @product-id - ???
- @version-build - internal revision of the codebase ???
- @version-major - pentaho bi platform major version (f.e.: 3).
- @version-minor - pentaho bi platform minor version (f.e.: 7).
- @version-milestone - milestone indicator (f.e.: stable)
- @version-release - ???
- <file> - Represents a repository item. Both "real" files and folders are represented by this element, but you can distinguish between them by examining the value of the @isDirectory attribute (true for folders, false for files)
  - @description - Human readable description of this item.
  - @isDirectory - true or false indicating whehter this item is a folder or not.
  - @lastModifiedDate - a UNIX timestamp indicating the last modification of this item.
  - @localized-name - the human readable, localized name of this file or folder.
  - @name - the local identifier of the file or folder.
  - @visible - true or false to indicate whether this item is visible to end users.
  - @url - applies to items for which isDirectory=false. This url can be used to execute this item. To execute this item, examine the response of the service identified by the @param-service-url attribute to discover any parameters that apply to this item.
  - @param-service-url - applies to items for which isDirectory=false. This url provides metadata concering the parameters applicable for this item.
  - <file> - Any items contained within a parent <file> element for which isDirectory="true" are recursively listed in their own <file> element.

(In the schema description above, elements are denoted as tagnames enclosed within angle brackets, and attributes are indicated with a leading @ sign)

Example getSolutionRepositoryDoc Response

The getSolutionRepositoryDoc service returns this XML fragment for the ChartComponent_ChartTypes.xaction that sits in the charts folder in the bi-developers solution:

Param Service URL

The value of the param-service-url attribute of the <file> items returned by the getSolutionRepositoryDoc service contain a url that may be used to discover the available parameters for that item. The form of the param-service-urls depends on the type of item:

.xaction items - /pentaho/ServiceAction?solution=<solution>&path=<path>&action=<xaction-name>.xaction&component=xaction-parameter
.prpt items - /pentaho/content/reporting/?renderMode=PARAMETER&solution=<solution>&path=<path>&name=<report-name>.prpt

So you need to call a different service depending on the type of item, and each has a number of service-specific parameters. The solution and path parameters are common to all param-service-url services.

Param Service URL Response

Note: there is more documentation pertaining to this topic in the Pentaho Reporting wiki. See http://wiki.pentaho.com/display/Reporting/Specification+for+the+BI-Server+Plugin+Parameter-XML+format for more information.

The response for this service is an XML document which has the following format:

<parameters> - document element.
- @autoSubmit - true or false. Don't know what this indicates
- @is-prompt-needed - true or false. Presumably indicates whether the item can run in the background without requiring a user to specify parameter values.
- @layout - No idea why this should be here.
- @subscribe - true or false. No idea what this means. (Maybe this indicates whether the current user has a subscription to this item???)
- <parameter> - represents a single parameter. Multiple <parameter> elements are typically present.
  - @is-mandatory - true or false. Presumably indicates whether the user has to supply a value for this parameter.
  - @is-multi-select - true or false. Presumably indicates whether this parameter can take on a list of values.
  - @is-strict - true or false. No idea what this means.
  - @name - The parameter name.
  - @type - The java fully qualified className indicating the data type of the values for this parameter.
  - <attribute> - In addition to the regular XML attributes listed above, some information is conveyed using these <attribute> elements. Some of these attributes seem to convey redundant information as compared to the regular XML attributes, some seem to actually contain extended information about the parameter. It is a mystery to me why there are two different ways to convey information about the parameter, perhaps this has to do with some backwards compatibility?
    - @name - The semantics of the <attribute> element depends on the value of its name XML attribute (@name) and the value of it's value XML attribute (@value). A number of valid values for @name are listed below.
      - parameter-render-type: this attribute contains information about how to present an value editor to the user to prompt for a parameter value. For this type of <attribute>, the @value attribute has values like "textbox", "dropdown" etc.
      - mandatory: seems redundant as compared to the @is-mandatory attribute of the <parameter> element. For this type of <attribute> the @value attribute is "true" or "false".
      - role: in this case the value XML atttribute contains a value that indicates from where the parameter receives its value. Exampe values for the @value attribute include "user", "schedule", "system"
      - parameter-group: in this case the value attribute contains a name identifying the group to which this parameter belongs. Values for this type of attribute look exactly like what is seen for name="@role" parameters.
      - parameter-group-label: a human-readable friendly name for this parameter-group (or role?)
      - label: In this case the value attribute contains a human-readable friendly name for this parameter.
      - hidden: In this case the value attribute contains "true" or "false" indicating whether this item should be visible to the end-user.
      - preferred: Value is "true" or "false". No idea what this means.
      - deprecated: Value is "true" or "false", presumably indicating whether the parameter is deprecated.
    - @value - The value of this attribute. Has a specific meaning depending on the value of the @name attribute (see above)
    - @namespace - Presumably, the combination of @namespace and @name identifies the attribute. Value always seems to be http://reporting.pentaho.org/namespaces/engine/parameter-attributes/core though
  - <values> - Information about possible values for this parameter.
    - <value> - Represents a particular value applicable to this parameter.
      - @label - A human-readable friendly name to present this value to the end-user.
      - @null - true or false indicating whether this value represents a NULL value. This is probably to distinguish between genuine NULL values and empty strings
      - @selected - true or false indicating whether this value is selected by default.
      - @type - A fully qualified java classname indicating the data type for this value
      - @value - A string representation of the actual value.

Param Service Response Example

In the getSolutionRepositoryDoc example, the value of the param-service-url attribute is:

/pentaho/ServiceAction?solution=steel-wheels&path=charts&action=ChartComponent_ChartTypes.xaction&component=xaction-parameter

By way of example, here's a fragment of the response:
<parameters>
  <parameter name="chart_type" type="java.lang.String">
   <attribute
   namespace="http://reporting.pentaho.org/namespaces/engine/parameter-attributes/core"
   name="role" value="user"
   />
   <attribute
   namespace="http://reporting.pentaho.org/namespaces/engine/parameter-attributes/core"
   name="parameter-group" value="parameters"
   />
   <attribute
   namespace="http://reporting.pentaho.org/namespaces/engine/parameter-attributes/core"
   name="parameter-group-label" value="Parameters"
   />
   <values>
   <value type="java.lang.String" value="bar" selected="true" />
   </values>
  </parameter>

  <parameter>
   ...more attributes and values here...
  </parameter>

  ...more parameters here...
</parameters>