This powerful and versatile connector lets you create forms, show custom HTML pages, make REST API calls, and more in your DaVinci orchestration flow.
Use it to create a sign-on page, show flow progress, or send custom responses in an API-triggered flow. You can use the simple forms and messages as quick placeholders to help you sketch out a new flow, and 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 name that the user entered into the registration form:
- 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.
- 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.
- 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.
Tip:- 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).
Important:For security reasons, not every attribute is allowed. We use a
DOMPurify
library to mitigate accidental vulnerabilities, such as XSS attacks.For a list of allow listed elements, see the current DOMPurify allow list, ignoring the
svgDisallowed
andmathMlDisallowed
lists. The allow listed elements also 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.
Important: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.
- 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.
Important: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 calledskeventresponse
with theSTATE
event type. To complete the process, add an event listener to listen for theskeventresponse
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
The following example uses the 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.Note: 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.Note: 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
- Following your Make REST API Call node, add an HTTP connector and select the Custom HTML Message capability.
- In the Message field, click {} and select the rawResponse variable from your Make REST API Call node by clicking (+).
- 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:
- In a browser, open the Online JSON Schema Validator and Generator tool. You'll use it to generate the JSON schema.
- Paste the JSON response you copied into the JSON field. Click Generate Schema From JSON. Copy the output from the JSON SCHEMA field.
- In your Make REST API Call node, paste the JSON schema into the Success Response Schema field.
- Apply your changes, then go back to your Custom HTML Message node.
- 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:
- Making an API call
Capabilities
- Send Success JSON Response
-
Send a successful response.
Details - Send Error JSON Response
-
Send an error response.
Details - Send Custom JSON Response
-
Send a custom response.
Details - Custom Html Message
-
Creates a customizable HTML message.
Details - HTML Form
-
Presents a form for users to complete.
Details - HTML Form with reCAPTCHA v2 Checkbox
-
Presents a checkbox on the HTML form.
Details - reCAPTCHA v2 Verification
-
Verify that you are not a robot and proceed.
Details - Make REST API Call
-
Extend the functionality of the DaVinci platform by invoking any third party service.
Details - Custom HTML Template
-
Create an HTML page using this customizable template.
Details - Create QR Code for URL
-
Create a QR code that contains a URL.
Details - Continue Polling
-
Use this capability in conjunction with Polling in Custom HTTP capabilities.
Details - Simulate Latency
-
Send a response with latency.
Details