Working with Documents

This topic explains how scripts interact with documents — iterating, committing changes, creating and removing documents, and how progress tracking works.

The standard pattern for processing documents is the IScriptContext.ReadDocument() loop. Each call advances to the next DocumentItem and updates progress automatically:

public override void Run(IScriptContext script)
{
    base.Run(script);

    while (script.ReadDocument())
    {
        var document = script.Document;

        // Read or modify the document

        script.UpdateDocument(document);
    }
}

UpdateDocument() serves two purposes:

1. Commits changes — marks the document as modified so ReadySuite persists any field data, resource, or family changes you made.
2. Advances progress — notifies the UI that a document was processed.

If you only read from a document without modifying it, you do not need to call UpdateDocument(). Progress is already tracked by ReadDocument() each time it advances to the next document.

while (script.ReadDocument())
{
    var document = script.Document;
    var value = document.GetFieldData(options.SourceField);

    if (!string.IsNullOrEmpty(value))
    {
        document.SetFieldData(options.TargetField, value.Trim());
        script.UpdateDocument(document);  // Commit this change
    }
    // No UpdateDocument needed when skipping — progress still advances
}

To add new documents to the project, use GetNewDocument() followed by CreateDocument():

var newDoc = script.GetNewDocument("NEW-0001");
newDoc.SetFieldData(options.SomeField, "value");
newDoc.SetNative(newDoc.GetNewNative(filePath));
script.CreateDocument(newDoc);

GetNewDocument() only creates an in-memory reference — the document is not added to the project until you call CreateDocument().

To attach a new document as a child of an existing document:

var parent = script.Document;
var child = script.GetNewDocument("ATTACH-0001");
child.SetNative(child.GetNewNative(attachmentPath));
script.CreateDocument(child);
parent.AddAttachment(child);
script.UpdateDocument(parent);

RemoveDocument() flags a document for removal. The document is not deleted immediately — ReadySuite removes it after the script finishes:

while (script.ReadDocument())
{
    var document = script.Document;

    if (ShouldRemove(document))
    {
        script.RemoveDocument(document);
    }
}

GetDocuments() returns the full document list, which is useful when you need random access or multiple passes. However, it does not track progress automatically — you must call ReadDocument(document) yourself on each document to update progress:

var documents = script.GetDocuments();
foreach (var doc in documents)
{
    script.ReadDocument(doc);  // Update progress

    // Process the document
}

Without ReadDocument(doc), the progress bar will not advance.

By default, progress is tracked automatically — ReadySuite sets the maximum to the document count and advances each time ReadDocument() is called. This works for most scripts.

For scripts that do work outside the standard document loop (multi-pass processing, file I/O, external calls), you can switch to manual progress using ScriptProgressMode:

public override void Run(IScriptContext script)
{
    base.Run(script);

    ProgressMode = ScriptProgressMode.Manual;
    MaximumSteps = totalSteps;

    // Do work...
    ProgressStep();  // Advance the progress bar

    // More work...
    ProgressStep();
}