> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/xconnector/introduction-to-xconnector.md). # 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
| 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) * [Node.js](https://nodejs.org/) or [Python](https://www.python.org/) web services * Container-based microservices * On-premises HTTP services The remote service is hosted and operated outside the Spark platform. ### 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: * 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 |