Add items to a portal

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 be specified when initially adding the item to the portal. A new portal item can be added to the root folder, or to any available subfolder for the currently authenticated user.

Note:

Currently, you can only create new portal items that store web maps or feature collections with this ArcGIS Runtime SDK.

The following example creates a new portal item called "Forest Features" that stores a feature collection. It sets properties to provide a summary (short description), a description, and a set of tags to improve searchability, and provides the json that defines the feature collection. The code then adds the new item to the root folder of the user's portal.

// define relevant tags to help users find this new portal item
List<String> tags = new ArrayList<>();
tags.add("TES");
tags.add("Wakim National Forest");
tags.add("Endangered species");

// create a new portal item, setting the properties that describe the item to portal users. 'portal' is a
// Portal instance that is authenticated as a user with permission to create new portal items
newPortalItem = new PortalItem(portal, PortalItem.Type.FEATURE_COLLECTION, "Forest Features",
  "The status of threatened, endangered, and sensitive species within the Wakim National Forest.",
  "Wakim National Forest engangered species features",
  tags
);

// create the content that this portal item will store; here, the json of an existing FeatureCollectionLayer
// is used to create the content.
FeatureCollection collection = featureCollectionLayer.getFeatureCollection();
PortalItemContentParameters content = PortalItemContentParameters.createJsonContent(collection.toJson());

// add the new item to the portal, with its content. Passing 'null' as the folder parameter saves the item
// to the users root folder
final ListenableFuture<String> addPortalItemFuture = authenticatedUser.addPortalItemAsync(newPortalItem,
    content, null);
addPortalItemFuture.addDoneListener(new Runnable() {
  @Override
  public void run() {
    try
    {
      String newItemId = addPortalItemFuture.get();
      showMessage(String.format("New item with ID '%s' was created", newItemId));
    } catch (InterruptedException | ExecutionException ex) {
      dealWithException(ex);
    }
  }
});

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.

// fetch the content in the authenticated user's root folder
final ListenableFuture<PortalUserContent> contentFuture = authenticatedUser.fetchContentAsync();
contentFuture.addDoneListener(new Runnable() {

  @Override
  public void run() {
    // iterate user's folders
    PortalUserContent portalUserContent = null;
    try {
      portalUserContent = contentFuture.get();
      for (PortalFolder folder : portalUserContent.getFolders()) {
        showMessage(String.format("Folder: %s\n", folder.getTitle()));
      }
    } catch (InterruptedException | ExecutionException e) {
      dealWithException(e);
    }
  }
});

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.addPortalItemAsync) you can update a portal item's content later using PortalItem.updateDataAsync, as shown in the following example.

// update the portal item content by passing in the new json string
final ListenableFuture<Void> updateDataFuture = portalItemToUpdate.updateDataAsync(newJson);
updateDataFuture.addDoneListener(new Runnable() {
  @Override
  public void run() {
    try
    {
      updateDataFuture.get();
      showMessage(String.format("Item with ID '%s' was updated", portalItemToUpdate.getItemId()));
    } catch (InterruptedException | ExecutionException ex) {
      dealWithException(ex);
    }
  }
});

A portal item's thumbnail image can be set, and it is then updated on the portal, as shown in the following example.

// update the portal item thumbnail
portalItemToUpdate.setThumbnailData(itemThumbnailData);

final ListenableFuture<Void> updatePropertiesFuture = portalItemToUpdate.updateItemPropertiesAsync();
updatePropertiesFuture.addDoneListener(new Runnable() {
  @Override
  public void run() {
    showMessage("Thumbnail was updated");
  }
});

Portal item information page

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

Set sharing

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
  • Everyone

Note:

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.