This document describes the procedures for using TIBCO Spotfire desktop to view and analyze eLynx data acquired via the eLynx API.  It describes a sample scenario for how to connect to the eLynx API and how to configure Spotfire using a script and parameters.

NOTE:  The script examples used in this document may be copied/pasted as a template but they must be modified to match your situation (e.g., your API key, report name, column configurations, etc.).

Prerequisites

The following items are needed to view and analyze eLynx data using Spotfire:

1. API key for the eLynx Public API
2. Report that returns desired data
3. Basic understanding of how to use a REST API to retrieve data
4. Basic understanding of how to use TIBCO Spotfire

For more information about using a REST API via Spotfire, please see the following article: https://community.tibco.com/feed-items/using-public-data-rest-api-spotfire

Connecting to eLynx with Spotfire desktop

STEP 1:  Create a data function

1. Open the Spotfire desktop application.
2. Click the Menu button (three vertical dots, upper left of page) to display the menu bar.
3. Click the Tools menu, and then click the Register Data Functions option to create a new data function.
4. In the Register Data Functions modal, enter values into the following fields::
   1. Name - The name of the Script (e.g., "Get Daily eLynx Data").  Entered by the user.
   2. Type - The type of script.  In this case, it is "R script" and cannot be changed.
   3. Packages - Enter the library packages to be used in the script.  Note that these must match the library entries declared in the script and be separated by semicolons.
   4. Description - Enter the description of the function and why it is used. 
   5. Allow Caching - Checkbox to use caching; this should be Unchecked for this script.

Additionally, there are three tab which must be configured as described in the following steps:

STEP 2: Configure the Script tab

On the Register Data Functions modal, the Script tab is used to enter the R script that will access the eLynx API and retrieve the data. The script should be prepared as follows:

1. Use the TIBCO Enterprise Runtime for R (TERR) to create, compile and test the script to confirm it works as expected.
2. Paste the tested script into the Script tab.

An example script is provided here as a reference.  This may be copied/pasted but the code must be modified to match your specific situation (e.g., your API key, your report name, any changes to columns, etc.).

# load the necessary packages
library("httr")
library("jsonlite")
library("xml2")
library("lubridate")

############################################################################
############################################################################

# set up the initial report parameters and get the data
baseURL <- "https://api.elynxtech.com/v1/datareport/"
apiKey <- "<your-api-key-here>"
report <- "<your-report-name-here>"  #name of a report that has been created already - sample report name is for daily data from 9986

# concatenate your strings to form the REST URI
call1 <- paste(baseURL, report,"?reportStartTime=", start, "&reportEndTime=", end, sep = "" )

# limit the number of concurrent connections (optional)
config(CURLOPT_MAXCONNECTS=1)

# execute the get call
get_data <- GET(call1, add_headers("Ocp-Apim-Subscription-Key" = apiKey))

# extract the result set as text and process it as JSON (will return nested lists/dataframes)
jsonText <- fromJSON(content(get_data,type="text"))

############################################################################
############################################################################

# begin processing the returned data
# extract the column names from the JSON (replace the spaces with underscores, optional)
returnedColNames <- gsub(" ","_",t(jsonText$tables$columns[[1]]$caption))
returnedDataList <- jsonText$tables$rows[[1]]$cells

# loop over the returned data and add each row to an initially empty dataframe
# (there are probably more elegant ways to do this with an lapply, but this works well enough)
eLynxDailyDataTable <- NULL
for (i in 1:length(returnedDataList)){
  eLynxDailyDataTable <- rbind(eLynxDailyDataTable,t(returnedDataList[[i]]))
}

# set the column names and remove the row names, if desired
colnames(eLynxDailyDataTable) <- returnedColNames
rownames(eLynxDailyDataTable) <- NULL

# fix the data types, if desired (view the originals with: jsonText$tables$columns[[1]]$dataType)
# convert from factors to strings
eLynxDailyDataTable <- transform(eLynxDailyDataTable,Device_Display_Name=as.character(Device_Display_Name)) 

# convert from factors to POSIXct
eLynxDailyDataTable <- transform(eLynxDailyDataTable,Date=parse_date_time(as.character(Date),"%m/%d/%Y %I:%M:%S %p %z"))

# as.numeric doesn't like commas, so remove them, and convert
eLynxDailyDataTable <- transform(eLynxDailyDataTable,SpotFlow=as.numeric(gsub(",","",SpotFlow))) 
eLynxDailyDataTable <- transform(eLynxDailyDataTable,Pressure=as.numeric(gsub(",","",Pressure))) 
eLynxDailyDataTable <- transform(eLynxDailyDataTable,Temperature=as.numeric(gsub(",","",Temperature))) 

# this process returns a simple dataframe with 2 base columns plus one for each data column

STEP 3: Configure the Input Parameters tab

The Input Parameters tab is used to configure the input date range parameters that control the amount of data to be returned by the script.  The sample script is written to have the start time and end time passed as input parameters, so two parameters must be configured:

• start - A parameter of DateTime data type representing the start date/time for the result set to be returned
• end - A parameter of DateTime data type representing the end date/time for the result set to be returned

These parameters must be configured in the Input Parameters tab as follows:

1. Click the Input Parameters tab.
2. Create the start input parameter:
   1. Click the Add... button to display the Input Parameter modal.
   2. Enter values into the following fields:
      1. Input parameter name - Enter the value "start"
      2. Display name - Enter whatever label is preferred (e.g., "Start Time").
      3. Type - The default value of "Value" cannot be changed.
      4. Allowed data types - Check the "DateTime" checkbox.
      5. Description - Enter a description of the parameter.
      6. Required parameter - This should be checked.
   3. Click the OK button to save the parameter and close the Input Parameter modal.
3. Create the end input parameter:
   1. Click the Add... button to display the Input Parameter modal.
   2. Enter values into the following fields:
      1. Input parameter name - Enter the value "end"
      2. Display name - Enter whatever label is preferred (e.g., "End Time").
      3. Type - The default value of "Value" cannot be changed.
      4. Allowed data types - Check the "DateTime" checkbox.
      5. Description - Enter a description of the parameter.
      6. Required parameter - This should be checked.
   3. Click the OK button to save the parameter and close the Input Parameter modal.

Additional instructions are available in a section below describing how to set these input parameters to be relative to the current time.

STEP 4: Configure the Output Parameters tab

The Output Parameters tab is used to configure the table parameters that contain the data returned by the script.  The sample script outputs a single parameter of type "Table" which contains the data:

• eLynxDailyDataTable - A parameter of Table data type containing the rows and columns of the result set to be returned.
  • IMPORTANT NOTE:  The Result parameter name value MUST exactly match the name of the variable used in the sample R script, but the Display Name can be set by the user.

This parameter must be configured in the Output Parameters tab as follows:

1. Click the Output Parameters tab.
2. Create the eLynxDailyDataTable output parameter:
   1. Click the Add... button to display the Output Parameter modal.
   2. Enter values into the following fields:
      1. Input parameter name - Enter the value "start"
      2. Display name - Enter whatever label is preferred (e.g., "Start Time").
      3. Type - The default value of "Value" cannot be changed.
      4. Allowed data types - Check the "DateTime" checkbox.
      5. Description - Enter a description of the parameter.
   3. Click the OK button to save the parameter and close the Output Parameter modal.

STEP 5: Save and Run the Data Function

Now that the script and parameters have been configured, the data function may be saved and run to populate the data for the first time as follows:

1. On the toolbar, click the Save button to save the data function.
2. Click the Run button to execute the data function and view the results.

STEP 6: Changing Parameters and Re-running the Function

The script and parameters can be edited at any time as follows using the Edit Parameters modal as follows:

1. Click the Data menu and select the Data function properties menu option.  The Edit Parameters modal will be displayed.
2. To reload the data:
   1. Check the Refresh function automatically checkbox in the Edit Parameters modal; or
   2. Click the Data menu option and then click the Reload all menu option.
3. To set the start and/or end Input Parameters to use relative time:
   
   1. Select the desired parameter in the Input parameters list.
   2. In the Input handler list (bottom left), select the "Expression" item.
   3. In the Data table dropdown, select the "eLynxDailyData" value from the list.
   4. In the Expression field, enter the following to adjust the time for Central Standard Time (i.e., 6 hours behind GMT):

DateTime(DateAdd("day",-6,Today()))