API_CALL

This function is a separate subscription and not available in all Valsight instances.

Basic Overview

Description	The API_CALL function enables Valsight to interact with external applications by making a POST call to a designated URL, facilitating data exchange between two.
Signature	API_CALL(url, [inputNodes], [resultLevels], [, format, version, message, timeout])
Parameters	Mandatory parameters url: The URL parameter specifies the destination web address which the POST request will be made. inputNodes: List of input nodes in square brackets that will be sent with the request. resultLevels: The levels in square brackets that Valsight expect receiving from the external server. Optional parameters format: The desired data format for the API response. Available format(s): JSON version: The version identifier that will be sent with the request. message: An optional message that will be sent with the request. timeout: The timeout parameter sets a specific time limit for the API call. If the external server does not responds within this predefined timeframe, the request will be automatically cancelled.
Limitations	In order to cast the response coming from external server into a valid/usable node, the response should strictly follow the Valsight Table JSON representation. See section named “Response format“. The configuration flags for the function by default disables the use of this function. featureFlags.apiCall.maxRowsToSend Maximum allowed number of rows in the input cubes combined. featureFlags.apiCall.maxMbsToReturn Maximum data allowed to be read from response in megabytes. featureFlags.apiCall.allowedUrlsRegex Allowed URL structure to make the API call to

Response format

Handling of the response is flexible for unknown attributes. Meaning if the response from external server contains unknown keys and values, Valsight simply ignores it. However, there are certain validations on the known keys.

response_status = { SUCCESS, ERROR }

SUCCESS: The computation was successful.

ERROR: There was an error during the computation, note if this the case, Valsight will display the error message that is contained in error_message

output = <a node in the Valsight Table JSON structure>

An example response should look like:

CODE

{
  "format": "JSON",
  "version": "1",
  "function_name" : "simple_plus",
  response_status: "SUCCESS",
  warning_msg: "",
  error_msg: "",
  "output" : {
        "version": "1",
        "columnMetadata": [
            {
                "name": "Year",
                "columnType": "level",
                "levelId": 1
            },
            {
                "name": "measure",
                "columnType": "measure"
            }
        ],
        "rowData": [
            ["2015","50"],
            ["2016","100"],
            ["2017","150"],
            ["2018","200"]
        ]
    }
}

Example

Input nodes are the nodes that will be sent to the external server. For this simple example, let’s imagine the external server simply adds these two nodes and returns the result.

Input:

Node A

Year	Country	Revenue
2020	DE	100
2021	DE	200
2022	DE	300
2023	DE	400
2024	DE	500

Node B

Year	Country	Revenue
2020	DE	350
2021	DE	400
2022	DE	450
2023	DE	500
2024	DE	550

To use the API_CALL with this setting, the following configuration of the function would be used:

API_CALL(“https://externalServer.com/sumTwoNodes“, ['Node A', 'Node B'], [“Year“, “Country“])

Where the URL points to the endpoint where the external server is. Input nodes in square brackets are what we want to send there and in the result we expect to see the levels Year and Country. Considering the external server operated fine. The produced result will be:

Year	Country	Revenue
2020	DE	450
2021	DE	600
2022	DE	750
2023	DE	900
2024	DE	1050