Endpoints
Skip to sectionPOST | /reports |
GET | /reports/{id}/status |
Queue a new report request generation.
Request Body POST /reports
application/json | Definition of the report request. Please note that sense-story-x.0, sense-excel-template-1.0, sense-data-x.0 and qv-data-x.0 types are only for internal use. Each report request type requires a specific template to be provided:
Each template type supports specific output types:
Each output type requires a specific output to be provided:
|
Responses POST /reports
202 application/json object | Report request accepted. |
400 application/json | Bad request, malformed syntax, errors in params or the report request is not valid. |
401 application/json | Unauthorized, JWT invalid or not provided. |
403 application/json | Forbidden, user did not authenticate. |
404 application/json | Not found. |
429 application/json | Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting". |
500 application/json | Internal server error. |
POST/reports
curl "https://your-tenant.us.qlikcloud.com/api/v1/reports" \
-X POST \
-H "Authorization: Bearer <API-key>" \
-H "Content-type: application/json" \
-d '{"type":"composition-1.0","definitions":{"selectionsByState":{"sel1":{"$":[{"fieldName":"Region","defaultIsNumeric":false,"values":[{"text":"Arizona","isNumeric":false}]}]}}},"compositionTemplates":[{"type":"sense-sheet-1.0","senseSheetTemplate":{"appId":"2451e58e-a1b9-4047-abf6-315e91d8a610","selectionsByStateDef":"sel1","sheet":{"id":"5ffe3801-1b6d-439d-a849-84d0748358f1"}}},{"type":"sense-sheet-1.0","senseSheetTemplate":{"appId":"2451e58e-a1b9-4047-abf6-315e91d8a610","selectionsByStateDef":"sel1","sheet":{"id":"ffrxJyA"}}}],"output":{"outputId":"composition1","type":"pdfcomposition","pdfCompositionOutput":{"pdfOutputs":[{"size":"A4","orientation":"A","resizeType":"autofit","align":{"horizontal":"center","vertical":"middle"}},{"size":"A4","orientation":"A","resizeType":"autofit","align":{"horizontal":"center","vertical":"middle"}}]}}}'
Request POST /reports
{
"type": "composition-1.0",
"definitions": {
"selectionsByState": {
"sel1": {
"$": [
{
"fieldName": "Region",
"defaultIsNumeric": false,
"values": [
{
"text": "Arizona",
"isNumeric": false
}
]
}
]
}
}
},
"compositionTemplates": [
{
"type": "sense-sheet-1.0",
"senseSheetTemplate": {
"appId": "2451e58e-a1b9-4047-abf6-315e91d8a610",
"selectionsByStateDef": "sel1",
"sheet": {
"id": "5ffe3801-1b6d-439d-a849-84d0748358f1"
}
}
},
{
"type": "sense-sheet-1.0",
"senseSheetTemplate": {
"appId": "2451e58e-a1b9-4047-abf6-315e91d8a610",
"selectionsByStateDef": "sel1",
"sheet": {
"id": "ffrxJyA"
}
}
}
],
"output": {
"outputId": "composition1",
"type": "pdfcomposition",
"pdfCompositionOutput": {
"pdfOutputs": [
{
"size": "A4",
"orientation": "A",
"resizeType": "autofit",
"align": {
"horizontal": "center",
"vertical": "middle"
}
},
{
"size": "A4",
"orientation": "A",
"resizeType": "autofit",
"align": {
"horizontal": "center",
"vertical": "middle"
}
}
]
}
}
}
Get report request processing status.
Path Parameters GET /reports/{id}/status
id string | Identifier of the request. |
Responses GET /reports/{id}/status
200 application/json | Returns the request processing status. |
400 application/json | Bad request. Malformed syntax, errors in params. |
401 application/json | Unauthorized, JWT invalid or not provided. |
403 application/json | Forbidden, user did not authenticate. |
404 application/json | Not found. |
429 application/json | Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting". |
500 application/json | Internal server error. |
GET/reports/{id}/status
curl "https://your-tenant.us.qlikcloud.com/api/v1/reports/{id}/status" \
-H "Authorization: Bearer <API-key>"
Response GET /reports/{id}/status
{
"resolutionAttempts": 1,
"status": "done",
"statusLocation": "/reports/01562a37-23e3-4b43-865d-84c26122276c/status",
"results": [
{
"location": "https://qlikcloud.com:443/api/v1/temp-contents/619baab68023910001efcb86?inline=1",
"outputId": "output1"
}
]
}
ReportRequest
Properties
meta optional | Define the request metadata. It includes priority, deadline and future settings on execution policy of the request. |
type string | Template type and version using semantic versioning. It must have the following name convention: dashed-separated-template-name-MAJOR.MINOR. Please note that sense-story-x.0, sense-excel-template-1.0, sense-data-x.0 and qv-data-x.0 are only for internal use. Each type requires a specific template to be provided:
Each template type supports specific output types:
Enum: composition-1.0 sense-image-1.0 sense-data-1.0 sense-sheet-1.0 sense-story-1.0 qv-data-1.0 qv-data-2.0 sense-excel-template-1.0 |
compositionTemplates optional | Composition of senseSheetTemplate and/or senseImageTemplate templates. |
senseImageTemplate | Used to export a single visualization as pdf or png. |
senseSheetTemplate | Used to export a sheet as pdf. |
output | No description |
definitions optional | Definitions of common properties that are shared between templates, e.g. selectionsByState can be the same for all templates within a composition of templates. |
Meta
Define the request metadata. It includes priority, deadline and future settings on execution policy of the request.
Properties
outputTtl string<iso8601> | Time to live of the final result artifacts in ISO8601 duration format. After that duration the request and underlying output files will not be guaranteed to be available. Default is 1 hour. |
exportDeadline string<iso8601> | The maximum interval, starting from the time the API request is received, within which a report must be produced, past this interval the report generation fails. The default value is 10 minutes, the maximum allowed value is 2 hours. |
Tag
stringThe tag passed by the requesting client. For more information please look at the document docs/meta-tags.md in the reporting-service repository
QSelection
Properties
fieldName string | The name of the field to be selected. |
values | The values of the field to be selected. |
defaultIsNumeric boolean | Default value that QFieldValue isNumeric property takes if missing. |
QFieldValue
In order to apply a selection just one of text/number needs to be set, this must be associated with the correct isNumeric bool. In some scenarios both text and number may be set.
Properties
text string | String value of the field value. |
number | No description |
isNumeric boolean | IsNumeric tells whether the field value is text or number. Default value is equal to defaultIsNumeric property in QSelection. |
SelectionError
Selection error related to a fieldName. The field name is missing or some of his selection values are missing
Properties
fieldName string | The field name that is missing. |
missingValues optional | No description |
isFieldNameMissing optional boolean | True is the fieldName is missing. The missingValues array is empty in this case |
detail optional string | Details about the field selection error. |
AppError
Error in resource handling
Properties
appId string | app id |
method string | The method that is failing. |
parameters object | Parameters of method that fails. |
SelectionStrategy
stringOutputItem
Properties
outputId string | The output identifier which uniquely identifies an output (PDF, image etc.) within the same request. It does not need to be a GUID. No spaces and colons are allowed in the outputId string. |
type string | The generated report type. Each template type supports specific output types:
Each output type requires a specific output to be provided:
Enum: image xlsx jsondata pdfcomposition excel |
pdfCompositionOutput optional | Output to be used to export a composition of templates as pdf. |
pdfOutput optional | Output to be used to export a single visualization or a sheet as pdf. |
imageOutput optional | Output to be used to export a single visualization as image. |
callBackAction optional | The callback to be performed once the report is done. |
PdfCompositionOutput
Output to be used to export a composition of templates as pdf.
Properties
pdfOutputs | The ordered list of PDF outputs, the number must match the composable templates. |
properties | Properties of the pdf artifact. In case of multiple PdfOutput composition, only PdfProperties specified in the PdfCompositionOutput are taken and the ones specified in each PdfOutput item are ignored. |
ExcelOutput
Output to be used to export a excel template.
Properties
outFormat default='xlsx' string | The image format of the report to be produced. Enum: xlsx |
ImageOutput
Output to be used to export a single visualization as image.
Properties
outZoom number<float> | The scale factor to be applied in image scaling. A zoom greater than 5 will not be applied to the device pixel ratio which will remain fixed at 5. |
outDpi maximum=1000 integer<int32> | Image resolution in DPI (default 96 DPI). |
outFormat default='png' string | The image format of the report to be produced. Enum: png jsondata |
PdfOutput
Output to be used to export a single visualization or a sheet as pdf.
Properties
size default='A4' string | Size of the pdf page. Enum: A1 A2 A3 A4 A5 A6 Letter Legal Tabloid |
orientation default='P' string | P for Portrait, L for Landscape and A for Auto-detect. Auto-detect sets the orientation depending on the content width and height proportions: if content width > height the orientation is automatically set to Landscape, Portrait otherwise. Enum: P L A |
imageRenderingDpi default=200, maximum=1000 number<int32> | This value is used for rendered images only, set to a default of 200 dpi. |
resizeType default='none' string | The type of resize to be performed:
Enum: none autofit fit |
resizeData object | The area where the object (eg. sheet, chart) is printed. Required in case of "fit" resizeType. |
align | Content alignment. |
properties | Properties of the pdf artifact. In case of multiple PdfOutput composition, only PdfProperties specified in the PdfCompositionOutput are taken and the ones specified in each PdfOutput item are ignored. |
PdfProperties
Properties of the pdf artifact. In case of multiple PdfOutput composition, only PdfProperties specified in the PdfCompositionOutput are taken and the ones specified in each PdfOutput item are ignored.
Properties
title string | No description |
subject string | No description |
author string | No description |
ComposableTemplate
Properties
type string | Template type and version using semantic versioning. It must have the following name convention, dashed-separated-template-name-MAJOR.MINOR Enum: sense-image-1.0 sense-sheet-1.0 |
senseImageTemplate | Used to export a single visualization as pdf or png. |
senseSheetTemplate | Used to export a sheet as pdf. |
SenseImageTemplate
Used to export a single visualization as pdf or png.
Properties
selectionStrategy optional, default='ignoreErrorsNoDetails' | No description Enum: failOnErrors ignoreErrorsReturnDetails ignoreErrorsNoDetails |
selectionType optional object | No description |
selectionsByState optional object | Map of selections to apply by state. Maximum number of states allowed is 125. Maximum number of fields allowed is 125 and maximum number of overall field values allowed is 150000. |
selectionsByStateDef optional string | The definition ID referring to a selectionsByState definition declared in definitions. |
temporaryBookmark optional object | No description |
persistentBookmark optional object | No description |
appId string | No description |
visualization | No description |
SenseSheetTemplate
Used to export a sheet as pdf.
Properties
selectionStrategy optional, default='ignoreErrorsNoDetails' | No description Enum: failOnErrors ignoreErrorsReturnDetails ignoreErrorsNoDetails |
selectionType optional object | No description |
selectionsByState optional object | Map of selections to apply by state. Maximum number of states allowed is 125. Maximum number of fields allowed is 125 and maximum number of overall field values allowed is 150000. |
selectionsByStateDef optional string | The definition ID referring to a selectionsByState definition declared in definitions. |
temporaryBookmark optional object | No description |
persistentBookmark optional object | No description |
appId string | No description |
sheet | It refers to the Sense Sheet to be exported. Note that if widthPx and heightPx are not specified, default values will be applied depending on the actual size and layout properties of the Sense Sheet object. |
Visualization
Properties
id string | The sense visualization id or json definition. |
type optional string | Choose visualization to export an image of a sense chart, sessionobject for a visualization to be created on-the-fly. An empty value leads to the type being inferred by its id. Enum: visualization sessionobject |
widthPx minimum=5, maximum=4000 number<float> | Width in pixels. |
heightPx minimum=5, maximum=4000 number<float> | Height in pixels. |
jsOpts optional object | A JSON object that is passed as-is to the mashup page while rendering. |
patches optional | Soft properties, aka patches, to be applied to the visualization. |
NxPatch
Patches to apply to sense charts. Patches are soft properties meaning that are not persistent and they live within a session.
Properties
qOp string | No description Enum: add remove replace |
qPath string | Path to the property to add, remove or replace. |
qValue optional string | Corresponds to the value of the property to add or to the new value of the property to update. |
Float64
number<float64>Sheet
It refers to the Sense Sheet to be exported. Note that if widthPx and heightPx are not specified, default values will be applied depending on the actual size and layout properties of the Sense Sheet object.
Properties
id string | The id of the sheet. |
widthPx optional, minimum=20, maximum=4000 number<float> | The width of the sheet in pixels. Default value is 1920 pixels. |
heightPx optional, minimum=20, maximum=4000 number<float> | The height of the sheet in pixels. Default value is: - 1280 pixels for normal sheet and custom sheet where width >= height - 2880 pixels for extended sheet and custom sheet where width < height |
jsOpts optional object | A JSON object that is passed as-is to the mashup page while rendering, this will be applied to all charts within the sheet. It includes properties of the whole sheet such as theme, gradient etc. |
jsOptsById optional object | A map for applying jsOpts to specific visualization IDs within the sheet. |
patchesById optional object | A map for applying soft properties, aka patches, to specific visualization IDs within the sheet. |
ReportStatus
objectProperties
status string | Status of the requested report. Enum: queued processing done failed aborted visiting |
reasons optional | Present when status is failed. |
results optional | Present when the status is "done". |
statusLocation optional string<uri> | Relative path to status location. |
resolutionAttempts optional integer<int32> | Count how many times the resolution of this report was attempted. |
SelectionErrors
Array<SelectionError>Errors occurring in selections.
Properties
fieldName string | The field name that is missing. |
missingValues optional | No description |
isFieldNameMissing optional boolean | True is the fieldName is missing. The missingValues array is empty in this case |
detail optional string | Details about the field selection error. |
AppErrors
Array<AppError>Errors occurring when dealing with the app.
Properties
appId string | app id |
method string | The method that is failing. |
parameters object | Parameters of method that fails. |
Results
objectProperties
results | No description |
Result
objectResult and info about the generated report.
Properties
outputId string | The output identifier which uniquely identifies an output (PDF, image etc.) within the same request. |
location string<uri> | Location to download the generated report. |
exportErrors optional | Errors occured during report generation. |
Reason
Properties
outputId string | The output identifier which uniquely identifies an output (PDF, image etc.) within the same request. |
traceId string | No description |
error | No description |
exportErrors | Errors occured during report generation. |
Error
objectProperties
errors | Errors occured during report generation. |
ExportErrors
Array<ExportError>Errors occured during report generation.
Properties
code string | The unique code for the error
|
title string | A summary in english explaining what went wrong. |
detail optional string | Optional. MAY be used to provide more concrete details. |
meta optional | Define the export error metadata. Each property is filled if it is related to the export error type. |
ExportError
objectError occured during report generation.
Properties
code string | The unique code for the error
|
title string | A summary in english explaining what went wrong. |
detail optional string | Optional. MAY be used to provide more concrete details. |
meta optional | Define the export error metadata. Each property is filled if it is related to the export error type. |
MetaExportError
Define the export error metadata. Each property is filled if it is related to the export error type.
Properties
appErrors | Errors occurring when dealing with the app. |
selectionErrors | Errors occurring in selections. |
CallBackAction
The callback to be performed once the report is done.
Properties
httpRequest | Http callback. The provided uri will be called once the report is done. |
HttpRequest
Http callback. The provided uri will be called once the report is done.
Properties
uri string | URI of the request. |
Definitions
Definitions of common properties that are shared between templates, e.g. selectionsByState can be the same for all templates within a composition of templates.
Properties
selectionsByState object | It maps an ID to a selectionsByState object. |