API_CALL

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

Overview

Description	The API_CALL function enables Valsight to interact with external applications by making a POST call to a designated URL, and returning the result to the Valsight model.
Syntax	`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 expects to receive 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 "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
2025	DE	100
2026	DE	200
2027	DE	300
2028	DE	400
2029	DE	500

Input node: B

Year	Country	Revenue
2025	DE	350
2026	DE	400
2027	DE	450
2028	DE	500
2029	DE	550

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

Formula: 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
2025	DE	450
2026	DE	600
2027	DE	750
2028	DE	900
2029	DE	1050