Portal API

Portals and Organizations

Portal for ArcGIS provides you with the same collaboration and sharing tools as ArcGIS Online, but differs in where it is hosted and what content is available to users. Portal for ArcGIS can be deployed behind your organization's firewall or a private instance can be hosted and managed by Esri for your organization.

For more information visitPortal for ArcGIS

Organization

An Organization is a part of the Portal created for a specific entity. Through a subscription to ArcGIS Online, organizations can set up a configurable, secure site that includes administrative controls, flexible data storage capabilities, and other site enhancements that enable geospatial information to be more pervasive within that organization or to the general public. Organizations can also access Esri's cloud to turn their data into web-accessible maps without needing additional server technology.

For more information, visit theConceptual Help

Groups and Users

Groups are a way to collaborate with other users who share a common interest related to geographic information. You join and create groups to exchange content related to a specific project or common activity. For example, you might be a biologist working on an international bird habitat map template. You might search for groups whose members are sharing local bird habitat data that you could use. You could join this group and share your template. Together, your group could create a standardized international habitat map with rich local data layers.

For more information, visit theConceptual Help

Accessing a Portal

Conceptually, a user always connects to an online portal to access his GIS content. Sometimes, he may connect to a "sandboxed" area of the portal earmarked for his Organization.

Portal Class

Portal is the main class and the entry point into the API. It has a callback listener PortalListener that is informed when each operation completes successfully or encounters an error. The callback method of the listener indicates that the portal loaded successfully and returns the portal object from which you can extract and display the relevant details.

To access a portal, you need to instantiate the portal with a credential or as a guest. Instantiating an Portal object will prompt a connection to a Portal/Organization. The API itself is agnostic of what is being connected to (Portal or Organization) and depends upon the URL and optionally the credential that is passed to Portal.

There are two cases:

1. URL points to an Organization account. Portal will connect to that Organization account. If Organization allows Anonymous access, a credential is not required. Otherwise it is.

2. URL points to a Portal. If no credential is provided (anonymous access), Portal will connect. If credential is provided and it belongs to an Organizational user, Portal will automatically and transparently connect to the Organization's account. If the credential does not belong to an Organizational user, Portal will connect to the Portal instead.

   The credential used to connect to a Portal/Organization could also be "flowed" to access webmaps and constituent services. At this point the credential only supports ArcGIS Tokens.

Code example accessing as a guest

String url = new String(http://arcgis.com);
Portal.newInstance(url, new PortalListener<Portal>);

With a credential
UserCredentials credentials = new UserCredentials();
credentials.setUserAccount("user login", "password");
//create a new instance of portal
Portal.newInstance(portalUrl, credentials,new PortalListener<Portal>() {

	@Override
      public void onError(Throwable e) {
		e.printStackTrace();
		}

	@Override
	public void onCallback(Portal portal) {
}
});

Verifying the Portal was loaded

The process of loading the portal is executed in a separate thread and hence the verification needs to be done explicitly by using the appropriate callback method. The delegate method portalDidLoad:(Portal )portal indicates that the portal loaded successfully and returns the portal object from which you can extract and display the relevant details. Only if the portal were successfully loaded, it would mean that it is completely initialized.

In the case of authenticated access to the portal and if the user belongs to an Organization, both Portal and Organization's properties are returned to the user in the PortalInfo object of the Portal. In case of anonymous access, only the properties of the portal are returned.

Untrusted Host Problem

If you encounter the error code of type STRINGErrorServerCertificateUntrusted, add the host of the portal url to the list of trusted hosts and try again.

Portal Info

The Portal object returned on a successful initialization of the Portal contains the PortalInfo. It provides all the information about the Portal .The access type of the user, Boolean indicating whether the Portal can be shared public or not, the default base map and the information about the name and thumbnails of the both Portal and Organization. It also provides predefined query strings for finding Featured Groups, Items and Home Page Featured Content.

In the case of authenticated access to the portal and if the user belongs to an Organization, both Portal and Organization's properties are returned to the user in the PortalInfo object of the Portal. In case of anonymous access, only the properties of the portal are returned.

Finding Featured Groups, Items and Home Page Featured Content

There may be some Featured Groups, Items and Content for the Portal or Organization. The PortalInfo provides query strings to find them. You have to construct a query with PortalQueryParams class and execute Portal's findGroupsWithQueryParams or findItemsWithQueryParams method to find them.

PortalInfo portalInfo = portal.getPortalInfo()

//finding featured groups
List<String> querys = portal.getPortalInfo().getFeaturedGroupsQueries();
for (String query : querys) {
 portal.findGroups(new PortalQueryParams(query), 
   new PortalListener<PortalQueryResultSet<PortalGroup>>() {

	@Override
	public void onCallback(PortalQueryResultSet<PortalGroup> results) {
}

@Override
	public void  onError(Throwable e) {
		e.printStackTrace();											
	}
});

//finding featured items group
PortalQueryParams queryParams = new PortalQueryParams(
    portal.getPortalInfo().getFeaturedItemsGroupQuery());

//finding homepage featured content
PortalQueryParams queryParams = new PortalQueryParams(
				portal.getPortalInfo().getHomepageFeaturedContentGroupQuery());

In order to get the results from the portal using these query params, make use of the portal listener. In the portal listener callback a list of results is returned.

For getting items from the featured items query

portal.findItems(new PortalQueryParams(
    portal.getPortalInfo().getFeaturedItemsGroupQuery()), 
    new PortalListener<PortalQueryResultSet<PortalItem>>() {

	@Override
    public void onCallback(PortalQueryResultSet<PortalItem> results) {					
		for(PortalItem item:results.getResults()){
		     item.getTitle());
		}
									
	}

	@Override
	public void onError(Throwable e) {						
		e.printStackTrace();
				
	}
});

For getting the groups from the homepage query

portal.findGroups(new PortalQueryParams(homepage), 
    new PortalListener<PortalQueryResultSet<PortalGroup>>() {

@Override
	public void onCallback(PortalQueryResultSet<PortalGroup> results) {
		for(PortalGroup r:results.getResults()){
		     group.getTitle());
		}
	}

	@Override
	public void onError(Throwable e) {
		e.printStackTrace();
	}
});

Extra call to fetch thumbnails

Even though the properties representing the portal and organization thumbnails are available as a part of the PortalInfo, they don't get returned as part of the successful initialization of the portal. An explicit fetch has to be made on the PortalInfo object to retrieve them. Also, to be notified about the result of these fetches, you have to adopt the PortalListener protocol and implement the relevant methods.

// check whether a filename exists for the thumbnail
// indicating the presence of the thumbnail
if (portalInfo.getPortalThumbnailFileName() !=null) {
    [portalInfo fetchPortalThumbnail];
} 
if (portalInfo.getOrganizationThumbnailFileName() !=null) {
    [portalInfo fetchOrganizationThumbnail];
}

To get the thumbnails from the portal, use the PortalListener<byte[]> which returns a byte array in the callback.

portal.getPortalInfo().fetchOrganizationThumbnail(
    new PortalListener<byte[]>() {

	@Override
	public void onCallback(byte[] byte) {								
	}

	@Override
	public void onError(Throwable e) {
	    e.printStackTrace();					
	}
});

Portal Item

An PortalItem is a unit of content in the Portal. Each item has a unique identifier and a well-known URL that is independent of the user owning the item. An item may have associated binary or textual data, which is available via theItem Data resource . For example an item of type map package returns the actual bits corresponding to the map package via the item data resource. For more information of the supported types of items, visitItem Types .

The numViews property tracks the number of times a file item type is downloaded for the first time or a text item type is opened. For a URL item type, the numViews property increases the first time a service is opened. The owner property of type, PortalUser represents the user who owns the Item.

Instantiation of Portal Item

Portal Items are either returned as a result of a query on the Portal. Once the portal has been initialized and returned in the callback successfully, a fetch on the portal returns a list of portal items.

portal.findItems(new PortalQueryParams("query"), 
    new PortalListener<PortalQueryResultSet<PortalItem>>() {

	@Override
	public void onCallback(PortalQueryResultSet<PortalItem> portalItemList) {	
	}

@Override
	public void onError(Throwable e) {
	}
});

Extra call to fetch thumbnails

An explicit fetch has to be made on the PortalItem object to retrieve its thumbnail image using the file name. Also, to be notified about the result of this fetch, you have to adopt the portallistener with the PortalItem and implement the relevant methods.

// check whether a filename exists for the thumbnail
// indicating the presence of the thumbnail
if (portalUItem.getThumbnailFileName() != null) {
    [portalItem fetchThumbnail];
}

Users and Groups

Users are invited to join an organization by that organization's administrator. See Joining an organization for more information. All members see a customized view of the site, for example, a gallery of the organization's featured content, and have access to the content and groups shared with the organization. PortalUser represents a registered user and is returned after a successful initialization of the Portal. It could have one of the following types of accesses:

• Private: Hides the user from other user searches and invites
• Account: Only members of the same organization can search for the user and the user's content and groups
• Public: The user and his content are searchable from anywhere within the portal. This is the default access.

The user can be obtained from the portal.

Extra call to fetch thumbnails

Even though the property representing the user's thumbnail is available as a part of the PortalUser, it does not get returned as part of the successful initialization of the portal. An explicit fetch has to be made on the PortalUser object to retrieve it. Also, to be notified about the result of this fetch, you have to use the portallistener with the byte[] and implement the relevant methods.

portal.getUser().fetchThumbnail(new PortalListener<byte[]>() {

	@Override
	public void onCallback(byte[] obj) {								
	}

	@Override
	public void onError(Throwable e) {
	}
});

Finding Groups

PortalUser contains various properties carrying details about the authenticated user, one of them is groups. This is an array of PortalGroup objects, each representing an actual group, in the portal or organization, which the user is a member of.

Also, to fetch the thumbnail for each group, as described previously, you have to make the extra call and respond to the methods of portallistener with portalgroup.

Fetching users of a group

In order to fetch the users of a group first call fetch users and pass it the portal listener. In the callback of the listener get the list of the admins and users in the group.

group.fetchUsers(new PortalListener<Void)(){
	
	@Override
	public void onCallback(Void obj){
 		group.getAdmins();
		group.getUsers();
    }
}

Fetching Contents of a User

You can fetch the contents associated with a particular user by using the methods fetchContent or fetchContentInFolder method. The latter is a folder specific fetch with the input parameter being the folder id string. The folder specific fetch is used to find the contents of a particular folder on the Portal. The former can also be called with the latter method with a folderId of nil.

portalUser.getPortalUser fetchContent();
// or
portal.getUser().fetchContentInFolder("folderId", new PortalListener<PortalUserContent>() {

	@Override
	public void onCallback(PortalUserContent obj) {															
	}

	@Override
	public void onError(Throwable e) {
	}
});

The array of PortalItem will contain all the items in the folder specified, or at the root level if the folder was not specified. In order to get the list of items inside a particular folder beyond the root, you have to call the fetchContentInFolder: again with the appropriate folder id that you obtain from the array of folders that is returned in the first call. ArcGIS portal does not allow more than one level of folder structure.

The items listed in the folders (root or sub) will always be of that owner. Other shared items will be available as item(s) in a group user is a member of.

Searching the Portal

To make a query on ArcGIS Portal to retrieve groups or items, you have to construct the query string with various parameters. PortalQueryParams class offers a few methods that would construct and return query strings for you for various common cases such as finding groups owned by a particular user and having a specific title, finding items in a particular group with the group ID, finding items of particular type in a specified group and so on. You can either use these predefined query parameters or construct one on your own for a custom query.

Queries on both Items and Groups can be done with the methods findItemsWithQueryParams: and findGroupsWithQueryParams: respectively, available in the Portal class. Both the methods require an PortalQueryParams object.

For instance, to find the list of items in a particular group:

PortalQueryParams queryParams = new PortalQueryParams(); 
queryParams.setQueryForItemsInGroup(groupId);

// You can also create your custom PortalQueryParams object.

PortalQueryParams queryParams = new PortalQueryParams();  

// Once you have the query parameter string, you can make the query on the portal.

portal.findItems(queryParams, portalListener);

In order to be notified about the query results, you have to user the portal listener with portalitem and implement the appropriate methods.

When constructing the query using the PortalQueryParams, you can also specify the limit of the list of results to be returned, its sort field, sort order and the start index. In this way, you would be able to display the results in a very intuitive way with paging. The default limit value is 10.

Constructing Custom Queries

Portal for ArcGIS has a full-featured text search engine and provides the ability to create your own queries. When performing a search foritems orgroups you can either specify a field or use the default fields. For items, the default fields are title, name, tags, snippet, description, item, accessinformation, spatialreference, type and typekeywords. For groups, the default fields are id, title, description, snippet, tags and owner. The best match is always returned. For example, a search for "fires" would return records containing "fire".

You can search any field by having field name followed by a colon ":" and then the term you are looking for. If you don't use a field indicator, the default fields will be searched.

As an example, to search for an item that has San Francisco in the title and is a layer package, the query would be:

String queryString = “ title:\"San Francisco\" AND type:\"layer package\"  ”;
PortalQueryParams queryParams = new PortalQueryParams(queryString);

For more information on creating query parameters string, visit Search Reference on ArcGIS Portal API.