---
title: Orchestration SDK connector
description: Configure the Orchestration SDK connector to exchange custom JSON metadata with the Orchestration SDK in your web or native application
component: connectors
page_id: connectors::orchestration_sdk_connector
canonical_url: https://docs.pingidentity.com/connectors/orchestration_sdk_connector.html
llms_txt: https://docs.pingidentity.com/connectors/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2026-11-05T00:00:00Z
section_ids:
  setup: Setup
  requirements: Requirements
  configuring-the-orchestration-sdk-connector: Configuring the Orchestration SDK connector
  using-the-connector-in-a-flow: Using the connector in a flow
  exchanging-custom-metadata-with-your-application: Exchanging custom metadata with your application
  working-with-the-applications-response: Working with the application's response
  limitations: Limitations
  capabilities: Capabilities
  exchangeCustomMetadata: Exchange Custom Metadata with Orchestration SDK
---

# Orchestration SDK connector

The Orchestration SDK connector lets a PingOne DaVinci flow exchange custom JavaScript Object Notation (JSON) *(tooltip: \<div class="paragraph">
\<p>An open, lightweight data-interchange format that uses human-readable text to store and transmit data.\</p>
\</div>)* metadata with the Orchestration SDK embedded in your web or native application. Use it to send instructions or context from a flow to your application and receive structured data back while the flow is running.

When your flow reaches an Orchestration SDK node, flow execution pauses. The node sends the JSON that you configure to the Orchestration SDK client in your application. Your application runs whatever SDK or logic it needs to, such as a device-risk SDK, a payment SDK, or your own internal SDK, then posts a JSON result back to the flow. The flow resumes with the application's result available as node output.

Use the Orchestration SDK connector when your application hosts its own user interface with the Orchestration SDK and you want your flow to orchestrate third-party or custom on-device SDK interactions. For example:

* Run a device-risk or fraud SDK in the application. The flow sends instructions to run the SDK and return a risk score and device ID, then branches to allow, prompt for step-up authentication, or deny based on the results.

* Run a payment or digital-signing SDK and branch on the outcome.

* Run a custom internal enterprise SDK and continue the flow based on its results.

|   |                                                                                                                                                                                                                                                                                                                                                             |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | For internal Ping Identity product SDKs, use their dedicated DaVinci connectors rather than this connector. For example, use the PingOne Verify connector for selfie or document verification, or the PingOne MFA connector for MFA. Learn more in [PingOne Verify connector](p1_verify_connector.html) and [PingOne MFA connector](p1_mfa_connector.html). |

The Orchestration SDK connector works only with flows that run through the Orchestration SDK. Learn more in the [Orchestration SDK documentation](https://developer.pingidentity.com/orchsdks/davinci/index.html).

## Setup

### Requirements

To use the Orchestration SDK connector, you'll need:

* An application that hosts your user experience with the Orchestration SDK, version 2.2.0 or later. Learn more in the [Orchestration SDK documentation](https://developer.pingidentity.com/orchsdks/davinci/index.html).

* A flow invoked through the Orchestration SDK. The connector doesn't work with flows invoked directly in a browser, such as with **Try Flow** or a PingOne flow URL.

### Configuring the Orchestration SDK connector

In PingOne DaVinci, add an **Orchestration SDK** connection. Learn more in [Adding a connector](https://docs.pingidentity.com/davinci/connectors/davinci_adding_a_connector.html).

|   |                                                                                                              |
| - | ------------------------------------------------------------------------------------------------------------ |
|   | This connector doesn't have a configuration at the environment level. You configure it in your flow instead. |

## Using the connector in a flow

The Orchestration SDK connector provides the **Exchange Custom Metadata with Orchestration SDK** capability, which pauses the flow and exchanges JSON with your application.

### Exchanging custom metadata with your application

1. In your flow, add the **Orchestration SDK** connector and select the **Exchange Custom Metadata with Orchestration SDK** capability.

2. In the **Custom Metadata (JSON)** field, enter the JSON to send to your application. This property needs to be a properly formatted JSON value. It can contain DaVinci parameters, which will be replaced at runtime. If you are using DaVinci parameters that are of type `string`, you will need to put string quotes around it.

   For example, include a string parameter in double quotes:

   ```json
   {
     "flowName": "{{global.flowName}}"
   }
   ```

   |   |                                                                                                                                                           |
   | - | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | The flow builder doesn't validate the JSON syntax in the **Custom Metadata (JSON)** field. Ensure the JSON you enter is valid before you deploy the flow. |

   The following example sends instructions to run a device-risk SDK and return the results:

   ```json
   {
     "action": "RUN_DEVICE_RISK_SDK",
     "configs": {
       "returnRiskScore": true,
       "returnDeviceId": true
     }
   }
   ```

   |   |                                                                                                                                                                                                                 |
   | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | You can include values from elsewhere in your flow by clicking **{}**, then selecting the variable that holds the value you want. Click **Switch View** to display the JSON formatted with syntax highlighting. |

3. Click **Apply** to save your changes.

When the flow runs, the JSON you configured is delivered to the `MetadataCollector` in your application. Learn how to handle collectors in your application in the [Orchestration SDK compatibility guide](https://developer.pingidentity.com/orchsdks/davinci/compatibility.html).

### Working with the application's response

After your application finishes running its SDK or logic, it posts a JSON result back to the flow, and the flow resumes.

The application's result JSON is available in the node output:

* Map any property from the result JSON in downstream nodes with the syntax `{{local.<nodeId>.payload.output.<key>}}`, where `<key>` is the property in the application's response. For example, if the application returns `{"riskScore": 20, "deviceId": "abc123"}`, you can map the risk score as `{{local.<nodeId>.payload.output.riskScore}}`.

  To find the node ID, select the node in your flow and view its ID in the node details.

* Any error encountered at this step is captured in the `error` object of the node output.

Your flow can branch on the results, such as routing to allow, step-up, or deny paths based on a risk score.

## Limitations

* The Orchestration SDK connector can only be used in flows that run through the Orchestration SDK.

* Direct browser invocation, such as **Try Flow** or a PingOne flow URL, isn't supported. If the flow reaches an Orchestration SDK node in a browser, a "Screen not supported" message is displayed.

* Don't use the Orchestration SDK connector to terminate a subflow.

## Capabilities

### Exchange Custom Metadata with Orchestration SDK

Exchange custom metadata and payloads between a DaVinci flow and an Orchestration SDK-enabled application. Use this to send instructions or context to the application and receive structured data back during flow execution.

> **Collapse: Show details**
>
> * Properties
>
> * Input Schema
>
> * Output Schema
>
> - Custom Metadata (JSON) textArea required
>
>   This property needs to be a properly formatted JSON value. It can contain DaVinci parameters, which will be replaced at runtime. If you are using DaVinci parameters that are of type 'string', you will need to put string quotes around it.
>
> * default object
>
>   * parameters object
>
>     * eventType string
>
>     * data object
>
>       * actionKey string
>
>       * formData object
>
>         * sdkMetadata object
>
> - output object
>
>   JSON returned by the SDK on resume — keys are defined by the SDK application. On error, the capability throws and DFE surfaces error details at local.\<nodeId>.payload.error (code, message, type), not inside this output object.
