Usage Patterns

This topic covers patterns frequently used in ReadySuite scripts, drawn from real-world examples.

Reading and Writing Field Data

The most common operation is reading a field value from a document, transforming it, and writing it back (or to a different field).

Copy

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

    if (!string.IsNullOrEmpty(value))
    {
        document.SetFieldData(options.TargetField, value.Trim().ToUpper());
        script.UpdateDocument(document);
    }
}

Creating Fields On-the-Fly

Use GetOrCreateField() when your script needs a field that may not exist yet.

Copy

var field = script.GetOrCreateField("MyCustomField");

For typed fields, use CreateField() with a FieldItemType:

Copy

if (!script.HasField("PageCount"))
{
    script.CreateField("PageCount", FieldItemType.Number);
}

Working with Natives and Pages

Access a document's native file, pages, or text resources:

Copy

if (document.HasNative())
{
    var native = document.GetNative();
    var fullPath = native.GetFullPath();
    var extension = native.FileExtension;
}

if (document.HasPages())
{
    var pages = document.GetPages();
    foreach (var page in pages)
    {
        // page.GetFullPath(), page.Width, page.Height, etc.
    }
}

Replace a native file:

Copy

var newNative = document.GetNewNative(newFilePath);
document.SetNative(newNative);
script.UpdateDocument(document);

Family and Attachment Relationships

Work with document families (parent-child / attachment relationships):

Copy

if (document.HasFamily() && document.IsParent())
{
    var attachments = document.GetAttachments();
    foreach (var attachment in attachments)
    {
        // Process child documents
    }
}

Create new documents and attach them:

Copy

var newDoc = script.GetNewDocument("NEW-0001");
newDoc.SetNative(newDoc.GetNewNative(filePath));
script.CreateDocument(newDoc);
document.AddAttachment(newDoc);
script.UpdateDocument(document);

Error Handling

Wrap per-document operations in try-catch blocks so one bad document doesn't stop the entire script:

Copy

while (script.ReadDocument())
{
    var document = script.Document;
    try
    {
        // Process document
        script.UpdateDocument(document);
    }
    catch (Exception ex)
    {
        script.AddWarning(document,
            string.Format("Failed to process {0}: {1}", document.DocId, ex.Message));
    }
}

Logging Messages and Warnings

Use AddMessage() for informational output and AddWarning() for issues:

Copy

script.AddMessage("Processing complete. Updated 42 documents.");
script.AddWarning(document, "Field was empty, skipped.");

Cancellation Support

Long-running scripts should check for cancellation:

Copy

while (script.ReadDocument())
{
    script.ThrowIfCancellationRequested();
    // ... process document
}

Or check manually:

Copy

if (script.IsCancellationRequested)
    break;

Bates Number Manipulation

Use BatesCounter for parsing and incrementing bates numbers:

Copy

var bates = new BatesCounter(document.BatesBeg);
string prefix = bates.Prefix;     // e.g. "ABC-"
long counter = bates.Counter;     // e.g. 1234
string id = bates.Identifier;     // e.g. "ABC-001234"
bates.Increment();

Multi-Pass Processing

Some scripts need to scan the full document set before processing. Use GetDocuments() for the first pass:

Copy

// First pass: collect data
var lookup = new Dictionary<string, string>();
var documents = script.GetDocuments();
foreach (var doc in documents)
{
    var key = doc.GetFieldData(options.KeyField);
    var value = doc.GetFieldData(options.ValueField);
    if (!string.IsNullOrEmpty(key))
        lookup[key] = value;
}

// Second pass: apply
while (script.ReadDocument())
{
    var document = script.Document;
    var key = document.GetFieldData(options.KeyField);
    if (lookup.TryGetValue(key, out var mapped))
    {
        document.SetFieldData(options.TargetField, mapped);
        script.UpdateDocument(document);
    }
}

Regex and Text Parsing

Common pattern for extracting or matching text:

Copy

var pattern = new Regex(@"\b[A-Z]{3}-\d{6}\b");
var value = document.GetFieldData(options.SourceField);

if (!string.IsNullOrEmpty(value))
{
    var match = pattern.Match(value);
    if (match.Success)
    {
        document.SetFieldData(options.TargetField, match.Value);
        script.UpdateDocument(document);
    }
}