Skip to main content
Version: 4.15.1

Try It Yourself

Welcome! It's great to see you in our Academy to try Dovetail yourself. The goal of this course is to familiarize yourself with our no code integration platform to enable you to built your own integrations.

This introduction is divided into two parts:

  • In the Demo Examples section you'll find all the information to guide you through the predefined examples that are already in your Dovetail demo environment. You'll learn your way around the interface, the components and basic integration patterns.
  • In the Build Your First Flow section you'll be guided through the process of building your first integration, or as we call it, flow.

Don't hesitate to contact us if you have any questions or remarks.

Enjoy!

The Dovetail team

Demo Examples​

Goal & Requirements​

The goals is to have a first look at Dovetail to:

  • Familiarize yourself with the application and interface
  • Get an idea of how a messaging system works
  • Show you how to build integrations with it

Learning objectives​

  • Introduction into the Flow Manager and Flow Designer
  • The concept of no code and interactions between components
  • Making minor adjustments to existing flows and observing the results
  • How to use the Dovetail Academy for documentation
  • The concept of a Messaging system, especially HTTP calls

Requirements​

  • Your Dovetail demo account with the examples
  • About 1 hour of your time

Important!
Syntax is highligted in codes blocks in this guide. You can hover over a code block and in the top right corner a copy icon will appear. Whenever you copy anything out of this guide into Dovetail verify there are no extra characters or spaces in the field.

Example: Hover over me!

1.GetCountryInfo example​

You will get a first view of the Dovetail interface and the way no code integration works. You'll be able to 'kick off' a flow, see the result, familiarize yourself with basic components and their functionality at each step of the flow.

Make sure you are logged in to your Dovetail demo account and navigate to the Flow Designer. The video below guides you through the example and additional details or remarks can be found in the guide underneath the video.

Flow description​

This example flow uses country ISO codes (Alpha-2) to get a Country's Capital and Name. It uses an open data source, you can find the full reference here.

If you have no backgound / basic knowledge of HTTP requests, please read the Reference about HTTP calls first and then return here. If are familiar with HTTP you can continue below.

Using this Flow​

The InboundHttp component is waiting for a message to start the flow. You send this message by visiting the link in the Notes tab in the Flow Designer.

Start this Example with the URL in the Flow Notes

When you follow the link you get an XML with data as a response, in this case data belonging to the country ISO code NL, the Netherlands. You can tell because after the ? in the url we are sending along two values:

apikey=622ef10d704e83f1c3000597
country=NL

Changing NL to any other existing ISO code will return its corresponding data. Try it!

What are the components doing?​

There are a few ways to get information about how this flow is functioning.

Go to the Route tab and:

  • Mouse-over the individual components to get a quick explanation
  • Click the Note icon above a component to see it's full notes
  • Click the Gear icon of a component to see its settings
    • Want to learn more about a component?
      Click the Blue info icon in the component settings to go to its documentation in the Dovetail Academy

Can you figure out how the components are interacting to produce the desired goal of retrieving a country's capital and name from its ISO code?

2.GetCountryFlag example​

You will look at an example flow and determine how it is functioning. With the Flow Manager's logs and transactions in your toolbox to analyse the state of a message while it flows through the integration.

The video below guides you through the example and additional details or remarks can be found in the guide underneath the video.

Flow description​

This example flow uses country ISO codes (Alpha-2) to get a Country's Flag. It uses an open data source, you can find the full reference here.

Using this Flow​

The InboundHttp component is waiting for a message to start the flow. We are going to built up the link to this flow with the parameters ourselves:

  1. Open the InboundHttp component, scroll down and copy the Test URL into your browser
  2. Append (add) the paramaters below to the URL you've just pasted into your browser
?apikey=622ef10d704e83f1c3000597&country=NL

If you follow the link you get a picture of the flag as a response, in this case the Dutch flag. Changing NL to any other existing ISO code will return the corresponding flag. Try it!

What are the components doing?​

There are a few ways to get information about how this flow is functioning.

Go to the Route tab and:

  • Mouse-over the individual components to get a quick explanation
  • Click the Note icon above a component to see it's full notes
  • Click the Gear icon of a component to see its settings
    • Want to learn more about a component?
      Click the Blue info icon in the component settings to go to its documentation in the Dovetail Academy

Go to the Flow Manager in the menu bar to get information about installed flows. See the Flow Manager reference in this guide.

  • Click on 2.GetCountryFlag and go to the Transactions tab

Can you figure out how the components are interacting to produce the desired goal of retrieving a country's flag from its ISO code?

Tip:
Use Transactions to see the header(s) and body at each step.

Explanation​

Examine the transactions for this flow. In this example you can see that the link to the flag is embedded in the JSON that the first HTTP request gets. Click the component after the HttpComponent (in this case RemoveHeaders Component) to see the state of the message after the HTTP operation. The flag url is a JSON element called sCountryFlag as you can see. After the conversion to XML we use XPath to set the flag url to a header. At the 2nd HttpComponent transactions you see this in the headers, this url is then used to request the flag's image.

3.GetCountryLanguages example​

You will look at an example flow and do a more in-depth analyses of how the data is being processed within the integration. The video below guides you through the example and additional details or remarks can be found in the guide underneath the video.

Flow description​

This example flow uses country ISO codes (Alpha-2) to get the Country's Language(s). It uses an open data source, you can find the full reference here.

Using this Flow​

The inbound http component is waiting for a message to start the flow. We are going to built up the link to this flow with the parameters ourselves:

  1. Open the InboundHttp component, scroll down and copy the Test URL into your browser
  2. Append (add) the paramaters below to the URL you've just pasted into your browser
?apikey=622ef10d704e83f1c3000597&country=NL

Follow the link to get a list of languages as a response, in this case Dutch and Frysian. Changing NL to any other existing ISO code will return the corresponding language list. Try it!

What are the components doing?​

There are a few ways to get information about how this flow is functioning.

Go to the Route tab and:

  • Mouse-over the individual components to get a quick explanation
  • Click the Note icon above a component to see it's full notes
  • Click the Gear icon of a component to see its settings
    • Want to learn more about a component?
      Click the Blue info icon in the component settings to go to its documentation in the Dovetail Academy

Go to the Flow Manager in the menu bar to get information about installed flows. See the Flow Manager reference in this guide.

  • Click on 3.GetCountryLanguages and go to the Transactions tab

Reset the ISO code to a country that returns at least two languages, i.e. NL. Can you figure out how the components are interacting to substract multiple languages from the same language element in the response?

Tip:
Use the Log to see the contents of the body at log components.
Use Transactions to see the header(s) and body at each step.

Explanation​

Examine the transactions for this flow. In this example you can see that country language are all in an element called Languages in the JSON response from the HTTP request. The SplitComponent uses XPath to split the multiple languages. Every language 'set' is sent through the bottom of the split component and then aggregates them again. Result: an array with the country's languages in a JSON array.

Build Your First Flow​

Goal & Requirements​

Build your first flow that retrieves data from an API with movies that are on Dutch TV today (Filmtotaal API) and enrich the response with data from another movie database (OMDB API).

Learning objectives​

  • Applying the concept of requests & responses, body & messages in a real world example
  • Using the Flow Designer to create, build and install flows
  • Using the Flow Manager for status information and debugging
  • Authenticating & Connecting with API's and reading their references
  • Getting to know useful tools, techniques and references

Requirements​

  • Your Dovetail demo account
  • API key from filmtotaal.nl (dvfrbql1qvltlvyed4y7a9cwx64vfzjs)
  • API key from OMDB, the OpenMovieDataBase (6ef8ad67)
  • Postman (A tool to create requests, download)
  • Visual Studio Code (A powerful text editor, download)
  • About 2 hours of your time

Important!
Syntax is highligted in codes blocks in this guide. You can hover over a code block and in the top right corner a copy icon will appear. Whenever you copy anything out of this guide into Dovetail verify there are no extra characters or spaces in the field.

Example: Hover over me!

Hello World!​

You will learn how to setup and connect to Dovetail by sending the classic coding example "Hello World" to it. Please follow along with the instruction video below in your own demo environment. Make sure you are logged in to your Dovetail demo account and have Postman available (download).

Resources & References​

Headers, Variables & Authorization​

Now it's time to introduce you to variables and headers in Dovetail. We'll use them to add a layer of security so this flow can't be connected to by anyone that guesses your inbound HTTP url.

Syntax & Expressions​

#{self.flow_name}
#{self.flow_id}
${header.Authorization}
'#{self.flow_id}' == '${header.Authorization}'

Resources & References​

Flow Manager - Transactions​

Sometimes something doesn't work the way you expect, you are debugging or you are curious about the state of your flow at a specific point? Transactions show the body and headers between the Dovetail components. We'll use the same flow as in the previous section.

Important!
Look at the next component if you want to see how the component before it 'interacted' with the message.

Resources & References​

Your first API call​

Let's connect to the Filmtotaal API now to retrieve an XML with information about the movies on Dutch TV today. Make sure you've got the Filmtotaal API key at hand (dvfrbql1qvltlvyed4y7a9cwx64vfzjs).

Syntax & Expressions​

${date-with-timezone:now:Europe/Amsterdam:dd-MM-yyyy}
#{Filmtotaal_url}?apikey=${header.FT_apikey}&dag=${header.day}&sorteer=${header.sort}
${header.dynamicURL}

Resources & References​

Splitting XML's​

Now it's time to show you how you can get the data in the <film> element in separate 'blocks' so we can process individual movie data later. We are going to learn a technique called XPath for this and then show you how it's done in Dovetail. We'll continue where we left in the section Your first API call.

Syntax & Expressions​

//*:filmsoptv/*:film

Resources & References​

Get Movie Title​

In this section we are going to put the separate movie titles after the split and put them on a header. We can send them along as a parameter to the OMDB database later to retrieve more movie data from that database (OMDB reference). We are going to use the XML file with the list of movies as retrieved in Your first API call.

Syntax & Expressions​

//*:film/*:titel
${bodyAs(String)}

Resources & References​

API call OMDB​

Now it's time to use each movie title from the Filmtotaal response to make a call on the Open Movie Data Base (OMDB API key: 6ef8ad67).

Syntax & Expressions​

#{OMDB_url}/?apikey=${header.OMDB_apikey}&t=${header.title}

Resources & References​

Filter, ContentRouter & Enrich component​

In this section we'll show you how you can use the Filter, ContentRouter and Enrich component. The Filter and ContentRouter are two components that are used to guide the direction of messages in your flow. The Enrich component can be used to combine data from the Filmtotaal database with the response from the OMDB database.

Syntax & Expressions​

${bodyAs(String)} not contains 'unable_to_access'
${bodyAs(String)} not contains 'Movie not found!'
${bodyAs(String)} contains 'Movie not found!'
${header.body}

Resources & References​

Using XSLT​

The last technique we would like to introduce you to is XSLT. Often you want to 'translate' an element in a source XML to an element with another name or format in a target XML. We call this mapping and use XSLT for this. Here you can download the XSLT file that was built with MapForce to use in your flow.

Syntax & Expressions​

breadcrumbId

Resources & References​

References​

HTTP calls​

Requests are used to retrieve data from a source. The source can be an endpoint like a REST-API, SQL database or FTP server. A request has a request-line, zero or more header(s) and optionally a body.

If you use the analogy of a letter:

  • Request-line; address on the enveloppe: The endpoint to sent the request to, the action to perform and the protocol used
  • Header(s); other metadata on the enveloppe: Name, Return address, Stamp to validate access to the postal service, etc.
  • Body; the letter itself: The main message, often in a data format like XML or JSON

HTTP Request​

The Demo examples in this guide use an open data source with data about countries. The reference for this data source has a clear description of how to build a HTTP request for it (scroll to the bottom of the page, see the first yellow block):

POST /websamples.countryinfo/CountryInfoService.wso HTTP/1.1
Host: webservices.oorsprong.org
Content-Type: application/json; charset=utf-8
Content-Length: length
{
  "sCountryISOCode": string
}
Request-line​
POST /websamples.countryinfo/CountryInfoService.wso HTTP/1.1
  • Action to perform (POST)
  • Specific location of the endpoint (/websamples...)
  • Protocol (HTTP/1.1)
Host: webservices.oorsprong.org
  • Url of the endpoint you want to communicate with
Header(s)​
Content-Type: application/json; charset=utf-8
  • The type of content in the body
Content-Length

  • The length of the content in the body

Body​
{  
  "sCountryISOCode": string  
}
  • Message itself, the syntax with the brackets is JSON, a data format

HTTP Response​

The second yellow block shows you the HTTP response after a succesfull request. Here you'll recognise the same structure as in the request. Instead of a request-line you find a status-line with a status code (200 OK means Succes). Filled with data it could look like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: length

{
    "sISOCode": string
    "sName": string
    "sCapitalCity": string
    "sPhoneCode": string
    "sContinentCode": string
    "sCurrencyISOCode": string
    "sCountryFlag": string
    "Languages": [
        {
        "sISOCode": string
        "sName": string
        },
        {
        "sISOCode": string
        "sName": string
        }
    ]
}

You see the same headers and a body (in JSON) that can hold data in its elements. According to your goal you can use any of this data to your advantage.

Flow Manager​

The Flow Manager shows an overview with information about flow(s), grouped by folder. See the Flow Manager page for more information in the Dovetail Academy.

It's divided with tabs between the Test and Production environment. The Example flows are installed in the Test environment. Click on a flow to go to it's Details, Log and Transactions (log per component).

Details​

An overview with the information regarding the flow. See the Flow Details page in the Dovetail Academy for more information.

Log​

Log with information about the flow. Important: Data that entered the Log component in your flows is also shown here.
See the Flow Logging page in the Dovetail Academy for more information.

  • Info i.e. Data from Log components, information about the flow starting up, etc.
  • Warnings i.e. Timeouts: an action was not completed because it took too long
  • Errors i.e. 404 not found, 401 Authorization required, etc.

Transactions​

Gives feedback about what the flow is doing on component level. It shows data of headers and the body at each step. See the Flow Tracing page in the Dovetail Academy for more information.