Adv. Geoprocessing 5 - Documenting & Sharing Tools

ENV 859 - Geospatial Data Analytics   |   Fall 2024   |   Instructor: John Fay  

Introduction

Recall our initial task in Section 1 Preparing For Analysis - the request that you be ready to help your supervisor “summarize the demographics found along a selected hurricane path”? Well, we’ve got the workflow for that down, but even better, we have a tool that would allow us to quickly run the analysis for any storm our boss asks. But let’s take that one more step forward and provide our boss with a tool so that she can do it herself!

To do this, we must make our tool as robust and easy to use as possible and be able to distribute it so that it works on anyone’s machine (within reason). Here we take a look at a ways to document and distribute our tools so that others can reap the benefits of our contribution.

Section Learning Objectives
A. Documenting your tool • Add documentation/metadata to your tool
B. Sharing your tool via “Zip & Ship” • Prepare your workspace for distribution
• Zipping up folder
• Confirm your workspace ships correctly
C. Sharing your tool via ArcGIS Online • Prepare your workspace for on-line sharing
• Create and review a shared workspace
• Post your workspace to ArcGIS Online
• Test your shared workspace

A. Documenting your tool

If you wish to provide your model for someone else to you, and that someone else could be you a few months down the road when you may have forgotten exactly how to use it, you’re going to want to document your model. Documentation can be brief or detailed; what’s important is including enough detail so that the intended user has enough information for him or her to use it without too much difficulty.

  • Make a copy of your “Hurricane Tracker - Preconditions” tool naming this tool “Hurricane Mapping Tool”.

  • Right-click the tool and select Edit Metadata. This brings up the form in which you can document your tool.

    • Add tags which will allow others to search for your tool, e.g., Hurricane, ENV859, …

    • The summary of the tool is what’s shown when the user opens up the tool. Type something you’ll recognize here.

    • Expand the Syntax area. This is where you give descriptions for the various parameters your model contains. Enter some text for the input and output parameters for your model in both the dialog and the scripting explanation boxes.

    • Add your name to the Credits box. If you want to be fancy, you can hold down the alt-key while pressing 0169 in the keypad to create the copyright symbol (©).

    • Notice all the other places where you can add documentation and metadata for your model. We won’t fill out everything for out model, but if you want to distribute your tools widely, you should consider these other model attributes.

    • Save the edits and close the description window.

  • Open up your model and hover the mouse over the help icons to view the documentation you added. Click through the various parameters and see where your entered text appears.
    NOTE: If the values don’t appear, try restarting ArcGIS Pro. :neutral_face:

  • Click on the Tool Help button. A web page comes up with some of the model metadata you added.

Note: I’ve seen mixed results from trying to save metadata. Sometimes it works, and sometimes it doesn’t. When things like this happen, the best recourse is often to search for answers online. For example, Google: arcpro metadata won't save. When I did I found the following page which has helpful information:

https://community.esri.com/thread/216887-problems-updating-model-metadata-in-arcgis-pro-213

Seems that often just restarting ArcGIS Pro does the trick…

B. Sharing your tool: “Zipping and Shipping”

If your workspace and data are well organized, your map and models set to relative path names, and your tool nicely documented, you can simply zip up the contents of your root folder into a single zip file and send that off to anyone with the same version of ArcGIS Pro and they should be able to use it.

Recall, however, that you should tidy up your workspace before zipping and shipping! Here is a checklist:

  • Ensure that all extraneous items in your projects are removed: unused layers, tools, map views, charts, etc. Keep only what’s pertinent to your tools successful workflow.

  • Take a moment to rename any items (layers, maps, etc.) to something that’s useful and friendly to the user. Raw filenames are usually less informative than what they represent. Even replacing underscores with spaces makes your product look more professional (“USA_Counties.shp” → “US Counties 1:3m”)

  • Select a proper base map and ensure the layers are appropriately symbolized and set to visible or not. For example, opening the map with all the storm track points is too busy and distracting.

  • Clear your scratch folder and scratch geodatabase. Files stored here should not be required to run your model and should be removed.

  • You may wish to clear your project’s history: Navigate to Analysis>History and select and remove all entries.

  • Save and close your project.

  • Remove the .backups, GpMessages, and Index folders in your project folder.

  • Zip your project folder.

  • Try opening it on another machine to ensure that all the data can be found. Try running your tool to ensure it works properly. Even better, ask a coworker to test the model out.

FOR DISCUSSION:

Can you think of any other ways to make your tool more friendly to the user? To share a more robust product? What problems might arise from using this method, if any?

C. Sharing your tool: Publishing on ArcGIS Online

ArcGIS Online allows you to share your models as geoprocessing services. The means for doing this changes quite frequently, as ArcGIS Online is constantly evolving. This is a general procedure, but it’s likely that a new process has been developed since writing this. If it fails, I recommend consulting the online documentation:
https://pro.arcgis.com/en/pro-app/help/analysis/geoprocessing/share-analysis/publishing-web-tools-in-arcgis-pro.htm and
https://pro.arcgis.com/en/pro-app/help/analysis/geoprocessing/share-analysis/use-a-geoprocessing-package.htm

  • Run the “Hurricane Mapper” tool once to produce some valid output.
  • Activate the Share menu and from the Geoprocessing dropdown, select the tool you just ran from the list. This will open the Geoprocessing Package pane.
    • Edit the name of your tool, include your Duke NetID so the name is unique.
    • Add info such summary, tags, etc.
    • Check the box next to Package Schema Only.
    • Optionally, place your geoprocessing package in a subfolder you’ve created in your AGOL account.
  • Share the tool with the ENV859_2022 group.
  • Click Analyze to see if you have any issues sharing your tool.
  • If none, select Package. This generates a geoprocessing package and uploads it to your ArcGIS online account.
  • When complete, navigate to your Duke AGOL page.
  • From there, you can see you can download your tool as a Geoprocessing Package (Consult the documentation how these can be used: https://pro.arcgis.com/en/pro-app/help/analysis/geoprocessing/share-analysis/use-a-geoprocessing-package.htm )

Recap

You’ve now run through the entire process for creating a robust, powerful, and user-friendly geoprocessing tool that you can share with others. The hurricane tool we’ve used as a basis for this exercise is a fairly simple one, but you should be able to envision that these tools can be quite complex under the hood, but present themselves as useful tools that others with very little GIS experience can us.

Thinking ahead, in running through these exercises, you’ve also previewed a number of important concepts relating to our next section: Programming in Python. Turns out, workspace set up, variables & data types, conditional execution, and iteration are all important and useful components in building script based tools. Yes, there will be a bit of learning curve in moving to a scripting environment for your tool-building. However, you should soon appreciate that the move pays quite big dividends in terms of what your tool can do and how easily it can be done…