Portals, such as ArcGIS Online and ArcGIS Enterprise, can store many types of items. Most types are directly related to the ArcGIS platform, including ArcGIS documents (.mxd, .3dd, .mapx), datasets and packages (.lyr, .kml, .tpk), service urls, and so on. You can also store things like Microsoft Office documents (.docx, .pptx, .xlsx), comma-separated values (.csv), portable document format (.pdf), and a variety of image formats (.jpg, .png, .tif). Perhaps the most familiar type of portal item is a web map — a JSON description of the data in a map, along with other display and behavioral properties. Web maps are particularly useful in your ArcGIS Runtime SDK apps, as they provide a way for you to display a consistent set of data and symbology to your users. Portal items also offer the ability to make and save changes to these items, if needed.
The PortalItem class represents an individual item stored in a portal. Each item includes the following:
- Metadata—such as a unique identifier (ID), title, summary, description, thumbnail image, and tags
- Binary or text-based data—for example, the JSON that defines a web map or a feature collection, or a URL pointing to a map service, or the binary data of a tile package or shapefile
- Sharing settings—the access level and groups to whom the item is accessible
This topic will describe creating new portal items in general, setting common properties, and adding them to a portal. For information specific to working with web map portal items, see the Display a map and Save a map topics. For information about setting the right access level for your items, see Share a portal item.
Create a new portal item
A new portal item must be created in the context of a particular portal, such as your ArcGIS Online organization. The user connecting to the portal must also have permissions to create new items. See the Access the ArcGIS Platform topic for information about connecting to a portal as an authenticated user. Once you've connected to your portal, you can create a new portal item by specifying the portal on which it will be hosted, the type of data it will store, and a name (title) to display for the item. The item content can be specified when initially adding the item to the portal, or can be updated later. A new portal item can be added to the root folder, or to any available subfolder for the currently authenticated user.
See the Enums.PortalItemType enumeration for a list of available portal item types.
The following example creates a new portal item called "TES Species Summary" that will store a PDF document. It sets properties to provide a summary (short description), a description, and a set of tags to improve searchability. The code then adds the new item to the root folder on the user's portal.
// Construct a portal item, connected to a portal that is authenticated to a user that can create portal items
title: "TES Species Summary"
tags: [ "TES", "Wakim National Forest", "Endangered Species", Utils.defaultTagForTests(testType)]
snippet: "2015 TES summary report"
description: "The 2015 summary report describing the status of threatened, " +
"endangered, and sensitive species within the Wakim National Forest"
if (portalUser.addPortalItemStatus === Enums.TaskStatusCompleted)
console.log("Portal item created");
else if (portalUser.addPortalItemStatus === Enums.TaskStatusErrored)
// Add the item via the user object using the local file url to the pdf
portalUser.addPortalItemWithUrl(wakimReportItem, wakimReportUrl, "Wakim Report.pdf");
When adding a new item to a portal, you can specify a subfolder in which to store the item. The available subfolders are those that belong to the currently connected portal user. The following example gets a list of the available subfolders in which a new portal item can be stored.
if (portalUser.fetchContentStatus !== Enums.TaskStatusCompleted)
console.log("folders count = ", portalUser.folders.count);
Update a portal item
A portal item can have content that is based on simple text or on binary data. The content for a portal item may be read from a local file as text (for a CSV item, for example), as binary data (for an image file, for example), or simply set with a URL (for GIS services). You assign content to a portal item when initially adding it to the portal (PortalUser::addPortalItemWithUrl, PortalUser::addPortalItemWithJson) and you can update a portal item's content later using PortalItem::updateItemWithJson, PortalItem::updateDataWithUrl, as shown in the following example.
// update the portal item with the new pdf content
wakimReportItem.updateDataWithUrl(wakimReportUrl2, "Wakim Report.pdf");
A portal item thumbnail image can also be set, as shown in the following example.
if (wakimReportItem.updateItemPropertiesStatus !== Enums.TaskStatusCompleted)
console.log("set thumbnail for item ");
wakimReportItem.thumbnailUrl = imgPath;
For best results, a thumbnail image should be 200 pixels wide by 133 pixels high (other sizes will be adjusted to fit). Acceptable thumbnail image formats are: PNG, GIF and JPEG. The maximum file size is 1Mb
Portal item metadata, such as its title, summary, description, and so on can also be updated by calling PortalItem::updateItemProperties to save changes to the item. This method is available to the item owner and administrator of the organization only.
When a user creates a new portal item (using ArcGIS Online or an ArcGIS Runtime API) its accessibility is private by default, meaning only the owner of the item (and the organization's administrators) are able to view it. If you choose to, you can share your portal item with:
- The creator of the item and portal administrators
- Your entire organization
- Specified portal groups
To control sharing for an item, you must be able to connect to the portal as an authenticated user with the appropriate permissions (the item owner or a portal administrator).
You may also choose to share your item among combinations of the above, such as your entire organization and some specified groups, for example. See the Share a portal item topic for more information.