API Description

Author:Stefan Eletzhofer Date:July 03, 2015 State:production

Abstract

This is a description of the report service.

Purpose

The purpose of this service is to expose the Windchill (tm) reporting API to the user without the need to persistently store the report definitions – thus effectively giving the user a powerful tool for complex queries.

The report service is also a tool for nexiles|apps to integrate custom queries.

URLs

The API may be accessed by using HTTP Requests to the following URLs.

Base URL

BASE URL:<<windchill host>>:<<port>>/<<web service>>/servlet/nexiles/tools/services/reports

The URLs below need the base url prefixed – e.g. to fetch the version one would use a URL like:

http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/version

API URLs

The following URLs define the API to the report service:

URL	Method	Purpose
reports	GET	return list of reports
reports	POST	post a QML and get respose data
reports/:name	GET	execute a report query
reports/:name	POST	create a report NOT YET IMPLEMENTED

API: Version

URL:files/version METHOD:GET

This fetches the version of the report service plug-in.

Data Format

The result of the HTTP GET is a JSON document, which has the following structure:

{
    version: "0.1dev",
    build: 4,
    date: "2013-04-15"
}

Example

Getting the plug-in version using cURL:

$ curl -q  --user nxoa:nxoa -X GET http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/version
{
  "version": "0.1dev",
  "build": 0,
  "date": "2013-04-04"
}

Using jQuery:

$.ajax({
    url: "/Windchill/servlet/nexiles/tools/services/reports/version",
    context: document.body,
    success: function(data) {
        console.log("plug-in version" + data.version);
    }
});

API: List Reports

URL:reports METHOD:GET

Queries the system for report templates. The URL parameters are passed to the query function – the usual parameters may be used (name, limit, ...).

The response will contain a JSON data structure with the query results.

Response Format

The result of the HTTP GET is a JSON document, which has the following structure:

{
    "count": <<number of reports>>,
    "items": [
        {
            "url": <<report execute URL>>,
            "report_url": <<report resource URL>>,
            "oid": <<OID of the report>>
            "name": <<name of the report>>
        },
        ...
    ]
}

url

Calling this URL executes the report. You can add any parameters the report needs to the URL.

report_url

This is the URL of the nexiles|gateway report resource. Calling this URL yields a JSON structure with report details – please refer to the nexiles|gateway core documentation.

Examples

Using cURL, listr all reports named like *Resolution*:

curl -q  --user nxoa:nxoa -X GET http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/?name=*Resolution*
{
  "_runtime": 0.016000032424926758,
  "count": 6,
  "items": [
    {
      "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/All%20Problem%20Report%20Influx%20And%20Resolution",
      "report_url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/reports/OR:wt.query.template.ReportTemplate:40922",
      "oid": "OR:wt.query.template.ReportTemplate:40922",
      "name": "All Problem Report Influx And Resolution"
    },
    {
      "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/All%20Change%20Request%20Influx%20And%20Resolution",
      "report_url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/reports/OR:wt.query.template.ReportTemplate:40924",
      "oid": "OR:wt.query.template.ReportTemplate:40924",
      "name": "All Change Request Influx And Resolution"
    },
    {
      "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/All%20Change%20Notice%20Influx%20And%20Resolution",
      "report_url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/reports/OR:wt.query.template.ReportTemplate:40926",
      "oid": "OR:wt.query.template.ReportTemplate:40926",
      "name": "All Change Notice Influx And Resolution"
    },
    {
      "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/Problem%20Report%20Influx%20And%20Resolution",
      "report_url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/reports/OR:wt.query.template.ReportTemplate:40914",
      "oid": "OR:wt.query.template.ReportTemplate:40914",
      "name": "Problem Report Influx And Resolution"
    },
    {
      "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/Change%20Request%20Influx%20And%20Resolution",
      "report_url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/reports/OR:wt.query.template.ReportTemplate:40916",
      "oid": "OR:wt.query.template.ReportTemplate:40916",
      "name": "Change Request Influx And Resolution"
    },
    {
      "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/Change%20Notice%20Influx%20And%20Resolution",
      "report_url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/reports/OR:wt.query.template.ReportTemplate:40918",
      "oid": "OR:wt.query.template.ReportTemplate:40918",
      "name": "Change Notice Influx And Resolution"
    }
  ]
}

API: QML Query

URL:reports METHOD:POST

Performs a query using a XML query spec in the POST body. Additional query parameters may be passed using URL parameters.

The response will contain a JSON data structure with the query results. The shape of the results depend on the actual query.

Note

If you get “funny” results, please be aware thet currently only strings, plain numbers and Business Objects are JSON serialized correctly. Please build your report “select” statement accordingly.

Response Format

The response is a JSON structure with the following format:

{
  "count": <<number of rows>>
  "items": [
    <<row 1>>,
    <<row 2>>,
    ...
    <<row N>>
  ]
}

The rows are arrays containing the selected values from the report. If a persistable object or a reference is selected, the OID of that object is returned.

Example

The following example shows how to POST a QML to the server. The QML used was created using the Windchill Report Manager UI, and then exported. This is a very simple example, which only queries for EPMDocuments using one parampter number.

The real power in this example is that this allows to assemble the query by e.g. adding more contition statements, adding join conditions etc.

QML Example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE qml SYSTEM "/wt/query/qml/qml.dtd">
<qml>
    <parameter name="number" type="java.lang.String">
        <parameterDefault isMacro="false">01-10000.ASM</parameterDefault>
    </parameter>
    <parameter name="state" type="wt.lifecycle.State">
        <parameterDefault isMacro="false">RELEASED</parameterDefault>
    </parameter>
    <statement>
        <query>
            <select>
                <column alias="EPM Document" heading="Number" propertyName="number" type="java.lang.String">master&gt;number</column>
                <column alias="EPM Document" heading="Name" propertyName="name" type="java.lang.String">master&gt;name</column>
                <column alias="EPM Document" heading="Description" propertyName="description" type="java.lang.String">description</column>
            </select>
            <from>
                <table alias="EPM Document">wt.epm.EPMDocument</table>
            </from>
            <where>
                <compositeCondition type="and">
                    <condition>
                        <operand>
                            <column alias="EPM Document" heading="Number" propertyName="number" type="java.lang.String">master&gt;number</column>
                        </operand>
                        <operator type="like"/>
                        <operand>
                            <parameterTarget name="number"/>
                        </operand>
                    </condition>
                </compositeCondition>
            </where>
        </query>
    </statement>
</qml>

Command line:

curl --user nxoa:nxoa -X POST -H "Content-Type: text/xml" -d @example-qml.xml http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/\?number\=01-1\*
{
  "_runtime": 0.015999794006347656,
  "count": 3,
  "items": [
    [
      "01-10000.ASM",
      "01-10000.asm",
      null
    ],
    [
      "01-10000.ASM",
      "01-10000.asm",
      null
    ],
    [
      "01-10000_SKEL.PRT",
      "01-10000_skel.prt",
      null
    ]
  ]
}

API: Executing a Report

URL:reports/:name METHOD:POST

Runs the named report and returns the result verbatim. Additional parameters for the report must be specified using URL parameters.

Response Format

N/A – the response format depends on the report.

Example

Command line:

curl --user nxoa:nxoa -L http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/reports/example\?number\=01\*
<queryResult>
    <metadata>
        <name>example</name>

    </metadata>

    <auxData> ...
    <qml> ...
    ...
    <result>
        <heading type="java.lang.String" tag="Number">Number</heading>
        <heading type="java.lang.String" tag="Name">Name</heading>
        <heading type="java.lang.String" tag="Description">Description</heading>
        <row idx="1">
            <Number>01-10000.ASM</Number>
            <Name>01-10000.asm</Name>
            <Description isNull="true"></Description>
        </row>
        <row idx="2">
            <Number>01-10000.ASM</Number>
            <Name>01-10000.asm</Name>
            <Description isNull="true"></Description>
        </row>
        ...
    </result>
</queryResult>