Skip to main content

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 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:

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.

JOTFORMgetSubmission - method used to retrieve 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.

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: