{
  "Name": "ReportWORQ - Global Pause Control Sample 1.0 (PA Engine)",
  "HasSecurityAccess": false,
  "PrologProcedure": "#****Begin: Generated Statements***\r\n#****End: Generated Statements****\r\n\r\n\r\n# PROCESS Overview and Key Information:\r\n\r\n# ReportWORQ - Global Pause Control Sample 1.0 (PA Engine)\r\n#This TI process controls the Reportworq global execution pause through the Reportworq REST API (api/v1). One process, four actions: pause, resume, status and cancelall.\r\n#While Reportworq is paused no new job starts, queued jobs stay Pending, and running jobs hold at their next TM1 call or phase boundary. This lets a TM1 maintenance process (for example a dimension update) run without waiting behind Reportworq queries.\r\n#With pause and pWaitForPause = true, this process calls the API until Reportworq reports that every running job is held (result = true), or until pMaxWaits calls have been made.\r\n#Each pause adds a hold and logs its holdId. Reportworq stays paused while any hold is active. resume with pHoldId releases only that hold; resume with pHoldId blank is an all-clear: it releases every hold, including one set from the Reportworq footer and any made by another workspace (a deliberate operator action).\r\n#This process never sends a resume without a holdId on its own: only an explicit pAction = resume does that.\r\n#cancelall cancels the jobs of the access token's workspace only.\r\n#The whole process runs on the prolog tab. Please note that you do not need to edit anything on the other tabs of this TI Process.\r\n#Requires IBM Planning Analytics Engine (v12) or Planning Analytics as a Service, for ExecuteHttpRequest, HttpResponseGetStatusCode and HttpResponseGetBody. These functions are not available on Planning Analytics v11 (on-premises): there, use ReportWORQ - Global Pause Control Sample 1.0 (PA v11) instead.\r\n#IBM reference for ExecuteHttpRequest (options -h header, -d body, -k do not verify the TLS certificate): https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=functions-executehttprequest\r\n#The request timeout of ExecuteHttpRequest is not a documented option, so this process never relies on one long call: every wait is at most pWaitSeconds (300 or less) and is repeated up to pMaxWaits times.\r\n#----------------------------------------------------------------------------\r\n\r\n\r\n# TI PARAMETERS Included definitions:\r\n\r\n# pApiUrl (String): Base address of the Reportworq REST API, ending in api/v1/. Example: https://localhost:8300/api/v1/\r\n# pAccessToken (String): Access token required for API access. Within Reportworq - Settings - Reportworq API - grab the Local API access token\r\n# pAction (String): pause, resume, status or cancelall\r\n# pDurationMinutes (String): Whole minutes to stay paused, counted from the moment every running job is held. Blank or 0 pauses until a resume is sent.\r\n# pWaitForPause (String): true or false. For pause only: wait until every running job is held before continuing. Blank means true.\r\n# pWaitSeconds (Numeric): Seconds to wait in one call for the pause to complete, 1 to 300. Default 300.\r\n# pMaxWaits (Numeric): How many waits of pWaitSeconds before giving up. Default 3 (three 5-minute waits).\r\n# pFailIfNotPaused (Numeric): 1 = log an ERROR and stop the process with an error when the pause was not confirmed in time, 0 = log a warning and continue. Default 1.\r\n# pIncludePending (String): true or false. For cancelall only: also cancel jobs that are still Pending in the queue. Blank means false.\r\n# pHoldId (String): For resume only: the holdId a pause logged. Releases only that hold. Blank releases every pause: an all-clear.\r\n# pAcceptSelfSignedCertificate (Numeric): 1 = do not verify the Reportworq TLS certificate (ExecuteHttpRequest option -k), for a self-signed certificate. 0 = verify it. Default 0.\r\n#----------------------------------------------------------------------------\r\n\r\n\r\n#No edit to below statements needed#\r\n\r\nvAccessToken = TRIM(pAccessToken);\r\nvApiUrl = TRIM(pApiUrl);\r\nvAction = LOWER(TRIM(pAction));\r\nvWait = LOWER(TRIM(pWaitForPause));\r\nvIncludePending = LOWER(TRIM(pIncludePending));\r\nvResumeHoldId = TRIM(pHoldId);\r\n#The holdId from a pause response; blank until one arrives.\r\nvHoldId = '';\r\n\r\n#Remove surrounding double quotes that are sometimes pasted along with the token or the address.\r\nIF( (LONG(vAccessToken) >= 2) & (SUBST(vAccessToken, 1, 1) @= CHAR(34)) & (SUBST(vAccessToken, LONG(vAccessToken), 1) @= CHAR(34)) );\r\n  vAccessToken = SUBST(vAccessToken, 2, LONG(vAccessToken) - 2);\r\nENDIF;\r\nIF( (LONG(vApiUrl) >= 2) & (SUBST(vApiUrl, 1, 1) @= CHAR(34)) & (SUBST(vApiUrl, LONG(vApiUrl), 1) @= CHAR(34)) );\r\n  vApiUrl = SUBST(vApiUrl, 2, LONG(vApiUrl) - 2);\r\nENDIF;\r\n\r\nIF( vApiUrl @= '' );\r\n  LOGOUTPUT( 'ERROR', 'pApiUrl is empty. Example: https://localhost:8300/api/v1/' );\r\n  PROCESSERROR;\r\nENDIF;\r\nIF( vAccessToken @= '' );\r\n  LOGOUTPUT( 'ERROR', 'pAccessToken is empty. Use the Local API access token from Reportworq Settings, Reportworq API.' );\r\n  PROCESSERROR;\r\nENDIF;\r\nIF( SCAN( ' ', vAccessToken ) > 0 );\r\n  LOGOUTPUT( 'ERROR', 'pAccessToken contains a space, which cannot be sent as a request header. Check the token.' );\r\n  PROCESSERROR;\r\nENDIF;\r\nIF( SUBST( vApiUrl, LONG(vApiUrl), 1 ) @<> '/' );\r\n  vApiUrl = vApiUrl | '/';\r\nENDIF;\r\n\r\nIF( vWait @= '' );\r\n  vWait = 'true';\r\nENDIF;\r\nIF( vWait @<> 'true' & vWait @<> 'false' );\r\n  LOGOUTPUT( 'ERROR', 'pWaitForPause must be true or false: ' | pWaitForPause );\r\n  PROCESSERROR;\r\nENDIF;\r\nIF( vIncludePending @= '' );\r\n  vIncludePending = 'false';\r\nENDIF;\r\nIF( vIncludePending @<> 'true' & vIncludePending @<> 'false' );\r\n  LOGOUTPUT( 'ERROR', 'pIncludePending must be true or false: ' | pIncludePending );\r\n  PROCESSERROR;\r\nENDIF;\r\n\r\n#Whole minutes only. Blank or 0 means no duration, so the pause lasts until a resume is sent.\r\nnDuration = 0;\r\nIF( TRIM(pDurationMinutes) @<> '' );\r\n  nDuration = ROUNDP( NUMBR( TRIM(pDurationMinutes) ), 0 );\r\nENDIF;\r\nIF( nDuration < 0 );\r\n  LOGOUTPUT( 'ERROR', 'pDurationMinutes must be blank, 0 or a positive number of minutes: ' | pDurationMinutes );\r\n  PROCESSERROR;\r\nENDIF;\r\n\r\n#The API accepts 1 to 300 seconds per wait.\r\nnWaitSeconds = pWaitSeconds;\r\nIF( nWaitSeconds < 1 );\r\n  nWaitSeconds = 300;\r\nENDIF;\r\nIF( nWaitSeconds > 300 );\r\n  nWaitSeconds = 300;\r\nENDIF;\r\nnMaxWaits = ROUNDP( pMaxWaits, 0 );\r\nIF( nMaxWaits < 1 );\r\n  nMaxWaits = 1;\r\nENDIF;\r\n\r\n#Build the request address for the chosen action.\r\nnWaiting = 0;\r\nIF( vAction @= 'pause' );\r\n  vUrl = vApiUrl | 'pause?waitForPause=' | vWait | '&waitSeconds=' | TRIM( STR( nWaitSeconds, 10, 0 ) );\r\n  IF( nDuration > 0 );\r\n    vUrl = vUrl | '&duration=' | TRIM( STR( nDuration, 10, 0 ) );\r\n  ENDIF;\r\n  IF( vWait @= 'true' );\r\n    nWaiting = 1;\r\n  ENDIF;\r\nELSEIF( vAction @= 'resume' );\r\n  vUrl = vApiUrl | 'resume';\r\n  IF( vResumeHoldId @<> '' );\r\n    vUrl = vUrl | '?holdId=' | vResumeHoldId;\r\n  ENDIF;\r\nELSEIF( vAction @= 'status' );\r\n  vUrl = vApiUrl | 'pause/status';\r\nELSEIF( vAction @= 'cancelall' );\r\n  vUrl = vApiUrl | 'cancelall?includePending=' | vIncludePending;\r\nELSE;\r\n  LOGOUTPUT( 'ERROR', 'pAction must be pause, resume, status or cancelall: ' | pAction );\r\n  PROCESSERROR;\r\nENDIF;\r\n\r\n#Only a pause that waits is repeated. Every other action is a single call.\r\nnMaxAttempts = 1;\r\nIF( nWaiting = 1 );\r\n  nMaxAttempts = nMaxWaits;\r\nENDIF;\r\n\r\nnAttempt = 0;\r\nnOk = 0;\r\nnFatal = 0;\r\nWHILE( nOk = 0 & nFatal = 0 & nAttempt < nMaxAttempts );\r\n  nAttempt = nAttempt + 1;\r\n  IF( nWaiting = 1 );\r\n    LOGOUTPUT( 'INFO', 'Reportworq pause: wait ' | TRIM( STR( nAttempt, 10, 0 ) ) | ' of ' | TRIM( STR( nMaxAttempts, 10, 0 ) ) | ', up to ' | TRIM( STR( nWaitSeconds, 10, 0 ) ) | ' seconds.' );\r\n  ELSE;\r\n    LOGOUTPUT( 'INFO', 'Reportworq ' | vAction | ': sending the request.' );\r\n  ENDIF;\r\n\r\n  #The token is only ever sent as a header and is never written to the log.\r\n  IF( pAcceptSelfSignedCertificate = 1 );\r\n    ExecuteHttpRequest( 'POST', vUrl, '-h accessToken:' | vAccessToken, '-h Content-Type:application/json', '-d {}', '-k' );\r\n  ELSE;\r\n    ExecuteHttpRequest( 'POST', vUrl, '-h accessToken:' | vAccessToken, '-h Content-Type:application/json', '-d {}' );\r\n  ENDIF;\r\n  nStatus = HttpResponseGetStatusCode;\r\n  sBody = LOWER( HttpResponseGetBody );\r\n\r\n  IF( nStatus = 200 );\r\n    LOGOUTPUT( 'INFO', 'Reportworq answered: ' | sBody );\r\n    IF( vAction @= 'pause' );\r\n      #Keep the id of the hold this call added, so the resume releases only this process's pause (an administrator's own pause stays in force).\r\n      nHoldPos = SCAN( '\"holdid\":\"', sBody );\r\n      nHoldSkip = 10;\r\n      IF( nHoldPos = 0 );\r\n        nHoldPos = SCAN( '\"holdid\": \"', sBody );\r\n        nHoldSkip = 11;\r\n      ENDIF;\r\n      vNewHoldId = '';\r\n      IF( nHoldPos > 0 );\r\n        vHoldRest = SUBST( sBody, nHoldPos + nHoldSkip, LONG( sBody ) - nHoldPos - nHoldSkip + 1 );\r\n        nHoldEnd = SCAN( CHAR(34), vHoldRest );\r\n        IF( nHoldEnd > 1 );\r\n          vNewHoldId = SUBST( vHoldRest, 1, nHoldEnd - 1 );\r\n        ENDIF;\r\n      ENDIF;\r\n      #A repeated wait adds a new hold, so release the one the previous wait added (the new one keeps Reportworq paused).\r\n      IF( vHoldId @<> '' & vNewHoldId @<> '' & vNewHoldId @<> vHoldId );\r\n        IF( pAcceptSelfSignedCertificate = 1 );\r\n          ExecuteHttpRequest( 'POST', vApiUrl | 'resume?holdId=' | vHoldId, '-h accessToken:' | vAccessToken, '-h Content-Type:application/json', '-d {}', '-k' );\r\n        ELSE;\r\n          ExecuteHttpRequest( 'POST', vApiUrl | 'resume?holdId=' | vHoldId, '-h accessToken:' | vAccessToken, '-h Content-Type:application/json', '-d {}' );\r\n        ENDIF;\r\n      ENDIF;\r\n      IF( vNewHoldId @<> '' );\r\n        vHoldId = vNewHoldId;\r\n        LOGOUTPUT( 'INFO', 'Reportworq pause hold: ' | vHoldId );\r\n      ENDIF;\r\n    ENDIF;\r\n    IF( nWaiting = 1 );\r\n      #The API answers {\"result\":true,...} once every running job is held, {\"result\":false,...} when the wait ran out.\r\n      IF( SCAN( '\"result\":true', sBody ) > 0 % SCAN( '\"result\": true', sBody ) > 0 );\r\n        nOk = 1;\r\n      ELSE;\r\n        LOGOUTPUT( 'INFO', 'Reportworq is not fully paused yet: running jobs are still finishing their current step.' );\r\n      ENDIF;\r\n    ELSE;\r\n      nOk = 1;\r\n    ENDIF;\r\n  ELSE;\r\n    LOGOUTPUT( 'ERROR', 'Reportworq answered HTTP ' | TRIM( STR( nStatus, 10, 0 ) ) | ': ' | sBody );\r\n    IF( vAction @= 'resume' & nStatus = 404 & vResumeHoldId @<> '' );\r\n      LOGOUTPUT( 'ERROR', 'No active pause hold ' | vResumeHoldId | ': it was already released or has expired. Leave pHoldId blank to release every pause (an all-clear).' );\r\n    ENDIF;\r\n    #No answer, request timeout or a gateway problem can be retried while waiting. Anything else (bad token, bad address) cannot.\r\n    IF( nWaiting = 1 & ( nStatus = 0 % nStatus = 408 % nStatus = 502 % nStatus = 503 % nStatus = 504 ) );\r\n      LOGOUTPUT( 'WARN', 'Trying again.' );\r\n    ELSE;\r\n      nFatal = 1;\r\n    ENDIF;\r\n  ENDIF;\r\nEND;\r\n\r\nIF( nOk = 1 );\r\n  LOGOUTPUT( 'INFO', 'Reportworq ' | vAction | ' completed.' );\r\n  IF( vAction @= 'pause' & vHoldId @<> '' );\r\n    LOGOUTPUT( 'INFO', 'To release only this pause, run resume with pHoldId = ' | vHoldId );\r\n  ENDIF;\r\n  IF( vAction @= 'pause' & vHoldId @= '' );\r\n    LOGOUTPUT( 'WARN', 'The holdId of this pause is unknown (the answer did not carry one). Resume it by hand: run resume with pHoldId blank, or use Resume in the Reportworq footer.' );\r\n  ENDIF;\r\nELSE;\r\n  IF( nWaiting = 1 & nFatal = 0 );\r\n    IF( vHoldId @<> '' );\r\n      LOGOUTPUT( 'ERROR', 'Reportworq was not fully paused after ' | TRIM( STR( nMaxAttempts, 10, 0 ) ) | ' waits of ' | TRIM( STR( nWaitSeconds, 10, 0 ) ) | ' seconds. The pause is still requested: run resume with pHoldId = ' | vHoldId | ' to lift it.' );\r\n    ELSE;\r\n      LOGOUTPUT( 'ERROR', 'Reportworq was not fully paused after ' | TRIM( STR( nMaxAttempts, 10, 0 ) ) | ' waits of ' | TRIM( STR( nWaitSeconds, 10, 0 ) ) | ' seconds. The pause may still be requested and its holdId is unknown, so it was not released: resume it by hand (run resume with pHoldId blank, or use Resume in the Reportworq footer).' );\r\n    ENDIF;\r\n  ELSE;\r\n    LOGOUTPUT( 'ERROR', 'Reportworq ' | vAction | ' failed. Check pApiUrl, pAccessToken and the pAcceptSelfSignedCertificate setting.' );\r\n  ENDIF;\r\n  IF( vAction @<> 'pause' % pFailIfNotPaused <> 0 % nFatal = 1 );\r\n    PROCESSERROR;\r\n  ENDIF;\r\nENDIF;\r\n",
  "MetadataProcedure": "\r\n#****Begin: Generated Statements***\r\n#****End: Generated Statements****",
  "DataProcedure": "\r\n#****Begin: Generated Statements***\r\n#****End: Generated Statements****",
  "EpilogProcedure": "\r\n#****Begin: Generated Statements***\r\n#****End: Generated Statements****",
  "Parameters": [
    {
      "Name": "pApiUrl",
      "Prompt": "Base address of the Reportworq REST API, ending in api/v1/",
      "Value": "https://localhost:8300/api/v1/",
      "Type": "String"
    },
    {
      "Name": "pAccessToken",
      "Prompt": "Access token required for API access",
      "Value": "",
      "Type": "String"
    },
    {
      "Name": "pAction",
      "Prompt": "Action: pause, resume, status or cancelall",
      "Value": "status",
      "Type": "String"
    },
    {
      "Name": "pDurationMinutes",
      "Prompt": "Pause only: whole minutes to stay paused once every running job is held, blank or 0 = until resumed",
      "Value": "",
      "Type": "String"
    },
    {
      "Name": "pWaitForPause",
      "Prompt": "Pause only: wait until every running job is held (true/false)",
      "Value": "true",
      "Type": "String"
    },
    {
      "Name": "pWaitSeconds",
      "Prompt": "Seconds to wait in one call for the pause to complete (1 to 300)",
      "Value": 300,
      "Type": "Numeric"
    },
    {
      "Name": "pMaxWaits",
      "Prompt": "How many waits of pWaitSeconds before giving up",
      "Value": 3,
      "Type": "Numeric"
    },
    {
      "Name": "pFailIfNotPaused",
      "Prompt": "Stop the process with an error when the pause is not confirmed in time (1 = yes, 0 = continue)",
      "Value": 1,
      "Type": "Numeric"
    },
    {
      "Name": "pIncludePending",
      "Prompt": "Cancel all only: also cancel jobs that are still Pending (true/false)",
      "Value": "false",
      "Type": "String"
    },
    {
      "Name": "pAcceptSelfSignedCertificate",
      "Prompt": "1 = do not verify the Reportworq TLS certificate (self-signed), 0 = verify it",
      "Value": 0,
      "Type": "Numeric"
    },
    {
      "Name": "pHoldId",
      "Prompt": "Resume only: the holdId a pause logged, to release only that hold (blank = release every pause: an all-clear)",
      "Value": "",
      "Type": "String"
    }
  ]
}