GET Export Parse Parameters

Abstract

The GET Export Parse Parameters endpoint is a utility endpoint used to validate and parse parameters of the GET Export Report endpoint.


Overview

The GET Export Parse Parameters endpoint is a utility endpoint used by the Pull ReportsAd Hoc Report Creator to validate and parse parameters of the GET Export Report endpoint which contain column resource paths such as filter, columns, and sort. The endpoint returns a JSON representation of valid parameters and error information regarding invalid parameters.

Unlike the GET Export Report endpoint, this endpoint returns a 200, OK response when a parameter is invalid and captures the parse error in the errors property of the returned JSON.

URL

/[context]/pullreports/catalog/[catalog id]/report/[report id]/export/parseParams

Components

/[context]

The web application context path of the WAR which contains the Pull Reports™ JAR. Typically this is the name of the WAR file.

/pullreports

The URL path to the PullReportsServlet. This path is configured automatically web.xml when installing Pull Reports™.

/catalog/[catalog id]

The id of the <catalog> as configured in Pull Reports™ XML Catalog files.

/report/[report id]

The id of the <report> as configured in the encompassing <catalog>.

/export/parseParams

The export parse parameters endpoint.

Parameters

columns, filter, sort

These three parameters have the same structural definition as the corresponding parameters in the GET Export Report endpoint. Each parameter will be parsed and represented as a member of the columns, filters, and sorts arrays respectively in the JSON result.

Response

Response Content-Type:  application/json

OK

Status Code:  200

JSON responses without error have this structure:

{
    // The "columns" property is an array of column objects which
    // represent the successfully parsed column resource path terms from 
    // the columns parameter.
    "columns":[{
        "tablePath":string
        ,"columnIds":[string]
    },...]

    // The "filters" property is an array of filter objects which
    // represent the successfully parsed filter parameters.
    "filters":[{
        // The "terms" array holds the parsed filter terms
        // to be OR'ed together.
        "terms":[{
            "tablePath":string
            ,"columnId":string
            ,"operator":string
            ,"values":[...]
        },...]
        ,"source":string // The value of the "filter" parameter.
    },...]

    // The "sorts" property is an array of sort objects which
    // represent the successfully parsed sort terms from the sort 
    // parameter. The "sorts" property will only be non-null if 
    // the "columns" parameter parses without error.
    ,"sorts":[{
        "tablePath":string
        ,"columnId":string
        ,"direction":string
        ,"source":string // the value of the "sort" term.
    },...]

    // The "errors" property captures any errors that occur when
    // parsing the columns, filter, and sort parameters.
    ,"errors": [
        {"param":string  // Either "columns", "filter", or "sort".
         "value":string  // The value of the parameter that was in error.
         "message"string // A description of the error.
        },...
    ]
}
Example 1. Example JSON Output Format

The GET Export Parse Parameters endpoint returns the following response for a request structured like so:

/[context]/pullreports/catalog/[catalog id]/report/[report id]/export/parseParams?columns=/parent@columnA,columnC;/parent/child;&filter=/parent@columnB+=+3&filter=/parent/child@columnW+in+('foo','bar')+or+/parent@columnA+is+not+null&sort=/parent/child@columnZ+desc;/parent@columnA

{
    "columns": [
        {"tablePath":"/parent"
         ,"columnIds":["columnA","columnC"]
        }
        ,{"tablePath":"/parent/child"
         ,"columnIds":["columnD","columnE","columnF"]
        }
    ]
    ,"filters": [
        {"terms": [
            {"tablePath":"/parent"
            ,"columnId":"columnB"
            ,"operator":"="
            ,"values":[3]}
         ],
         "source":"/parent@columnB = 3"
         }
        ,{"terms": [
            {"tablePath":"/parent/child"
            ,"columnId":"columnW"
            ,"operator":"in"
            ,"values":["foo","bar"]}
            ,{"tablePath":"/parent"
            ,"columnId":"columnA"
            ,"operator":"is not null"}
         ],
         "source":"/parent/child@columnW in ('foo','bar') or /parent@columnA is not null"
         }
    ]
    ,"sorts":[{
        "tablePath":"/parent/child"
        ,"columnId":"columnZ"
        ,"direction":"desc"
        ,"source":"/parent/child@columnZ desc"
        }
        ,{"tablePath":"/parent"
        ,"columnId":"columnA"
        ,"direction":"asc"
        ,"source":"/parent@columnA"
        }
    ]
}

Bad Request

Status Code: 400

Responses whose columns parameter results in zero exportable, permitted columns return a 400 response.

Forbidden

Status Code: 403

A 403 status code is returned if an <access_control_voter> associated with the <report> or <catalog> fails. A 403 status is also returned if an <access_control_voter> associated with a <relationship> or <column> referenced via the columns, filter, or sort parameter fails.