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
OrganizationAn 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 UsersGroups 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 ClassPortal is the main class and the entry point into the API.
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:
- 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.
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, null);
// With a credential
UserCredentials credentials = new UserCredentials();
credentials.setUserAccount("user login", "password");
//create a new instance of portal
Portal.newInstance(portalUrl, credentials);
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
From the portal teh portalInfo object can be fetched. 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 ContentThere 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.
//call the async task
new MyTask.execute();
Private class MyTask extends AsyncTask<Void, Void,Void>{
protected void doInBackGround(Void… params){
Portal portal = new Portal(portalUrl, credentials);
PortalInfo portalInfo = null;
try{
portalInfo = portal.fetchPortalInfo();
}catch(Exception e){}
List<String> querys = portal.fetchPortalInfo().getFeaturedGroupsQueries();
for (String query : querys) {
PortalQueryResultSet<PortalGroup> results = null;
try {
results = portal.findGroups(queryParams);
} catch (Exception e3) {
e3.printStackTrace();
}
}
}
return null;
}
//finding featured items group
PortalQueryParams queryParams = new PortalQueryParams(portal.getPortalInfo().getFeaturedItemsGroupQuery());
//finding homepage featured content
PortalQueryParams queryParams = new PortalQueryParams(portal.getPortalInfo().getHomepageFeaturedContentGroupQuery());
For getting items from the featured items query
PortalQueryResultSet<PortalItem> results = portal.findItems(new PortalQueryParams(portal.fetchPortalInfo().getFeaturedItemsGroupQuery()));
for(PortalItem item:results.getResults()){
item.getTitle());
}
For getting the groups from the homepage query
PortalQueryResultSet<PortalGroup> results = portal.findGroups(new PortalQueryParams(homepage));
for(PortalGroup r:results.getResults()){
group.getTitle());
}
Put the above calls in the doInBackground() method of an Async task.
Extra call to fetch thumbnailsEven 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, and async task. Create a class that extends the AsyncTask class. In the doInBackground() method put the code shown below. In order to start the task, user new YourTask().execute() which in turn calls the doInBackground() method.
new FetchThumbnailTask.execute();
private class FetchThumbnailTask extends AsyncTask{
protected Void doInBackground(Void ….params)
try {
byte[] data = portal.fetchPortalInfo()
.fetchOrganizationThumbnail();
ByteArrayInputStream bytes = new ByteArrayInputStream(data);
final BitmapDrawable bmd = new BitmapDrawable(bytes);
if (bmd != null)
{
YourActivityName.this.runOnUiThread(new Runnable() {
@Override
public void run() {
//set the bitmap in your imageview
organizationThumbnail.setImageBitmap(bmd.getBitmap());
}
});
}
} catch (Exception e2) {
e2.printStackTrace(); }
return null;
}
}
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.
Extra call to fetch thumbnailsAn 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 thumbnailsEven 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.
byte[] data = portal.fetchUser().fetchThumbnail();
if (group.getThumbnailFileName() != null) {
data = group.fetchThumbnail();
Bitmap bitmap = BitmapFactory.decodeByteArray(data,
0, data.length);
mGroups.add(new MyGroup(group, bitmap));
YourActivityName.this.runOnUiThread(new Runnable() {
@Override
public void run() {
//make ui updates here
}
});
}
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 groupWith the new workflow it's straightfoward to get the users and admins from a group:
group.getUsers();
group.getAdmins();
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();
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.
PortalQueryResultSet<PortalItem> resultSet = portal.findItems(queryParams);
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 QueriesPortal 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.