How to: Upload Spark service files via API

To upload and publish a service to a new environment, we recommend using the following 3 step process:

1. Upload Excel file to Spark

2. Check compilation status

3. Publish service

This guide walks through how to use the 3 APIs together. All 3 APIs are necessary to create a new service. This guide uses Postman to interact with the APIs, but you can use any tool you like.

Authorization

• Bearer {token} accessible from Authorization - Bearer token or systematically via Client Credentials.

  • The request headers should include a key for Authorization with the value Bearer {token}.

• API key created from Authorization - API keys. The API key groups must contain User groups that are also assigned to Permissions - Features permissions Spark.ServiceUpload.json, Spark.ServiceCompilationProgress.json, and Spark.ServicePublish.json or just Spark.AllEncompassingProxy.json.

  • The request headers should include the keys x-synthetic-key and x-tenant-name with the API key and tenant name respectively.

Upload Spark service files

Request

1. Setup a POST request to https://excel.{environment}.coherent.global/{tenant}/api/v3/folders/{folder}/services/{service}/upload.

   • {folder} and {service} should represent the target destination for the uploaded service.

2. Setup the request headers for the API call.

   • Include the necessary Authorization.

   • Note that the Content-Type should be multpart/form-data.

   • Postman may automatically create some headers for you.

3. For the request body:

   1. Create the serviceFile key and change the key type to File. Then you can select the Excel file you want to upload.

      
   2. Enter the values for engineUploadRequestEntity as described below. For information about customizing the values, see Upload Excel file to Spark. These values are placeholders as they will be updated in Publish service.

      {
          "request_data":
              {
                  "version_difference":"minor",
                  "effective_start_date":"2010-01-01",
                  "effective_end_date":"2120-01-01"
              }
      }

4. Send the API call. Spark will inform you if the service name already exists.

Response

HTTP 200 OK Content-Type: application/json

The success response should look similar to the output below. Take note of the nodegen_compilation_jobid, original_file_documentid, and engine_file_documentid as this information is needed for the subsequent steps.

{
    "status": "Success",
    "response_data": {
        "lines_of_code": 11.0,
        "hours_saved": 0.02107043788185858,
        "nodegen_compilation_jobid": "19bd64d6-f567-0bd4-c73f-190ed4bc49c3",
        "original_file_documentid": "265ddaee-89b9-42ff-96af-3cf08ceaf344",
        "engine_file_documentid": "f15269d5-0104-4269-8c46-ba5996b5b1c4",
        "hash_signature_chain": false,
        "warnings": [],
        "infos": [],
        "current_statistics": null,
        "no_of_sheets": 1,
        "no_of_inputs": 2,
        "no_of_outputs": 1,
        "no_of_formulas": 1,
        "no_of_cellswithdata": 15
    },
    "response_meta": {
        "service_id": null,
        "version_id": "b4555085-1535-4058-8335-212216c89044",
        "version": "0.1.0",
        "process_time": 1138,
        "call_id": null,
        "compiler_type": "Neuron",
        "compiler_version": null,
        "source_hash": null,
        "engine_id": null,
        "correlation_id": null,
        "parameterset_version_id": null,
        "system": "SPARK",
        "request_timestamp": "2026-01-19T12:49:16.092Z"
    },
    "error": null
}

Check compilation status

After the Excel file is uploaded, the file is converted from Excel to code using the Neuron compiler. It's important to check the status of the compilation to ensure that the job completed successfully before the service can be published. We'll use the following API to do so.

Request

1. Setup a GET request to https://excel.{environment}.coherent.global/{tenant}/api/v3/folders/{folder}/services/{service}/getcompilationprogess/{nodegen_compilation_job_id}.

   • {folder} and {service} should represent the target destination for the uploaded service. This should be the same as the previous API call.

2. {nodegen_compilation_job_id} can be found from Upload Spark service files Response.

3. Setup the request headers for the API call.

   • Include the necessary Authorization.

   • Postman may automatically create some headers for you.

4. Send the API call.

Response

HTTP 200 OK Content-Type: application/json

If the progress is 100, the compilation has completed.

{
    "status": "Success",
    "response_data": {
        "status": "Success",
        "last_error_message": "null",
        "progress": 100
    },
    "response_meta": {
        "system": "SPARK",
        "request_timestamp": "2023-05-19T01:39:42.074Z"
    },
    "error": null
}

Publish service

Once the compilation was successful, we can publish the uploaded service.

Request

The success response should look similar to the output below. Take note of the nodegen_compilation_jobid, original_file_documentid, and engine_file_documentid as this information is needed for the subsequent steps.

1. Setup a POST request to https://excel.{environment}.coherent.global/{tenant}/api/v3/folders/{folder}/services/{service}/publish.

   • {folder} and {service} should represent the target destination for the uploaded service. This should be the same as the previous API calls.

2. Setup the request headers for the API call.

   • Include the necessary Authorization.

   • Note that the Content-Type should be application/json.

   • Postman may automatically create some headers for you.

3. For the request body, use the JSON below and complete the following parameters:

   1. Replace {service} with the name used and previous steps.

   2. Replace {original_file_documentid} and {engine_file_document_id} with the values returned from Upload Spark service files Response.

   3. For information about customizing the values, see Upload Excel file to Spark.{

      {
        "request_data": {
          "draft_service_name": "my service name",
          "version_label": "my service label",
          "effective_start_date": "2024-01-19T12:12:00.000Z",
          "effective_end_date": "2126-01-19T12:12:00.000Z",
          "original_file_documentid": "265ddaee-89b9-42ff-96af-3cf08ceaf344",
          "engine_file_documentid": "f15269d5-0104-4269-8c46-ba5996b5b1c4",
          "version_difference": "minor",
          "release_note": "my release note",
          "description": "my description",
          "should_trck_user_action": "true"
        }
      }

4. Send the API call.

Response

HTTP 200 OK Content-Type: application/json

The service is now published!

{
    "status": "Success",
    "response_data": {
        "version_id": "{version_id}"
    },
    "response_meta": {
        "system": "SPARK",
        "request_timestamp": "2023-05-18T21:20:42.498Z"
    },
    "error": null
}