Run a job by API#

This page shows how to drive job execution with the /api/v1 commands: check the server is up, list the jobs you can run, run one, poll its status, and cancel it. It then shows the depth trick that makes the API worth reaching for, filtering a single run down to one output type and one destination, so the same job delivers a PDF by email to one caller and a PowerPoint by Slack to another.

For the two delivery models and their key models, read The automation API first.

Before you begin#

• The target job is authored and appears in the job list.
• You have a token. On the Local API it is the workspace access token, minted in the admin API settings; on the Cloud API it is the Cloud Connector token. See The automation API.
• On the Local API the token also selects the workspace, so use the token minted in the workspace whose jobs you want. On the Cloud API, add ?workspace={name} once more than one workspace exists.

Authenticate#

Present the token as an accessToken header on every call:

accessToken: <your-token>

You may instead pass it as an ?accessToken=<token> querystring, but the header form is preferred, the querystring form is less secure. On the Local API the access token is the workspace selector, there is no separate workspace parameter.

The commands#

info and history are deprecated and return 404. Do not build against them.

Run and poll#

1. ping to confirm the endpoint and token are good.
2. list to get the exact job name or path.
3. run with a job specification. The minimum is the job Name; the call returns a jobId immediately (it is fire-and-forget).
4. status with that jobId, polling until the job completes. progress runs 0 to 100 and logReport carries the run log.
5. cancel with the jobId if you need to stop it. A canceled job is granted a 60-second grace period to finish and release memory before it is force-stopped.

A minimal run body:

{
  "Name": "Reports/Monthly/Board Pack"
}

Override parameters for a run#

The run body can replace a job's authored parameter values for that one run, one entry per named parameter, without editing the job. Each override names the parameter and carries a typed value, for example a delimited list, an IBM Planning Analytics subset or mdx, an mdxrepeater that runs once per list item, a sql value list, or a Workday adaptive burst. Each type has its own required fields (for example a subset needs the server and dimension, a sql value list needs the connection name).

Filter a run to one output type and one destination#

A Reportworq job can be authored to produce several formats and send to several destinations. On a single run, the caller can narrow that down without touching the job, using two override lists on the run body:

• AllowedOutputFileTypes, a subset of excel, pdf, powerpoint, csv.
• AllowedDestinationTypes, a subset of file, email, sharepoint, sheets, slack, teams.

Only the listed formats and destinations fire for that run. There is also a ConvertPowerPointToPdf flag to force a PowerPoint deck to PDF for the one run.

When to use it, the worked example. You have one authored job, "Board Pack", that can produce both a PDF and a PowerPoint and can send by both email and Slack. Two different callers drive it two different ways from the very same job:

Caller A, a finance mailer, wants the PDF by email:

{
  "Name": "Reports/Monthly/Board Pack",
  "AllowedOutputFileTypes": ["pdf"],
  "AllowedDestinationTypes": ["email"]
}

Caller B, a team-channel bot, wants the PowerPoint by Slack:

{
  "Name": "Reports/Monthly/Board Pack",
  "AllowedOutputFileTypes": ["powerpoint"],
  "AllowedDestinationTypes": ["slack"]
}

One authored job, two callers, two entirely different deliveries, with no duplicate job to maintain. This is the reason to constrain a run at call time rather than authoring a separate job per audience.

Download the produced file#

After run and status, an integration can fetch the produced output over a token-authenticated download URL, so the caller can hand the file downstream (an approval step, a ticket, a notification) rather than wait for a distributor to deliver it.

Notes and limits#

• The API-override parameter types are a subset of the fuller authoring parameter catalog. Pivot-table, SmartView, Anaplan, and PA-dimension authoring types are not distinct API override types.
• Cancellation is not instant. A canceled job gets a 60-second grace period before force-stop.
• Three different refusals look similar. "REST API not available for this license" (HTTP 400) means the API capability is missing from the license; "The Reportworq API is disabled" means the workspace's API toggle is off; "Invalid Access Token" means the key is wrong. Check them in that order.

Going deeper. To launch these runs from IBM Planning Analytics Turbo Integrator, from Workato, or from Windows Task Scheduler, and for the PowerShell hang fix, see Turbo Integrator, Workato, and Task Scheduler.