Attachment

What It Is

An attachment in ServiceNow is a binary file associated with any record in the platform, stored in a two-table architecture: sys_attachment holds the metadata (filename, size, content type, table reference), while sys_attachment_doc contains the actual file content as compressed binary data. Unlike generic IT file storage systems, ServiceNow attachments are deeply integrated with the platform's access control, workflow, and audit systems. Each attachment inherits security context from its parent record and can trigger business rules, script actions, and approval workflows. The platform treats attachments as first-class data objects, not merely files dropped into folders.

Architecturally, attachments sit at the persistence layer of ServiceNow's three-tier architecture, directly above the database but below the application logic that governs forms, lists, and workflows. This positioning enables attachments to participate in all platform services: they respect domain separation, participate in import sets, get included in update sets when attached to configuration records, and flow through Integration Hub spokes. The GlideRecord API provides attachment manipulation methods, and the REST API exposes attachment operations as native endpoints. This deep integration distinguishes ServiceNow attachments from external file storage solutions that require custom integration work.

The business function centers on evidence preservation and collaboration in IT service management. When a user reports a laptop screen crack with a photo, that attachment becomes evidence linked to the incident's lifecycle. When a change requires architectural diagrams, those files travel with the change record through approval workflows, becoming part of the permanent audit trail. In knowledge management, attachments provide supporting documentation that maintains relevance as articles get updated. This isn't just file storage—it's contextual document management where files live and die with the business processes they support.

ServiceNow designed this two-table split for both performance and philosophical reasons. Storing file content separately from metadata allows the platform to query attachment lists without loading binary data, critical for form performance when records have dozens of attachments. The design also reflects ServiceNow's commitment to treating everything as structured data—even binary files get metadata fields, audit trails, and relationship management. Alternative approaches like external file systems or single-table storage would sacrifice either performance or the platform's unified data model. The current design prioritizes platform integration over raw storage efficiency.

End users interact with attachments through drag-and-drop on forms and email integrations, treating them as natural extensions of their work artifacts. They expect attachments to follow security rules—accessible to the same people who can see the parent record—and to persist through record state changes. Administrators manage attachment behavior through Attachment Rules, file size limits, and content type restrictions, focusing on security and storage management. Developers work with attachments programmatically through GlideSysAttachment APIs, create custom attachment processing workflows, and build integrations that move files between ServiceNow and external systems. Process owners care about attachment compliance, retention policies, and ensuring critical documentation doesn't get lost during record transitions.

Without attachments, ServiceNow would lose much of its value as an IT service management platform. Incident management would devolve into text-only descriptions, forcing users to store evidence in external systems and breaking audit trails. Change management would lack supporting documentation, making approvals based on incomplete information. Knowledge management would become pure text, eliminating the rich documentation that makes articles useful. The platform would fragment into a system of record that references important files stored elsewhere, destroying the unified workspace that drives adoption. Email integrations would lose file forwarding capability, forcing manual processes that bypass the platform entirely.

Where It Fits in the Platform

Attachments occupy a unique position in ServiceNow's data architecture, functioning as both dependent data objects and independent entities with their own lifecycle. They inherit access controls from parent records through the platform's ACL system, but maintain separate audit trails and can be manipulated independently through APIs and batch operations. This dual nature allows attachments to participate in platform services like data replication and backup while maintaining tight coupling to business records. The attachment system bridges ServiceNow's structured data model with the unstructured file world, providing platform-native handling for binary content.

The platform treats attachment storage as a first-class concern, with dedicated configuration options for encryption at rest, compression algorithms, and storage location management. In cloud instances, attachments automatically benefit from ServiceNow's enterprise storage infrastructure, while on-premises deployments require careful planning around disk space and backup strategies. The system integrates with the platform's performance monitoring, alerting administrators when attachment storage approaches capacity limits or when individual files exceed configured size thresholds.

Key Relationships:

• Access Control Lists (ACLs) — Attachments inherit read/write permissions from their parent records through standard ACL evaluation. Special attachment-specific ACLs can override this inheritance for scenarios requiring different file access than record access.
• Attachment Rules — Configuration records that define file type restrictions, size limits, and access controls per table. These rules execute before attachment upload and can block files that violate organizational policies.
• Email Processing — Inbound email attachments automatically convert to ServiceNow attachments on target records. The email system respects attachment rules and can filter or quarantine files based on content type or size.
• Integration Hub — Spokes can read, create, and transfer attachments between ServiceNow and external systems. Attachment handling in flows requires explicit steps since binary data doesn't flow through standard data pills.
• Update Sets — Attachments on configuration records (like Knowledge articles) get captured in update sets and migrate between instances. Attachments on data records don't participate in update sets, requiring separate migration strategies.
• Domain Separation — Attachments respect domain boundaries through their parent record's domain assignment. Users can only access attachments in their domain scope, and cross-domain attachment sharing requires explicit configuration.

How You Encounter This in Practice

Attachment Rules Blocking Business-Critical Files

You're a ServiceNow admin and users are complaining that they can't attach architectural diagrams to change requests—the files are getting rejected with cryptic error messages. You discover that someone configured attachment rules to block .vsd and .drawio files as "potentially unsafe," but the change management process requires these technical diagrams for approval. The rules are table-specific, so the same files upload fine to knowledge articles but fail on change requests.

Understanding attachment rules unlocks the ability to create nuanced file policies that balance security with business needs. You can configure different rules per table, allowing CAD files on change requests while blocking them on incidents. You can set up role-based exceptions, letting architects upload technical files while restricting other users. You can also implement size limits that vary by record type—allowing larger files on major changes while keeping incident attachments small for email performance.

Without this knowledge, administrators typically take the path of least resistance: either disable attachment rules entirely (creating security risks) or maintain overly restrictive policies that force users to store critical files outside ServiceNow. Both approaches undermine the platform's value as a single source of truth for IT processes.

Performance Issues from Attachment-Heavy Records

You're a developer investigating why certain incident forms load slowly, and you discover that some records have 50+ small screenshots attached—each one a separate database query when the form renders. Users have been attaching individual error screenshots instead of combining them into single documents, creating records with massive attachment lists. The form's attachment widget loads metadata for all files upfront, causing 2-3 second delays on records that should render instantly.

Understanding the attachment architecture reveals why the two-table design helps with metadata queries but doesn't eliminate the performance impact of large attachment counts. You can implement client scripts that lazy-load attachment lists, create business rules that consolidate multiple small attachments, or develop custom attachment widgets that paginate large lists. You might also discover that certain attachment operations trigger unnecessary business rules, contributing to the performance problem.

Developers without this understanding often blame general form performance or database issues, missing the specific attachment-related bottleneck. They might optimize unrelated queries while ignoring the attachment metadata loading that's actually causing the delay.

Attachment Security Gaps During Record Transfers

You're an administrator implementing a new assignment group workflow where incidents get transferred between internal IT and an external vendor, and you realize that sensitive attachments remain accessible to the original group even after transfer. The incident's assignment group changed, but attachment access follows the record's ACL inheritance, which doesn't automatically revoke access from users who previously had legitimate access. Confidential client data in attachments is now visible to people who shouldn't see it in the new context.

Understanding attachment access control reveals that you need explicit business rules or workflow steps to handle attachment security during record transitions. You can create attachment-specific ACLs that evaluate current assignment group membership, implement attachment scrubbing rules that remove sensitive files during transfers, or build approval workflows that require manual review before external groups gain access to existing attachments.

Administrators without this knowledge assume that changing record ownership automatically adjusts attachment access, creating security gaps that persist until someone notices inappropriate access during an audit. They might also implement record-level security without considering that attachments maintain their own access patterns.

What People Get Wrong

This misconception treats attachments as simple file storage when they're actually complex data objects with metadata, relationships, and access controls that must be preserved during migrations. When administrators export and import data without considering attachment architecture, they often lose file-to-record associations, break access controls, or corrupt binary data through improper encoding. The sys_attachment and sys_attachment_doc tables have a specific relationship that must be maintained—importing one without the other creates orphaned metadata or binary data with no context.

The misconception exists because attachments appear to behave like simple files from a user perspective—you upload a file, it appears in a list, you download it again. This surface simplicity hides the underlying complexity of record relationships, domain separation, access inheritance, and binary data management. Administrators coming from traditional file system backgrounds expect straightforward copy-and-paste operations that don't account for ServiceNow's integrated data model.

In production, this misunderstanding leads to failed migrations where critical documentation disappears during instance refreshes or data transfers. Integration projects fail when external systems can't properly handle ServiceNow's attachment API requirements. Emergency data recovery efforts become complex archaeology projects as administrators try to reconstruct file-to-record relationships from incomplete exports. The impact compounds over time as users lose confidence in the platform's ability to preserve important files, leading to shadow IT storage solutions.

While attachment access does inherit from parent record ACLs by default, this inheritance can be overridden with attachment-specific ACLs, and the timing of access evaluation can create unexpected security gaps. Users who gained access to attachments at one point may retain that access even after record permissions change, since attachment access gets cached in certain scenarios. Additionally, attachment URLs can be shared directly, potentially bypassing record-level security checks if not properly configured. Some email integrations and API operations handle attachment access differently than interactive form access.

This misconception arises because the majority of attachment access does follow standard patterns—most users accessing files through forms experience the expected security behavior. The edge cases involving direct URLs, cached access, system account operations, and cross-domain scenarios represent a small percentage of interactions but carry disproportionate security risk. Administrators testing attachment security through normal UI workflows may never encounter these edge cases until they become security incidents.

The production consequences include unauthorized access to sensitive files, compliance violations when confidential documents leak across organizational boundaries, and security audit failures when attachment access doesn't match documented record permissions. Incident response becomes complicated when administrators can't quickly determine who has accessed specific files or when access was granted. Integration security reviews miss attachment-specific vulnerabilities, creating gaps in otherwise comprehensive access control implementations.

Admin vs Developer Perspective

For Admins

Admins primarily configure attachment rules through System Security > Attachment Rules to control who can upload, download, or delete files on different tables. They monitor attachment storage consumption through the sys_attachment table and must balance security with usability when setting maximum file sizes and allowed extensions. Troubleshooting attachment issues often involves checking attachment rule configurations, verifying file size limits, and understanding why certain users can't access files. The most critical admin decision is setting appropriate security rules, since overly permissive attachment access can create data exposure risks across the entire platform.

For Developers

Developers work with attachments through the GlideSysAttachment API for programmatic file operations and query sys_attachment records to manage file metadata. They must understand the two-table storage model where sys_attachment holds metadata while sys_attachment_doc contains the actual file data. Common scripting patterns include iterating through attachments on records, programmatically creating attachments from external sources, and building custom attachment viewers or download mechanisms. Developers frequently need to handle attachment operations in Business Rules and Script Includes, particularly for automated document processing workflows.

How It Connects to Other Concepts

• Access Control Lists (ACLs) — While attachment rules control file-level security, table ACLs determine whether users can even see records that have attachments. The interaction between these two security layers often confuses administrators, especially when users report they can see a record but can't access its files. Attachment rules effectively create a second security layer that evaluates after standard ACL checks.
• Email Processing — Inbound email processors automatically create attachment records when emails contain file attachments, creating direct relationships between sys_email records and their associated sys_attachment records. This automation bypasses normal attachment rules validation, which can create security gaps if not properly configured.
• Journal Fields — When users add attachments to records, the system automatically creates journal entries in activity streams and work notes, linking file operations to the audit trail. The sys_audit table tracks attachment additions and deletions as separate audit events, providing a complete history of file activity on records.
• Import Sets — Transform maps can programmatically create attachments during data imports, but this requires careful scripting since the standard import process doesn't handle binary data. Developers must use the GlideSysAttachment API in transform scripts to properly encode and attach files from external systems during import operations.
• REST API — The Attachment API (/api/now/attachment) provides external systems with programmatic access to upload and download files, but authentication and attachment rules still apply to API calls. Integration developers must understand that REST API attachment operations respect the same security model as the web interface, including file size limits and extension restrictions.
• Workflow and Flow Designer — Process automation can trigger based on attachment events through Business Rules or Flow triggers that monitor the sys_attachment table for inserts or updates. This enables automated document processing workflows, like extracting text from PDFs or routing records based on attached file types, creating powerful integrations between file operations and business processes.

Junior vs Senior Knowledge Gap

Junior developers typically treat attachments as simple file uploads and miss the critical security implications of attachment rules configuration. They often create overly permissive attachment rules during development without understanding that these rules cascade across all records of a table type, potentially exposing sensitive documents to unauthorized users. The most common mistake is setting up attachment rules based on immediate functional needs without considering the broader security model, leading to data exposure issues that only surface in production when users start accessing files they shouldn't see. Many juniors also struggle with the concept that attachment rules operate independently from table ACLs, creating confusion when troubleshooting access issues.

The mental model shift happens when professionals understand that attachments are not just files—they're security-controlled data objects with their own lifecycle and access patterns. Experienced developers recognize that the two-table storage architecture (sys_attachment and sys_attachment_doc) exists for performance reasons and affects how they write queries and scripts. They also understand that attachment operations can significantly impact database performance, especially when processing large files or bulk attachment operations, leading them to implement more sophisticated error handling and progress tracking in their code. Senior professionals think about attachment storage as a finite resource that requires monitoring and management, not an unlimited capability.

What experienced architects know that never appears in documentation is that attachment deletion doesn't immediately free up database space—the platform uses a cleanup job that runs periodically to actually remove file data from sys_attachment_doc. They also understand that attachment rules can create significant performance bottlenecks when they involve complex script conditions, since these scripts execute every time someone accesses a file. Senior professionals recognize that email attachments and manually uploaded attachments behave differently in terms of virus scanning and content filtering, affecting how they design secure document processing workflows. They know to monitor the attachment processing queue during high-volume operations and understand the relationship between attachment operations and instance memory consumption.

An experienced architect asks questions about attachment lifecycle management that juniors never consider: How will we handle attachment archival and cleanup? What's the long-term storage growth pattern? How will attachment rules interact with our existing role-based security model? What happens to attachments when parent records are deleted through business rules versus manual deletion? They also investigate the specific attachment scanning and anti-malware capabilities available in their instance, understanding that different deployment types have different security scanning capabilities. Most importantly, senior professionals always ask about the business impact of attachment downtime or corruption, leading them to implement proper backup and recovery strategies for file data.

Quick Reference

• The sys_attachment_doc table stores actual file content in a data field with a default maximum size of 1GB per file, but this limit is configurable through system properties.
• Attachment rules with script conditions execute every time a user attempts to access a file, making complex rules a potential performance bottleneck on high-traffic tables.
• The content_type field in sys_attachment is auto-detected from file headers and cannot be spoofed by changing file extensions, providing a security layer against malicious file uploads.
• Deleted attachment records remain in sys_attachment_doc until the scheduled cleanup job runs, meaning database storage doesn't immediately decrease after attachment deletion.
• The GlideSysAttachment API methods copy() and writeBase64() bypass attachment rule validation, making them powerful but potentially dangerous for security if not properly controlled.
• Email attachments automatically inherit the security context of their parent email record, which can create unexpected access patterns when emails are forwarded between different security groups.
• The state field in sys_attachment tracks upload progress and can indicate partially uploaded or corrupted files that need cleanup.
• Attachment rules evaluate in order, with the first matching rule taking precedence—there's no rule inheritance or combination logic, making rule ordering critical for complex security scenarios.
• The average_image_color field automatically calculates for image attachments and can be used for UI theming or content categorization in custom applications.
• Virus scanning results are stored in the hash field and can prevent file downloads if malware is detected, but scanning availability depends on instance configuration and licensing.