URL Merge Condition Example

This tutorial shows how to use URL Merge Conditions to limit the data returned by your REST models. In this example, we’re going to use to show the local time for a given Account based on its latitude and longitude.

For this example, we’re using a free web service called Geonames.

Before you begin, you’ll need to create an account here.

Step 0: Set up your REST data source.

  1. Navigate to Configure > Data Sources > Data Sources.
  2. Click New Data Source.
  3. Select REST for the Data Source Type.
  4. Enter a unique name.
  5. Click Next Step.
  6. Enter the following URL: http://api.geonames.org

The Geonames service requires your username be sent with every request. To do this, add your username as a URL parameter.

  1. Click URL Parameters to send with every request to expand the section.
  2. Click the first row’s box, and click Append.
  3. Create the parameter:
    • Field: username
    • Value: Your Geonames username

Finally, click Save.

Step 1: Compose a new page, or open a previously built page.

image1

For this example, we’re going to use an Account Detail page.

image2

Build an Account Detail page.

Step 2: Create a model on the REST service you want to use and enter merge templates in the Data Source URL.

image3

  1. Create a new model.
  2. Pick the appropriate REST Data Source.
  3. Important: In the Data Source URL area, enter merge templates for the parameters that you’ll want to populate via a model condition. In this case we’re using {{Latitude}} and {{Longitude}} so we can create conditions to pull in the Latitude and Longitude fields from our Account Model.

A. If you are planning on populating these areas with fields from another model, make sure that model contains the appropriate fields.

image4

B. It’s also a good idea to make sure these fields are populated for your example record.

image5

It’s the little things.

Step 3: Create URL Merge Condition(s).

image6

  1. Click on your REST model.
  2. Click to add URL Merge Conditions.

A. The merge templates you specified in the Data Source URL will come up as options.

image7

  • No Parameters available in this list? Make sure you entered merge templates in your Data Source URL in Step 2.
  • In this example we’re setting Latitude to the shipping Latitude field form the Account Model, and Longitude to the Shipping Longitude field from the account model. In Steps 2A & B we made sure we included these fields in the Account model, and that they actually had data in them.

Step 4: Add the fields you want to include from this REST service

image8

  • To get fields, you may have to enter sample parameters (in this case Latitude and Longitude).
  • Make sure your test parameters will return the fields you want. For example, if my test latitude and longitude happens to be in the middle of the ocean, then this service won’t return the Time field, which is one of the fields I want. So I made sure my test lat and long were for a city (and not the Lost City of Atlantis).
  • If you accidentally enter test parameters that don’t return the fields you want, you can click the refresh icon next to All Fields and enter new ones.

Continue composing your page, including fields from your REST model as desired.

image9

In this case we’re using a Page Title to display these fields. Put time in {{{triple curly brackets}}} so it will come out unformatted.

Step 5: Click Save, then click Preview to open your page in a new tab.

image10

Success! Thanks to our URL Merge Conditions we can see the date and time for this Account!

image11