Feature Update – *service and manually entered dates/times

Here’s what’s new:

Use *service to embed outside apps and other tools

There’s a lot that GuidedTrack can do, but now the possibilities are nearly endless. Show your users the current weather, generate a random image of a kitten, provide recipes and currency conversions, add job searching from Indeed, and the list goes on. If a person or company offers a web API for it, then you can most likely add it to your GuidedTrack program!

For instance, the Mashape Marketplace is a database chock-full of public and private APIs that can be easily added to GuidedTrack. Search the marketplace for an app that interests you, and when you find one, create an account (it’s free to join) and follow the steps below.

Beyond Mashape, you can add APIs from just about any other source, as long as they’re compatible with basic authentication or custom headers over HTTP (about 90% of APIs out there will fit these restrictions).

There are two parts to adding a *service: setting it up in the settings page, and adding the GuidedTrack code.

Part 1: Setting up the Settings page

In this example, we’ll walk you through adding an from the Mashape Marketplace. Other types of services may require somewhat different steps. Be sure to read the documentation for any API you want to use in order to understand how it works.

1. Create an account on the Mashape Marketplace, if you haven’t already done so.

2. Click on “Default Application” from your dashboard.

3. In the top-right, you’ll see a button that says “Get the Keys.” Click this button:

4. You’ll see a modal appear with your api key, which is a long string of letters and numbers. Copy this somewhere safe.

5. In GuidedTrack, in the program you want to use, navigate to​ the “Settings” page, and the “Services” tab, and click on “New Service”​:

6. The name we’ll use for this service is “Random quotes”. It could be anything at all — it doesn’t need to match the Mashape API name, as this name is just used to identify it within the context of your GuidedTrack program.

7. We need to get the URL to make a request to Mashape, so go to the page for the API you want. In this example, we’ll go to the page for the “Random quotes” api​.

8. Where it says “Endpoint Definition”, there’s a URL that we can point our requests to. You’ll notice on the right-hand side for this example there are actually two Endpoint Definitions. One says “POST” and the other says “GET”. There are a few different kinds of requests you can make to APIs; the most common are GET, POST, PUT, and DELETE. Different APIs will support different ones.

Here’s roughly what each of these mean:

  • GET – read a resource
  • POST – create a new resource
  • PUT – update an existing resource
  • DELETE – delete an existing resource

In this case, we want GET because we want to read a quote from the API, so copy the URL for GET into the GuidedTrack form:

9. For the last part, we need to provide a way to prove that we have permission to make this request. Mashape doesn’t authenticate requests via username/password, so we’ll leave those fields blank. Instead, we include the API key (the one you copied earlier) in a custom header. Click on “Add Header” to create one.

Custom header is an extra piece of information that gets sent along with every request this service makes; headers are used for lots of different things, and even among websites that use them for authentication, the name of the header can vary.

10. In the case of Mashape, ​the header name that we send the key in is “X-Mashape-Key”. So we’ll fill in the key and value for the header like so:

11. Once that’s done, click “Save”, and you’ll be ready to write your GT code!

Part 2: Adding GuidedTrack Code

To make a request to the Random Quotes API, we can use this GuidedTrack code:

1. First, we add the *service keyword and include the name we gave to our service, in this case we called it “Random quotes”.

2. The keyword *path is used when your service has multiple locations within the same domain. This is just like a website URL: when we defined the service we gave it a base URL, and now we want to specify which part of the site to go to. In this case, all requests to the Random Quotes API go to the same place as the URL specified on the Services page (i.e. the URL in the settings: https://andruxnet-random-famous-quotes.p.mashape.com/), so we just write “/” to indicate we’re looking for this base URL. (if there was a hypothetical API we wanted at https://andruxnet-random-famous-quotes.p.mashape.com/romance-quotes, then our path would be “/romance-quotes”)

3. We use “*method: GET” to indicate what kind of request we’re making.

4. The *send keyword is used to send an association of data (your “request”) to the server that hosts the API (e.g. Mashape). This data will tell the server what you want it to do or what information you want it to send back. In the documentation for the Random Quotes API, it tells us that it supports two different fields: “cat” to indicate which category of quote (“movies” or “famous”), and “count” to indicate how many quotes to return. In this example, we want to specify that we want one quote from a movie {“count” -> 1, “cat” -> “movies”}   (the API site also says we can leave out the “count” and it will retrieve just a single quote, but we’re keeping it here for the sake of the example).

5. Lastly, we use *success and *error to get certain information about what happened (the result, or the data you’re interested in). Each of these can be given a block of GuidedTrack code that it will display in the case where the request succeeds or fails, respectively. There are a few restrictions on what can be indented under a *success or *error block; by and large the guiding principle is that it shouldn’t be anything that breaks the page or messes with the program flow, so no *question, *button, or *goto.

The other thing to know about *success and *error is that inside of each of them you get access to the special “it” variable. This is a temporary variable that can only be used inside of the block, which holds the response the server sends back. It’s usually in the form of an association. It’s important to save the important pieces of this variable as something else so that you don’t lose it if you plan to use it later on. For instance, in our example we had a line that said >> quote = it[“quote”]. That way we can store the output of the quote as the “quote” variable and use it elsewhere. We had a similar variable to store the movie name.

As a result of what was typed in the *success block, the user might see something like this:

While you can theoretically save the entire output by assigning “it” to a new variable, this is not necessarily a good idea because the output may store a lot of information you are not interested in, which you don’t want to become a permanent part of your GuidedTrack program’s data.

Create dates and times manually

You can include questions that asks users to enter a *date and/or *time, and now you can also include your own manually entered dates/times.

This is useful if you plan to show the same date over and over and want to store it as a variable, or for adding or subtracting the time or date the user entered with one of your own.

You can add a simple date, like the one below, using an association to define the year and optionally, the day and month:

Or add just a time, specifying the hour and optionally the minute:

You can also create a variable that has both a date and a time:

An hour is required for a calendar::time type of manually added time while a year is required for a calendar::date type of variable.