# Introduction to XConnector

`XConnector` is an integration pattern that allows Spark services to interact with external applications or services.

Unlike traditional Spark services, where execution logic is derived directly from an Excel model and compiled into a WebAssembly module, the `XConnector` pattern enables Spark to invoke externally hosted code.

This allows organizations to integrate Spark calculations with existing systems, custom logic, and external data sources while maintaining a consistent API interface through Spark.

It is important to understand that `XConnector` does not execute external code inside the Spark platform. Instead, Spark acts as an integration layer that forwards requests to an external application.

Because of this architecture, `XConnector` follows a shared responsibility model between Coherent and the customer organization.

## `XConnector` as an integration pattern

Traditional Spark services operate as follows:

* Excel workbook → WebAssembly module → Spark API endpoint → Execution within Spark runtime

The `XConnector` integration pattern operates differently:

* Excel workbook (mappings) → Spark API endpoint → Proxy / API gateway → Customer-hosted remote application

In this pattern Spark:

* Defines the API structure.
* Maps inputs and outputs.
* Forwards requests to an external system.

The actual execution logic runs outside of the Spark platform in a remote application. Because execution occurs outside the Spark platform, ownership and operational responsibility for that external code lies with the customer.

## Use cases

`XConnector` is an extremely powerful capability when combined with your existing Spark services. Code written in programming languages (such as [Node.js](https://nodejs.org/) or [Python](https://www.python.org/)) can be executed and have their results returned back to Spark.

Some of our recommended use cases include:

* Provide consistent access to internal and external calculations and/or data for your organization's Spark users in Excel via [Coherent Assistant](https://docs.coherent.global/assistant/).
* Deploy knowledge produced in Excel and Python using consistent API structures.
* Incorporate external data as part of the logic for an existing Spark service.
* Centralize a conditional multiple step process using Spark services that orchestrate other Spark services and external data.

## Architecture and information flow

<figure><img src="/files/dWStXaTqf4Wgq3ePhTD5" alt=""><figcaption></figcaption></figure>

| Component                                                        | Description                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client application                                               | System invoking the Spark API (web app, backend service, Postman, Excel add-in, etc.).                                                                                                                                                                      |
| [#spark-xconnector-service](#spark-xconnector-service "mention") | Spark service that defines inputs, outputs, and configuration for invoking an external service. It facilitates communication between the [#client-application](#client-application "mention") and the [#remote-application](#remote-application "mention"). |
| [#proxy-service](#proxy-service "mention")                       | API gateway or relay service responsible for routing requests to the [#remote-application](#remote-application "mention").                                                                                                                                  |
| [#remote-application](#remote-application "mention")             | External application that executes the logic and returns results.                                                                                                                                                                                           |

1. Client application invokes a Spark API endpoint and sends input data.
2. Spark evaluates the [#spark-xconnector-service](#spark-xconnector-service "mention") configuration associated with the service.
3. Spark constructs an HTTP request containing the input payload and authentication token.
4. Request is sent to the proxy service.
5. [#proxy-service](#proxy-service "mention") validates the request and forwards to the [#remote-application](#remote-application "mention").
6. [#remote-application](#remote-application "mention") processes the request and returns a response.
7. Response is returned through the [#proxy-service](#proxy-service "mention") and Spark back to the client application.

Spark acts as an orchestration layer, while the remote application performs the actual computation.

### Spark `XConnector` service

An `XConnector` service in Spark resembles a standard Spark service but has a different purpose. Instead of executing a WebAssembly module derived from an Excel model, the service is used to:

* Define the input and output schema.
* Configure the remote service endpoint.
* Forward requests to the external service.

The Excel workbook associated with the `XConnector` service is typically used only to define input and output mappings (see [How to: Map inputs and outputs](/build-spark-services/map-inputs-and-outputs.md)) as well as `XConnector` configurations. No computational logic needs to exist in the workbook. From the perspective of a client application, the `XConnector` service behaves like a normal Spark API endpoint.

### Remote application

The remote application is the system that performs the actual computation. It must expose an `HTTPS` endpoint that can:

* Accept JSON input.
* Execute business logic.
* Return JSON output.

Examples of software for the remote service implementations include:

* [AWS Lambda](https://aws.amazon.com/lambda/)
* [Azure Functions](https://azure.microsoft.com/en-us/products/functions)
* &#x20;[Node.js](https://nodejs.org/) or [Python](https://www.python.org/) web services
* Container-based microservices&#x20;
* On-premises HTTP services&#x20;

The remote service is hosted and operated outside the Spark platform.&#x20;

### Proxy service

Although Spark can technically invoke a remote service directly, it is strongly recommended that a proxy or API gateway be placed between Spark and the [#remote-application](#remote-application "mention").

The proxy service provides several important capabilities:&#x20;

* Authentication and authorization validation.
* Token issuer validation.
* Rate limiting and traffic control.
* Request transformation.
* Monitoring and logging.
* Protection of internal infrastructure.

Common proxy implementations include:

* [Amazon API Gateway](https://aws.amazon.com/api-gateway/)
* [Azure API Management](https://azure.microsoft.com/en-us/products/api-management)
* [Google Cloud Apigee API Management](https://cloud.google.com/apigee)
* [Kong Gateway](https://konghq.com/products/kong-gateway)

The proxy service acts as a secure relay between Spark and the remote application.

## Shared responsibilitly model

Because the `XConnector` architecture involves systems outside the Spark platform, responsibilities are divided between Coherent and the customer. Spark provides the integration mechanism, but external systems remain under the customer’s operational control.

| Responsibility area                                                            | Coherent                         | Customer                         |
| ------------------------------------------------------------------------------ | -------------------------------- | -------------------------------- |
| Spark platform                                                                 | :white\_check\_mark: Responsible |                                  |
| Spark API infrastructure                                                       | :white\_check\_mark: Responsible |                                  |
| [#spark-xconnector-service](#spark-xconnector-service "mention") configuration | :white\_check\_mark: Responsible | :white\_check\_mark: Responsible |
| [#proxy-service](#proxy-service "mention")                                     |                                  | :white\_check\_mark: Responsible |
| [#remote-application](#remote-application "mention")                           |                                  | :white\_check\_mark: Responsible |
| Infrastructure hosting remote services                                         |                                  | :white\_check\_mark: Responsible |
| Secrets, API keys, and credentials                                             |                                  | :white\_check\_mark: Responsible |
| Compliance and regulatory controls                                             |                                  | :white\_check\_mark: Responsible |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coherent.global/xconnector/introduction-to-xconnector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.