=============== API Description =============== :Author: Stefan Eletzhofer :Date: |today| :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: `<>:<>/<>/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. .. image:: reports-list.jpg :width: 800px Response Format --------------- The result of the **HTTP GET** is a JSON document, which has the following structure:: { "count": <>, "items": [ { "url": <>, "report_url": <>, "oid": <> "name": <> }, ... ] } **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": <> "items": [ <>, <>, ... <> ] } 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: .. literalinclude:: example-qml.xml :language: xml :linenos: 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\* example ... ... ... Number Name Description 01-10000.ASM 01-10000.asm 01-10000.ASM 01-10000.asm ... .. vim: set ft=rst tw=75 nocin nosi ai sw=4 ts=4 expandtab: