PortalItem Class

  • PortalItem
  • class Esri::ArcGISRuntime::PortalItem

    An item (unit of content) stored in an ArcGIS portal, such as a layer, web map, package file, or map service. More...

    Header: #include <PortalItem.h>
    Since: Esri::ArcGISRuntime 100.0
    Inherits: Esri::ArcGISRuntime::Item, Esri::ArcGISRuntime::Loadable, and Esri::ArcGISRuntime::JsonSerializable

    Public Functions

    PortalItem(const QString &itemId, QObject *parent = nullptr)
    PortalItem(Esri::ArcGISRuntime::Portal *portal, const QString &itemId, QObject *parent = nullptr)
    PortalItem(Esri::ArcGISRuntime::Portal *portal, Esri::ArcGISRuntime::PortalItemType portalItemType, QObject *parent = nullptr)
    PortalItem(const QUrl &url, QObject *parent = nullptr)
    virtual ~PortalItem() override
    Esri::ArcGISRuntime::PortalAccess access() const
    void addComment(const QString &comment)
    void addRating(float rating)
    Esri::ArcGISRuntime::PortalGroupListModel *adminGroups() const
    float averageRating() const
    int commentCount() const
    Esri::ArcGISRuntime::PortalItemCommentListModel *comments() const
    QString culture() const
    void fetchComments()
    void fetchGroups()
    QString folderId() const
    bool isCommentsEnabled() const
    Esri::ArcGISRuntime::PortalGroupListModel *memberGroups() const
    Esri::ArcGISRuntime::PortalGroupListModel *otherGroups() const
    QString owner() const
    Esri::ArcGISRuntime::Portal *portal() const
    int ratingCount() const
    QUrl serviceUrl() const
    void shareWith(bool everyone, bool organization)
    void shareWithGroups(const QStringList &groupIds)
    qint64 size() const
    Esri::ArcGISRuntime::PortalItemType type() const
    QString typeName() const
    void unshare()
    void unshareGroups(const QStringList &groupIds)
    void updateDataWithJson(const QString &json)
    void updateDataWithUrl(const QUrl &fromUrl, const QString &fileName = QString())
    QUrl url() const
    int viewCount() const

    Reimplemented Public Functions

    virtual void cancelLoad() override
    virtual void load() override
    virtual Esri::ArcGISRuntime::Error loadError() const override
    virtual Esri::ArcGISRuntime::LoadStatus loadStatus() const override
    virtual void retryLoad() override
    virtual QString toJson() const override
    virtual QJsonObject unknownJson() const override
    virtual QJsonObject unsupportedJson() const override

    Signals

    void addCommentCompleted(bool success)
    void addRatingCompleted(bool success)
    void doneLoading(const Esri::ArcGISRuntime::Error &loadError)
    void fetchCommentsCompleted(bool success)
    void fetchDataProgressChanged(const Esri::ArcGISRuntime::NetworkRequestProgress &progress)
    void fetchGroupsCompleted(bool success)
    void loadStatusChanged(Esri::ArcGISRuntime::LoadStatus loadStatus)
    void shareWithCompleted(bool success)
    void shareWithGroupsCompleted(bool success, const QStringList &failedToShareGroupIds)
    void unshareCompleted(bool success)
    void unshareGroupsCompleted(bool success, const QStringList &failedToUnshareGroupIds)
    void updateDataCompleted(bool success, const QString &itemId)

    Static Public Members

    Esri::ArcGISRuntime::PortalItem *fromJson(const QString &json, Esri::ArcGISRuntime::Portal *portal = nullptr, QObject *parent = nullptr)

    Detailed Description

    ArcGIS portals support various types of portal items, including:

    • Web maps and scenes.
    • Services such as feature, map, scene, image, and OGC services that can be added as layers to a map.
    • Data files that can be uploaded, stored, and downloaded, such as .mmpk or .vtpk files.
    • Applications and tools.

    Each portal item contains information about the item such as its unique ID, the owning Portal, and the type of item it is (PortalItemType). Portal items can be kept private to the users that created them, shared with other users in specific groups, or made public and accessible to everyone.

    You can use the portal item ID along with a portal URL to quickly instantiate a new portal item object. The item's details page has the following URL format: http://www.arcgis.com/home/item.html?id=[item_id]. If your portal item is a web map, you can also obtain a URL with the format: http://www.arcgis.com/home/webmap/viewer.html?webmap=[item_id] from the [ArcGIS Online Map Viewer](https://doc.arcgis.com/en/arcgis-online/get-started/get-started-with-mv.htm). In both cases, you can use the [item_id] as the ID to instantiate a portal item.

    Alternatively, you can obtain a portal item directly from a portal using a method such as Portal::findItems().

    Create a new portal item

    To add a new item to a portal, create the PortalItem object passing the portal as a parameter to the constructor, then call PortalUser::addPortalItemWithJson or PortalUser::addPortalItemWithUrl. The portal user must have been created with credentials that provide sufficient privileges to add items to the portal. Before adding an item to the portal, the title and type must be set. If itemId is set, this will be ignored and a new unique ID will be provided when the item is added to the portal and loaded.

    PortalItem* portalItem = new PortalItem(portal, PortalItemType::WebMap, parent);
    portalItem->setTitle("My Item");
    portalItem->setTags(QStringList() << TestObject::defaultTagForTests());
    portal->portalUser()->addPortalItemWithJson(portalItem, json);

    Load existing portal item

    To load an existing item from portal, create PortalItem object with valid itemId or url, and call PortalItem::load.

    The portal item ID can be used along with a portal URL to quickly instantiate a new portal item object. The ID can be determined from the URL of the item details web page or the map viewer URL (for maps only) in your portal. The item details page has the following format: http://www.arcgis.com/home/item.html?id=[itemId]. The web map viewer has the following format: http://www.arcgis.com/home/webmap/viewer.html?webmap=[itemId]. In both cases the [itemId] can be used as the ID to instantiate a portal item.

    PortalItem* portalItem = new PortalItem(portal, itemId, parent);
    connect(portalItem, &PortalItem::doneLoading, this, [portalItem](){
      qDebug() << "Item title:" << portalItem->title();
    });
    portalItem->load();

    Retrieve an existing portal item

    Alternatively, you can search for and load existing items in the portal using Portal::findItems or PortalUser::items. If you know the specific ID of the item you wish to retrieve, you can construct the portalItem by passing both the portal and the ID to its constructor and calling PortalItem::load to retrieve the details.

    See also Layer::item, GeoModel::item, and Basemap::item.

    Member Function Documentation

    [explicit] PortalItem::PortalItem(const QString &itemId, QObject *parent = nullptr)

    Constructor that accepts an item ID (itemId) and an optional parent.

    Use this constructor you wish to fetch a particular item from a portal. Call load on the resultant object to fetch the metadata for this item. Note that most of the getter methods will return nullptr, 0 or an empty QString until the load operation is complete.

    A portal item's ID can be obtained using the itemId method. The ID can also be determined from the URL of the item details web page or the map viewer URL (for maps only) in your portal. The item details page has the following format: http://www.arcgis.com/home/item.html?id=[itemId]. The web map viewer has the following format: http://www.arcgis.com/home/webmap/viewer.html?webmap=[itemId]. In both cases the [itemId] can be used as the ID to instantiate a portal item.

    This constructor uses a default portal to https://www.arcgis.com.

    PortalItem::PortalItem(Esri::ArcGISRuntime::Portal *portal, const QString &itemId, QObject *parent = nullptr)

    Creates a portal item object for a specified portal and a specified item ID.

    • portal - The portal.
    • itemId - The item ID.
    • parent - The optional parent QObject.

    Use this constructor to instantiate a PortalItem from an existing item using its unique ID.

    The portal item ID can be determined from the URL of the item details web page or the map viewer and scene viewer web applications in your portal. The item details page has the following format https://www.arcgis.com/home/item.html?id=[item_id]. The map viewer has the format https://www.arcgis.com/home/webmap/viewer.html?webmap=[item_id] or https://www.arcgis.com/apps/mapviewer/index.html?webmap=[item_id], depending on whether you use the classic map viewer or the new map viewer. The scene viewer has the following format https://www.arcgis.com/home/webscene/viewer.html?webscene=[item_id]. In all cases, the [item_id] can be used as the ID to instantiate a portal item.

    See also portal and Item::itemId.

    [since Esri::ArcGISRuntime 100.6] PortalItem::PortalItem(Esri::ArcGISRuntime::Portal *portal, Esri::ArcGISRuntime::PortalItemType portalItemType, QObject *parent = nullptr)

    Creates a new portal item with the specified type in the specified portal.

    • portal - The portal.
    • portalItemType - The type of portal item.
    • parent - The optional parent QObject.

    Use this constructor if you wish to create a new a PortalItem to add to a portal.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    See also portal and type.

    [explicit] PortalItem::PortalItem(const QUrl &url, QObject *parent = nullptr)

    Creates a portal item object.

    • url - The URL to the portal item.
    • parent - The optional parent QObject.

    Use this object to create a portal item from a URL. The supported URL formats are:

    [override virtual] PortalItem::~PortalItem()

    Destructor.

    Esri::ArcGISRuntime::PortalAccess PortalItem::access() const

    Returns the portal item access.

    A portal item can be accessed by various types of users. There are four levels of access that can be associated with a PortalItem. Some of the access levels can be concurrent, others cannot. access however only returns a single PortalAccess level enumeration even though multiple levels of access may have been specified. If multiple access levels have been specified on a PortalItem, the returned access level will be the least restrictive access level.

    void PortalItem::addComment(const QString &comment)

    Adds a comment to a portal item that the user has access to. This method is only available to authenticated users.

    • comment

    The addCommentCompleted signal will emit after the operation is complete.

    [signal, since Esri::ArcGISRuntime 100.1] void PortalItem::addCommentCompleted(bool success)

    Signal emitted when the asynchronous addComment operation is complete.

    • success - Whether adding comment completed successfully.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    void PortalItem::addRating(float rating)

    Adds a rating to a portal item that the user has access to.

    • rating

    Only one rating can be given to a portal item per user. If this call is made on an already rated portal item, the new rating will overwrite the current one. A user cannot rate their own portal item. This method is only available to authenticated users.

    The addRatingCompleted signal will emit after the operation is complete.

    rating must be a floating point number between 1.0 and 5.0.

    [signal, since Esri::ArcGISRuntime 100.1] void PortalItem::addRatingCompleted(bool success)

    Signal emitted when the asynchronous addRating operation is complete.

    • success - Whether adding rating completed successfully.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    Esri::ArcGISRuntime::PortalGroupListModel *PortalItem::adminGroups() const

    Returns a list of groups that the item is in and for which the current portal user is an administrator.

    To access these groups, call fetchGroups, and wait for the fetchGroupsCompleted signal to emit or an errorOccurred if unsuccessful.

    float PortalItem::averageRating() const

    Returns the average rating of this portal item.

    Uses a weighted average called "Bayesian average."

    [override virtual] void PortalItem::cancelLoad()

    Reimplements: Loadable::cancelLoad().

    Cancels loading metadata for the object.

    Cancels loading the metadata if the object is loading.

    See Loadable.

    int PortalItem::commentCount() const

    Returns the number of comments on this portal item.

    Esri::ArcGISRuntime::PortalItemCommentListModel *PortalItem::comments() const

    Returns a list of comments on this portal item.

    QString PortalItem::culture() const

    Returns the culture (language and country) of the portal item.

    [signal] void PortalItem::doneLoading(const Esri::ArcGISRuntime::Error &loadError)

    Signal emitted when this object is done loading.

    • loadError - Details about any error that may have occurred.

    Note: If there is a load error it will also be emitted on the errorOccurred signal.

    See also Loadable and Object.

    void PortalItem::fetchComments()

    Returns the comments for the portal item that you have access to. This method is only available to authenticated users.

    The fetchCommentsCompleted signal will emit after the operation is complete.

    Example: Fetch the comments model for an item:

    int totalCommentsCount = 0;
    connect(portalItem, &PortalItem::fetchCommentsCompleted, [portalItem, &totalCommentsCount](bool success)
    {
      if (!success)
        return;
    
      PortalItemCommentListModel* commentsModel = portalItem->comments();
      if (!commentsModel)
        return;
    
      totalCommentsCount = commentsModel->size();
    });
    
    portalItem->fetchComments();

    [signal, since Esri::ArcGISRuntime 100.1] void PortalItem::fetchCommentsCompleted(bool success)

    Signal emitted when the asynchronous fetchComments operation is complete.

    • success - Whether fetching comments completed successfully.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    [signal] void PortalItem::fetchDataProgressChanged(const Esri::ArcGISRuntime::NetworkRequestProgress &progress)

    Signal emitted periodically to report fetch data progress.

    Information about the fetch data progress is returned in progress.

    void PortalItem::fetchGroups()

    Returns the groups this portal item belongs to.

    Only those groups that are visible to the current portal user will be returned.

    The fetchGroupsCompleted signal will emit after the operation is complete.

    [signal, since Esri::ArcGISRuntime 100.1] void PortalItem::fetchGroupsCompleted(bool success)

    Signal emitted when the asynchronous fetchGroups operation is complete.

    • success - Whether fetching groups completed successfully.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    QString PortalItem::folderId() const

    Returns the ID of the folder in which the owner has stored the item. The property is only returned to users who are the item's owner or the org admin.

    An empty folderID means either an error or that the folderID is unknown to the user. An empty folderID means that the item is stored at the root folder of the user directory.

    [static] Esri::ArcGISRuntime::PortalItem *PortalItem::fromJson(const QString &json, Esri::ArcGISRuntime::Portal *portal = nullptr, QObject *parent = nullptr)

    Creates a new PortalItem from json with an optional portal and parent.

    If the portal is not specified, then the default Portal will be used (ArcGIS Online).

    See also JsonSerializable.

    bool PortalItem::isCommentsEnabled() const

    Returns true if the comments are allowed on the portal item, false otherwise.

    [override virtual] void PortalItem::load()

    Reimplements: Loadable::load().

    Loads the metadata for the object asynchronously.

    Loads the metadata if the object is not loaded.

    See Loadable.

    [override virtual] Esri::ArcGISRuntime::Error PortalItem::loadError() const

    Reimplements: Loadable::loadError() const.

    Returns the load error.

    See Loadable.

    See also Error.

    [override virtual] Esri::ArcGISRuntime::LoadStatus PortalItem::loadStatus() const

    Reimplements: Loadable::loadStatus() const.

    See Loadable.

    [signal] void PortalItem::loadStatusChanged(Esri::ArcGISRuntime::LoadStatus loadStatus)

    Signal emitted when the loadStatus changes for this object.

    See also Loadable.

    Esri::ArcGISRuntime::PortalGroupListModel *PortalItem::memberGroups() const

    Returns a list of groups that the item is in and for which the current portal user is a member (read-only).

    To access these comments, call fetchGroups, and wait for the fetchGroupsCompleted signal to emit or an errorOccurred if unsuccessful.

    Esri::ArcGISRuntime::PortalGroupListModel *PortalItem::otherGroups() const

    Returns a list of groups that the item is in that are public or shared to the user's organization, but that the current portal user is not a member of (read-only).

    To access these comments, call fetchGroups, and wait for the fetchGroupsCompleted signal to emit or an errorOccurred if unsuccessful.

    QString PortalItem::owner() const

    Returns the username of the user who owns this portal item.

    Esri::ArcGISRuntime::Portal *PortalItem::portal() const

    Returns the ArcGIS portal that contains this portal item.

    Will throw ErrorType::CommonIllegalState if the portal item is loaded or loading.

    int PortalItem::ratingCount() const

    Returns the number of ratings on the portal item.

    When the user adds their item rating, the number of ratings needs to be incremented.

    [override virtual] void PortalItem::retryLoad()

    Reimplements: Loadable::retryLoad().

    Loads or retries loading metadata for the object asynchronously.

    Will retry loading the metadata if the object is failed to load. Will load the object if it is not loaded. Will not retry to load the object if the object is loaded. Will always call the done loading if this is called.

    See Loadable.

    QUrl PortalItem::serviceUrl() const

    Returns the URL of the service that this portal item represents. This only applies to portal items that represent web-accessible resources such as map services.

    Will return an empty URL if the item doesn't represent a web-accessible resource.

    void PortalItem::shareWith(bool everyone, bool organization)

    Shares this portal item with everyone or just with the user's organization. This method is only available to authenticated users.

    • everyone
    • organization

    If both 'everyone' and 'organization' are true, the portal item will be shared with everyone (Public). If both 'everyone' and 'organization' are false, the portal item will be made private, unless the item has been shared with one or more groups. In that case, the items access property will be set to PortalAccess::Shared. The groups an item has been shared with are not affected by this method.

    [signal] void PortalItem::shareWithCompleted(bool success)

    Signal emitted when the asynchronous shareWith method completes.

    The parameter success is true when the operation succeeded, otherwise false.

    void PortalItem::shareWithGroups(const QStringList &groupIds)

    Shares this portal item with the specified portal groups. This method is only available to authenticated users.

    • groupIds - the groups to be shared with.

    The portal groups are added to the existing set of portal groups the item is shared with. The result of this method is an unmodifiable collection of portal groups, one for each group with which the item could not be shared. It is empty if all groups were shared with successfully. It is not necessary to load the PortalGroup objects that are passed to this method.

    [signal, since Esri::ArcGISRuntime 100.1] void PortalItem::shareWithGroupsCompleted(bool success, const QStringList &failedToShareGroupIds)

    Signal emitted when the asynchronous shareWithGroups method completes.

    The parameter success is true when the operation succeeded, otherwise false. The parameter failedToShareGroupIds is the list of groups the item could not be shared with.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    qint64 PortalItem::size() const

    Returns the size of this portal item.

    Will return -1 if an error occurs.

    [override virtual] QString PortalItem::toJson() const

    Reimplements: JsonSerializable::toJson() const.

    Returns the JSON representation of this object.

    See also JsonSerializable.

    Esri::ArcGISRuntime::PortalItemType PortalItem::type() const

    Returns the content type of this portal item.

    A portal item's type cannot be changed once it has an item ID. If you wish to change the type you must create a new PortalItem.

    QString PortalItem::typeName() const

    Returns the type name of this portal item.

    Most generally the type name is the string representation of the PortalItemType returned by type. However if the type is PortalItemType::Unknown, the type name is set with the type found in the portal item JSON. This allows API to deal with new portal item types added since the latest API release.

    See also type.

    [override virtual] QJsonObject PortalItem::unknownJson() const

    Reimplements: JsonSerializable::unknownJson() const.

    Returns the unknown data from the source JSON.

    Unknown JSON is a dictionary of values not defined in the ArcGIS specification used to create this object but found in the source JSON. If the object is written back to JSON, any unknown JSON data is not persisted. The ArcGIS specification may be for a web map, web scene, REST API, and so on.

    See also JsonSerializable.

    void PortalItem::unshare()

    Stops all sharing of this portal item.

    This sets the access property of the item to PortalAccess::Private and makes the item accessible to only the item owner. Removes all groups from the set of groups the item is shared with.

    [signal] void PortalItem::unshareCompleted(bool success)

    Signal emitted when the asynchronous unshare method completes.

    The parameter success is true when the operation succeeded, otherwise false.

    void PortalItem::unshareGroups(const QStringList &groupIds)

    Stops sharing this portal item with the specified collection of portal groups.

    • groupIds - the groups to stop sharing with.

    The collection of groups are removed from the set of groups the item is shared with. The result is an unmodifiable collection of portal groups, one for each group for which the item could not be unshared, empty if all groups were unshared with successfully. It is not necessary to load the PortalGroup objects that are passed to this method.

    [signal, since Esri::ArcGISRuntime 100.1] void PortalItem::unshareGroupsCompleted(bool success, const QStringList &failedToUnshareGroupIds)

    Signal emitted when the asynchronous unshareGroups method completes.

    The parameter success is true when the operation succeeded, otherwise false. The parameter failedToUnshareGroupIds is the list of groups the item could not be unshared with.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    [override virtual] QJsonObject PortalItem::unsupportedJson() const

    Reimplements: JsonSerializable::unsupportedJson() const.

    Returns the unsupported data from the source JSON.

    Unsupported JSON is a dictionary of values defined in the ArcGIS specification used to create this object but not currently used in this API. If the object is written back to JSON, any unsupported JSON data is persisted. The ArcGIS specification may be from a web map, web scene, REST API, and so on.

    See also JsonSerializable.

    [signal, since Esri::ArcGISRuntime 100.1] void PortalItem::updateDataCompleted(bool success, const QString &itemId)

    Signal emitted when the asynchronous updateDataWithJson or updateDataWithUrl method completes.

    success Whether the update was successful. itemId The item ID of the PortalItem that was updated.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    [since Esri::ArcGISRuntime 100.1] void PortalItem::updateDataWithJson(const QString &json)

    Starts an asynchronous task to update the remote PortalItem with the provided json.

    The portalItem will be updated using the following arguments:

    • json. A string representation of the JSON to use when updating the item.

    The updateDataCompleted signal will emit after the operation is complete.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    [since Esri::ArcGISRuntime 100.1] void PortalItem::updateDataWithUrl(const QUrl &fromUrl, const QString &fileName = QString())

    Starts an asynchronous task to update the remote PortalItem from a local or online url.

    The portalItem will be updated using the following arguments:

    • fromUrl. The local or online URL from which the portalItem will be populated. For local files, this should be of the form "qrc:/example.csv" or "file://"; for online resources this should be of the form "https://...".
    • fileName (optional). The name of the file which will be associated with the PortalItem (including extension). If a file name is not supplied, the portal item will have no file associated with it for future downloads.

      Note: A file name is only relevant for certain item types such as PortalItemType.Image.

    The updateDataCompleted signal will emit after the operation is complete.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also Items and item types.

    QUrl PortalItem::url() const

    Returns the URL of this portal item.

    Will throw ErrorType::CommonIllegalState if the portal item is loaded or loading.

    int PortalItem::viewCount() const

    Returns the number of views of this portal item.

    Will return -1 if an error occurs.

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.