Effortlessly Attach API Responses File to Record: Use saveResponseBodyAsAttachment()

[Community Alums]

Hey Community,

As ServiceNow professionals, we're often tasked with making API calls and handling the data returned in a meaningful way. One common scenario is saving response data as an attachment to a record in ServiceNow. Whether it's a PDF report, a JSON response, or even an XML file, the saveResponseBodyAsAttachment() method is here to make our lives a lot easier.

What is saveResponseBodyAsAttachment()?
The saveResponseBodyAsAttachment() method is a powerful tool in the RESTMessageV2 class that allows you to save the response body of an API call directly as an attachment to a record in ServiceNow. This method can handle various types of data, from binary files like PDFs to text formats such as JSON or XML.

Key Benefits

1. Automatic File Handling: No need to manually process the response and create an attachment—this method does it all in one go.
2. Versatile: It works with different data types, whether it’s binary or text.
3. Seamless Integration: Perfect for use cases where you need to attach files like reports or logs directly to ServiceNow records.

Parameters Breakdown

1. tableName (String): The name of the table where you want to attach the file. This is the table that contains the record you're working with.
2. recordSysId (String): The sys_id of the specific record you want to attach the file to. This ensures the attachment is linked to the correct record.
3. fileName (String): The name you want to give the saved file. This is how the file will appear in the attachment list.

What Does it Return?

The saveResponseBodyAsAttachment() method returns void, meaning it doesn’t provide any direct output or return value. Unlike the write() or writeBase64() methods in GlideSysAttachment, which return the sys_id of the created attachment, this method handles the attachment process without giving you the sys_id directly. If you need to track or reference the attachment later, you'll need to query the sys_attachment table based on your record and file details as I did in the real-world use case.

Using saveResponseBodyAsAttachment()
Let’s walk through a simple example:

var request = new sn_ws.RESTMessageV2();
request.setEndpoint('https://example.com/api/data');
request.setHttpMethod('GET');

// Making the API call and saving the response as an attachment
request.saveResponseBodyAsAttachment('incident', 'some-record-sys_id', 'data_report.pdf');

var response = request.execute();        
var httpResponseStatus = response.getStatusCode(); 

gs.info(" http response status_code:  " + httpResponseStatus); 

 In this snippet:

• We make a GET request to an API endpoint.
• The response body is automatically saved as a file named data_report.pdf attached to an incident record identified by some-record-sys_id.

Important Considerations

1. MID Server Roles: If you're sending the REST message through a MID server, ensure the MID server user has the necessary roles to read and write both attachment records and records in the specified table.
2. Error Handling: If the attachment fails to save, you can call getErrorMessage() on the related RESTResponseV2 object to retrieve details about the error.

Real-World Use Case
Imagine you're working on a loan management application that needs to attach PDF reports directly to loan case records. Instead of manually converting and attaching these files, the saveResponseBodyAsAttachment() method does it all in one step, reducing errors and saving time.

var httpStatus = '';
var contentType = 'application/pdf';
var recodeSysId = 'record_sys_id';
var fileName = 'Asset_Report.pdf';
var tableName = 'table_name';

var request = new sn_ws.RESTMessageV2();
request.setEndpoint('https://sandbox.plaid.com/asset_report/pdf/get');
request.setHttpMethod('POST');
request.setRequestHeader('Content-Type', 'application/json');

var requestBody = {
    client_id: 'your_client_id_here',
    secret: 'your_secret_here',
    asset_report_token: 'your_asset_report_token_here'
};
request.setRequestBody(JSON.stringify(requestBody));

request.saveResponseBodyAsAttachment(tableName, recodeSysId, fileName);

var response = request.execute();
httpStatus = response.getStatusCode();
gs.info('HTTP Status: ' + httpStatus + '\n');

if (httpStatus === 200) {
    var attachmentGR = new GlideRecord('sys_attachment');
    attachmentGR.addQuery('table_name', tableName);
    attachmentGR.addQuery('table_sys_id', recodeSysId);
    attachmentGR.addQuery('file_name', fileName);
    attachmentGR.orderByDesc('sys_created_on');
    attachmentGR.setLimit(1);
    attachmentGR.query();

    if (attachmentGR.next())
        gs.info('PDF file successfully attached to the record. Attachment sys_id: ' + attachmentGR.sys_id);
} else {
    gs.error("Asset PDF Report Not generated. HTTP Status: " + httpStatus);
 }

Here, a loan report is generated via an API call and directly attached to the respective loan case record in ServiceNow. Simple, efficient, and less prone to errors.

Conclusion
The saveResponseBodyAsAttachment() method is a lifesaver when you need to automate the process of saving API responses as attachments. By integrating this method into your ServiceNow flow/workflows, you can handle file attachments with ease, ensuring that important documents are always linked to the correct records without manual intervention.

So the next time you’re dealing with an API response that needs to be saved as an attachment, give saveResponseBodyAsAttachment() a try—you won’t be disappointed!

[Hetang Modi]

Does the "saveResponseBodyAsAttachment" work seamlessly when used with executeAsync() as well?