---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# cabrillo.attachments - Client

# cabrillo.attachments - Client {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read

The name space for Cabrillo JS attachment
functions. This enables adding and viewing attachments.

## cabrillo.attachments - addFile(String tableName, String sysId, Object params, String
options) {#ariaid-title2}

Presents a document picker and uploads the selected file.
Important:  
This method is deprecated. Use the [addFiles()](https://servicenow-prod.fluidtopics.net/v50lzCCTLFkIHjWDnjXAXA#CA-addFiles_S_S_O_S "Presents a document picker to select and upload files.") method instead.
{#CA-addFile_S_S_O_S__table_yt5_3qw_2bb__entry__3}

| Name | Type | Description |
|-|-|-|
| tableName | String | Table name of the record to which to attach the attachment. |
| sysID | String | The sys_id of the record to which to attach the attachment. |
| params | Object | Unused. Set to null. |
| options | String | Unused. Set to null. |
[Table 1. Parameters]

{#CA-addFile_S_S_O_S__table_yt5_3qw_2bb} {#CA-addFile_S_S_O_S__table_zt5_3qw_2bb__entry__2}

| Type | Description |
|-|-|
| promise | If successful a Cabrillo.Attachment object. If the operation fails, an error. |
[Table 2. Returns]

{#CA-addFile_S_S_O_S__table_zt5_3qw_2bb}  

    var table = 'incident';
    var sysID = 'a9e30c7dc61122760116894de7bcc7bd';

    cabrillo.attachments.addFile(table,
        sysID, 
        null,
        null
    ).then(function(attachment) {
        if (attachment) {
            console.log('Added a new file.', attachment);
        } else {
            console.log('User cancelled adding an attachment.');
        }
    }, function(error) {
        console.log('Failed to attach new file.', error);
    });

## cabrillo.attachments - addFiles(String tableName, String sysId, Object params, Object options) {#ariaid-title3}

Presents a document picker to select and upload files.
{#CA-addFiles_S_S_O_S__table_yt5_3qw_2bb__entry__3}

| Name | Type | Description |
|-|-|-|
| tableName | String | Name of the table that contains the record to attach the file to. |
| sysID | String | Sys_id of the record to attach the file to. |
| params | Object | Optional. Reserved for future use. Set to null. |
| options | Object | Optional. Additional settings for uploading files. { "isSingleSelection": Boolean } |
| options.isSingleSelection | Boolean | Optional. Flag that indicates whether the document picker for uploading files allows multi-selection. Valid values: * true: Only one file to upload can be selected at a time. * false: Multiple files to upload can be selected at a time. {#CA-addFiles_S_S_O_S__ul_nkl_n4f_xwb} Default: False |
[Table 3. Parameters]

{#CA-addFiles_S_S_O_S__table_yt5_3qw_2bb} {#CA-addFiles_S_S_O_S__table_wgq_ynf_xwb__entry__2}

| Type | Description |
|-|-|
| Promise | Contains any successfully created attachments and any errors. If multiple files were selected, a Cabrillo.Attachment is created for each successfully uploaded file while an error message is generated for each unsuccessful upload. Data type: Object { "attachments": [Array], "errors": [Array] } |
| Promise.attachments | Contains any successfully created attachments. Data type: Array "attachments": [Cabrillo.Attachment] |
| Promise.errors | Contains any errors. Data type: Array "errors": ["String"] |
[Table 4. Returns]

{#CA-addFiles_S_S_O_S__table_wgq_ynf_xwb}  
This example creates a button for adding multiple attachments to an incident record and checks for any upload errors.

    this.attachMultipleFilesButton = function() {
       c.log("Attempting to add multiple attachments to INC0010453");
       var table = 'incident';
       var sysID = 'fc74aefa1bfb2c10181499f1b24bcb3c';

       cabrillo.attachments.addFiles(table, sysID).then(function(result) {
          if (result) {
             handleMultipleResult(result)
          } else {
             c.log('User cancelled adding an attachment.');
          }
       }, function(error) {
          c.log('Failed to attach new files.', error);
       });
    }

    // A helper function to handle addFiles results 
    function handleMultipleResult(result) {
       c.log('Added multiple attachments.', result);
       if (result.attachments) {
          c.log('Number of new attachments', result.attachments.length);
       }
       if (result.errors) {
          c.log('Number of errors during upload', result.errors.length);
       }
    }

## cabrillo.attachments -viewFile(Cabrillo.Attachment attachment, Cabrillo.Rect sourceRect,
String sourceBase64Image) {#ariaid-title4}

Presents a document picker and uploads the selected file.
Note:  
Scaling using a sourceRect parameter with a sourceBase64 image is only supported on iOS. Android ignores these parameters and opens the image without a scaling animation.
{#CA-viewFile_CA_CR_S__table_wvb_ybf_wbb__entry__3}

| Name | Type | Description |
|-|-|-|
| attachment | Cabrillo.Attachment | Describes the attachment to view. |
| sourceRect | Cabrillo.Rect | Optional. Describes the source rectangle of the image to scale up. |
| sourceBase64Image | String | Optional. A base64 representation of the source image to scale up. |
[Table 5. Parameters]

{#CA-viewFile_CA_CR_S__table_wvb_ybf_wbb} {#CA-viewFile_CA_CR_S__table_xvb_ybf_wbb__entry__2}

| Type | Description |
|-|-|
| promise | If successful, an unresolved object, otherwise an error. |
[Table 6. Returns]

{#CA-viewFile_CA_CR_S__table_xvb_ybf_wbb}  

    // A Cabrillo.Attachment dictionary to view
    var attachment = {
        sys_id: '8e99daa3ff133100ba13ffffffffff2d',
        content_type: 'image/jpeg',
        path: '8e99daa3ff133100ba13ffffffffff2d.iix'
    };

    cabrillo.attachments.viewFile(attachment,
        null,
        null
    ).then(function() {
        // It worked. Nothing to do here.
    }, function(error) {
        console.log('Failed to view file.', error);
    });

To scale an image that was tapped into a native image viewer, the
viewFile() method accepts optional arguments for the image's rectangle
on the page as well as a base64 encoded thumbnail of the image. The thumbnail is scaled into
the full size image with an animation.

    // Grab image metadata from an image that was tapped
    var imageMetadata = imageMetadataFromEvent(event);

    // Optional rect of image on page
    var imageRect = imageMetadata.rect;

    // Optional base64 encoded image to scale up into native viewer
    var base64EncodedImage = imageMetadata.base64;

    // A Cabrillo.Attachment dictionary to view
    var attachment = {
        sys_id: '8e99daa3ff133100ba13ffffffffff2d',
        content_type: 'image/jpeg',
        path: '8e99daa3ff133100ba13ffffffffff2d.iix'
    }

    cabrillo.attachments.viewFile(attachment,
        imageRect,
        base64EncodedImage
    ).then(function() {
        // It worked. Nothing to do here.
    }, function(error) {
        console.log('Failed to view file.', error);
    });