Portals, such as ArcGIS Online and Portal for ArcGIS, 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 Esri.ArcGISRuntime.Portal.ItemType 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.
// (myPortal is a connection to a portal as a user with permission to create new portal items)
var item = new PortalItem(myPortal, PortalItemType.PDF, "TES Species Summary");
// the Snippet property provides a brief summary for the item
item.Snippet = "2015 TES summary report";
// use the Description to describe the item in more detail
item.Description = "The 2015 summary report describing the status of threatened, endangered, and sensitive species within the Wakim National Forest.";
// provide relevant tags to help users find the item
item.Tags.Add("Wakim National Forest");
// add the new item (without content) to the portal
var newPortalItem = await myPortal.User.AddPortalItemAsync(item);
Don't be confused by the static PortalItem.CreateAsync method, which is used to instantiate a portal item in your code using the unique ID for an existing item on the portal. Despite what the name may imply, it is not used to create a brand new portal item.
When adding a new item to a portal, you can specify the item content and 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.
// fill a list box with the user's folder names
var myStuff = await myPortal.User.GetContentAsync();
foreach (var folder in myStuff.Folders)
The following example adds a new portal item into a folder selected by the user.
// get the selected subfolder (if any) where the new item will be stored
var subFolder = PortalFoldersListBox.SelectedItem as PortalFolder;
// add the new item (without content) to the portal
var newPortalItem = await myPortal.User.AddPortalItemAsync(item, null, subFolder);
If you add an empty portal item, you can load the content (data) for the item later as described in the following section.
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 can assign content to a portal item when initially adding it to the portal (PortalUser.AddPortalItemAsync) or you can update a portal item's content later using UpdateDataAsync, as shown in the following example.
// read data (FileStream) from the local PDF file
var pdfData = File.OpenRead(reportFilepath);
// update the portal item with the PDF content, close the PDF file
A portal item thumbnail image can also be set as part of the content, as shown in the following example.
// create a thumbnail image for the portal item
var thumbnailData = new FileStream(@"D:\Temp\TES-Report.jpg", FileMode.Open);
// update the portal item with the thumbnail, close the image file
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 UpdateItemPropertiesAsync 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.