Flex5 REST API - Running a Report

Overview

For background on the context of this article, please be sure you're familiar with the content of Flex5 REST API - Getting Started Guide. This article is a short walkthrough on how to use the /api/report interface from your application. It assumes that you have the necessary knowledge to write such an application and to access a 3rd-party's API.

Basic Request Format

As mentioned in the Getting Started wiki, you will need an authorization token for your Request Header. For the remainder of your request, you have a couple of options. You can follow a syntax similar to that used in Flex4 XML-based data producer report development and put your query parameters in the URL, or you can put them in the Request Body.

URL-based Parameters

If you opt for using the URL method, the XML-based data producer URL looks like this:

Flex4 XML-based Data Producer URL

https://<your-company>.flexrentalsolutions.com/xml-data/<data-producer-id>?<param-id-1>=<param-value_1>&<param-id-2>=<param-value-2>

In Flex5 API terms, that evolves to something like this:

Flex5 API Endpoint URL

https://<your-company>.flexrentalsolutions.com/f5/api/<api-path>/<path-variable(s)>?parameterSubmission=true&<param-id-1>=<param-value-1>&<param-id2>=<param-value-2>

where api-path includes any necessary additions such as inventory-tree/nodes, where path-variable(s) includes things like modelId or documentId, and where param-id1 and param-id-2 are parameter ids as found in report-definitions.json. The parameter count can, of course, vary. In any case, if you're using a report that requires one or more parameters, your first parameter must be parameterSubmission with a value of true. If this is not included, we cannot guarantee your results.

Path and Path Variable

For the Report API, the path is simply /f5/api/report and the only path variable you need is the reportId as specified in the id property of the report-definitions.json.

Request Body Parameters

If you choose to utilize the Request Body for sending parameters, simply organize the parameters and their values according to the specification you're using. For example, if you use Swagger UI to test this endpoint, you will get a request in CURL like:

curl -X GET "https://flex5dev.flexrentalsolutions.com/f5/api/report/process/deposit_invoice" -H "accept: */*" -H "X-Auth-Token:
eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAAAOVWwY7TMBD9l5wrq10oVL0hceGA2AtcEAfXnk1n17HDjJPSRfw7k27buNRJgzhyqKI64zfP782M87PgZlOsC9Le7otZYQh0BFusF8vlcn43ny9Wb1evZ0UEr338YE-hFlqJroEqZMbguVh_PfxVNYVHMJFVi7A7xqgHlO0GtWNFYLQzF5sV-
hZ8DLRPNx3fmUCgGgZ6Zyv0J0Ajv0p7XcIQUpIyZdJttOAgnjaqDT6HmoU3GvRlhkGPCT_qQBHo8n23pt3hIbgXNM9i2GB8U22AVGiBCC1kpMkdyFQsEnjRP34RZn_m7rlVGv3BJZODHjvVEIOTMljJGqcC6uSM13CBDCjedqoM2zPqAViMaT4GzxixhaH6MFvtS7jXzLtANnP-
LEIaoMuSoNRRIHP4Lw58PMiTt9_pfWgu3M9YlPG3g-c9p5Ke5DAklKVb8lLcqJYxrrLCwWuHz-mBD_gDAlfBNg4uMVP5UsfORS9MHrC8Wk5iryQyofFXDda_Lik09Y3GZ6MHHdhQ2DGoLVoLg0EvxaS-
NzLxROpz6WeGFcVG5OwyijGEvVVHB3u3GDSZrYrhSZbyfTYUnFZsP1DS_hlnpp0bsObwcGiiTGUOTibTtLMKohouc22j8hnKUsngraYb_mUySWON95TaaYJtkGuiS1fVkbM1vEEH9-g_1V3Vn826jnkPLfZjtGsLGStPDy7sRKhKJrgCGbeO_6K50iS6iVuhL60tV-
1n7hvqnwthusETbRkSZYquk4WbdneMDPr_R7dvs0I-Qo6fZ29e3S1Wv34D5ysavMMJAAA.zEmCqGoMGN7Kqz3hqipJzakLaqGcvU9mB4GyZ8vB08D9JzpFJW_NeV3B20SfRwLIAP54Zoo8zwBhvzSpAT-8IA"

Note that it lacks the aforementioned parameters. As of this writing, we're using Swagger 2.9.2 and "request body" parameters are not supported. When we are able to update our dependency, we will attempt to update this wiki with new information.

Internally, we often use Postman as an alternative due to its advanced features and testing capabilities. Its console output for a similar request shows the raw request (and headers) as this:

GET /f5/api/report/process/deposit_invoice?parameterSubmission=true&PROJECT_ELEMENT_ID=5d03ea40-2334-11e9-bddb-080027bee86d
accept: */*
X-Auth-Token: eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAAAOVWTY_TMBD9LzlX1n4VLb0hceGA2AtcEAfXnk1n17HDjJPSRfx3Jtm2camTBnHkUEV1xm-e35sZ52fBzbpYFaS93RWLwhDoCLZYXS-Xy6vr-
_u72-XN20URwWsfP9hDqIVWomugCpkxeC5WX_u_qqbwBCayahG2-xj1iLLdoHasCIx25mSzQt-Cj4F26ab9OxMIVMNA72yF_gBo5Fdpr0sYQ0pSpky6jRYcxMNGtcaXULPwRoO-
zDAYMOFHHSgCnb7v1rTrH4J7QvMohg3GN9UaSIUWiNBCRprcgUzFIoEX_eMXYfZn7oFbpdH3Lpkc9NSpxhgclMFK1jgVUCdnPIcLZEDxplNl3J5JD8BiTPMxeMaILYzVh9loX8KDZt4GspnzZxHSAF2WBKWOApnDf3XgYy9P3n6nd6
E5cT9jUcbfDp53nEp6kMOQUJZuyUtxoVqmuMoKB68dvqQH7vFHBK6CbRycYqbypY4di16YPGJ5tpzEnklkQuPPGmx4XVJo6guNz0aPOrCmsGVQG7QWRoNei0l9b2TiidTH0s8MK4qNyNllFGMIB6v2Dg5uMWgyGxXDsyzl-
2wsOK3YYaCk_TPNTDs3Yk3_cGiiTGUOTibTvLMKohovc22t8hnKUsngraYL_mUySWNN95TaaoJNkGuiS1fVkbM1vEYHD-g_1V3VH806j3kPLQ5jtGsLGSvPty5sRahKJrgCGbeO_6K50iS6iRuhL60tV-1nHhrqnwthvsEzbRkTZY6
us4Wbd3dMDPr_R7dvi0I-QvafZ29uru5uf_0GTjUvXsMJAAA.77GfbKRnAQ59-Vd4Y7FxSi0f95jt8TC7PTh5ZoPCQGzX4uzclufoA9KiPBeDhak6hb08I5ASsVacTFfcNJghrA
cache-control: no-cache
Postman-Token: 1125bedd-44d1-4da4-89f9-656ce60163e2
User-Agent: PostmanRuntime/7.6.1
Host: flex5dev.flexrentalsolutions.com
accept-encoding: gzip, deflate

Notice that both automatically include the X-Auth-Token, but the location of various parts of the URL is different. (Also, note that we have added carriage returns to enforce wrapping)

Postman's CURL code is as follows:

curl -X GET \
  'https://flex5dev.flexrentalsolutions.com:8443/f5/api/report/process/deposit_invoice?PROJECT_ELEMENT_ID=5d03ea40-2334-11e9-bddb-080027bee86d' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Postman-Token: 0f46fef1-d2dc-4572-8429-5672c279de64' \
  -H 'X-Auth-Token: eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAAAOVWTY_TMBD9LzlX1n4VLb0hceGA2AtcEAfXnk1n17HDjJPSRfx3Jtm2camTBnHkUEV1xm-e35sZ52fBzbpYFaS93RWLwhDoCLZYXS-Xy6vr-
_u72-XN20URwWsfP9hDqIVWomugCpkxeC5WX_u_qqbwBCayahG2-xj1iLLdoHasCIx25mSzQt-Cj4F26ab9OxMIVMNA72yF_gBo5Fdpr0sYQ0pSpky6jRYcxMNGtcaXULPwRoO-
zDAYMOFHHSgCnb7v1rTrH4J7QvMohg3GN9UaSIUWiNBCRprcgUzFIoEX_eMXYfZn7oFbpdH3Lpkc9NSpxhgclMFK1jgVUCdnPIcLZEDxplNl3J5JD8BiTPMxeMaILYzVh9loX8KDZt4GspnzZxHSAF2WBKWOApnDf3XgYy9P3n6nd6
E5cT9jUcbfDp53nEp6kMOQUJZuyUtxoVqmuMoKB68dvqQH7vFHBK6CbRycYqbypY4di16YPGJ5tpzEnklkQuPPGmx4XVJo6guNz0aPOrCmsGVQG7QWRoNei0l9b2TiidTH0s8MK4qNyNllFGMIB6v2Dg5uMWgyGxXDsyzl-
2wsOK3YYaCk_TPNTDs3Yk3_cGiiTGUOTibTvLMKohovc22t8hnKUsngraYL_mUySWNN95TaaoJNkGuiS1fVkbM1vEYHD-g_1V3VH806j3kPLQ5jtGsLGSvPty5sRahKJrgCGbeO_6K50iS6iRuhL60tV-1nHhrqnwthvsEzbRkTZY6
us4Wbd3dMDPr_R7dvi0I-QvafZ29uru5uf_0GTjUvXsMJAAA.77GfbKRnAQ59-Vd4Y7FxSi0f95jt8TC7PTh5ZoPCQGzX4uzclufoA9KiPBeDhak6hb08I5ASsVacTFfcNJghrA \
  -H 'accept: */*' \
  -H 'cache-control: no-cache'

Report Types

Flex has 3 types of reports: Global, Definition, and Instance. For a detailed explanation of these, please see our Help Center article, Global, Definition, and Instance Level Reports. What's the difference? Currently, the Flex5 API only supports Instance Level reports. The default file type is PDF, however, with the addition of the REPORT_FORMAT parameter and appropriate value, you can get other types. As of this writing, the only tested values are pdf and csv.

Additional functionality will be added in the future.

Response

As of this writing, all responses are returned as a base64-encoded String. If necessary, your app will need to handle the decoding of that String for whatever its intended use. After decoding, you should be able to download and open the file.