Building a Script

This topic covers the structure of a ReadySuite script — the required attributes, how to wire up options and reports, and how to reference external libraries.

Script Class

Every document script extends ScriptContainer and overrides Run(). Every field script extends FieldContainer and overrides Parse().

Copy

public class MyScript : ScriptContainer
{
    public override void Run(IScriptContext script)
    {
        base.Run(script);

        while (script.ReadDocument())
        {
            var document = script.Document;
            // Work with the document
            script.UpdateDocument(document);
        }
    }
}

Copy

public class MyFieldScript : FieldContainer<string>
{
    public override string Parse(DocumentItem item)
    {
        return item.GetFieldData(Context.GetField("SomeField"));
    }
}

Required Attributes

Every script class must have the following attributes:

Attribute	Purpose
[Script]	Defines the script name, category, and version
[ScriptGuid]	A unique GUID that identifies the script
[ScriptAuthor]	Author name, company, and optionally email
[Description]	A brief description shown in the ReadySuite UI

Copy

[Script(Name = "My Script", Category = "Custom Tools", Version = "1.0")]
[ScriptGuid("A1B2C3D4-E5F6-7890-ABCD-EF1234567890")]
[ScriptAuthor(Name = "Your Name", Company = "Your Company")]
[Description("A brief description of what this script does.")]
public class MyScript : ScriptContainer

The ScriptGuid must be unique across all scripts. Generate a new GUID for each script you create.

Adding Options

To present configurable options to the user before the script runs, define a class that extends ScriptOptions and override LoadOptions():

Copy

private MyOptions options;

public override void LoadOptions()
{
    Options = options = new MyOptions();
}

See UI & Options for a complete guide on the available property types, field pickers, validation, and UI controls.

Adding a Report

To show a summary after execution, extend ScriptCategoryReport or ScriptTextReport and override LoadReport():

Copy

private ScriptCategoryReport report;

public override void LoadReport()
{
    Report = report = new ScriptCategoryReport();
}

ScriptCategoryReport displays structured key-value data grouped by category:

Copy

report.AddItem("Summary", "Documents Updated", updatedCount.ToString());
report.AddItem("Summary", "Documents Skipped", skippedCount.ToString());
report.AddItem("Errors", "Failed Documents", failedCount.ToString());

ScriptTextReport displays free-form text output:

Copy

var report = new ScriptTextReport();
report.AppendLine("Processing complete.");
report.AppendLine($"Updated {count} documents.");
Report = report;

External Assembly References

Scripts can reference external DLLs using a cs_ref pragma comment at the top of the file:

Copy

//cs_ref MimeKit.dll
using MimeKit;

Place the DLL alongside your script file or in a known location. This is commonly used for email parsing, PDF processing, and other specialized tasks.