Box Connector 25.2
Box Connector Help

# Write a Lua Script

A Lua script that is run from a connector must have the following structure:

    function handler(config, document, params)
    	...
    end

The `handler` function is called for each document and is passed the following arguments:

Argument | Description
--- | ---
`config` | A `LuaConfig` object that you can use to retrieve the values of configuration parameters from the connector’s configuration file.
`document` | A `LuaDocument` object. The document object is an internal representation of the document being processed. Modifying this object changes the document.
`params` | The `params` argument is a table that contains additional information provided by the connector: TYPE. The type of task being performed. The possible values are `ADD`, `UPDATE`, `DELETE`, or `COLLECT`. SECTION. The name of the section in the configuration file that contains configuration parameters for the task. FILENAME. The document filename. The Lua script can modify this file, but must not delete it. OWNFILE. Indicates whether the connector (and CFS) has ownership of the file. A value of `true` means that CFS deletes the file after it has been processed.

The following script demonstrates how you can use the `config` and `params` arguments:

    function handler(config, document, params)
    	-- Write all of the additional information to a log file
    	for k,v in pairs(params) do
    		log("logfile.txt", k..": "..tostring(v))
    	end

    	-- The following lines set variables from the params argument
    	type = params["TYPE"]
    	section = params["SECTION"]
    	filename = params["FILENAME"]

    	-- Read a configuration parameter from the configuration file
    	-- If the parameter is not set, "DefaultValue" is returned
    	val = config:getValue(section, "Parameter", "DefaultValue")

    	-- If the document is not being deleted, set the field FieldName
    	-- to the value of the configuration parameter
    	if type ~= "DELETE" then
    		document:setFieldValue("FieldName", val)
    	end

    	-- If the document has a file (that is, not just metadata),
    	-- copy the file to a new location and write a stub idx file
    	-- containing the metadata.
    	if filename ~= "" then
    		copytofilename = "./out/"..create_uuid(filename)
    		copy_file(filename, copytofilename)
    		document:writeStubIdx(copytofilename..".idx")
    	end

    	return true
    end

For the connector to continue processing the document, the `handler` function must return `true`. If the function returns `false`, the document is discarded.

TIP: You can write a library of useful functions to share between multiple scripts. To include a library of functions in a script, add the code `dofile("library.lua")` to the top of the lua script, outside of the `handler` function.

Copyright 2025 Open Text
Version 25.2 | Last updated April 2025

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: Knowledge Discovery Box Connector 25.2

Topic Title: Write a Lua Script