JOTFORM Library

The JOTFORM Library is an importable library containing functions to connect, authenticate, and interact with the Jotform API. This library is used in the Jotform Adapter. The library uses simple core concepts and common design patterns to ensure they are extensible and easy to understand. You can get very creative - checkout the Jotform API documentation for all the available methods.

When imported into projects, typically only the JOTFORMclient module needs to be required in order to create the client and access the API methods.

require "JOTFORM.JOTFORMclient"

How it works:

Use the Translator’s built in help to review how to use each function:

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

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.

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.

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: