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:
- Pause Run Resume pauses Reportworq, waits until every running job is held, runs another TI process (your dimension update), and always resumes Reportworq afterwards. This is the one most customers want.
- Global Pause Control is a single process that sends one pause command to Reportworq: pause, resume, status or cancel all. Use it when you want to build your own sequence, or to check or lift a pause by hand.
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#
- PA v11 variants: curl on the Planning Analytics server. It ships with Windows 10 version 1803 and later and Windows Server 2019 and later (
C:\Windows\System32\curl.exe), and with every common Linux distribution. The TM1 server must be allowed to runExecuteCommand. - PA Engine variants: Planning Analytics Engine (v12) or Planning Analytics as a Service, which provide the TI functions
ExecuteHttpRequest,HttpResponseGetStatusCodeandHttpResponseGetBody. - The Reportworq Local API must be reachable from the Planning Analytics server, with a Local API key. Copy its access token from Settings, Configuration, API, Local API keys. Name the key for the process that uses it, for example "TM1 pause": the name appears in the pause status as the caller.
- A Reportworq release that includes the pause. The TM1 Script Downloads page lists the minimum Reportworq version for each sample.
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.
- Import the
.profile with Architect or Planning Analytics Workspace (Processes, Import), or post the.jsonfile 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. - Set the default of pApiUrl to the address of your Reportworq REST API, ending in
api/v1/. The default ishttps://localhost:8600/api/v1/. - 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.
- If the Reportworq address uses a self-signed certificate, set pAcceptSelfSignedCertificate to
1. The process then passes the-koption to curl orExecuteHttpRequest, which skips certificate verification. With the default0the certificate is verified. Use1only when the address is on a network you trust. - For a PA v11 variant, set pCurlPath if curl is not on the Planning Analytics server's PATH, for example
C:\Windows\System32\curl.exeor/usr/bin/curl. The default iscurl.
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:
- 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.
- It runs the process named in pProcessName and notes how it ended.
- 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#
- Find the chore that runs your dimension update process.
- Replace that process in the chore with the Pause Run Resume variant for your Planning Analytics version.
- Set pProcessName to the dimension update process.
- Set pDurationMinutes to comfortably longer than the update takes.
- 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#
- Read the TM1 server log for what a run did: both samples log what Reportworq answered and the identifier of their pause.
- The access token stays out of the log. The PA v11 variants pass it to curl on the command line, so it is visible to anyone who can list the processes running on the Planning Analytics server while a request is in flight, but it is never written to the TM1 log or to the temporary answer file. The samples refuse a token, address or curl path that holds a quote or one of
` $ % < > |. - A missing identifier means no automatic resume. If Reportworq's answer to a pause does not carry an identifier, Pause Run Resume does not resume on its own, so that it cannot release a pause it did not make. It relies on its safety net; to resume sooner, use Resume jobs on the Activity screen.
- The samples call the Local API, so the Planning Analytics server must be able to reach the Reportworq address. A hosted Planning Analytics service outside your network cannot.
- The pause does not cover everything. See Limits of the pause.
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 pageOr write to support@reportworq.com directly.