Connector Framework Server 24.1

# Debug a Lua Script

When you run a Lua script and the script fails due to an error, CFS writes the error to the import log stream, and to the `ImportErrorDescription` field of any documents that are affected.

To debug your Lua scripts, you can use the `LuaDebug` action. You can use this action to pause and resume scripts, and set and remove breakpoints. When a script is paused you can view the values of variables, view a stack trace, and step over single lines.

## Sessions

CFS can have more than one import thread, and might run multiple Lua scripts concurrently. This means that you can have multiple Lua Debugging sessions. You might want to pause or continue running scripts on one thread but not others. Some of the commands available through the `LuaDebug` action allow or require you to specify a `session` action parameter. If the `session` parameter is optional and you do not specify a session, the command applies to all sessions. To view open sessions and obtain the values you can set for the `session` action parameter, use the command `/action=LuaDebug&command=get-status`.

## Example

The following procedure demonstrates how to set a breakpoint in a script, view the values of Lua variables when the script is paused, and step over single lines. The actions in this procedure assume that your CFS is running on the local machine and is listening for actions on port 7000. For more information about the `LuaDebug` action, refer to the Connector Framework Server Reference.

To debug a Lua script

1. In the CFS configuration file, configure the script to run. This example uses the `AddLanguageDetectionFields` script that is included with CFS. For example:

       [ImportTasks]
       Post0=Lua:scripts/AddLanguageDetectionFields.lua

2. Start CFS.

3. To pause the script before a specific line is executed, set a breakpoint on that line. Line 33 of the `AddLanguageDetectionFields` script sends an action to IDOL Server and stores the response in a variable named `response`. To stop the script before this happens, use the following action:

       http://localhost:7000/action=luadebug
                                  &command=set-breakpoint
                                  &file=scripts/AddLanguageDetectionFields.lua
                                  &line=33

4. (Optional) Confirm the breakpoint has been set using the `get-breakpoints` command:

   `http://localhost:7000/action=luadebug&command=get-breakpoints`

   CFS returns the response.

       <autnresponse xmlns:autn="http://schemas.autonomy.com/aci/">
          <action>LUADEBUG</action>
          <response>SUCCESS</response>
          <responsedata>
             <data>
                <command>get-breakpoints</command>
                <breakpoints>
                   <breakpoint source="C:\Autonomy\ConnectorFramework\scripts\AddLanguageDetectionFields.lua" line="33"/>
                </breakpoints>
             </data>
          </responsedata>
       </autnresponse>

5. Send CFS an `IngestTest` action so that CFS ingests a document and runs the script:

       http://localhost:7000/action=IngestTest&adds=...

   TIP: Use an `IngestTest` action, rather than an `Ingest` action, because the `IngestTest` action does not index any information into IDOL Server. For more information about the `IngestTest` action, see Ingest Data for Testing.

   CFS runs the script. The `IngestTest` action does not finish (because the script is paused at the breakpoint) and therefore does not return a response.

6. Retrieve a token for the debugging session by sending CFS the `LuaDebug` command `get-status`:

   `http://localhost:7000/action=LuaDebug&command=get-status`

   CFS returns the response. You can see that there is a single debugging session and the Lua script has stopped at the breakpoint.

       <autnresponse xmlns:autn="http://schemas.autonomy.com/aci/">
          <action>LUADEBUG</action>
          <response>SUCCESS</response>
          <responsedata>
             <data>
                <command>get-status</command>
                <session id="e4f7c45f561930cd17a5aed0fe1481d8">
                   <status>AtBreak</status>
                </session>
             </data>
          </responsedata>
       </autnresponse>

7. To retrieve the values of the Lua variables at the breakpoint, run the `LuaDebug` command `get-locals`. Use the session token that you retrieved with the `get-status` command:

       http://localhost:7000/action=LuaDebug
                                  &command=get-locals
                                  &session=e4f7c45f561930cd17a5aed0fe1481d8

   CFS returns the response.

       <autnresponse xmlns:autn="http://schemas.autonomy.com/aci/">
         <action>LUADEBUG</action>
         <response>SUCCESS</response>
         <responsedata>
           <data>
             <command>get-locals</command>
             <session id="e4f7c45f561930cd17a5aed0fe1481d8">
               <locals>
                 ...
                 <local name="idolHost" type="string">localhost</local>
                 <local name="idolACIPort" type="number">9000</local>
                 <local name="timeout" type="number">30000</local>
                 ...
                 ...
                 <local type="string" name="detectionString">This is a document that
                      contains text in English. Automatic Language Detection will
                      detect the language and add the information to the document
                 ...</local>
               </locals>
             </session>
           </data>
         </responsedata>
       </autnresponse>

8. Use the `step` command to run line 33. CFS does not run subsequent lines (the script will remain paused). Use the session token you retrieved with the `get-status` command:

       http://localhost:7000/action=LuaDebug
                                  &command=step
       			    &session=e4f7c45f561930cd17a5aed0fe1481d8

   CFS returns the response.

       <autnresponse xmlns:autn="http://schemas.autonomy.com/aci/">
         <action>LUADEBUG</action>
         <response>SUCCESS</response>
         <responsedata>
           <data>
             <command>step</command>
             <session id="e4f7c45f561930cd17a5aed0fe1481d8"/>
           </data>
         </responsedata>
       </autnresponse>

9. To see what effect the step had on the variables, run the `get-locals` command again. You should see a new variable named `response` that contains the response from the `DetectLanguage` action.

       http://localhost:7000/action=LuaDebug
                                  &command=get-locals
                                  &session=e4f7c45f561930cd17a5aed0fe1481d8

10. After examining the variables, you might want to remove the breakpoint. To remove the breakpoint, send CFS the following action:

        http://localhost:7000/action=LuaDebug
                                   &command=remove-breakpoint
                                   &file=scripts/AddLanguageDetectionFields.lua
                                   &line=33

    CFS returns the response. You can also use `/action=LuaDebug&command=get-breakpoints` to confirm that the breakpoint has been removed.

11. To continue running the Lua script, use the `continue` command:

        http://localhost:7000/action=LuaDebug
                                   &command=continue
                                   &session=e4f7c45f561930cd17a5aed0fe1481d8

    CFS continues to run the script. The `IngestTest` action finishes and returns a response.

Copyright 2023 Open Text
Version 24.1 | Last updated December 2023

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: IDOL Connector Framework Server 24.1

Topic Title: Debug a Lua Script