Content Comparison

The JOTFORM Library is an importable library containing functions to connect, authenticate, and interact with the Jotform Adapter component, like our other Applications adapters, 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.

Here is how it works:

...

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.

Concepts used:

Custom Fields

require "JOTFORM.JOTFORMclient"

Code Block

language	lua

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

How it works:

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

Expand

title	JOTFORMClient - creates the adapter framework using a metatable

JOTFORMclient creates the Slack 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.

Code Block

language	lua

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

JOTFORMgetSubmission is passed the client object and the table of defined parameters. JOTFORMgetSubmission formats the required endpoint and parameters to call 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:

Expand

title	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.

Code Block

language	lua

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

Expand

title	JOTFORMgetSubmission retrieves form submission entries created since a specified timestamp

JOTFORMcustom

Code Block

language	lua

-

Expand

title	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.

code

Concepts used:

Expand

language	lua

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

Expand

title	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.

Code Block

language	lua

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:

Expand

JOTFORMtimestampToEpoch

title	title	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.

Expand

title	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.

Code Block

language	lua

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.

...

Version	Old Version 1	New Version Current
Changes made by	Aryn Wiebe	Aryn Wiebe
Saved on	Dec 19, 2023	Jun 19, 2024

Content Comparison

Versions Compared

Key

How it works: