What's new ⬇ Download Reportworq
⬇ Guide PDF

Pause samples for Planning Analytics#

Two sample Turbo Integrator (TI) processes let a Planning Analytics server control the Reportworq global execution pause by itself, so a dimension update never has to run alongside reports:

Both call the Reportworq REST API, and each comes in two variants. Pick the one for your Planning Analytics version:

Your Planning Analytics Download How it calls Reportworq
Planning Analytics v11, on-premises (Windows or Linux) Reportworq - Pause Run Resume Sample 1.0 (PA v11), Reportworq - Global Pause Control Sample 1.0 (PA v11), and the helper Reportworq - Pause Response Reader 1.0 (PA v11) Runs curl with ExecuteCommand. curl writes the answer to a temporary file in the TM1 log directory, the helper process reads it back, and the file is deleted.
Planning Analytics Engine (v12) or Planning Analytics as a Service Reportworq - Pause Run Resume Sample 1.0 (PA Engine), Reportworq - Global Pause Control Sample 1.0 (PA Engine) The TI function ExecuteHttpRequest. Nothing else to install.

ExecuteHttpRequest does not exist on Planning Analytics v11, so the PA Engine variants do not compile there. The two variants of a sample take the same parameters and behave the same way; the PA v11 variants add pCurlPath.

Before you begin#

Get and install the samples#

The samples are downloads. They are not installed by the Reportworq installer. Open TM1 Script Downloads, download each sample as a .pro file (or as a .json file for the TM1 REST API), and check its SHA-256 hash as described on that page.

  1. Import the .pro file with Architect or Planning Analytics Workspace (Processes, Import), or post the .json file to the Processes endpoint of your TM1 REST API. For a PA v11 variant, import Reportworq - Pause Response Reader 1.0 (PA v11) as well, and keep its name exactly as it is: the samples call it by that name, and check that it is there before they send anything.
  2. Set the default of pApiUrl to the address of your Reportworq REST API, ending in api/v1/. The default is https://localhost:8600/api/v1/.
  3. Set the default of pAccessToken to the access token from the Local API key. The token is sent as a request header and is never written to the TM1 log.
  4. If the Reportworq address uses a self-signed certificate, set pAcceptSelfSignedCertificate to 1. The process then passes the -k option to curl or ExecuteHttpRequest, which skips certificate verification. With the default 0 the certificate is verified. Use 1 only when the address is on a network you trust.
  5. For a PA v11 variant, set pCurlPath if curl is not on the Planning Analytics server's PATH, for example C:\Windows\System32\curl.exe or /usr/bin/curl. The default is curl.

Each sample runs from its Prolog tab (Pause Run Resume also uses the Epilog tab). You do not edit the other tabs.

Pause Run Resume#

This process wraps a maintenance process:

  1. It pauses Reportworq and waits until every running job is held. If that does not happen in time, it lifts its own pause, stops with an error, and does not run your process.
  2. It runs the process named in pProcessName and notes how it ended.
  3. In the Epilog it resumes Reportworq, whether or not your process succeeded. It then fails if your process failed, so the problem is not hidden.
Parameter Meaning
pApiUrl The Reportworq REST API address, ending in api/v1/. Default https://localhost:8600/api/v1/.
pAccessToken The Local API key's access token.
pProcessName The TI process to run while Reportworq is paused, for example your dimension update. It cannot be Pause Run Resume itself.
pDurationMinutes The safety net, in whole minutes. Default 30. A blank or 0 value falls back to 30.
pWaitSeconds How long to wait for the pause in one call, 1 to 300 seconds. Default 300.
pMaxWaits How many waits to make before giving up. Default 3, which is up to 15 minutes.
pAcceptSelfSignedCertificate 1 to accept a self-signed certificate. Default 0.
pCurlPath PA v11 variant only: the curl program to run. Default curl.

The safety net. The pause is requested with a duration, so that if the Planning Analytics server stops before the Epilog runs, Reportworq resumes by itself. The time counts from the moment every job is held. Set pDurationMinutes to longer than your maintenance process needs. If it is shorter, Reportworq resumes while the maintenance is still running.

Its own pause only. Pause Run Resume resumes with the identifier of the pause it made, so it never lifts a pause that an administrator started from the Activity screen. If both are active, Reportworq stays paused until the administrator resumes too.

Schedule it in place of a dimension update#

  1. Find the chore that runs your dimension update process.
  2. Replace that process in the chore with the Pause Run Resume variant for your Planning Analytics version.
  3. Set pProcessName to the dimension update process.
  4. Set pDurationMinutes to comfortably longer than the update takes.
  5. Try it first with a manual run and watch Activity in Reportworq: the status message shows the jobs pausing, and the pause ends when the process finishes.

The chore then pauses Reportworq, runs the update with nothing querying, and resumes.

Global Pause Control#

One process, four actions, chosen with pAction:

pAction What it does
pause Pauses Reportworq. With pWaitForPause true (the default) it waits until every running job is held. It logs the identifier of its pause.
resume Resumes Reportworq. With pHoldId set to the identifier a pause logged, it releases only that pause. With pHoldId blank it is an all-clear: it releases every pause, including one set from the Activity screen and any made by another workspace.
status Logs the pause status, including the same message the Activity screen shows.
cancelall Cancels the running jobs of the workspace that the access token belongs to. With pIncludePending true, pending jobs are canceled too.

The default for pAction is status, so a first run changes nothing.

Parameters for pause:

Parameter Meaning
pDurationMinutes Whole minutes to stay paused, counted from the moment every running job is held. Blank or 0 pauses until a resume.
pWaitForPause true or false. Blank means true.
pWaitSeconds 1 to 300 seconds per wait. Default 300.
pMaxWaits How many waits before giving up. Default 3, which is up to 15 minutes.
pFailIfNotPaused 1 (default) stops the process with an error if the pause is not confirmed in time. 0 logs the problem and carries on.

The other parameters are pApiUrl, pAccessToken, pAcceptSelfSignedCertificate and (PA v11 variant) pCurlPath as above, pIncludePending (cancelall only, default false) and pHoldId (resume only).

If the pause is not confirmed in time, the pause is still in force. The process logs its identifier so that you can run resume with pHoldId to lift it.

This process never sends a resume on its own. Only an explicit resume action does.

Notes and limits#

Going deeper. For the calls these processes make, see Pause and resume by API. For the controls an administrator uses by hand, see Pause job execution.

Feedback on this page

Comments, questions, requests, or something missing or unclear? Email us - the page you are on is filled in for you.

Email feedback on this page

Or write to support@reportworq.com directly.