Retrieve attachments and attachment metadata

  • Release version: Zurich
  • Updated July 31, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Retrieve attachments and attachment metadata

    TheNowAttachmentService APIin ServiceNow enables customers to manage attachments efficiently within their ServiceNow instance. This includes uploading attachments to specific records, downloading one or multiple attachments, deleting attachments, validating attachments by hash comparison, and retrieving attachment metadata generated upon upload.

    Show full answer Show less

    This API provides multiple method implementations to suit different programming approaches: completion handlers, async/await patterns, and (deprecated) Combine publishers. Before using the API, you must import the NowData framework and initialize a NowAttachmentService object.

    Key Features

    • Upload attachments: Attach files and associate them with specific ServiceNow records.
    • Download attachments: Retrieve one or multiple attachments from your instance.
    • Delete attachments: Remove attachments as needed.
    • Validate attachments: Ensure attachment integrity by comparing computed and expected hashes.
    • Retrieve attachment metadata: Access metadata generated at upload, useful for managing and displaying attachment information.
    • Flexible method usage: Choose from completion handlers, async/await, or Combine publishers (deprecated) according to your development preferences.
    • Attachment metadata pagination: Use the attachmentMetadataPaginator(filter:limit:) method to handle large sets of metadata with a Paginator object, enabling easy iteration and infinite scroll UI implementations in UIKit or SwiftUI.

    Practical Use and Implementation

    To start using the API, import the NowData framework and initialize the service object with the instance URL. For handling large metadata sets, leverage the Paginator's methods such as first(), last(), next(), previous(), and reset() to navigate pages of results. The Paginator supports subscription to publishers on appropriate dispatch queues, facilitating smooth UI updates and efficient data loading.

    Note that some paginator methods may throw exceptions if, for example, there are no additional pages to fetch, so error handling is recommended.

    Benefits for ServiceNow Customers

    • Streamlined attachment management integrated directly with ServiceNow records.
    • Support for robust and flexible programming models to suit various app development needs.
    • Efficient handling of large attachment metadata sets, improving UI responsiveness and user experience.
    • Enhanced data integrity through attachment validation capabilities.

    The NowAttachmentService API enables you to perform CRUD operations on attachments and retrieve attachment metadata from your ServiceNow instance.

    Using this API you can:
    • Upload attachments to your ServiceNow instance and associated them to a specific record.
    • Download one or more attachments.
    • Delete attachments.
    • Validate an attachment by comparing the computed hash of the attachment to the expected hash.
    • Download attachment metadata. This metadata is generated by your ServiceNow instance when an attachment is uploaded.

    For additional information on working with attachments, see Attachment API.

    All NowAttachmentService methods provide three implementations for returning results data. One that calls a completion handler with the return results, one that preforms an async/await, and another that returns a Combine publisher (deprecated). For example, each upload() method uploads and associates a specified attachment to a specified record. However, the NowAttachmentService - upload(data: Data, configuration: NowAttachmentUploadConfiguration, progressUpdate: @escaping ProgressUpdate, completion: @escaping (Result<NowAttachmentMetadata, NowDataError>)) method calls a completion handler with the return results, the NowAttachmentService - upload(data: Data, configuration: NowAttachmentUploadConfiguration, progressUpdate: @escaping ProgressUpdate) async throws method performs an async/await, and the NowAttachmentService - upload(data: Data, configuration: NowAttachmentUploadConfiguration, progressUpdate: @escaping ProgressUpdate) method returns a Combine publisher.

    Before you are able to use the NowAttachmentService API, you must import NowData and then initialize a NowAttachmentService object.
    // Import the NowData framework
import NowData

func makeAttachmentService(instanceUrl: URL, 
  completion: @escaping ((Result<NowAttachmentService, NowServiceErrors>) → Void))

    Attachment metadata pagination

    You can use the NowAttachmentService methods to download attachment metadata for one or more attachments. When downloading metadata from multiple attachments, you may want to use the NowAttachmentService - attachmentMetadataPaginator(filter: Filter, limit: Int) method, which returns a Paginator object that enables you to easily iterate over the potentially large amount of data that is returned. You typically use paginated return results to provide infinite scroll capabilities for data presented inside a UITableView, a UICollectionView (UIKit), or a List (SwiftUI), or to simplify page iteration of results in general.

    After obtaining a Paginator object, subscribe to its publisher to start receiving data.
    paginator.publisher
  .subscribe(on: DispatchQueue.global())
  .receive(on: DispatchQueue.main)
  .sink { ... }
  .store(in: &subscriptions)
    The returned Paginator object provides the following methods that enable you to page through the returned records:
    • first()
    • last()
    • next()
    • previous()
    • reset()
    Note:
    Some Paginator methods may throw an exception, such as when there are no more pages to fetch.

    In addition, the Paginator object provides properties that enable you to obtain insights into the paginated data. For additional details on these properties and the available methods, see Paginator API - iOS.