The Planning Analytics Engine introduced a number of new features but one I am especially excited about is ExecuteHttpRequest.

The documentation can be found here:

https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=functions-executehttprequest

Http Methods:

For those not familiar with Http Requests/ Methods, I have pulled information from https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods 

The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.

The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.

The PATCH method applies partial modifications to a resource.

The PUT method replaces all current representations of the target resource with the request payload.

The DELETE method deletes the specified resource.

In layman's terms this translates to:

GET requests will "Get" data, we can return the values from a View for example or return the details of a Turbo Integrator Process

POST requests will trigger an action (run a TI process, Chore, update a dimension etc.)

PATCH will update a specific area of a request (update the data tab of a TI process or change the schedule for a chore)

PUT will overwrite a process/ chore in it's entirety (prolog, metadata, data, epilog etc..)

DELETE will delete the process/ chore

Http Response:

"The HTTP response is cached in memory. A response consists of a status code, a number of headers and a body, any of which can be queried by using the corresponding TurboIntegrator functions: HttpResponseGetStatusCode, HttpResponseGetHeader, and HttpResponseGetBody."

Status Code:

Taken from: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

HTTP response status codes indicate whether a specific HTTP request has been successfully completed. Responses are grouped in five classes:

1. Informational responses (100 – 199)
2. Successful responses (200 – 299)
3. Redirection messages (300 – 399)
4. Client error responses (400 – 499)
5. Server error responses (500 – 599)

Typically we should be expecting to see but are absolutely not limited to:

• 200 Successful response (it worked!)
• 204 No Content (It worked but you did not ask for anything to be returned)
• 400 Bad request (The request is missing information or contains too much information or listed unexpected information!)
• 401 Unauthorized (Incorrect credentials or user does not exist)
• 403 Forbidden (You do not have permission to run this request)
• 404 Not Found (The request was made for a resource that does not exist

Headers:

Taken from https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers

Headers can be grouped according to their contexts:

• Request headers contain more information about the resource to be fetched, or about the client requesting the resource.
• Response headers hold additional information about the response, like its location or about the server providing it.
• Representation headers contain information about the body of the resource, like its MIME type, or encoding/compression applied.
• Payload headers contain representation-independent information about payload data, including content length and the encoding used for transport.

Headers need to be sent with the request to authenticate against a resource or to tell the source what format you would like the response to come back as,

If we look at the provided documentation example:

# Get the cube rules from a remote TM1 server

ExecuteHttpRequest(

  'GET',

  'https://ibmcloud:11838/api/v1/Cubes(''A'')/Rules',

  '-u admin:',

  '-o response.json'

  '-c tm1_cert.perm' );

  rules = HttpResponseGetBody();

  # Update the rules of a cube on a remote TM1 server

  ExecuteHttpRequest(

   'PATCH',

   'https://ibmcloud:11838/api/v1/Cubes(''A'')',

   '-u admin:',

   '-h Content-Type:application/json',

   '-d { "Rules" : "" }',

   '-k' );

status_code = HttpResponseGetStatusCode();

The section we are interested in is:

-h header - The request header. A request can have multiple headers.

In the example the header is set as:

    '-h Content-Type:application/json',

The Content-Type header determines the response type (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type)

This request will return a response in JSON format, we are also able to set the format as HTML, Text, csv, pdf, xml and many many more,

Body:

Taken from https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages

The final part of the request is its body. Not all requests have one: requests fetching resources, like GET, HEAD, DELETE, or OPTIONS, usually don't need one. Some requests send data to the server in order to update it: as often the case with POST requests (containing HTML form data).

Bodies can be broadly divided into two categories:

• Single-resource bodies, consisting of one single file, defined by the two headers: Content-Type and Content-Length.
• Multiple-resource bodies, consisting of a multipart body, each containing a different bit of information. This is typically associated with HTML Forms.

In our example above we have:

   '-d { "Rules" : "" }',

-d body - The request body. When started with an @ character, the body will be read from the file having the name found following the @ character.

This 'body' is sending a request to update the "Rules" with a blank string aka clearing the rules. Conversely, this could contain our new Rules to update them.

Summary:

In summary. there is a little reading to do and some tweaks to our understanding of how data is transferred/ requested and how we can interact with aspects of IBM Planning Analytics. Once we grow more confident with this aspect we can start to investigate making Http Requests to other resources and pull data from sources as part of our modelling requirements

Stay tuned, I will add new blogs showing additional examples and how I've used ExecuteHttpRequest to keep two IBM Planning analytics servers in sync