How to Implement Multipart Upload in ServiceNow for Secured Signing or any APIs requiring this

Secured Signing’s API requires file uploads in multipart/form-data format, which ServiceNow doesn’t natively support without IntegrationHub. Since Secured Signing isn’t included as a Spoke in IntegrationHub, handling binary data like attachments becomes more challenging.

However,an effective solution, shared on the ServiceNow Developer page Multipart Upload Helper , shows how to perform multipart uploads using ServiceNow’s internal REST API and the response.getStreamWriter() object. This method enables packaging and sending files to Secured Signing or any API that requires multipart uploads.

The multipart upload process in this script involves sending binary data (file attachments) to a third-party API, like Secured Signing, using this approach. The goal is to package the attachment to meet the multipart/form-data standard, which is commonly used for file uploads over HTTP.

Here’s how this multipart upload works in detail:

1. RETRIEVING THE ATTACHMENT

The first step is to retrieve the attachment you want to send. This is done using the GlideSysAttachment API, which provides access to the attachment’s binary data. This attachment will later be wrapped in a multipart format to prepare it for uploading.

var attachmentGR = new GlideSysAttachment().getContentStream(attachmentID);`

2. INTERNAL REST API (response.getStreamWriter) WORKAROUND

ServiceNow internally provides an undocumented method, response.getStreamWriter(), that allows direct streaming of data to the HTTP response. In this script, this feature is used to create a multipart-formatted temporary file that contains both metadata (such as content disposition and content type) and binary data (the attachment).

2.1 Setting Up Boundaries:

Multipart requests use boundaries to separate different parts of the request (like metadata and file content). This is critical for parsing the content properly on the server side. A unique boundary value is generated in the script:

writer.writeString("--" + boundaryValue + "\r\n");

2.2 Adding Metadata (Content-Disposition):

The Content-Disposition header indicates the disposition type (form-data) and provides additional information about the content, such as the name of the form field and the file’s name:

writer.writeString('Content-Disposition: form-data; name="file"; filename="' + fileName + '"\r\n');

2.3 Adding Content-Type:

This tells the server the MIME type of the file (e.g., image/png, application/pdf):

writer.writeString('Content-Type: ' + contentType + '\r\n');

2.4 Separating Headers from Content:

After defining the metadata, an empty line is added (as required by the multipart format) to separate the headers from the binary data:

writer.writeString('\r\n');

2.5 Writing the Binary Data:

The actual binary file is then written to the stream:

writer.writeStream(inputStream);

2.6 Closing the Boundary:

Finally, the closing boundary is added, indicating the end of the multipart content:

writer.writeString("\r\n--" + boundaryValue + "--\r\n");

In summary, this method uses response.getStreamWriter() to simulate how multipart data is packaged in a real HTTP request.

3. SAVING MULTIPART CONTENT AS AN ATTACHMENT

After creating the multipart-formatted content using the getStreamWriter object, the script saves it back as a temporary attachment in ServiceNow. This temporary attachment holds the properly formatted multipart request, including headers, boundaries, and binary data, in clear text.

request.saveResponseBodyAsAttachment(this.grHostRecord.getTableName(), this.grHostRecord.sys_id, this.attachmentName);

This step is crucial because it allows ServiceNow to store the multipart content temporarily, which will be used in the next step to send the data to the third-party API.

4. SAVING THE MULTIPART DATA TO THE SECURED SIGNING API

Once the multipart-formatted content is saved as an attachment, the script sends the attachment’s sys_id directly as the body of the HTTP request. This is done using the setRequestBodyFromAttachment() method:

restMessage.setRequestBodyFromAttachment(mpHelper.getBodyId());

This effectively sends the multipart-formatted attachment to the external service (in this case, SecuredSigning), with all headers, boundaries, and file content intact.

4. CLEAN UP: DELETING THE TEMPORARY MULTIPART ATTACHMENT

After the multipart upload is completed, the script deletes the temporary multipart attachment that was created specifically for this request. This helps keep the ServiceNow instance clean and avoids cluttering it with unnecessary temporary files:

mpHelper.deleteBody();

Key Functions Explained

• response.getStreamWriter():
  Allows direct writing of headers, boundaries, and binary content into an HTTP response. This is used to manually construct a multipart-formatted message.
• MultipartHelper Class:
  This helper class handles the entire process of preparing the multipart request. It sets the host record, adds attachments, and generates a temporary multipart attachment that can later be sent via HTTP.
• setRequestBodyFromAttachment():
  This function is a RESTMessageV2 method that allows you to send the content of an attachment (in this case, the multipart-formatted attachment) as the body of a REST API request.

The Multipart Workflow

1. Create Multipart Data:
   Using response.getStreamWriter(), metadata and binary content are wrapped in a multipart format.
2. Save the Multipart Data as an Attachment:
   This multipart-formatted content is saved as a temporary attachment in ServiceNow.
3. Send the Multipart Data:
   The temporary attachment is sent to the third-party API using setRequestBodyFromAttachment().
4. Clean Up:
   The temporary attachment is deleted after it has been sent, keeping the system clean.

Conclusion

The multipart upload process in ServiceNow involves utilizing response.getStreamWriter() to construct multipart-formatted data, temporarily store it as an attachment, and subsequently send it via a REST API call. This approach ensures compliance with the multipart/form-data standard, enabling seamless binary data uploads to third-party systems.