Pagination¶

When working with large datasets in ServiceNow, responses are often split into multiple pages. The SDK provides specialized iterators to help you traverse these results efficiently.

Understand pagination¶

ServiceNow uses limit and offset parameters or link headers to manage pagination. The SDK abstracts this complexity by providing an iterator that can automatically fetch subsequent pages as you process records.

The SDK provides specialized iterators for common APIs:

TablePageIterator: For table record collections.
AttachmentPageIterator: For attachment collections.

Use the page iterator¶

Basic iteration¶

To iterate over multiple pages of records, use the NewDefaultTablePageIterator (for standard table records) or NewTablePageIterator (for custom types).

// 1. Execute a list request
listResponse, err := client.Now2().TableV2("incident").Get(ctx, nil)
if err != nil {
    log.Fatal(err)
}

// 2. Create the iterator
iterator, err := tableapi.NewDefaultTablePageIterator(listResponse, client.RequestAdapter)
if err != nil {
    log.Fatal(err)
}

// 3. Iterate over all records across all pages
err = iterator.Iterate(ctx, false, func(record *tableapi.TableRecord) bool {
    // Process the record
    sysId, _ := record.GetSysID()
    fmt.Printf("Incident ID: %s\n", *sysId)
    return true // Continue to the next record
})

if err != nil {
    log.Fatal(err)
}

Iterate item-by-item¶

If you need more control than a callback, you can use NextItem and HasNext to pull items one at a time.

// Iterate item by item using NextItem
for iterator.HasNext() {
    item, err := iterator.NextItem(ctx)
    if err != nil {
        break
    }
    fmt.Println(item)
}

Attachment iteration¶

Iterating over attachments is similar, using the AttachmentPageIterator.

// 1. Execute an attachment list request
attachmentResponse, err := client.Now2().Attachment2().Get(ctx, nil)
if err != nil {
    log.Fatal(err)
}

// 2. Create the iterator
attachmentIterator, err := attachmentapi.NewAttachmentPageIterator(attachmentResponse, client.RequestAdapter)
if err != nil {
    log.Fatal(err)
}

// 3. Iterate over attachments
if err := attachmentIterator.Iterate(ctx, false, func(attachment attachmentapi.Attachment2) bool {
    fileName, _ := attachment.GetFileName()
    fmt.Printf("Attachment: %s\n", *fileName)
    return true
}); err != nil {
    log.Fatal(err)
}

Reverse iteration¶

You can iterate backwards through pages by passing true to the reverse parameter of the Iterate method. This uses the previous link headers provided by the ServiceNow API.

err = iterator.Iterate(ctx, true, func(record *tableapi.TableRecord) bool {
    // Process records in reverse order
    return true
})

Advanced features¶

You can navigate between pages manually using methods like Next(), Previous(), First(), and Last().

// Fetch the next page of results manually
nextPage, err := iterator.Next(ctx)
if err != nil {
    log.Fatal(err)
}

// Process the items on the next page
results := nextPage.Result
for _, item := range results {
    fmt.Println(item)
}

State management¶

The iterator maintains state, allowing you to reset or restart iteration.

// Reset the iterator to the beginning
iterator.Reset()

// Restart iteration of the current page
iterator.ResetPage()

Reset(): Returns the iterator to the first page and first item.
ResetPage(): Restarts iteration of the current page.

Next steps¶

Table Operations: Learn more about the initial requests that produce paginated results.
Querying: Learn how to use queries to limit the number of records returned.