External URL & Webhook

Learning Points

• How to get data from external APIs

• How to provide other applications with real-time information through webhook

Covered Areas

• Constant

• Template

• External URL in Page Data Source

• Workflow Webhook

Overview

1. Constant

1.1 General Information

• Constant is created at app-level.

• Set of Constants can be used in Template, External URL and Webhook. Both Authentication and Data Request are supported.

• Set of Constants can be used in:

  • • • URL Editor

      • Key Value Pair of Query, Header and Content

• For any Constant created, the Constant ID must fulfill the following rules:

  • • • Cannot be empty

      • Must be unique (case insensitive)

      • Only A-Z, a-z, 0-9, -, _ are allowed

      • Cannot start or end with “-”

      • No space is allowed

      • 20 characters max.

• Values of Constants will not be brought to other environment(s) through deployment and users can edit and encrypt the value of Constants in other environment(s), unless it is locked in the developing environment.

• The value of Constant can be encrypted. The action of encryption is not reversible, that means it cannot be decrypted and shown in plain text after encrypted.

1.2 Detailed Steps

1. At App Management > Developing Environment, on the side menu, click External URL Template.

2. Go to the tab ‘Constant’.

3. Click the ‘+’ button to create a new constant.

4. Fill in the Constant ID and Value, then click '' to confirm.

2. Template

2.1 General Information

• Templates are created at app-level.

• Templates can be used while setting up External URL Data Source in pages or Webhooks in workflows.

2.2 Detailed Steps

1. At App Management > Developing Environment, on the side menu, click External URL Template.

2. Go to the tab ‘Template’, click the ‘+’ button to create a new template.

3. Fill in the ‘TEMPLATE NAME’.

4. In the 1st step ‘Authentication’, you may select the way of Authorization and set it up if needed, then click ‘Continue’. (You may go to Step.5 directly if ‘No Authorization’ is selected.)

a. For OAuth authorization, click ‘Set Up’ to open the URL Editor.

b. Click ‘+ URL Setting’ and setup the URL of authentication, then click ‘OK’

• There is a preview for the URL after adding a component.

• URL Editor supports the following components:

c. Set ‘Timeout (s)’ and ‘Token Key’.

• Input the name of the returned token key and the key value will be stored to the System Variable ‘$OToken’.

• If there are no values returned within the Timeout set, Dragonce will retry to get the value again.

d. Input Key Value Pair for Query, Header and Content, then click ‘Continue’.

• Query is using “GET method”, and that for Content is “POST method”.

• Value can be encrypted in design time for data protection. The action of encryption is not reversible, that means it cannot be decrypted and shown in plain text after encrypted.

• The Key Value Pair supports the following components:

5. In the 2nd step ‘Data Request’, click ‘Set Up’ to set up the URL.

6. Set up the URL, then click ‘OK’.

URL Editor supports the following components:

7. Input Timeout and Key and Value for Query, Header, and Content, then Click ‘Continue’.

• Query is using “GET method”, and that for Content is “POST method”.

• Value can be encrypted in design time for data protection. The action of encryption is not reversible, that means it cannot be decrypted and shown in plain text after encrypted.

• The Key Value Pair supports the following components:

8. In the 3rd step ‘Data Format’, input ‘Data Key’. Select the ‘Data Type’ and click ‘Continue’.

• The External URL only supports JSON format as return.

• The Data Type refers to the widget type of Dragonce.

• Click the ‘Required’ checkbox to do checking on the returns.

9. In the 4th step ‘Error Handling’, enter the number of Retry Count. You may skip the error checking or customize the error messages for each error type. 

• Retry Count is applicable to both OAuth and Data Request.

• Error handling is available for the following error types:

10. Click ‘Test’ to perform testing on the settings.

11. Click ‘Start’ to try to retrieve data through API calls.

12. Close the window after successful retrieval of values.

13. Click ‘Finish’ to complete the settings.

3. External URL in Page Data Source

3.1 Detailed Steps

1. In the Page Builder, click the ‘Page Data Source’ icon.

2. Click ‘Add Data Source’.

3. In the 1st step ‘Data Source’, input the name of Label and choose ‘External URL’ for Data Source.

4. Click ‘Set Up’ next to the Data Source.

5. Select any pre-built template to copy.

• Settings from the selected template will overwrite the current settings.

6. If you want to create a new setting instead of using template, please go back to 2. Template > 2.2 Detailed Steps > Step.4-13.

[Caution: All request parameters set in ‘External URL’ will be considered as Required.]

7. Click ‘Continue’.

8. In the 2nd step ‘Record Filter’, click ‘Continue’.

9. In the 3rd step ‘Mapping’, mouse over the ‘Current Page Widget’ to map source data widget with widgets on the page.

10. Click the ‘Finish’ button to complete the setup.

4. Workflow Webhooks

4.1 Detailed Steps

1. In the Workflow Builder, click the ‘Workflow Webhook’ icon.

2. Click ‘+ New Generation’.

3. Click ‘Webhook Settings’.

4. Select any pre-built template to copy.

Settings from the selected template will overwrite the current settings.

5. If you want to create a new setting instead of using template, please go back to 2. Template > 2.2 Detailed Steps > Step.4-8.

[Caution: All request parameters set in ‘Webhook’ will be considered as Optional.]

a. In the 4th step ‘Error Handling’, enter the number of Retry Count, decide whether to pass hard code value to current form widget when there is an error  i.e. Network Error / Empty Response / Missing Token / No Value for Constant / Data Key Error. Then, click ‘Finish’.

6. After setting up the URL and adding the data, mouse over the ‘Current Page Widget(s)’ to map data with widgets of Dragonce.

7. Click the ‘Submit’ button to complete the setup.

Real Life Example

This is the weather forecast that we would like to get from ‘Yahoo! Weather API’. 

Run time result:

The example below shows part of the returned JSON from the API. (some data is omitted)

{

"query":{

"count":1,

"created":"2018-07-11T12:41:27Z",

"lang":"en-US",

"results":{

"channel":{

"description":"Yahoo! Weather for Hong Kong, HK",

"language":"en-us",

"lastBuildDate":"Wed, 11 Jul 2018 08:41 PM HKT",

"ttl":"60",

"location":{

"city":"Hong Kong",

"country":"Hong Kong",

"region":" HK"

},

"wind":{

"chill":"86",

"direction":"195",

"speed":"14"

},

"atmosphere":{

"humidity":"68",

"pressure":"994.0",

"rising":"0",

"visibility":"16.1"

},

"astronomy":{

"sunrise":"5:47 am",

"sunset":"7:11 pm"

},

"image":{

"title":"Yahoo! Weather",

"width":"142",

"height":"18",

"link":"http://weather.yahoo.com",

"url":"http://l.yimg.com/a/i/brand/purplelogo//uh/us/news-wea.gif"

},

"item":{

"title":"Conditions for Hong Kong, HK at 08:00 PM HKT",

"lat":"22.283319",

"long":"114.158722",

"link":"http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-2165352/",

"pubDate":"Wed, 11 Jul 2018 08:00 PM HKT",

"condition":{

"code":"26",

"date":"Wed, 11 Jul 2018 08:00 PM HKT",

"temp":"87",

"text":"Cloudy"

},

"forecast":[

{

"code":"30",

"date":"11 Jul 2018",

"day":"Wed",

"high":"90",

"low":"81",

"text":"Partly Cloudy"

},

{

"code":"4",

"date":"12 Jul 2018",

"day":"Thu",

"high":"87",

"low":"83",

"text":"Thunderstorms"

},

{

"code":"4",

"date":"13 Jul 2018",

"day":"Fri",

"high":"85",

"low":"81",

"text":"Thunderstorms"

},

{

"code":"4",

"date":"14 Jul 2018",

"day":"Sat",

"high":"84",

"low":"81",

"text":"Thunderstorms"

},

{

"code":"47",

"date":"15 Jul 2018",

"day":"Sun",

"high":"85",

"low":"82",

"text":"Scattered Thunderstorms"

},

],

}

}

}

}

}

Detailed Steps

1. Build the page with the following configurations.

2. In the Page Builder, click the ‘Page Data Source’ icon.

3. Click ‘Add Data Source’.

4. In the 1st step ‘Data Source’, input ‘HK Weather’ as the name of Label and choose ‘External URL’ for Data Source.

5. Click ‘Set Up’ next to the Data Source.

6. In the 1st step ‘Authentication’, click ‘Continue’.

7. In the 2nd step ‘Data Request’, click ‘Set Up’ to set up the URL.

8. Click ‘+ URL Setting’ to add a new URL.

9. Copy this link: 

https://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20weather.forecast%20where%20woeid%20in%20(select%20woeid%20from%20geo.places(1)%20where%20text%3D%22hong%20kong%2C%20hong%20kong%22)&format=json&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys  

and paste it as Text and click ‘Apply’ to confirm. Then, click ‘OK’ 

10. Click ‘Continue’.

11. In the 3rd step ‘Data Format’, click ‘+ Key Value Pair’ to add new Data Key and corresponding Data Type.

12. Fill in the Data Key and select corresponding Data Type following the table below:

13. Click ‘Continue’.

14. In the 4th step ‘Error Handling’, click  ‘Test’ to perform testing on the settings.

15. Click ‘Start’ to try to retrieve data through API call.

16. Close the window after successful retrieval of values.