esri / hub-py Goto Github PK

I'm not sure why add_derived_indicator is a unique function when it really is just add_indicator. I believe that function works for even scripting adding any indicator, and there isn't any additional attribute, so we don't need to be so specific.

They should serve as both a guide to a new user, as well as unit tests for functionality.

Should include rich narrative, images (if and where applicable).

Refer https://developers.arcgis.com/python/guide/ for pattern.

Should generate API reference for Hub

• Get latest version of arcgis
• Add hub as a lazy property which tests if GIS is AGOL instance and only then calls class Hub()
• Test rest of the functionality
• Refine examples
• PR working version to geosaurus

#38

Feature support:

• User can add, update, delete, fetch a particular and search for all indicators for an initiative.
• Example demonstrating ^

Current process for updating an initiative is

init1_data = init1.definition
init1_data['title'] = 'New Title'
init1.update(initiative_properties=init1_data)

Needs to work like https://developers.arcgis.com/python/guide/managing-your-content/#Updating-item-properties

#34

Feature Support:

• User can search for events and visualize all events for a Hub in an embedded webmap
• Example demonstrating ^

Getting Community User email addresses (and other private information) is only available to community org admins. So add option to add the Community admin credentials. This would then add a full communityGIS object to the Hub that would be used instead for subsequent community related API calls (e.g. community_user search)

Blank initiatives need two things:

1. Data
2. Groups

Test-cases:

1. I can edit created initiative
2. Reflects under filter Mine in initiative manager

Re-run initiatives notebook

Events may have either initiativeId or siteId. Currently, it's not very easy to get initiativeId from the siteId.

The idea is to promote analysis by marrying the tools and libraries supported in ArcGIS notebooks to the solution templates of Initiatives to create analysis solutions in a notebook and configure them to the initiative from the same interface.

 myInitiative = myhub.initiatives.get(id)

myInitiative.analytics.search()
>> returns all the implemented analytics for a particular initiative


myInitiative.analytics.get('hotSpotAnalysis')
>> returns item associated to that analysis Id for the initiative

# perform analysis using `arcgis`
myInitiative.analytics.add(item generated from analysis)

hotSpot = myInitiative.analytics.get(`hotSpotAnalysis')
# update existing layer using `arcgis` and assign to `hotSpot`
hotSpot.update(hotSpot)

# delete analytic
hotspot.delete()

Currently returns list with [X,Y]

Change it to return location of type - arcgis.geometry.Point

• create/find initiatives
• create/find/cancel event
• Search for data
• Search for Hubs

• Given a Hub, get a list of all events
• Given an adopted initiative, events for that initiative
• Given an Event, list of attendees

e.g.

# pass the first event that matches query 'Vision Zero' into vz_h
hackathon = dchub.events.search(q="Vision Zero")[0]
# pass the first event returned within the vision zero initiative into vz_h
hackathon = dc_vz_i.events[0]

# pass list of all hackathon attendees/organizers into hackathon_a/o (include contact info, user location, number of submitted apps, etc)
hackathon_a = hackathon.attendees()
hackathon_o = hackathon.organizers()

Add checks to test if a user has logged in with credentials on add/update/delete functions and allow operation accordingly.

• Follow arcgis error handling conventions for performing analysis without signing in.

for example:

# returns all hub objects that match 'Washington, DC', assume the one we want is first in the list
hubs = Hub.search("Washington, DC")

# create object for DC's Hubs
dchub = hubs[0]

Hub API

Usage:

1. User fetches site using mySite = myHub.sites.get(siteId)
2. User can clone to their or another org mySite.clone(org=None)

Note: Test process using item.clone() and document limitations/features here.

• change script in add() to allow for delete protection
• change script in delete that first disables it before deleting

To Test:
Check setting of groups in AGOL once created. Also try deleting them and verify that they don't.

A Hub is a comprehensive object for managing all of the content related to that Hub. Technically, there are two AGO organizations - but this should be transparent to the developer .

myHub1 = hub.Hub("https://dc.maps.arcgis.com", username, password)
myHub2 = hub.Hub("https://community.maps.arcgis.com", username, password)
myHub3 = hub.Hub("https://www.arcgis.com", username, password)
myHub4 = hub.Hub("https://opendata.dc.gov", username, password)

myHub1.orgs.enterprise #=> https://dc.maps.arcgis.com
myHub1.orgs.community #=> https://community.maps.arcgis.com

myHub2.orgs.enterprise.url #=> https://dc.maps.arcgis.com
myHub2.orgs.community.url #=> https://community.maps.arcgis.com

myHub3.orgs.enterprise.url #=> https://dc.maps.arcgis.com
myHub3.orgs.community.url #=> https://community.maps.arcgis.com

myHub4.orgs.enterprise.url #=> https://dc.maps.arcgis.com
myHub4.orgs.community.url #=> https://community.maps.arcgis.com

len(myHub1.events.search()) #=> 4
len(myHub2.events.search()) #=> 4
len(myHub3.events.search()) #=> 4
len(myHub4.events.search()) #=> 4

Nouns

hub
initiative
indicator
site
initiative team
initiative template
hub organization
community organization
solution template
initiative template
user
event
page
catalog
analysis
comment
location

Different use cases to cover

data science

• extract data from initiatives
  event (hackathon)
• organizer
• attendee
  searching
• across hubs
  • by location ("All Hubs located in the UK")
  • by organization type ("All Hubs at the state level")
  • by number of initiatives, events ("All Hubs that have hosted at least 10 events")
  • by initiatives adopted ("All Hubs that have adopted Vision Zero")
• across initiatives (this is probably just Portal API calls)
  • by location ("All Vision Zero initiatives in the US")
  • by age ("All initiatives created within six months")
  • by last updated ("All initiatives updated within the past month")
  • by tag ("All livable initiatives")
• across applications
  • by initiative ("All applications in the Vision Zero initiative")
  • by type ("All dashboards")
    initiative updating
• add application to an initiative
  community organization
• view members (present in the Python API)
• invite members (present in the Python API)

• unshare content from groups
• delete groups
• delete initiative

To test:

• initiative shouldn't be found on hub
• groups shouldn't be found on AGOL
• initiative site does not get deleted

1. scope will be an optional parameter to the initiatives.search() function.
2. Valid values for the parameter are:

• official - all Public initiatives in Enterprise org
• community - all Public initiatives in Community org
• all - All initiatives in current GIS (anonymous or signed in) with outside_org=True
• None (for no user-provided value) - All initiatives in current GIS (anonymous or signed in)

Usage:

myHub.initiatives.search(scope='official', title='Vision Zero')

Functionality supported:

>>> hub.sites.add(title=title, group_id, domain=None, initiative=None)
>>> site.update()
>>> site.delete()
>>> hub.sites.get(siteId)
>>> hub.sites.search(initiative=None, creator/owner=None)

1. For initiative site
2. For other sites

Specify Minimum viable dictionary needed to create a site using Python. Item dictionary will be passed to the gis.content.add() function to create the site item correctly.

The Python API needs to prevent Sites from having a subdomain longer than 63 characters. It’s a limit of DNS and was added to our UI. But our Python also needs to prevent bad URL

myInitiative.delete(site=True, apps=True)

apps can only be deleted by a user that has permissions to delete those items. In other cases, give appropriate error message.

example:

# activate an initiative
dc_vz = Hub.initiative.activate("Vision Zero")

Hub API

The implementation architecture will be identical to that of an Initiative has Indicators.

mySite = myHub.sites.get(id)

#pages 
mySite.pages.add(name)
mySite.pages.get(id)
mySite.pages.search(name=None, owner=None, tags=None)
mySite.pages.clone(page, title=None)    #clones page within the same site

myPage.update()
myPage.delete()

Indicators can be datasets or other types of information. Adding _layers seems to be unnecessary jargon (GIS-y) and also overly specific when that's not always the case.

if the indicators are specifically data, should we call it that?

This is a bit complicated due to restrictions of the AGO api for protecting user credentials. Here is a rough sketch.

• Given an Initiative, get the full list of followers
  • include username, joined date, email (only if Community Admin)

This call should work for

• Anonymous - only get for public initiatives and public users (per API)
• Core Member - ability to get all members (will not include email)
• Core Member with Community Admin credentials - (includes Email)

For this to work for both non-Community Admin and with Community Admin the Hub will need to support the option to also add Credentials for the community org. This may look something

hub = GIS.hub("https://opendata.dc.gov")
dcInitiatives = hub.initiatives.search()
initiativeFollowers = dcInitiatives[0].followers
firstUser = initiativeFollowers[0] 
firstUser.username #=> 'sally'
firstUser.email #=> Null

# Hub has reference to 2 Orgs: Enterprise + Community. First, they are both 'anonymous'
hub._enterpriseGIS 
hub._communityGIS

# Sign into the Enterprise Org. This will replace/store hub._enterpriseGIS with a signed in GIS
hub.enterpriseSignin(enterpriseUsername, enterprisePassword) #=> True (success)

# Sign into the Community Org. This will replace/store hub._communityGIS with a signed in GIS
hub.communitySignin(communityUsername, communityPassword) #=> True

# Now the requests return additional information
dcInitiatives = hub.initiatives.search()
initiativeFollowers = dcInitiatives[0].followers
firstUser = initiativeFollowers[0] 

# getting profile information may require 'lazy loading' during each user (group.users doesn't return this info)
firstUser.username #=> 'sally'
firstUser.email #=> `[email protected]`

Add Support for Referencing both Orgs

As we've discussed, I think that we need to add caching of both organizations (enterprise + community) so that the right org can be used explicitly in other methods.

in Hub.init - add something like the following (but with much better error checking)

    def __init__(self, gis, username=None, password=None):
        self.gis = gis
        self._username = username
        self._password = password
        self.gis = GIS(self.url, self._username, self._password)
        try:
            self._gis_id = self.gis.properties.id
            # add test if actually a Hub
            # orgType is either 'enterprise' or 'community'
            self._hubRole = self.gis.properties.portalProperties.hub.settings.orgType 
            if self._hubRole == 'enterprise':
                self._enterpriseGIS = self.gis
                self._communityGIS = GIS(self.community_org_url)
            elif self._hubRole == 'community':
                self._enterpriseGIS = GIS(self.enterprise_org_url)
                self._communityGIS = self.gis
        except AttributeError:
            self._gis_id = None

    def enterpriseSignin(username=None, password=None)
        self._enterpriseGIS = GIS(self.enterprise_org_url, username, password)

    def communitySignin(username=None, password=None)
        self._communityGIS = GIS(self.community_org_url, username, password)

@ManushiM

myhub.initiatives.add_from_template(templateid, title, description=None)

will adopt existing initiative template and create new initiative

• Should org-ids/event feature service layer be exposed to user?
• https://github.com/ArcGIS/hub-indexer/blob/master/docs/api.md ?
• surveys/event attendees/apps?
• new noun/class ?
• unit tests? or how else to test?
• (new functionality suggestions)

• by initiatives adopted ("All Hubs that have adopted Vision Zero")
• across initiatives (this is probably just Portal API calls)
• by location ("All Vision Zero initiatives in the US")
• by age ("All initiatives created within six months")
• by last updated ("All initiatives updated within the past month")
• by tag ("All livable initiatives")

example pseudo-code

vz_initiative = Initiatives.search("Vision Zero", status='template')
vz_hubs = vz_initiatives.hubs

vz_hubs_2 = Initiatives.search("Vision Zero", status='adopted')

TBD

The current UI for adding indicators to an initiative restricts the flexibility of updating attributes on the fly.

E.g. Indicator streetCrashes accepts only two attributes currently Injuries and Fatalities. Future versions of hub may (?) allow a user to tweak attributes in initiatives instead of solution templates of initiative templates.

Script this only in case of valid use-case or if ^ doesn't hold, whichever is first.

arcgis.hub.EventManager.search() currently does a client-side search by downloading all events and looping through each event entity. Events by design are records in a FeatureLayer. Thus this search op can be delegated to be run server-side using a regular FeatureLayer.query() operation. Not a priority, but if scalability becomes an issue, we may revisit this enhancement.

Steps to test:

• Site is created and is visible as an item in the initiative editor
• Clicking view/edit redirects correctly
• Site is added to Collaboration group on AGOL

@ajturner

While this can be done using the Python API like:

site = gis.content.add(site item dictionary)
site.update(data)

does this warrant for creating class Site() now since it is a crucial concept anyway?

Current version has two issues:

1. Doesn't compare with solution template to see if the id for indicator that you add exists.
2. Allows for adding indicators with duplicate id/name.

To test fix:

1. Adding indicator that doesn't exist in corresponding solution (derived from initiative) template must return an error message
2. Adding indicator with existing id should return an indicator already exists message
3. Updating non existent indicator should return an error message