Overview#
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 the TI function 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 exists only on Planning Analytics Engine (v12) and Planning Analytics as a Service. It does not exist on 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.
Requirements#
- PA v11 variants: curl on the Planning Analytics server. It is built into Windows 10 version 1803 and later and Windows Server 2019 and later (
C:\Windows\System32\curl.exe), and it is available on Linux. 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 enabled and reachable from the Planning Analytics server. The samples use the access token from the same page.
- A Reportworq release that includes the pause (5.0.2.620 or later). The download page lists the minimum Reportworq version for each sample.
Getting the samples#
The samples are downloads and are not installed with Reportworq. 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.
To install a sample:
- 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:8300/api/v1/. - Set the default of pAccessToken to the access token from Settings, Reportworq API. 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:8300/api/v1/. |
| pAccessToken | The Local API 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 footer. If both are active, Reportworq stays paused until the administrator resumes too.
To 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, and set pDurationMinutes to comfortably longer than the update takes. The chore then pauses Reportworq, runs the update with nothing querying, and resumes. Try it first with a manual run and watch the footer in Reportworq.
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 Reportworq footer and any made by another workspace. |
status |
Logs the pause status, including the same message the Reportworq footer shows. |
cancelall |
Cancels the running jobs of the workspace that the access token belongs to. With pIncludePending true, pending jobs are canceled too. |
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. |
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.
The default for pAction is status, so a first run changes nothing. The other parameters are pApiUrl, pAccessToken, pAcceptSelfSignedCertificate and (PA v11 variant) pCurlPath as above, pIncludePending (cancelall only, default false) and pHoldId (resume only).
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 the resume control in the Reportworq footer.
- 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.
Related topics#
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.