Using C.SPARK_UDFCALLAPI() [legacy]

This functionality is deprecated and not supported.

Introduction

This implementation of Xcall has 2 parts, the Xcall block to define the request, and a user-defined function, Spark_UdfCallAPI to receive responses.

Xcall using Spark Assistant: Data Flow

Sample files

In this example we are using two files (Downstream and Upstream file) to show the functionality of the Xcall using Spark Assistant.

Downstream File

• The downstream Excel file contains 2 Xoutputs (Output1 & Output2), where Output1 is a single value and Ouput2 is a separate JSON object having its own outputs.

Upstream File

• The upstream Excel file contains the Xcall block, JSON response and the user-defined functions (UDFs).

You can use the below files to follow along!

17KB

DownstreamService_example.xlsx

Open

21KB

UpstreamService_example.xlsx

Open

Preparation

This functionality requires the user to download Spark Assistant Excel add-in.

Downstream service

1. The downstream service must be an existing service in the same Spark tenant.

2. You will need the downstream folder name, service name and a sample of the request body.

• Folder & Service name - You can check out the folder name and service name of downstream service on folder page. Note down the name on the folder card to perform the following steps.

• Request body – Select your downstream service and click on the API tester from the left side menu. Under API Request (Inputs), you can see inputs in different formats. Click into Raw view and note down request body for the following steps.

API Tester: Request Body Sample Under RAW View

Upstream service

Request

Create an XCall block in upstream service to make an API call. The XCall block can be anywhere in your workbook but must be on the same sheet as your C.SPARK_UDFCALLAPI() function.

This table needs the following mandatory fields:

• CALLTYPE: SparkService

• FOLDERNAME: name of folder containing downstream service.

• SERVICENAME: name of downstream service.

• REQUESTBODY: payload for calling downstream service. Must be in JSON format. You can copy the REQUESTBODY from downstream service API tester. If this is your first time using the SparkService we encourage to leave content of request_meta empty. Spark will use the latest version and the default Service Type to execute this service. The request_meta follows the parameters that can be defined in request_meta.

Make sure that FOLDERNAME and SERVICENAME match the uploaded service folder name and service name on Spark

XCall Block Example

REQUESTBODY example (v3 format):

{
    "request_data": {
        "inputs": {
            "InputField": "InputValue"
        }
    },
    "request_meta": {}
}

Response

With Spark Assistant, a user-defined function C.SPARK_UDFCALLAPI([XCallTableRange]) can be defined in an Excel worksheet of the upstream service to receive API response from the downstream service.

• [XCallTableRange] is the location of XCall table in upstream service. e.g. $A$1:$B$4. You can also use a named range for convenience.

• The function must be on the same sheet as the XCallTable.

• The function will return a JSON formatted string with two parts.

  • The first, metadata, contains information about the call to the downstream service such as status, error_code, and response_time.

  • The second, data, contains the response body of the downstream service.

Output of this function in Excel doesn't return the same one as Spark does. You may notice there is a #NAME? error in Excel. We suggest uploading the upstream service to Spark and check real outputs from in the API Tester.

Response from Spark (example):

{
    "metadata": {
        "name": null,
        "calltype": "SparkService",
        "status": "200",
        "error_code": "",
        "response_time": "225"
    },
    "data": {
        "status": "Success",
        "response_data": {
            "outputs": {
                "OutputField": "OutputValue"
            },
            "warnings": [],
            "errors": [],
            "service_chain": []
        },
        "response_meta": {
            "service_id": "166f5109-b01f-4d14-b10d-49669e3489e0",
            "version_id": "52e710a8-9ca1-4ab2-9366-dc304a9eb670",
            "version": "1.0.0",
            "process_time": 4,
            "call_id": "07ea654c-4136-4075-a195-7eaba15391c4",
            "compiler_type": "Type3",
            "compiler_version": "1.0.0",
            "source_hash": null,
            "engine_id": "F0D5B2B02645AAE15F63BABFBF94FBEF",
            "correlation_id": "",
            "system": "SPARK",
            "request_timestamp": "2022-02-28T16:14:25.148Z"
        },
        "error": null
    }
}