Turbo Integrator, Workato, and Task Scheduler#

The automation API is the substrate under three ready-made ways to launch a job from outside Reportworq: an IBM Planning Analytics Turbo Integrator (TI) process, a Workato recipe, and a Windows Task Scheduler task. This page covers each, and the one PowerShell setting that keeps a script-launched job from appearing to hang.

When to use it. Launch a job this way when the trigger is another system's event rather than a clock, for example a TI process that has just finished loading actuals and should regenerate the reporting pack on data-ready. If you previously used Cube Monitoring to launch jobs from Planning Analytics, note that Cube Monitoring has been removed in this release, and the REST-API Turbo Integrator described here is its replacement, it now also reaches IBM Planning Analytics Cloud through the Cloud Connector relay.

Before you begin#

• The target job is authored and listable through the API.
• You have the right token for the delivery model: a workspace access token for the Local API, or the Cloud Connector token for the Cloud API. See The automation API.
• For a Cloud call from Planning Analytics Cloud, the on-prem instance is registered with CloudHub (the Cloud Connector is enabled), and you have the workspace name for ?workspace=.

Launch a job from IBM Planning Analytics Turbo Integrator#

Reportworq ships sample TI processes you adapt rather than write from scratch. There are four "Run Job" samples, one for each way you run Planning Analytics:

• Rest API Run Job Sample, for an on-premises Planning Analytics (PA v11) model calling the Local API.
• Rest API Run Job Sample - Cloud, for IBM-hosted Planning Analytics Cloud (PA v11), reached through the Cloud Connector relay.
• Rest API Run Job Sample - v12, for hosted Planning Analytics v12 Cloud and Planning Analytics as a Service (PAaaS), reached through the Cloud Connector relay.
• Rest API Run Job Sample - v12 On-Prem, for an on-premises Planning Analytics v12 / PA-Engine model calling the Local API directly.

If your instance cannot yet be upgraded to the release that carries the latest version of a sample, the Downloads page offers the current .pro and .json for each one as a plain file.

The two v11 samples make their HTTP call with PowerShell, launched from the TI ExecuteCommand function (the Cloud sample carries its PowerShell prolog with it). The two v12 samples use no PowerShell at all: each posts the job request with the native TI function ExecuteHttpRequest, so it needs no shell and no files on disk. Use the v12 sample for hosted PA v12 Cloud or PAaaS, and the v12 On-Prem sample for an on-premises PA v12 / PA-Engine model. See Which sample for PA v12 / PAaaS below.

To use one:

1. In the connection editor, click Install REST API TI Process. Reportworq opens a chooser that lists the available samples. Check only the samples you need (nothing is selected for you), then click Install Selected. Only the processes you checked are created in your Planning Analytics model, so an older server is never handed a sample it cannot compile.
2. Set the Reportworq server address (or the CloudHub base URL), the token, and the target job name.
3. For a Cloud call on a multi-workspace instance, set the ?workspace={name} querystring.
4. Call the process where your model's data load finishes, so the reporting pack regenerates on data-ready.

The TI process calls the REST run command described in Run a job by API, so the same parameter and distribution overrides are available from TI.

Which sample for PA v12 / PAaaS#

The Planning Analytics v12 / PA-Engine runs in a container with no operating-system shell, whether you run it in the cloud or on-premises, so the ExecuteCommand TI function is not available there. Because both v11 samples rely on ExecuteCommand to launch PowerShell for their HTTP call, neither can run on PA v12. The two v12 samples make the same call the native way, with ExecuteHttpRequest, so they work on the containerized engine with no PowerShell, no shell, and no scaffolding on disk. Pick by where your v12 model runs.

Hosted PA v12 Cloud or PAaaS: use the Rest API Run Job Sample - v12. It reaches your Reportworq instance through the Cloud Connector relay, authenticates with the Cloud API key (pCloudConnectorApiKey), and takes a pWorkspaceName for a multi-workspace instance. It takes the same parameters as the v11 Cloud sample, with two differences:

• It drops pTlsSecurity, because the v12 engine negotiates TLS natively.
• It adds an optional pRequestLogFolder. Leave it blank and the process writes nothing; set it to a folder and each run writes a timestamped file with the request it sent and the response it received, which is handy when troubleshooting a call. A run is treated as successful on any 2xx HTTP status.

On-premises PA v12 / PA-Engine: use the Rest API Run Job Sample - v12 On-Prem. This is the on-premises analog of the v12 sample. It makes the same native ExecuteHttpRequest call, but talks to the Local API on the same machine rather than the cloud, so its parameters differ:

• It authenticates with the Local API access token (pAccessToken), not a Cloud API key. Copy the token from Settings > Reportworq API in Reportworq.
• It posts to the local endpoint, with pApiUrl defaulting to https://localhost:8600/api/v1/run.
• There is no workspace on the Local API, so it has no pWorkspaceName.
• It includes -k (skip certificate verification) by default, because an on-premises endpoint usually presents a self-signed or internal-CA certificate that ExecuteHttpRequest would otherwise refuse. That default is safe only because the endpoint is the loopback address. If you point pApiUrl at a non-loopback host, remove -k and, if the endpoint uses an internal CA, add -c <path-to-CA-file> instead, so the access token is not exposed on an untrusted network.
• Like the v12 Cloud sample, it drops pTlsSecurity and adds the optional pRequestLogFolder debug file. A run is treated as successful on any 2xx HTTP status.

Launch a job from Workato#

The Reportworq Workato connector wraps the same command set as recipe actions:

• Check Server Status, returns true or false.
• List Jobs.
• Run Asynchronous, starts a job and returns its job id.
• Run Synchronous, starts a job and polls to completion, up to a Timeout in seconds.
• Get Job Status and Cancel Job.

The connector authenticates with the Cloud API token. Its Parameters and Notification inputs are semicolon-delimited. A typical recipe runs a job synchronously, waits for completion, then routes the result downstream to an approval, a ticket, or a notification.

Launch a job from Windows Task Scheduler#

An OS task can issue a REST run on a schedule the native scheduler does not cover, most simply by having the task run a small PowerShell script that calls the API. If you script it in PowerShell, apply the fix below.

The PowerShell and TI hang fix#

A job launched from a PowerShell script (including a Turbo Integrator PowerShell prolog) delivers its reports correctly, but the script itself never returns, it stalls after a successful run. The reports are never the problem, only the script's completion is. The cause is Windows Invoke-WebRequest trying to parse the server's HTML response.

Add this line near the top of the script:

$PSDefaultParameterValues['Invoke-WebRequest:UseBasicParsing'] = $true

This is now shipped by default in the generated Cloud TI PowerShell prolog, so newer generated scripts are already immune. It remains the fix for hand-rolled or older PowerShell scripts and older self-hosted run scripts. If a script-launched job delivers output but the launching script hangs, this is the setting to add.

This applies only to the PowerShell-based v11 samples (on-premises and Cloud) and to your own PowerShell scripts. The two v12 samples (Rest API Run Job Sample - v12 and Rest API Run Job Sample - v12 On-Prem) use the native ExecuteHttpRequest function with no PowerShell, so this hang cannot occur there and no prolog setting is needed.

Notes and limits#

• Cube Monitoring has been removed. Its connection-editor options no longer appear; migrate any job launches that relied on it to the REST-API Turbo Integrator here. Cube-monitoring settings left on an existing connection are ignored, and its control cubes and dimensions on the server are inert.
• On PA v12 / PA-Engine, use a v12 sample. The ExecuteCommand TI function the PowerShell samples depend on is not available on the containerized v12 engine, so only the native ExecuteHttpRequest samples run there: Rest API Run Job Sample - v12 for hosted Cloud or PAaaS, and Rest API Run Job Sample - v12 On-Prem for an on-premises PA v12 / PA-Engine model.
• The Cloud path needs only outbound 443. A Planning Analytics Cloud model reaches your on-prem instance through the Cloud Connector relay with no inbound exposure. See The automation API.
• Cloud calls are subject to short maintenance windows. Build retries into an unattended caller.

Going deeper. For the command surface these integrations call, parameter overrides, and filtering a run to a specific output type and destination, see Run a job by API. For choosing an authentication type when connecting to Planning Analytics, see Connect IBM Planning Analytics.