Overview

Living data is an integration mechanism that can fetch data from any data source that support http get interface. This can be a website, an API, or any service. Use living data with your services or use Idomoo's built in services that can return the current date, do simple maths calculations, and a few others.

When defining a living data source you also define a policy regarding the frequency of regenerating the video with a fresh data from the data source. This makes the video "living". It is no longer always the same. It changed according to the frequency and the data source you configured.


Please note: every time the video is being generated it reduce credits according to the length of the video.


Living Data parameters can be used wherever you could use a regular parameter, like in text placeholders, scene logic and the Edit Path feature. For example, you can have the current time appear in a text placeholder. Another example could be selecting a Living Data parameter in your Scene Logic so you could have scene A shown on Sundays and scene B on other days of the week.



How to Configure Living Data Parameters


Click this button  (at the top right corner of your Storybuilder interface) and in the panel that opens click to select the Living Data tab.




Setting Up the Refresh Schedule


Under Recreate the video with living data choose when the video is refreshed, updating the value for all the Living Data parameters you defined.

The options are:

  • Never - The parameters’ values are processed only once when the video is generated.
  • Every Call - Refreshing the landing page updates the Living Data parameters each time the video is requested.
  • Every # minutes/hours/days/weeks - Generates a new video after the amount of time you set with refreshed Living Data parameters.



Setting Up Living Data Parameters



You add Living Data parameters by clicking the Plus button. Once you click the rest of the panel reveals with the following options:

  • Parameter - Select which parameter you want to turn into a Living Data parameter, or create a new one.
  • Data Source - Idomoo has designed some services, called Living Data Services, that make it easy to do some important operations. You can see a list by opening the drop-down menu at the end of the text field. Please see the Living Data Services and External Data Sources sections for more info. But moreover, The Data Source is a general purpose text field which can be used with any web address. If you type in google.com you receive the text content of google.com.
  • Response Mode - Here you can choose if you want to receive the response from the Data Source either as a string or as a JSON object.
    Please see the External Data Source section for more info.



The +ADD PARAMETER Button



Use this button to add one of your non-living-data parameters to your Living Data source, allowing your Living Data parameter's logic to be more complex, precise and data driven. However, it is not available when using the Current Date or Current Time services as the data source.

Note: Living Data parameters cannot be used inside other Living Data parameters.



Living Data Services


Living Data services were designed by Idomoo to give you some ready made options to work with. They are:

  • Current Date - The data fed into your parameter is equal to the current date, at time of generation.
  • Current Time - your parameter is equal to the current time at time of generation.
  • Time Difference - your parameter is equal to the difference between two dates and times (days, hours and minutes left from a date to another date).
  • Calculator - your parameter is equal to the result of the calculation you configure.
  • HubSpot - allowing you to retrieve contact data from your HubSpot CRM. More about this here.



Current Date


Select Current Date by clicking the down arrow at the far right of the Data Source text field to expose the list of services, then click on Current Date.
The following string appears:



date?output_format=MM/DD/YYYY&timezone=America/New_York
  • output_format - Change how you'd like to display the data using this parameter. You can use any combination of the legal formats in the Date and Time Formats section below.
  • timezone - This parameter defines your desired time zone. The supported formats are TZ database names which can be found here:
    https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    Example: EST, CET, Europe/Oslo, and so on.

The response mode for this service is String.



Current Time


To select Current Time, click the down arrow at the far right of the Data Source text field and expose the list of services. Finally click Current Time.
The following string appears:

time?output_format=HH:mm:ss&timezone=America/New_York

Just as above, you can modify the output_format and timezone according to your needs and to the legal formats which appear in the table below.

The response mode for this service is String.



Time Difference


Select Time Difference (or time_diff for short) by clicking the down arrow at the far right of the Data Source text field to expose the list of services. Then click Time Difference.
The following string appears:

time_diff?input_format=MM/DD/YYYY&output_format=DD:HH:MM:SS&from_date=&to_date=12/31/2020

Since this service provides you with a date difference, it is going to need the following parameters:

  • input_format - The format in which the data arrives for both from_date and to_date.
  • from_date - the first term of the date difference.
  • to_date - the second term of the date difference
  • output_format - The format in which the data is returned. See more below.

The output format is where the magic happens. This is how you define how you'd like the time difference to be returned. The syntax for the output_format does not use the regular accepted formats you can see in the table below. Instead it uses these values


SyntaxDescription
DDAmount of days
HHAmount of hours
MMAmount of minutes
SSAmount of seconds


Keep in mind that you will always get the complete difference in any value you choose. For example, if the difference is 2 days and 3 hours, but you don't ask to see the days, you will get 51 hours.

Between these value you can place any other character you'd like. Here are a couple of examples, where the time different is 2 days, 3 hours, 30 minutes, and 45 seconds.

  • DD:HH:MM:SS → 2:3:30:45
  • DD days HH hours MM minutes SS seconds → 2 days 3 hours 30 minutes 45 seconds
  • HH:MM:SS → 51:30:45
  • DDd HHh → 2d 3h


The response mode for this service is String.



Date and Time Formats


The accepted formats for the input_format and output_format are the following:

DescriptionsyntaxExample
YearYYYY2000, 2001, 2002 … 2012, 2013
YY00, 01, 02 … 12, 13
MonthMMMMJanuary, February, March … 1
MMMJan, Feb, Mar … 1
MM01, 02, 03 … 11, 12
M1, 2, 3 … 11, 12
Day of YearDDDD001, 002, 003 … 364, 365
DDD1, 2, 3 … 364, 365
Day of MonthDD01, 02, 03 … 30, 31
D1, 2, 3 … 30, 31
Do1st, 2nd, 3rd … 30th, 31st
Day of WeekddddMonday, Tuesday, Wednesday … 2
dddMon, Tue, Wed … 2
d1, 2, 3 … 6, 7
HourHH00, 01, 02 … 23, 24
H0, 1, 2 … 23, 24
hh01, 02, 03 … 11, 12
h1, 2, 3 … 11, 12
Minutemm00, 01, 02 … 58, 59
m0, 1, 2 … 58, 59
Secondss00, 01, 02 … 58, 59
s0, 1, 2 … 58, 59
Sub-secondS…0, 02, 003, 000006, 123123123123… 3



Calculator


Select Calculator by clicking the down arrow at the far right of the Data Source text field to expose the list of services. Then click Calculator.
The following string appears:

calc?expr=round(4/3)



Manipulate this string to do mathematical calculations using parameters, numbers, and mathematical functions.
The Data Source format is always: calc?expr=your_expression
In the example above you can see that the expression equals to divide 4 by 3 and round the result.

This is the list of functions we can use and combine.


Simple Arithmetic


These simple arithmetic symbols can be used in your calculation expression.

SyntaxNameDescription
+addition
-subtraction
*multiplication
**powerYou can also do roots by using fractions (0.5 is sqrt)
/divisionDivision always returns a float number
//integer divisionDivides to the lower integer
%modulo


Advanced Calculations


You can also use these simple functions.

SyntaxNameDescription
abs(x)absoluteReturns a positive number (valid for only 1 argument)
max(x1, x2, …)maximumReturns the highest number
min(x1, x2, …)minimumReturns the lowest number
round(x)roundRound number x to an integer.
round(x, y)roundRound number x with y amount of decimal digits.
When using the second optional variable, the outcome is always a float number. If not using the second variable, rounded to integer and integer returned.


The response mode for this service is String.



External Data Sources and Response mode with JSON parsing


Any API endpoint can be used as a Data Source, and the response mode can be either in text format or JSON. If the response is in JSON format, you can choose which value from the JSON object is used as the value for the parameter.
In the following example we are using the Chuck Norris API to explain how you can configure an External Data Source: by adding the API endpoint.
See this link for more info on how this API works.

Here are the steps to follow:

  1. Select which parameter you want to turn into a Living Data parameter, or create a new one. In this example, we used Text2 which is a parameter in a text placeholder.
  2. Insert the API endpoint, in this case https://api.chucknorris.io/jokes/random?category=history, under Data Source.
  3. This API response is in JSON format, so choose JSON as the Response mode.
    Here’s an example of a response from the Chuck Norris API:

    The key that contains the joke I'd like to display is the one called value.
  4. Write the key name you need, in this case value, in the Response Value text field.

    Here as well, you can use the + ADD PARAMETER function to utilize your non Living Data parameters as key name.
  5. When a key name is entered the TEST button lights up, which if pressed, shows a preview of the key’s value, in this case “The Great Wall of China was originally created to keep Chuck Norris out. It failed miserably”.


You can use JMESPath to parse Data Source output, though only a single value or group of values joined together by JMESPath functions are used.