HTTP Connector

This powerful and versatile connector lets you show custom HTML pages, make REST application programming interface (API) calls, and more in your DaVinci orchestration flow.

Use it to create a custom HTML message, show flow progress, or send custom responses in an API-triggered flow. You can use the messages as quick placeholders to help you sketch out a new flow. If you want to craft a memorable user experience, use the Custom HTML Template capability to create complete HTML pages with your own structure, style, and scripts.

Because this connector allows you to quickly add API calls and user interfaces, it can be a valuable sketching tool in your flow design process or to prove the design for a connector your organization might build.

Setup

Configuring the HTTP connector

In DaVinci, add an HTTP connection. For help, see Adding a connector.

Connector configuration

reCAPTCHA v2 Site Key

The site key provided in your reCAPTCHA dashboard. For help, see Creating reCAPTCHA keys in the Google documentation.

This field is only needed for the connector’s reCAPTCHA capability.

reCAPTCHA v2 Secret Key

The secret key provided in your reCAPTCHA dashboard. For help, see Creating reCAPTCHA keys in the Google documentation.

This field is only needed for the connector’s reCAPTCHA capability.

Select an OpenID token management connection for signed HTTP responses

To add a selection to this list, go to Connections and add a Token Management connector.

This selection is only needed if you want to sign HTTP responses.

Using the connector in a flow

Showing simple messages

If you want to show information to the user, the Custom HTML Message capability gives you a premade page with a title, message, and button. You can’t change the structure, but you can add an icon or style the message with your own CSS. This is useful for error messages and confirmations, such as confirming a user’s registration details.

In your flow, add the HTTP connector and select the Custom HTML Message capability.
Add a Message Title, such as “Welcome”.
Add a Message. You can include values from elsewhere in your flow by clicking {}, then selecting the attribute that holds the value you want.

For this example, insert the username that the user entered into the registration form created by the PingOne Forms connector:
If you don’t want the flow to end here, turn on Show Continue Button and customize the button Display Name.

Building a custom page

The Custom HTML Template capability lets you include an HTML page in your flow. The structure, style, and behavior is entirely up to you.

For creating forms, the PingOne Forms connector provides a drag-and-drop experience builder. Learn more in PingOne Forms Connector and PingOne Forms.

Starting with a template from the UI Studio

To start your custom HTML page, you can autofill its settings from any template you created in the UI Studio. This makes it easy to create several pages from the same template. Keep the following in mind:

If you modify your HTML page in your flow, it won’t affect your original template in the UI Studio.
When you select a UI template from within an HTTP node, it overwrites any work you’ve done in that node. The UI templates are best used for newly-created HTTP nodes.

A screen capture showing the user selecting a UI template.

Adding your own HTML, CSS, and scripts

Your custom page defines the look and behavior of a widget that is powered by React.

Adding custom HTML

The HTML Template field lets you see and modify the HTML for your page.

Click Switch View to see the HTML formatted with syntax highlighting.
Click the Maximize() icon to give yourself more room to work.
To access a variety of useful tools, right-click the field when you’re in syntax highlighting mode (dark background).

For security reasons, the HTML field only allows certain HTML elements. You can find the elements on the allow list in the DOMPurify allow list.

Note that custom HTML elements from the svgDisallowed and mathMlDisallowed lists are not allowed.

These restrictions apply to all custom HTML fields in DaVinci.

+ If you want your HTML to include values from elsewhere in your flow, switch back to the initial view (white background), click {}, and then select the variable that holds the value you want.

+ image::jne1643389462789.gif[alt="A screen capture that shows the user switching the HTML Template field to normal view, then inserting an input variable.",role="border-no-padding",role="border-no-padding"]

The HTML Template field doesn’t support inline events or script tags. See Adding a custom script below.

Adding custom CSS

The CSS field lets you add styles to the HTML page. The contents of the CSS field is appended to the body of the widget. You can use any standard CSS, including @import.

A screen capture of the CSS field with some sample CSS.

Adding a custom script

The Script field allows you to customize the behavior of your page. You can use any standard JavaScript in the Script field.

The HTML Template field doesn’t support inline events or script tags. Instead of triggering events with the HTML, such as with <button onclick="myFunction()">Click me</button>, use the Script field to listen for the event instead.

Example: Triggering a script with a button

In the HTML Template field, add a button.

<h2>JavaScript addEventListener()</h2>

<p>This example uses the addEventListener() method to attach a click event to a button.</p>

<button id="myButton">Try it</button>

<p id="demo"></p>

In the Script field, add an event listener and associate it with the button ID.

//Listen for a click event on 'myButton', then run myFunction
document.getElementById("myButton").addEventListener("click", myFunction);

function myFunction () {
  //Enter your code here, for example:
  document.getElementById("demo").innerHTML = Date();
}

Managing the widget’s states and functions

By default, scripts can’t access the state and functions of the widget that contains the HTML page. To access them, you can use event-based communication between the script and the widget by dispatching JavaScript custom events.

In the Script field, trigger a custom event using the following structure.

const event = new window.CustomEvent('skevent', {
    detail: {
        type: EVENT_TYPE,
        payload: PAYLOAD
    }
})

window.dispatchEvent(event);

The widget has an event listener for skevent, so the widget will catch and process this event. The detail object is designed to match syntax of a standard Redux action object. You can use the following event types:

SET_STATE lets you set a value in the state of the widget:

const event = new window.CustomEvent('skevent', {
    detail: {
        type: 'SET_STATE',
        payload: {
            name: 'email',
            value: 'testuser@example.com'
        }
    }
});

window.dispatchEvent(event);

GET_STATE lets you get a value from the current state of the widget:

const event = new window.CustomEvent('skevent', {
    detail: {
        type: 'GET_STATE',
        payload: 'email'
    }
});

window.dispatchEvent(event);

The GET_STATE event dispatches an event called skeventresponse with the STATE event type. To complete the process, add an event listener to listen for the skeventresponse event:

window.addEventListener('skeventresponse', e => {
    switch(e.detail.type) {
        case 'STATE':
            console.log(e.detail.payload);
            break;
    }
});

The event listener produces the result from the GET_STATE event:

{
  "name": "email",
  "value": "testuser@example.com"
}

Making a REST API call

A screen capture of the complete REST API flow.

You can use the HTTP connector to make a call to any REST API. You can choose the call method (such as GET or POST) and configure query parameters, headers, body, and the responses. This is a flexible way to integrate your flow with external systems.

Best practice is to use secret variables stored in DaVinci > Variables. Learn more in Variables and Creating Variables.

The following example uses the http://deckofcardsapi.com/Deck of Cards API] call to draw five cards, then make the cards available in the flow.

The Deck of Cards API documentation specifies the following URL to draw five cards:

http://deckofcardsapi.com/api/deck/new/draw/?count=5

Getting an API response

Making an API call

In your flow, add the HTTP connector and select the Make REST API Call capability.
In the URL, enter the API URL. In this example, this is http://deckofcardsapi.com/api/deck/new/draw/.
From the HTTP Method list, select the action to take, such as GET.
In the Query Parameters section, add each query parameter and its value. You can include values from elsewhere in your flow by clicking {}, then selecting the variable that holds the value you want. For this example, get five cards every time:
In the MTLS Support list, select a key configured in PingOne to select the client certificate used in outbound mTLS connections.

Keys are configured in PingOne. To create a key in the PingOne admin console, click the Certificates & Keypairs link.

Click Apply to save your changes.

In your own flow, you can use the Headers and Body Parameters sections the same way to add any other parameters you need in your API call, and use the Body list, select the content type of the body data you’re sending to the API.

Working with the API response
1. Following your Make REST API Call node, add an HTTP connector and select the Custom HTML Message capability.
2. In the Message field, click {} and select the rawResponse variable from your Make REST API Call node by clicking (+).
3. Test the flow by clicking Save, Deploy, and Try Flow.
  
  The resulting message shows the card information, including the card value, suit, and an image. Copy this block of text, starting with {"headers"…. You’ll use it in the next step.
Separate the raw response into usable values by defining a response schema:
1. In a browser, open the Online JSON Schema Validator and Generator tool. You’ll use it to generate the JavaScript Object Notation (JSON) schema.
2. Paste the JSON response you copied into the JSON field. Click Generate Schema From JSON. Copy the output from the JSON SCHEMA field.
3. In your Make REST API Call node, paste the JSON schema into the Success Response Schema field.
4. Apply your changes, then go back to your Custom HTML Message node.
5. In your Custom HTML Message node, remove the rawOutput variable that you included in the Message field. Because you added a response schema, you can select specific parts of the JSON response to include in our message. Click {} and select the cards variable:

Capabilities

Send Success JSON Response

Send a successful response.

Show details

Properties
returnRequestParameters toggleSwitch
Additional Fields in the Response selectNameValueListColumn: Use this section to add additional fields to the response
additionalFieldsName textField
Validate the additional properties toggleSwitch: The flow will fail if the validation is failed.
Signed Response toggleSwitch: Sign the response as JWT using your company’s private keys. Signatures can be validated using JWKS public keys in the Company section.
Validity textField: Expiry time in milliseconds. Default is 86400000 (1 day).

Send Error JSON Response

Send an error response.

Show details

Properties
returnRequestParameters toggleSwitch
Additional Fields in the Response selectNameValueListColumn: Use this section to add additional fields to the response
additionalFieldsName textField
Signed Response toggleSwitch: Sign the response as JWT using your company’s private keys. Signatures can be validated using JWKS public keys in the Company section.
Validity textField: Expiry time in milliseconds. Default is 86400000 (1 day).

Send Custom JSON Response

Send a custom response.

Show details

Properties
HTTP Body (JSON) textArea: 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.
httpStatusCode textField
httpHeaders textArea

Custom Html Message

Creates a customizable HTML message.

Show details

Properties

messageTitle textField

Default:

Information

message textArea

Message Icon URL textField

Message Icon Height (in pixels) textField

showFooter toggleSwitch

Submit button

challenge textField

Enable Polling? toggleSwitch

pollInterval textField

Default:

pollRetries textField

Default:

pollChallengeStatus toggleSwitch

showContinueButton toggleSwitch

reCAPTCHA v2 Verification

Verify that you are not a robot and proceed.

Show details

Properties
title textField: Form title.
bodyHeaderText textField: Form body title.
nextButtonText textField

Make REST API Call

Extend the functionality of the DaVinci platform by invoking any third party service.

Show details

Properties

URL textField required

HTTP Method dropDown required

Query Params keyValueList

Headers keyValueList

Body dropDown

Body Params keyValueList

raw codeEditor

Input your raw request body

Success Response Content Type dropdownWithCreate

Content Type of the response data. To apply output schema content type must be application/json

outputSchema codeEditor

Follow example for JSON schema.

Keep API output if the validation failed toggleSwitch

Error Response Content Type dropdownWithCreate

Content Type of the response data. To apply output schema content type must be application/json

outputSchemaError codeEditor

Follow example for JSON schema.

MTLS Support dropDown

Select the client certificate used to make outbound mTLS connections.

None (Default)

Ignore TLS Errors toggleSwitch

When enabled, the connector ignores TLS errors. Use this for testing in non-production environments.

Timeout (ms) textField

Timeout for API call. Leave blank to not have timeout.

Output Schema
output object
rawResponse object
properties object
statusCode integer
body array/object/number/string/boolean
headers array

Custom HTML Template

Create an HTML page using this customizable template.

Show details

Properties
HTML Source dropDown: Select the source of the HTML content
Template
HTML Template textArea
CDN Hostname textField: Enter the CDN that hosts the HTML you would like to use. The CDN domain must be listed in the Trusted Sites under the connector settings.
Use Recaptcha Verification toggleSwitch: Add sk-component skrecaptcha to use this feature.
Form validation rules validationRules: Rules to check to validate form inputs
CSS codeEditor
Script codeEditor: Write custom JavaScript. Caution: Custom code is for advanced users only. Before using custom code, review the security risks in the DaVinci documentation by searching for "Using custom code safely".
inputSchema codeEditor: Follow example for JSON schema.
outputSchema codeEditor: Follow example for JSON schema.
formFieldsList formFieldsList
challenge textField
Output Schema
output object
formFieldsList object

Create QR Code for URL

Create a QR code that contains a URL.

Show details

Properties
URL textField required
Input Schema
default object
customUrl string required minLength: 0 maxLength: 400: Custom URL to create the QR Code

Output Schema
output object
generatedQr string

Continue Polling

Use this capability in conjunction with Polling in Custom HTTP capabilities.

Show details

Properties
Node ID of the UI node (Optional) textField: In advanced scenarios, it might be required to specify the Node ID of the UI node where polling in enabled. When a Node ID is not entered (default behavior), polling will continue on the current UI node.

Simulate Latency

Send a response with latency.

Show details

Properties

Delay Time (ms) textField

Time to wait for response to be sent in milliseconds. Default: 50

Default:

Return Success Response toggleSwitch

Return success or failure response

HTTP Body (JSON) textArea

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.

Output Schema
output object
type object
example

Connectors

HTTP Connector

Setup

Configuring the HTTP connector

Connector configuration

reCAPTCHA v2 Site Key

reCAPTCHA v2 Secret Key

Select an OpenID token management connection for signed HTTP responses

Using the connector in a flow

Showing simple messages

Building a custom page

Starting with a template from the UI Studio

Adding your own HTML, CSS, and scripts

Adding custom HTML

Adding custom CSS

Example: Triggering a script with a button

Managing the widget’s states and functions

Making a REST API call

Getting an API response

Capabilities

Send Success JSON Response

Send Error JSON Response

Send Custom JSON Response

Custom Html Message

reCAPTCHA v2 Verification

Make REST API Call

Custom HTML Template

Create QR Code for URL

Continue Polling

Simulate Latency