serac-labs Document Management for ServiceNow
Document Management handles attachments, templates, and document generation.
Document Architecture
Record
├── Attachments (sys_attachment)
│ └── Attachment Data (sys_attachment_doc)
├── Generated Documents
└── Document Templates
Key Tables
| Table | Purpose |
|---|---|
sys_attachment |
Attachment metadata |
sys_attachment_doc |
Attachment content |
sys_report_template |
Report templates |
dms_document |
Document records |
Attachments (ES5)
Upload Attachment
// Attach file to record (ES5 ONLY!)
function attachFile(tableName, recordSysId, fileName, contentType, content) {
var attachment = new GlideSysAttachment()
// Content can be base64 encoded string
var attachmentSysId = attachment.write(tableName, recordSysId, fileName, contentType, content)
return attachmentSysId
}
// Example
var base64Content = "SGVsbG8gV29ybGQh" // Base64 encoded
attachFile("incident", incidentSysId, "notes.txt", "text/plain", base64Content)
Read Attachment
// Read attachment content (ES5 ONLY!)
function getAttachmentContent(attachmentSysId) {
var attachment = new GlideSysAttachment()
var content = attachment.getContent(attachmentSysId)
return content
}
// Get attachment as base64
function getAttachmentBase64(attachmentSysId) {
var attachment = new GlideSysAttachment()
var bytes = attachment.getBytes(attachmentSysId)
// Convert to base64
var base64 = GlideBase64.encode(bytes)
return base64
}
List Attachments
// Get all attachments for record (ES5 ONLY!)
function getRecordAttachments(tableName, recordSysId) {
var attachments = []
var gr = new GlideRecord("sys_attachment")
gr.addQuery("table_name", tableName)
gr.addQuery("table_sys_id", recordSysId)
gr.query()
while (gr.next()) {
attachments.push({
sys_id: gr.getUniqueValue(),
file_name: gr.getValue("file_name"),
content_type: gr.getValue("content_type"),
size_bytes: gr.getValue("size_bytes"),
created_on: gr.getValue("sys_created_on"),
created_by: gr.sys_created_by.getDisplayValue(),
})
}
return attachments
}
Copy Attachments
// Copy attachments between records (ES5 ONLY!)
function copyAttachments(sourceTable, sourceSysId, targetTable, targetSysId) {
var attachment = new GlideSysAttachment()
attachment.copy(sourceTable, sourceSysId, targetTable, targetSysId)
}
// Copy specific attachment
function copyOneAttachment(attachmentSysId, targetTable, targetSysId) {
var source = new GlideRecord("sys_attachment")
if (!source.get(attachmentSysId)) {
return null
}
var attachment = new GlideSysAttachment()
var content = attachment.getBytes(attachmentSysId)
return attachment.write(
targetTable,
targetSysId,
source.getValue("file_name"),
source.getValue("content_type"),
content,
)
}
Document Templates (ES5)
Create Document Template
// Create document template (ES5 ONLY!)
var template = new GlideRecord("sys_report_template")
template.initialize()
template.setValue("name", "Incident Summary Report")
template.setValue("table", "incident")
template.setValue("description", "Summary report for incident resolution")
// Template content with placeholders
template.setValue(
"template",
"<html>\n" +
"<head><title>Incident Summary</title></head>\n" +
"<body>\n" +
"<h1>Incident Summary Report</h1>\n" +
"<h2>${number}</h2>\n" +
"<p><strong>Description:</strong> ${short_description}</p>\n" +
"<p><strong>Caller:</strong> ${caller_id.name}</p>\n" +
"<p><strong>Priority:</strong> ${priority}</p>\n" +
"<p><strong>State:</strong> ${state}</p>\n" +
"<p><strong>Resolution:</strong> ${close_notes}</p>\n" +
"<p><strong>Resolved By:</strong> ${resolved_by.name}</p>\n" +
"<p><strong>Resolved On:</strong> ${resolved_at}</p>\n" +
"</body>\n" +
"</html>",
)
template.insert()
Generate Document from Template
// Generate document from template (ES5 ONLY!)
function generateDocumentFromTemplate(templateName, recordSysId) {
// Get template
var template = new GlideRecord("sys_report_template")
if (!template.get("name", templateName)) {
return null
}
// Get record
var tableName = template.getValue("table")
var gr = new GlideRecord(tableName)
if (!gr.get(recordSysId)) {
return null
}
// Process template
var content = template.getValue("template")
content = processTemplateVariables(content, gr)
return content
}
function processTemplateVariables(template, gr) {
// Replace ${field} and ${field.property} patterns
var pattern = /\$\{([^}]+)\}/g
var match
while ((match = pattern.exec(template)) !== null) {
var fieldPath = match[1]
var value = getFieldValue(gr, fieldPath)
template = template.replace(match[0], value)
}
return template
}
function getFieldValue(gr, fieldPath) {
var parts = fieldPath.split(".")
var value = gr
for (var i = 0; i < parts.length; i++) {
if (!value) return ""
if (i < parts.length - 1) {
// Reference field - get referenced record
value = value[parts[i]].getRefRecord()
} else {
// Final field
if (value.isValidField && value.isValidField(parts[i])) {
value = value[parts[i]].getDisplayValue() || value.getValue(parts[i])
} else {
value = ""
}
}
}
return value || ""
}
PDF Generation (ES5)
Generate PDF
// Generate PDF from HTML (ES5 ONLY!)
function generatePDF(htmlContent, fileName) {
try {
var pdfCreator = new sn_pdfgeneratorutils.PDFGenerationAPI()
var pdfBytes = pdfCreator.convertToPDF(htmlContent)
// Return as base64
return {
success: true,
content: GlideBase64.encode(pdfBytes),
fileName: fileName || "document.pdf",
}
} catch (e) {
gs.error("PDF generation failed: " + e.message)
return {
success: false,
error: e.message,
}
}
}
// Generate and attach PDF to record
function generateAndAttachPDF(templateName, recordSysId, fileName) {
// Generate HTML from template
var html = generateDocumentFromTemplate(templateName, recordSysId)
if (!html) {
return { success: false, error: "Template generation failed" }
}
// Convert to PDF
var pdf = generatePDF(html, fileName)
if (!pdf.success) {
return pdf
}
// Get table name from template
var template = new GlideRecord("sys_report_template")
template.get("name", templateName)
var tableName = template.getValue("table")
// Attach PDF
var attachmentSysId = attachFile(tableName, recordSysId, fileName, "application/pdf", pdf.content)
return {
success: true,
attachment_sys_id: attachmentSysId,
}
}
Document Workflow (ES5)
Document Approval
// Create document for approval (ES5 ONLY!)
function submitDocumentForApproval(documentSysId, approvers) {
var doc = new GlideRecord("dms_document")
if (!doc.get(documentSysId)) {
return { success: false, message: "Document not found" }
}
// Update state
doc.setValue("state", "pending_approval")
doc.update()
// Create approval records
for (var i = 0; i < approvers.length; i++) {
var approval = new GlideRecord("sysapproval_approver")
approval.initialize()
approval.setValue("sysapproval", documentSysId)
approval.setValue("approver", approvers[i])
approval.setValue("state", "requested")
approval.insert()
}
// Notify approvers
gs.eventQueue("document.approval.requested", doc, approvers.join(","), "")
return { success: true }
}
Version Control
// Create new document version (ES5 ONLY!)
function createDocumentVersion(documentSysId, newContent, changeNotes) {
var doc = new GlideRecord("dms_document")
if (!doc.get(documentSysId)) {
return null
}
// Get current version
var currentVersion = parseInt(doc.getValue("version"), 10) || 1
var newVersion = currentVersion + 1
// Archive current version
var archive = new GlideRecord("dms_document_version")
archive.initialize()
archive.setValue("document", documentSysId)
archive.setValue("version", currentVersion)
archive.setValue("content", doc.getValue("content"))
archive.setValue("created_by", gs.getUserID())
archive.insert()
// Update document with new version
doc.setValue("version", newVersion)
doc.setValue("content", newContent)
doc.work_notes = "Version " + newVersion + ": " + changeNotes
doc.update()
return {
document_sys_id: documentSysId,
version: newVersion,
}
}
// Get document version history
function getDocumentVersions(documentSysId) {
var versions = []
var version = new GlideRecord("dms_document_version")
version.addQuery("document", documentSysId)
version.orderByDesc("version")
version.query()
while (version.next()) {
versions.push({
version: version.getValue("version"),
created_on: version.getValue("sys_created_on"),
created_by: version.sys_created_by.getDisplayValue(),
})
}
return versions
}
Attachment Security (ES5)
Check Attachment Access
// Check if user can access attachment (ES5 ONLY!)
function canAccessAttachment(attachmentSysId) {
var attachment = new GlideRecord("sys_attachment")
if (!attachment.get(attachmentSysId)) {
return false
}
// Check access to parent record
var parentTable = attachment.getValue("table_name")
var parentSysId = attachment.getValue("table_sys_id")
var parent = new GlideRecord(parentTable)
return parent.get(parentSysId) // Returns false if no read access
}
Moving files in and out: the attachment tools
Everything above this line is the script side. It can copy an attachment from one record to another and
read what is already there, and it can do neither of the two things people usually want: get a file the
agent is holding into a record, or get a file out of the instance and into the agent. A background
script has no access to the agent's filesystem and cannot return megabytes of bytes to it. Six tools go
over /api/now/attachment instead.
| Tool | Direction | Takes |
|---|---|---|
snow_upload_attachment |
in | base64 in content |
snow_file_upload |
in | base64 in file_data — same endpoint, different parameter names |
snow_attach_file |
in | a local path, read and posted multipart |
snow_get_attachments |
out | table_name + table_sys_id, returns metadata only |
snow_file_download |
out | attachment_sys_id, returns base64 + content type |
snow_delete_attachment |
— | attachment_sys_id, deletes permanently |
base64 or a path
snow_upload_attachment and snow_file_upload hit the same endpoint with the same semantics; they differ
only in what the parameters are called (content/table_sys_id versus file_data/record_sys_id).
Neither reads a file — you hand them bytes you already have.
snow_attach_file is the one that reads from disk. It stats the file first and refuses above
max_size_mb, which defaults to 25 — a client-side guard, not the instance's. The instance has its own
limit in com.glide.attachment.max_size (MB, 1024 by default but very often lowered), and
glide.attachment.extensions restricts which suffixes are accepted at all. A file inside your 25 MB and
outside the instance's limit fails at the API with a 400, not at the guard.
Base64 inflates by a third, so a 24 MB file is a 32 MB request body. If you are pushing anything large,
prefer snow_attach_file — multipart sends the bytes as they are.
Reading a file back
snow_get_attachments returns metadata only: sys_id, file_name, size_bytes, content_type. Two
calls to get content, always:
const list = await snow_get_attachments({ table_name: "incident", table_sys_id: incSysId })
const shot = list.attachments.find((a) => a.content_type.indexOf("image/") === 0)
const file = await snow_file_download({ attachment_sys_id: shot.sys_id }) // base64 + content_type
There is no "download every attachment on this record" call. Loop the list yourself, and check
size_bytes before you do — the response carries the whole file as base64 in the tool result.
When the table restricts attachments
Attachment access is not the parent record's ACL. It is resolved through sys_attachment, and three
things gate it independently:
glide.attachment.role— an instance property naming a role required to attach at all.- Table-level attachment control. A table can be marked so that only users with a named role may
attach or read;
sys_security_aclrows onsys_attachmentwith the parent table as their condition are the usual mechanism. - The parent record's own read ACL. Losing read on the incident loses its attachments too.
The failure shape is worth recognising because it is misleading. sys_attachment is a table like any
other, so a caller who cannot read it gets an empty list rather than an error — snow_get_attachments
returning [] on a record that visibly has attachments in the UI is a permissions answer, not an empty
record. Read failures on a single attachment tend to surface as not-found rather than forbidden, because
the platform does not confirm that a sys_id you cannot see exists. So "attachment not found" straight
after a successful listing on the same record is a permissions difference between the two reads, not a
deleted file. Check with snow_acl_explain against sys_attachment before assuming the file is gone.
snow_delete_attachment is a hard delete of the sys_attachment row and its sys_attachment_doc
chunks. There is no recycle bin and it is not captured in an update set — it is data, not configuration.
MCP Tool Integration
Available Tools
| Tool | Purpose |
|---|---|
snow_query_table |
Query attachments and templates |
snow_execute_script |
Test document scripts |
snow_artifact_manage |
Find artifacts (action: "find", type required) |
snow_get_attachments |
List what is attached to a record |
snow_file_download |
Fetch one attachment's bytes |
snow_attach_file |
Attach a local file (multipart) |
snow_upload_attachment |
Attach base64 content |
snow_file_upload |
Attach base64 content (alternative parameter names) |
snow_delete_attachment |
Delete an attachment permanently |
Example Workflow
// 1. Get record attachments
await snow_query_table({
table: "sys_attachment",
query: "table_name=incident^table_sys_id=inc_sys_id",
fields: "file_name,content_type,size_bytes,sys_created_on",
})
// 2. Generate document
await snow_execute_script({
script: `
var html = generateDocumentFromTemplate('Incident Summary', 'inc_sys_id');
gs.info('Generated: ' + (html ? 'success' : 'failed'));
`,
})
// 3. Find document templates
await snow_query_table({
table: "sys_report_template",
query: "table=incident",
fields: "name,description,table",
})
Best Practices
- File Types - Restrict allowed types
- Size Limits - Set max file sizes
- Virus Scanning - Scan uploads
- Access Control - Inherit from parent
- Version Control - Track changes
- Cleanup - Remove orphaned files
- Templates - Use for consistency
- ES5 Only - No modern JavaScript syntax