All Collections
User Guides
Analytics: UbiFunctions User Guide
Analytics: UbiFunctions User Guide

Use UbiFunctions serverless computation environment to extract, transform, schedule, and analyze data.

Agustin Pelaez avatar
Written by Agustin Pelaez
Updated over a week ago

Forget about needing extra servers for your App, you have UbiFunctions, a serverless computing environment for the IoT. Also known as FaaS (Functions as a Service), Ubidots’ serverless function environment allows you to run custom functions on-demand, directly from Ubidots cloud. 

What is an UbiFunction?

An UbiFunction is user-defined code that runs, on-demand, by either (1) making an HTTP GET or POST request to the UbiFunction’s URL automatically created by Ubidots, or (2) based on a predefined repeat interval.

Ubifunctions is included in Professional plans and above.

Table of Contents

1. When to use UbiFunctions?

You can use UbiFunctions to extend Ubidots’ capabilities with your custom logic. Most use-cases fall into the following three categories:

  1. Extract data from 3rd party APIs

  2. Customize your own HTTP API Gateway

  3. Transform and Analyze sensor data

1. Extract data from 3rd party APIs

Most web applications have an API and in most cases, you’ll be able to access your data programmatically without much difficulty. 

Imagine you have a Bitcoin cluster and want to turn it on or off based on the Bitcoin/Energy price relationship? Or let’s say you want to research the relationship of a commodity price with specific weather conditions? Use UbiFunctions to run your code periodically and query 3rd party APIs to extract Weather, Energy, or Currency data and aggregate the time-series data in Ubidots for analytics and action. 

Weather data extraction example:

  • AmbientWeather devices → AmbientWeather Cloud → Ubidots (See example)

  • WeatherUnderground → Ubidots (Coming Soon – but you can always develop the Function yourself using Steps 2 & 3 below)

2. Customize your own HTTP API Gateway

There may be cases where an HTTP communication with Ubidots is not possible locally, or changing the HTTP methods, payload, and/or URLs is just too painful.

In such cases, UbiFunctions will enable you to create a custom HTTP API to ingest data while transforming the payload to fit Ubidots’ expected JSON and URL format. Here are some cases where a custom reception is specially useful:

3. Transform and Analyze sensor data

Last but not least, being able to run custom functions on top of your datasets by accessing the power of Python and Node.js from your Ubidots account. With UbiFunctions, you have access to most features and libraries that make these programming languages the favorites for data transformation and analysis. 

Here some possible use-cases for data transformation and analysis:

  • Assign a GPS location to your devices, based in the neighboring WiFi routers or cell tower IDs. (See example)

  • Assess the probability of an accident in the shop floor, based on a worker’s properties (i.e. city, production process, shift) and a machine’s variables (i.e. speed, temperature, pressure, vibration). (Speak with Ubidots)

2. Creating an UbiFunction

UbiFunctions are accessed from the "Data" tab of your Ubidots header under "Function":

Step 1: Click the blue "+" icon to create your first UbiFunction:

Step 2: Give the function a name. Keep in mind this name will later become part of the function’s URL.

3. Coding an UbiFunction

UbiFunctions accepts NodeJS LTS or Python3, which means you can use Javascript or Python code to extract, transform, and analyze data. Your function receives "args" as a dictionary, which you can then access in your code to performs the desired data transformation. The code is run whenever the endpoint URL is requested.

Sample Function Example:
By default, every new UbiFunction is populated with a sample code that uses input data (TOKEN, Device, & Temp Value) to make a request to Ubidots API. This sample code demonstrates a simple HTTP GET endpoint that receives an Ubidots token, a device label, and a temperature value as URL parameters, then uses this data to make an HTTP POST request to Ubidots API.

You can actually test the sample function by clicking on the button “Make it live”, then paste the URL below into your web browser, updating the Username and TOKEN of your account.


NOTE: The identifier of any function within UbiFunctions is simply the name assigned. Here, the test function is named "new-function" and accordingly, by testing the sample function provided, the UbiFunctions engine will identify this particular function in your account (no one else's) and report back a Temp Value and TOKEN. 

You may now begin coding your function. Please note the return payload must always be in a dictionary format. Sending a single variable cannot be understood and must be returned in a dictionary format.

To know what libraries UbiFunctions modules currently supports, please check this article UbiFunctions & Plugins: Supported libraries.

4. Access to your Tokens in UbiFunctions

Securely access your Token from the UbiFunction’s code, avoiding copy-pasting API tokens in the code directly, by selecting a Token in the dropdown from the left panel and calling it using _auth_token key.

5. UbiFunction excecution time

Within the UbiFunctions configuration, you can extend the execution time up to 40 seconds to run tasks that would take longer than expected, by default the value will be 10 seconds.

If you need for time, feel free tor each out our support team at support@ubidots.com.

6.Using Raw functions

It is possible to use content types other than "application/json", as well as adding custom paths to the UbiFunction's URL and customizing the response codes of your functions. To learn more, please check this article: "UbiFunctions: Using Raw functions"

7. Running Function

During the development process, you will want to test your function to see if you are on the right track towards the desired output. To do so, click on "Run Function." This will being up an modal screen requesting some input data to test with. If your function requires an input, you need only enter a JSON dictionary of sample inputs. You may leave this blank if your function does not require an input.

In the case of Ubidots default sample function, enter the JSON payload below containing the parameters you look to pass through the HTTP GET request:

{
"token":"your-token",
"Device":"sample-function",
"Temperature":"45"
}

After clicking on "Run with this input" a console window will emerge with both the output and the console of the results:

  • Output: This is what your function returns. It must be in a JSON dictionary format. In your code, make sure to use "return" to quit the function and return the dictionary.

  • Console: This is used to debug purposes. Use console.log("hello") to leave trails in this console.

Examples

6. Billing of UbiFunctions

Ubifunctions is included in Professional plans and above.

  • Executions are timed-out after 40 seconds. If you wish to extend this time, please reach out to our support team.

  • If any execution surpasses 2 seconds; it is counted as 2 executions (or more, based on time length of the execution) 

  • Executions are billed at increments of $5 per million executions.

Need help coding your Ubifunction? Feel free to ask for help to our support team via the in-app chat channel or via email at support@ubidots.com. 

Want to share a helpful function to teach others how to connect the dots? Feel free to post it at community.ubidots.com and help another IoT innovator achieve their goals. 

Other users also found helpful: 

Did this answer your question?