{
  "Name": "Reportworq - Pause Run Resume 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 - Pause Run Resume Sample 1.0 (PA Engine)\r\n#This TI process runs another TI process (for example a dimension update) while Reportworq is paused, so the update does not wait behind Reportworq queries.\r\n#   1. Prolog: pause Reportworq through the REST API and wait until every running job is held. If that does not happen in time, Reportworq is resumed and the process stops with an error without running pProcessName.\r\n#   2. Prolog: run pProcessName with ExecuteProcess and keep its return code.\r\n#   3. Epilog: always resume Reportworq, even when pProcessName failed, and log the outcome.\r\n#The pause is requested with a duration (pDurationMinutes) as a timed safety net: if this process ever dies before the epilog, Reportworq resumes on its own when that time is up. The safety net starts once every running job is held, so set it longer than the process needs to run.\r\n#Each pause request adds a hold and the response carries its holdId. This process resumes with resume?holdId=, which releases only its own hold: if an administrator (or another process) also paused Reportworq, it stays paused until that pause is released too.\r\n#This process never sends a resume without its holdId. If the holdId is unknown (the pause answer did not carry one), it logs that and leaves its pause to the timed safety net.\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 - Pause Run Resume 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:8600/api/v1/\r\n# pAccessToken (String): Access token required for API access. In Reportworq: Settings, Configuration, API, Local API keys\r\n# pProcessName (String): The TI process to run while Reportworq is paused, for example your dimension update.\r\n# pDurationMinutes (String): Safety net, whole minutes. Reportworq resumes by itself this long after it is fully paused if this process never resumes it. Default 30.\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# 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\nvProcessName = TRIM(pProcessName);\r\n\r\n#Set to 1 as soon as a pause request has been sent, so the epilog knows a resume is owed. Set back to 0 once a resume went through.\r\nnResumeOwed = 0;\r\nnProcessFailed = 0;\r\nvProcessReturn = -1;\r\n#The holdId from the pause response; blank until one arrives. A resume is only ever sent with it, never without.\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:8600/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, Configuration, API, Local API keys.' );\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( vProcessName @= '' );\r\n  LOGOUTPUT( 'ERROR', 'pProcessName is empty. Name the TI process to run while Reportworq is paused.' );\r\n  PROCESSERROR;\r\nENDIF;\r\nIF( vProcessName @= GetProcessName() );\r\n  LOGOUTPUT( 'ERROR', 'pProcessName cannot be this process itself.' );\r\n  PROCESSERROR;\r\nENDIF;\r\nIF( SUBST( vApiUrl, LONG(vApiUrl), 1 ) @<> '/' );\r\n  vApiUrl = vApiUrl | '/';\r\nENDIF;\r\n\r\n#Whole minutes. A blank or 0 would leave Reportworq paused forever if this process died, so it falls back to the 30 minute default.\r\nnDuration = 30;\r\nIF( TRIM(pDurationMinutes) @<> '' );\r\n  nDuration = ROUNDP( NUMBR( TRIM(pDurationMinutes) ), 0 );\r\nENDIF;\r\nIF( nDuration < 1 );\r\n  nDuration = 30;\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\nvPauseUrl = vApiUrl | 'pause?waitForPause=true&waitSeconds=' | TRIM( STR( nWaitSeconds, 10, 0 ) ) | '&duration=' | TRIM( STR( nDuration, 10, 0 ) );\r\n#Set once the holdId is known. A resume without a holdId could release pauses this process did not make, so none is sent.\r\nvResumeUrl = '';\r\n\r\n#----------------------------------------------------------------------------\r\n# STEP 1: PAUSE REPORTWORQ AND WAIT UNTIL EVERY RUNNING JOB IS HELD\r\n#----------------------------------------------------------------------------\r\nnAttempt = 0;\r\nnPaused = 0;\r\nnFatal = 0;\r\nWHILE( nPaused = 0 & nFatal = 0 & nAttempt < nMaxWaits );\r\n  nAttempt = nAttempt + 1;\r\n  LOGOUTPUT( 'INFO', 'Reportworq pause: wait ' | TRIM( STR( nAttempt, 10, 0 ) ) | ' of ' | TRIM( STR( nMaxWaits, 10, 0 ) ) | ', up to ' | TRIM( STR( nWaitSeconds, 10, 0 ) ) | ' seconds.' );\r\n\r\n  #From here a pause may be in effect even if this call fails, so a resume is owed.\r\n  nResumeOwed = 1;\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', vPauseUrl, '-h accessToken:' | vAccessToken, '-h Content-Type:application/json', '-d {}', '-k' );\r\n  ELSE;\r\n    ExecuteHttpRequest( 'POST', vPauseUrl, '-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    #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    #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      nPaused = 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    LOGOUTPUT( 'ERROR', 'Reportworq answered HTTP ' | TRIM( STR( nStatus, 10, 0 ) ) | ': ' | sBody );\r\n    #No answer, request timeout or a gateway problem can be retried. Anything else (bad token, bad address) cannot.\r\n    IF( 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\n#From here every resume (the one below and the epilog) releases only this process's hold.\r\nIF( vHoldId @<> '' );\r\n  vResumeUrl = vApiUrl | 'resume?holdId=' | vHoldId;\r\nENDIF;\r\nIF( nResumeOwed = 1 & vHoldId @= '' );\r\n  LOGOUTPUT( 'WARN', 'The holdId of this process''s pause is unknown, so it will not send a resume (that could release pauses it did not make). Its timed pause lifts by itself ' | TRIM( STR( nDuration, 10, 0 ) ) | ' minutes after every running job is held.' );\r\nENDIF;\r\n\r\nIF( nPaused = 0 );\r\n  LOGOUTPUT( 'ERROR', 'Reportworq was not confirmed paused, so ' | vProcessName | ' was NOT run.' );\r\n  #A pause that was accepted but not completed is still draining, so lift it now rather than leave Reportworq held.\r\n  IF( nResumeOwed = 1 & vHoldId @<> '' );\r\n    IF( pAcceptSelfSignedCertificate = 1 );\r\n      ExecuteHttpRequest( 'POST', vResumeUrl, '-h accessToken:' | vAccessToken, '-h Content-Type:application/json', '-d {}', '-k' );\r\n    ELSE;\r\n      ExecuteHttpRequest( 'POST', vResumeUrl, '-h accessToken:' | vAccessToken, '-h Content-Type:application/json', '-d {}' );\r\n    ENDIF;\r\n    nStatus = HttpResponseGetStatusCode;\r\n    IF( nStatus = 200 % nStatus = 404 );\r\n      #404: the hold was already released or had expired, so nothing is left to resume.\r\n      LOGOUTPUT( 'INFO', 'This process''s pause was lifted after the failed pause.' );\r\n      nResumeOwed = 0;\r\n    ELSE;\r\n      LOGOUTPUT( 'ERROR', 'The resume after the failed pause answered HTTP ' | TRIM( STR( nStatus, 10, 0 ) ) | '. The timed pause lifts by itself ' | TRIM( STR( nDuration, 10, 0 ) ) | ' minutes after it completes. Resume Reportworq by hand if it stays paused.' );\r\n    ENDIF;\r\n  ENDIF;\r\n  PROCESSERROR;\r\nENDIF;\r\n\r\n#----------------------------------------------------------------------------\r\n# STEP 2: RUN THE PROCESS WHILE REPORTWORQ IS PAUSED\r\n#----------------------------------------------------------------------------\r\nLOGOUTPUT( 'INFO', 'Reportworq is paused. Running ' | vProcessName | '.' );\r\nvProcessReturn = ExecuteProcess( vProcessName );\r\n\r\nIF( vProcessReturn = ProcessExitNormal() );\r\n  LOGOUTPUT( 'INFO', vProcessName | ' finished normally.' );\r\nELSE;\r\n  nProcessFailed = 1;\r\n  LOGOUTPUT( 'ERROR', vProcessName | ' did not finish normally. ExecuteProcess returned ' | TRIM( STR( vProcessReturn, 10, 0 ) ) | ' (0 = normal, 1 = minor errors, 2 = quit, 3 = with message, 4 = serious error, 5 = on init, 6 = break). See the TM1 server log for that process.' );\r\nENDIF;\r\n\r\n#The epilog resumes Reportworq whatever happened above.\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": "#****Begin: Generated Statements***\r\n#****End: Generated Statements****\r\n\r\n\r\n#################################################\r\n#  RESUME REPORTWORQ, ALWAYS\r\n#  Runs whether or not the process in pProcessName\r\n#  succeeded. Please do not edit this tab.\r\n#################################################\r\n\r\nnResumed = 0;\r\n\r\n#Never resume without this process's holdId: that could release pauses it did not make.\r\nIF( nResumeOwed = 1 & vHoldId @= '' );\r\n  LOGOUTPUT( 'ERROR', 'The holdId of this process''s pause is unknown, so no resume was sent. The timed pause lifts by itself ' | TRIM( STR( nDuration, 10, 0 ) ) | ' minutes after every running job is held. Resume Reportworq by hand if it must resume sooner.' );\r\nENDIF;\r\n\r\nIF( nResumeOwed = 1 & vHoldId @<> '' );\r\n  nResumeAttempt = 0;\r\n  WHILE( nResumed = 0 & nResumeAttempt < 3 );\r\n    nResumeAttempt = nResumeAttempt + 1;\r\n    LOGOUTPUT( 'INFO', 'Resuming Reportworq, attempt ' | TRIM( STR( nResumeAttempt, 10, 0 ) ) | ' of 3.' );\r\n    IF( pAcceptSelfSignedCertificate = 1 );\r\n      ExecuteHttpRequest( 'POST', vResumeUrl, '-h accessToken:' | vAccessToken, '-h Content-Type:application/json', '-d {}', '-k' );\r\n    ELSE;\r\n      ExecuteHttpRequest( 'POST', vResumeUrl, '-h accessToken:' | vAccessToken, '-h Content-Type:application/json', '-d {}' );\r\n    ENDIF;\r\n    nStatus = HttpResponseGetStatusCode;\r\n    #vResumeUrl carries this process's holdId (set on the prolog), so only its own pause is released. 404: that hold was already released or had expired.\r\n    IF( nStatus = 200 % nStatus = 404 );\r\n      nResumed = 1;\r\n      nResumeOwed = 0;\r\n      LOGOUTPUT( 'INFO', 'Reportworq answered: ' | LOWER( HttpResponseGetBody ) );\r\n    ELSE;\r\n      LOGOUTPUT( 'ERROR', 'The Reportworq resume answered HTTP ' | TRIM( STR( nStatus, 10, 0 ) ) | ': ' | LOWER( HttpResponseGetBody ) );\r\n      IF( nResumeAttempt < 3 );\r\n        #Wait 5 seconds before trying again.\r\n        Sleep( 5000 );\r\n      ENDIF;\r\n    ENDIF;\r\n  END;\r\n\r\n  IF( nResumed = 0 );\r\n    LOGOUTPUT( 'ERROR', 'Reportworq could not be resumed. The timed pause lifts by itself ' | TRIM( STR( nDuration, 10, 0 ) ) | ' minutes after it completed. Resume Reportworq by hand if it stays paused.' );\r\n  ENDIF;\r\nENDIF;\r\n\r\n#Log the outcome of the whole run, then fail the process if anything went wrong.\r\nIF( nProcessFailed = 0 & nResumeOwed = 0 );\r\n  LOGOUTPUT( 'INFO', 'Pause, run and resume completed: ' | vProcessName | ' finished normally and this process''s pause is released (Reportworq stays paused only if someone else also paused it).' );\r\nELSE;\r\n  IF( nProcessFailed = 1 );\r\n    LOGOUTPUT( 'ERROR', 'Pause, run and resume finished with an error: ' | vProcessName | ' returned ' | TRIM( STR( vProcessReturn, 10, 0 ) ) | '.' );\r\n  ENDIF;\r\n  PROCESSERROR;\r\nENDIF;\r\n",
  "Parameters": [
    {
      "Name": "pApiUrl",
      "Prompt": "Base address of the Reportworq REST API, ending in api/v1/",
      "Value": "https://localhost:8600/api/v1/",
      "Type": "String"
    },
    {
      "Name": "pAccessToken",
      "Prompt": "Access token required for API access, in Reportworq: Settings, Configuration, API, Local API keys",
      "Value": "",
      "Type": "String"
    },
    {
      "Name": "pProcessName",
      "Prompt": "The TI process to run while Reportworq is paused",
      "Value": "",
      "Type": "String"
    },
    {
      "Name": "pDurationMinutes",
      "Prompt": "Safety net: Reportworq resumes by itself this many minutes after it is fully paused",
      "Value": "30",
      "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": "pAcceptSelfSignedCertificate",
      "Prompt": "1 = do not verify the Reportworq TLS certificate (self-signed), 0 = verify it",
      "Value": 0,
      "Type": "Numeric"
    }
  ]
}