QlikElixir.REST.Reports (qlik_elixir v0.4.0)

View Source

Qlik Cloud Reporting API client.

The Reporting API is asynchronous and has exactly three operations: you queue a request, you poll its status, and you list the outputs it produced. There is no listing of past reports and no way to delete or fetch one by id — a report request is a job, not a stored resource.

POST /api/v1/reports              -> 202 {requestId, outputsUrl, message}
GET  /api/v1/reports/{id}/status  -> 200 {status, ...}
GET  /api/v1/reports/{id}/outputs -> 200 {data: [{outputId, location, sizeBytes, status}]}

The generated file lives in temporary content and is fetched from the location returned with each output. It expires after meta.outputTtl (one hour by default).

Queueing a report

The request body is passed through untouched, so any template type documented at https://qlik.dev/apis/rest/reports/ works. This exports a Sense sheet to PDF:

request = %{
  type: "sense-sheet-1.0",
  senseSheetTemplate: %{
    appId: "app-123",
    sheet: %{id: "sheet-456"}
  },
  output: %{
    type: "pdf",
    outputId: "monthly-sales",
    pdfOutput: %{size: "A4", orientation: "L", resizeType: "autofit"}
  },
  meta: %{outputTtl: "PT10M"}
}

{:ok, %{"requestId" => id}} = Reports.create(request, config: config)

Waiting for it

generate/2 does the whole round trip — queue, poll, list outputs:

{:ok, [output]} = Reports.generate(request, config: config)
{:ok, pdf} = Reports.download_output(output, config: config)
File.write!("monthly-sales.pdf", pdf)

The pieces are also available on their own (create/2, await/2, list_outputs/2) when you want to queue now and collect later.

API reference: https://qlik.dev/apis/rest/reports/

Summary

Functions

await(request_id, opts \\ [])

Polls a report request until it reaches a terminal status.

create(request, opts \\ [])

Queues a report request.

download_output(output_or_location, opts \\ [])

Downloads a generated report file.

generate(request, opts \\ [])

Queues a report, waits for it and returns its outputs.

get_status(request_id, opts \\ [])

Gets the processing status of a report request.

list_outputs(request_id, opts \\ [])

Lists the outputs produced so far for a report request.

Functions

await(request_id, opts \\ [])

@spec await(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, QlikElixir.Error.t()}

Polls a report request until it reaches a terminal status.

Returns the final status map when the report is done. A failed or aborted report is an error, as is running out of time.

Options

  • :interval - Milliseconds between polls (default: 2000)
  • :timeout - Milliseconds to wait before giving up (default: 300_000). Qlik's own export deadline defaults to 10 minutes and caps at 4 hours; set this above meta.exportDeadline if you raised it.
  • :config - Custom configuration

Examples

iex> QlikElixir.REST.Reports.await("7d6bc2ee-...", config: config)
{:ok, %{"status" => "done", ...}}

create(request, opts \\ [])

@spec create(
  map(),
  keyword()
) :: {:ok, map()} | {:error, QlikElixir.Error.t()}

Queues a report request.

request is the report definition described in the module docs; it is sent as-is. Qlik answers 202 Accepted with the request id and the URL of its outputs.

Rate limited by Qlik to 10 requests per minute.

Examples

iex> QlikElixir.REST.Reports.create(request, config: config)
{:ok, %{"requestId" => "7d6bc2ee-...", "outputsUrl" => "https://...", "message" => "..."}}

download_output(output_or_location, opts \\ [])

@spec download_output(
  map() | String.t(),
  keyword()
) :: {:ok, binary()} | {:error, QlikElixir.Error.t()}

Downloads a generated report file.

Takes either an output map from list_outputs/2 or its location URL, and returns the raw file. The location points at temporary content that expires with the request's outputTtl.

Examples

iex> {:ok, pdf} = QlikElixir.REST.Reports.download_output(output, config: config)
iex> File.write!("report.pdf", pdf)

generate(request, opts \\ [])

@spec generate(
  map(),
  keyword()
) :: {:ok, [map()]} | {:error, QlikElixir.Error.t()}

Queues a report, waits for it and returns its outputs.

Equivalent to create/2, then await/2, then list_outputs/2. Accepts the options of all three.

Outputs expire with the request's outputTtl. To be able to collect them again later, drive the three calls yourself and keep the requestId that create/2 returns.

Examples

iex> {:ok, [output]} = QlikElixir.REST.Reports.generate(request, config: config)
iex> output["outputId"]
"monthly-sales"

get_status(request_id, opts \\ [])

@spec get_status(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, QlikElixir.Error.t()}

Gets the processing status of a report request.

status is one of "queued", "processing", "visiting", "aborting", "done", "failed" or "aborted".

Examples

iex> QlikElixir.REST.Reports.get_status("7d6bc2ee-...", config: config)
{:ok, %{"status" => "done", "resolutionAttempts" => 1, ...}}

list_outputs(request_id, opts \\ [])

@spec list_outputs(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, QlikElixir.Error.t()}

Lists the outputs produced so far for a report request.

Outputs are generated asynchronously, so the list is only complete once the request has reached a terminal status.

Options

  • :filter - SCIM filter, eq on outputId (e.g. ~s(outputId eq "cover"))
  • :limit - Page size
  • :page - Cursor for the page to return
  • :sort - "+outputId", "-outputId", "+sizeBytes", "-sizeBytes", or a list of them
  • :config - Custom configuration

Examples

iex> QlikElixir.REST.Reports.list_outputs("7d6bc2ee-...", config: config)
{:ok, %{"data" => [%{"outputId" => "monthly-sales", "location" => "https://...", "sizeBytes" => 484_927, "status" => "done"}], "links" => %{}}}