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:
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:
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.