Attaching files to an Item

The Utility.pickDocument JavaScript API method allows you to display the iOS document picker to the user to select new files. Every time a file is added to the files collection, the method returns the file name to be used later with List.addItem or List.Item.updateItem. When invoking List.addItem, you will include the attachments property in the JavaScript object parameter sent to the method.


Use Utility.pickDocument to add files to the files collection and store the filename(s) in a JavaScript array. If you want, you can display the filename to the user to let him know the file will be attached to the item.

The code should be similar to the following code snippet:

// You need to define the array of filenames
var attachmentsArray = [];

function addAttachment() {
    SPlus.Utility.pickDocument(function(result) {
        // get the String with the file name and add the filename to the array
        var filename = result;
        // display the aray of filenames in a label to the user
    }, function(response) {
        //TODO: Implement how to handle errors
    }, function(response) {
        //TODO: Implement how to handle a user’s cancel

Once you selected the file(s) to be attached to the item, you will include the attachments property in the JavaScript object parameter sent to List.addItem or List.Item.updateItem as shown below:

//Create a dictionary with all the item’s attributes
var attributesDictionary = {"Title": taskName, "StartDate": startDate};

//Create a dictionary with the attachments’ information
var attachmentsDictionary = new Object()
for (var i = 0; i < attachmentsArray.length; i++){
	filename = attachmentsArray[i];
	attachmentsDictionary[filename] = "Add";

//Get ready the args parameter that will be used with List.addItem
var args = {"attachments": attachmentsDictionary, "attributes": attributesDictionary}

As seen above, you need to create an object with the attachments of the new item as filename:operation pairs. The object structure is similar to the following:


But when editing an item with List.Item.updateItem, you may need to change or delete a file from that item. To achieve those, you need to use “Update” or “Remove” instead of “Add”. Below you can find an example:


As a reference you have the following operations available:

  • Add – Attach the referenced file to the item.

  • Update – Change an existing file for another one.

  • Remove – Delete an existing file referenced by filename.