There are a few new TurboIntegrator functions in Planning Analytics Engine (or version 12) that do not exist (yet?) in the server version 11 that I’m working with all the time.

One of these new functions is ExecuteHttpRequest that allows you to call HTTP endpoint from PA. This post describes how do something very similar in version 11 while we wait for ExecuteHttpRequest to be back-ported to v11.

I had to do some HTTP calls in version 11 recently, so I put together a few TI processes that mimic the v12 ExecuteHttpRequest functionality in v11. Similar arguments and execution logic both to avoid reinventing the wheel and to make it easier to upgrade to v12 later on. It wouldn’t be a straight ‘find & replace’, but the fundamentals of the call handling are the same, making conversion way easier.

So the goal was to be able run something like this in a TI:

NumericSessionVariable('SysHttpStatus');
StringSessionVariable('SysHttpBody');
# Create a new process from file
sProcessBody = '@http\request_body.txt';
ExecuteProcess( 'Sys ExecuteHttpRequest', 
  'pRequestId',sRequestId,
  'pMethod', 'Post',
  'pUrl','http://localhost:55130/api/v1/Processes',
  'pBody',sProcessBody,
  'pAuthorizationType','CAMNamespace',
  'pCredentialToBase64Encode',Expand('%sUser%:%sPassword%:%sNamespace%'),
  'pHeader1Name','content-type',
  'pHeader1Value','application/json'
  );
ExecuteProcess('SysHttpResponseGetStatusCode',  'pRequestId',sRequestId);
ExecuteProcess('SysHttpResponseGetBody',  'pRequestId',sRequestId);
Logoutput('info','Status ' | NumberTOString(SysHttpStatus) | ' body : ' | SysHttpBody);
# run the process
ExecuteProcess( 'SysExecuteHttpRequest', 
  'pRequestId',sRequestId,
  'pMethod', 'Post',
  'pUrl','http://localhost:55130/api/v1/Processes(''''MyProcess'''')/tm1.ExecuteWithReturn',
  'pBody','',
  'pAuthorizationType','CAMNamespace',
  'pCredentialToBase64Encode',Expand('%sUser%:%sPassword%:%sNamespace%'),
  'pHeader1Name','content-type',
  'pHeader1Value','application/json'
  );
ExecuteProcess('SysHttpResponseGetStatusCode',  'pRequestId',sRequestId);
ExecuteProcess('SysHttpResponseGetBody',  'pRequestId',sRequestId);
Logoutput('info','Status ' | NumberTOString(SysHttpStatus) | ' body : ' | SysHttpBody);

which will create a process defined in the http\process_body.txt file on the PA server running on port 55130 and execute it. I’m using TM1 Rest API endpoint as an example (same as in v12 ExecuteHttpRequest documentation), you can call any URL endpoint.

And you can build on SysExecuteHttpRequest & TM1 Rest API calls like the ones above to implement the TIs that finish when data is committed unlike ExecuteProcess which returns execution before that or mimic the other great v12 process control functions like WaitForAllJobs ;) Here’s hoping these functions will be ported back to v11 though.

Why ExecuteHttpRequest is added in PA engine:

• ExecuteCommand is going away in v12 (no interaction with OS in containers) so any external interaction (e.g. emails) will need another way to talk to something
• TM1RunTI will not work in v12 either (as well as anything else using C API) and would leave a gap in PA orchestration capability, requiring some external tool to connect 2 PA databases. ExecuteHttpRequest would allow using TM1 Rest Api to achieve the same functionality

SysExecuteHttpRequest in Planning Analytics v11

So how do we replicate ExecuteHttpRequest()?

Well, we would use ExecuteCommand to run Invoke-Web-Request powershell cmdlet :) Would be Curl on linux, but I need it only on Windows at the moment, please reach out if you’d need it on linux and we can put something together.

The SysExecuteHttpRequest TI generates a powershell script based on the parameters passed to it. Parameters are similar to v12 engine one with a few extra ones described below.

Generated script then:

• runs the Invoke-Web-Request
• saves the header, body, response, status code from response as files in http folder

These generated files are read by the other TIs to mimic the v12 functions:

• SysHttpResponseGetStatusCode acts as HttpResponseGetStatusCode
• SysHttpResponseGetBody - HttpResponseGetBody
• SysHttpResponseGetHeader - HttpResponseGetHeader

SysExecuteHttpRequest parameter: pResponseID

An interesting caveat in ExecuteHttpRequest documentation is that

The Planning Analytics Engine only keeps one HTTP response at a time. A new successful HTTP request execution update and overwrites the cached response.

So the TI’s I wrote replicate this ‘storing only 1 response’ behaviour by default via using SessionVariables to hold the data we want to pass to parent process, like this:

	NumericSessionVariable('SysHttpStatus');
	ExecuteProcess('Sys HttpResponseGetStatusCode',  'pRequestId',sRequestId);

But I added the pResponseID parameter in these TIs allows to have different files generated for each request in http folder, each filename is ResponseID.filetype:

Writing and reading different response files by RequestId can allow storing multiple responses and making the requests isolated from each other.

For example the you could make GetRequest TIs write the results to a cube with RequestId as a dimension and then CellGet them to allow multiple requests running in parallel without impacting each other.

Files are fairly self-explanatory, it’s the cookies, body, response, headers, status of the web request and the additional couple:

• transcript contains the Powershell transcript of script execution, all the console messages from the script. There shouldn’t be anything interesting in this file unless there are errors
• sv file allows re-using all cookies information for the same RequestId, it contains SessionVariable of the previously executed requests, that’s my attempt on doing the same as v12’s function, which as per documentation:

For convenience, the engine reuses the cookie it found in the previous responses in new requests when the Cookie header is absent.

SysExecuteHttpRequest parameters: pAuthorizationType and pCredentialToBase64Encode

These 2 are specifically for connecting to Planning Analytics instances and they mimic -u user parameter of the ExecuteHttpRequest function. We need to Base64 encode a set of credentials (user:password for basic authentication, user:password:namespace for CAM) to connect to PA server so these 2 parameters form the Authorization header for PA authentication.

Known limitations

• Only windows so far, reach out if you want something similar with curl instead of Iwr
• I haven’t implemented the -c certificate_file parameter so far, either reach out or add the -Certificate parameter to Iwr and the loading of the certificate file in SysExecuteHttpRequest.