How the Jotform Adapter Works

The Jotform Adapter component, like our other adapters, uses simple core concepts and common design patterns to ensure they are extensible and easy to understand.

Here is how it works:

main calls JOTFORMclient, passing the Jotform API key from the custom fields

In main, the 'S' object will be used to call the methods defined in JOTFORMclient.

local S = JOTFORMclient{key=component.fields().Key}

Concepts used:

Custom Fields

JOTFORMClient creates the adapter framework using a metatable

JOTFORMclient creates the Jotform adapter framework.

JOTFORMgetSubmission and JOTFORMcustom modules are defined in a metatable as methods and set to the S object. The API key passed to JOTFORMclient is assigned to the new S table so that it can be used by the methods. If the API key is not passed, a “Missing key“ error is thrown.

local MT={}

MT.__index = {}
MT.__index.custom  = require 'JOTFORM.JOTFORMcustom'
MT.__index.getSubmission = require 'JOTFORM.JOTFORMgetSubmission'

help.map{dir='JOTFORM/help',methods=MT.__index}

function JOTFORMclient(T)
   if T.key == '' or T.key == nil then error('Missing key',2) end
   local S= {}
   setmetatable(S, MT)
   S.key = T.key
   return S
end

Concepts used:

Meta tables
Setting up help for an object with methods using the MT.__index table of methods.
Using a table as a function argument

main calls JOTFORMgetSubmission to get content from submitted forms

The COUNT Library is used to get the data from the custom field called “Since”. JOTFORMgetSubmission is called, passing in the Form ID configured in custom fields, and a “created at“ filter value for the timestamp of the last poll.

local Since = COUNTget('Since')   
local Status, R = S:getSubmission{form_id=component.fields().FormId, filter=Since, live=true}

Concepts used:

COUNT Library
Custom Fields
Colon Operator passes the S client object and table of parameters as the first argument
Live Flag

JOTFORMgetSubmission retrieves form submission entries created since a specified timestamp

JOTFORMgetSubmission is passed the client object and the table of defined parameters. JOTFORMgetSubmission formats the required endpoint and parameters to call JOTFORMcustom to make the '/form/<form_id>/submissions' API call. The Filter parameter is set to a timestamp of the last poll.

local function JOTFORMgetSubmission(T, C)
   if C.form_id == '' or C.form_id == nil then error('Missing form_id',2) end
   local Since = os.date('%Y-%m-%d %H:%M:%S',C.filter)
   local Filter = {}
   Filter["created_at:gt"] = Since   
   local P = {}      
   P.filter = json.serialize{data=Filter,compact=true}    
   iguana.logInfo('Retrieving form submissions from '..Since)
   return T:custom{api='/form/'..C.form_id..'/submissions', parameters=P, live=C.live}
end

return JOTFORMgetSubmission

Concepts used:

JOTFORMcustom takes in any API request parameters, makes a request and returns the response

JOTFORMcustom is a helper function designed to handle different API requests with Jotform.

It prepares the API Key to be passed as a parameter for authentication and assigns the url endpoint prepared by JOTFORMgetSubmission. net.http.get{} is used to send the request to Jotform. The response is parsed and either the response or error response is returned.

local function JOTFORMcustom(T, C)
   local P = C.parameters or {}
   P.apiKey = T.key   
   local Url = "https://api.jotform.com"..C.api
   trace(Headers, Url, C.parameters)
   local R, Code = net.http.get{url=Url, headers=Headers,parameters=P, live=C.live}
   
   if (C.live ~= true) then
      return "notlive"
   end
   R = json.parse{data=R}
   if Code ~= 200 then
      return false, R
   else
      return true, R
   end
end

return JOTFORMcustom

Concepts used:

In main, the response is returned, parsed and the content of each submission is queued

If JOTFORMgetSubmission returns a successful response with submission content, then the “Since“ custom field used to create the polling filter is set to a Unix Epoch time integer using JOTFORMtimestampToEpoch (see next section). For each submission content entry, the content is serialized as a string and queued.

The component is then set to run every 5 minutes.

if Status == true and #R.content > 0 then
   -- Update our count
   COUNTset('Since',JOTFORMtimestampToEpoch(R.content[1].created_at))
   -- Push form submissions downstream in chronological order
   for i=1,#R.content do
      queue.push{data = json.serialize{data=R.content[i]}}
  end
end
   
component.setTimer{delay=5*60*1000}

Concepts used:

JOTFORMtimestampToEpoch function converts a UTC timestamp to Unix Epoch Time

JOTFORMdateConversion contains the JOTFORMtimestampToEpoch() function which takes a timestamp in UTC and converts it to Unix Epoch Time.

Using pattern matching, the timestamp pieces (year month, day, hour, min, sec) are isolated and used to create the equivalent Unix Epoch integer to replace the “Since“ custom field.

function JOTFORMtimestampToEpoch(timestamp)
    local pattern = "(%d+)-(%d+)-(%d+) (%d+):(%d+):(%d+)"
    local year, month, day, hour, min, sec = timestamp:match(pattern)

    if year and month and day and hour and min and sec then
        local epochTime = os.time({
            year = tonumber(year),
            month = tonumber(month),
            day = tonumber(day),
            hour = tonumber(hour),
            min = tonumber(min),
            sec = tonumber(sec)
        })
        return epochTime
    else
        return nil  -- Invalid timestamp format
    end
end

Concepts used:

Thats it! This component is intentionally designed to enable you to easily extend its functionality to meet your exact workflow needs.

You can get very creative - checkout the Jotform API documentation for all the available methods.