Awesome

ember-arcgis-portal-services

Ember Services for working with ArcGIS Portal/Online. Essentially a wrapper around the functions from arcgis-rest-js for working with items, groups, and users that integrates with torii authentication.

Getting Started

Installation

To consume this library in any ember application:

ember install ember-arcgis-portal-services

Dependencies

This project uses ember-fetch, and a few packages from arcgis-rest-js, which will be installed as dependencies.

If you're using torii for oauth management, please also npm install torii-provider-arcgis. More information here.

Otherwise, you can use the portalOpts parameter described below, but you need a service named session in your app or addon. You can generate a dummy service using ember generate service session. TODO: there's probably a better way to do this...

ArcGIS Portal Services

After adding this to your project, you will have a number of services available for injection into your routes/controllers/services.

Shared Methods

All the services expose a set of shared helper properties and methods:

Property	Returns	Description
`geocodeUrl`	`string`	Return the geocode base url

NOTE: Most public methods take an optional portalOpts parameter. This takes the form:

{
  portalHostname: 'some.portal.com',
  token: 'BZSOMETOKENQJ'
}
// it might also look like this
{
  portalHostname: 'https://some.portal.com',
  token: 'BZSOMETOKENQJ'
}

Method	Returns	Description
`encodeForm`	`string`	This is used internally. Formats an object into a html form. In most cases, not necessary to call this.
`request (url, options, portalOpts)`	`promise`	This is used internally. Promisified xhr that does basic handling of Portal's 400-in-a-200 errors
`getPortalUrl()`	`string`	Get the portal url i.e. `https://org.maps.arcgis.com`
`getPortalRestUrl()`	`string`	Get the portal rest url i.e. `https://org.maps.arcgis.com/sharing/rest`

Items Service

Method	Returns	Description
`search(form)`	`promise`	Executes via `/sharing/rest/search`. The form is an object properties matching the search params
`getById(id, portalOpts)`	`promise`	Returns the Item.
`getDataById(id, portalOpts)`	`promise`	Returns the Item-Data (`/data`).
`update(item, portalOpts)`	`promise`	Updates an existing item. The `.owner` property must be set.
`create(item, portalOpts)`	`promise`	Creates an item. The `.owner` property must be set.
`move (itemId, folderId, portalOpts)`	`promise`	Move the item to a specified folder
`remove(itemId, owner, portalOpts)`	`promise`	Delete the item.
`protect(itemId, owner, portalOpts)`	`promise`	Protect the item (to avoid accidental deletion).
`unprotect(itemId, owner, portalOpts)`	`promise`	Unprotect the item.
`getRelatedItems(itemId, relationshipType, direction, portalOpts)`	`promise`	Related Items
`addRelationship (username, itemId, destItemId, relType, portalOpts)`	`promise`	Add a relationship between items
`removeRelationship (username, itemId, destItemId, relType, portalOpts)`	`promise`	Delete a relationship between items
`addImageResourceFromUrl (itemId, owner, filename, url)`	`promise`	Add an image at the specified url to the item as a resource
`export (username, itemId, title, exportOpts, portalOpts)`	`promise`	Export a service item to a file. Call getStatus for job status
`getStatus(item, portalOpts)`	`promise`	Get item/job status
`addPart(item, portalOpts)`	`promise`	Add an item file part
`getParts(item, portalOpts)`	`promise`	Get a list of uploaded item file parts

Groups Service

Method	Returns	Description
`search(form, portalOpts)`	`promise`	Executes via `/sharing/rest/community/groups`. The form is an object properties matching the search params
`getById(id, portalOpts)`	`promise`	Returns the Group.
`getBulk(ids, portalOpts)`	`promise`	Returns an array of Groups.
`getItemsById(id, portalOpts)`	`promise`	Returns Items in the group. Note: Does not currently support paging.
`save(group, portalOpts)`	`promise`	Creates or Updates a group.
`rename(group, newTitle, portalOpts)`	`promise`	Renames an existing group.
`update(group, portalOpts)`	`promise`	Updates an existing group.
`create(group, portalOpts)`	`promise`	Creates an item. The `.owner` property must be set.
`remove(id, portalOpts)`	`promise`	Delete the Group.
`protect(id, portalOpts)`	`promise`	Protect the Group from deletion.
`unprotect(id, portalOpts)`	`promise`	Unprotect the Group from deletion.
`users(id, portalOpts)`	`promise`	Return array of users that are members of the Group. Documentation
`addUsers(id, users, portalOpts)`	`promise`	Adds users to the Group. Expects an array of usernames.
`addAdmins(id, admins, portalOpts)`	`promise`	Adds admins to the Group. Expects an array of usernames.
`reassign(id, username, portalOpts)`	`promise`	Reassign ownership of the group
`remove(id, portalOpts)`	`promise`	Deletes a group from AGO
`join(id, portalOpts)`	`promise`	Request for current user to join a group
`leave (id, portalOpts)`	`promise`	Request for current user to leave a group
`isUserGroupAdmin (id, username, portalOpts)`	`boolean`	User's group admin status
`getUserMembership (id, username, portalOpts)`	`promise`	Return the type of group membership of a user
`updateUserMemberships (id, users, type, portalOpts)`	`promise`	Updates membership(s) from user to admin or admin to user
`ensureUniqueGroupName (title, step, portalOpts)`	`promise`	Return a group name guaranteed to be unique in the org
`doesGroupExist` (title, portalOpts)	`promise`	Return a boolean indicating whether the group exists in the org
`sendGroupMessage (groupId, subject, message, users, notificationChannelType, portalOpts)` (deprecated)	`promise`	Sends a notification to the group. See: http://mediawikidev.esri.com/index.php/ArcGIS.com/User_Notifications
`sendEmailNotification (groupId, subject, message, users = [], portalOpts)`	`promise`	Sends an email notification to the specified group members
`sendBuiltinNotification (groupId, subject, message, users = [], portalOpts)`	`promise`	Sends a "builtin" notification to the specified group members
`sendPushNotificaiton (groupId, data, users = [], portalOpts)`	`promise`	Sends a push notification to the specified group members

Sharing Service

The sharing service separates setting Access (private/shared/org/everyone) from sharing with a group. This allows the methods to be more deterministic.

Method	Returns	Description
`setAccess(owner, itemId, access, portalOpts)`	`promise`	where access is null
`shareWithGroup(owner, itemId, groupId, confirmItemControl, portalOpts)`	`promise`	Shares an item with a group. `confirmItemControl` defaults to `false`. If set to `true` then `itemControl` (aka edit permission) is conferred via group membership
`unShareWithGroup(owner, itemId, groupId, portalOpts)`	`promise`	Un-Share an item with a group.
`changeGroupSharing(action, owner, itemId, groupId, portalOpts)`	`promise`	Actual implementation of the sharing. Action can be 'share' or 'unshare'
`isItemSharedWithGroup(itemId, groupId, portalOpts)`	`promise`	Checks to see if an item has already been shared with a group

User Service

Method	Returns	Description
`search(form, portalOpts)` (deprecated)	`promise`	Delegates to allUsers if user is authenticated or portalOpts is provided, otherwise delegates to searchUsers
`searchCommunityUsers(form, portalOpts)`	`promise`	Executes via `/sharing/rest/community/users`. The form is an object properties matching the search params
`searchPortalUsers(form, portalOpts)`	`promise`	Executes via `/sharing/rest/portals/self/users`. The form is an object properties matching the search params
`getByName(username, portalOpts)`	`promise`	Get a user object by name.
`update(user, portalOpts)`	`promise`	Update a user
`signup (user, portalOpts)`	`promise`	Signs the user up to the organization
`getNotifications (portalOpts)`	`promise`	Gets the user's "builtin" notifications
`removeNotification (id, portalOpts)`	`promise`	Removes the notification
`getInvitations (portalOpts)`	`promise`	Gets the user's invitations
`getInvitationById (id, portalOpts)`	`promise`	Gets the specified invitation for the user
`acceptInvitation (id, portalOpts)`	`promise`	Accepts the invitation
`declineInvitation (id, portalOpts)`	`promise`	Declines the invitation
`getUserTags (username, portalOpts)`	`promise`	Gets item tags used by the user

OAuth Service

Note: This is not used for authentication - rather its purpose is to allow Application Items to be programatically manipulated.

Method	Returns	Description
`registerApp (itemId, redirectUris, appType = 'browser', portalOpts)`	`promise`	Registers an App item. Returning clientId, client secret etc
`updateApp(clientId, redirectUris, portalOpts)`	`promise`	Currently just supports changing the set of valid redirect uris. PR's accepted to expand this

Geocode Service

Method	Returns	Description
`findLocationAddress(inputString)`	`promise`	Returns a location address based on an input string that moves through a specified or default geocode url

Portal Service

Method	Returns	Description
`getById (id, portalOpts)`	`promise`	Get portal info by Id
`self (portalOpts)`	`promise`	Perform a portals/self call
`update(portal, portalOpts)`	`promise`	Update a portal. Lots of rules apply to what can be changed
`uploadResource (file)`	`promise`	Upload a file as a portal resource
`addImageResourceFromUrl (url, filename)`	`promise`	Upload a file as a portal resource, from a url
`addResource (name, content, portalOpts)`	`promise`	Add a resource to a portal
`getResources ()`	`promise`	Get list of portal resources
`removeResource (resourceName, portalOpts)`	`promise`	Remove a resource from a porta
`users(portalId, start = 1, num = 100, portalOpts)`	`promise`	Get a portal users.
`configureSocialProviders (opts, portalOpts)`	`promise`	Configure social logins.
`checkUsername (username, portalOpts)`	`promise`	Checks whether the specified username is available
`checkUrlKey (urlKey, portalOpts)`	`promise`	Checks whether the specified urlKey is available
`activate (opts, portalOpts)`	`promise`	Activates the organization
`addApprovedApp (itemId, properties, portalOpts)`	`promise`	Adds an approved app to the portal. Used to create App Launcher entries
`getApprovedApps (portalOpts)`	`promise`	Gets all approved apps to the portal.
`sendMessage (subject, message, users, notificationChannelType, portalOpts)` (deprecated)	`promise`	Sends a notification to the specified users. See: http://mediawikidev.esri.com/index.php/ArcGIS.com/User_Notifications
`sendEmailNotification (subject, message, users = [], portalOpts)`	`promise`	Sends an email notification to the specified users
`sendBuiltinNotification (subject, message, users = [], portalOpts)`	`promise`	Sends a builtin notification to the specified users
`sendPushNotification (data, users = [], portalOpts)`	`promise`	Sends a push notification to the specified users
`setUserDefaultSettings (opts, portalOpts)`	`promise`	sets default user settings
`getUserDefaultSettings (opts, portalOpts)`	`promise`	gets default user settings
`setSigninSettings (opts, portalOpts)`	`promise`	sets organization signin settings
`getSigninSettings (opts, portalOpts)`	`promise`	gets organization signin settings
`validatePassword (password, portalOpts)`	`promise`	validates whether the provided password meets the requirements

Folders Service

Method	Returns	Description
`getUserFolders (username, portalOpts)`	`promise`	Resolves with an array of folders
`folderExists (folderTitle, username, portalOpts)`	`promise`	Resolves with bool
`create (folderTitle, username, portalOpts)`	`promise`	Creates a folder
`remove (folderId, username, portalOpts)`	`promise`	Removes a folder

Hosted Service

Used to create/manage hosted feature services. Use the feature-service in ember-arcgis-server-services to work with features/records in the service.

Method	Returns	Description
`serviceExists (serviceName, orgId, portalOpts)`	`promise`	Check if a service exists
`create (svcParams, username, folderId, portalOpts)`	`promise`	Create a Service + Item
`addToDefinition (fsUrl, definition, layerId, portalOpts)`	`promise`	Add/Edit a layer or table to the service
`updateDefinition (fsUrl, definition, layerId, portalOpts)`	`promise`	Update a service/layer's definition
`deleteFromDefinition (fsUrl, definition, layerId, portalOpts)`	`promise`	Delete from a service/layer's definition

environment.js

Configuration for how to connect to the portal is managed in the torii section. If you are using ArcGIS Online, the portalUrl property is not needed.

// environment.js
...
torii: {
  sessionServiceName: 'session',
  providers: {
    'arcgis-oauth-bearer': {
      apiKey: 'SECRET-KEY-FOR-YOUR-APP',
      portalUrl: 'https://yourawesomeportal.com'
    }
  }
}
...

Running

ember server
Visit your app at http://localhost:4200.

Running Tests

Note: Currently there are no automated tests for this addon. PR's welcomed :)

npm test (Runs ember try:testall to test your addon against multiple Ember versions)
ember test
ember test --server

Building

ember serve
Visit the dummy application at http://localhost:4200.

For more information on using ember-cli, visit http://ember-cli.com/" target="_blank" class="rg-linkified-code">http://ember-cli.com/.

Resources

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file.