Introduction to ModelBuilder
ModelBuilder is a visual programming language in ArcGIS Pro that allows you use a graphical editor to create custom tools that allow you to automate complex, tedious, or repetitive tasks where there are consistent step-by-step workflow sequences of operations.
Using ModelBuilder, you graphically chain together sequences of tools from the toolbox.
Advantages:
- ModelBuilder diagrams allow you to change parameters and re-run tools without having to retype and remember your prior settings.
- ModelBuilder creates accessible diagrams as documentation for reports.
- ModelBuilder's only prerequisite requirement is familiarity with ArcGIS Pro tools and workflows.
- ModelBuilder is a simpler alternative to Python scripting in ArcPy and requires no background in coding.
- ModelBuilder can be a good solution for GIS people who infrequently create automated workflows.
Disadvantages:
- ModelBuilder provides no ability to automate symbology or layout.
- ModelBuilder creates an illusion of simplicity by hiding important details.
- ModelBuilder promotes vendor lock-in to ESRI products.
- ModelBuilder is a specialized skill, as opposed to Python programming as a general skill.
- ModelBuilder diagrams of complex workflows can be incomprehensible.
- ModelBuilder does not facilitate modular decomposition.
- When you create spaghetti code in a visual programming language, it actually looks like spaghetti.
This tutorial demonstrates the basic use of ModelBuilder to automate simple workflows.
- Workflows
- Creating a ModelBuilder Diagram
- View Python
- Saving Diagrams
- Example Spatial Aggregation: Power Plants
- Example Spatial Selection: Construction
- Diagram Export
- Project Packages
Workflows
A workflow is "the sequence of steps involved in moving from the beginning to the end of a working process" (Merriam-Webster 2023).
ModelBuilder might be better called WorkflowBuilder since what you are usually creating in ModelBuilder are automated workflows for complex sequences of processing tasks rather than models that are analytical representations of real-world phenomena.
ModelBuilder allows you to transform conceptual workflows into sequences of tool operations while also documenting those workflows as diagrams that facilitate communication of information about those workflows with non-technical audiences.
Workflows can be expressed in text as a sequence of steps. For example, this is the workflow for the address selection example given below:
- Download and unzip the shapefiles from the Lake County, Illinois Open Data and Records Hub.
- Import the data into the project database using the Export Features tool.
- Select the streets with construction activity using the Select tool.
- Select the addresses within 50 meters of the construction activity using the Select Layer By Location tool.
- Copy the selected features into a new project database feature class using the Export Features tool.
- Customize the map symbology.
- Create a figure layout map of the affected addresses.
Creating a ModelBuilder Diagram
To start the ModelBuilder editor, on the Analysis ribbon, select ModelBuilder.
To add a tool, on the View ribbon, select Geoprocessing, search for the tools and drag them into ModelBuilder. Tools are represented in model builder as rectangles and data is represented with ovals.
- ModelBuilder tools are often daisy-chained, with outputs of each tool to the inputs of the next tool in the sequence.
- Inputs are selected from the dropdown lists in the tool dialogs, and ModelBuilder adds corresponding connection lines to the diagram.
- Where there are multiple files with similar names, this diagramming can help the creator make sure they have selected the appropriate inputs.
View Python
Behind the scenes, ModelBuilder creates Python code that you can view.
On the ModelBuilder ribbon, click the Export options (green arrow) and select Send To Python Window to view or copy the code.
Saving Diagrams
ModelBuilder diagrams are kept in a toolbox that you can view in the Catalog pane.
ModelBuilder diagrams must be explicitly saved using the Save button on the ModelBuilder ribbon.
You must save your diagram before saving your project or saving a project package, or your diagram may be missing some or all components when you reopen the project or project package.
Example Spatial Aggregation: Power Plants
This example demonstrates spatial aggregation (spatial join) by using power plant data to calculate per-capita coal-fired power plant generating capacity by state.
The power plant data is originally from the Energy Information Administration, and the state polygons are originally from the US Census Bureau. Both data sets are publicly available through the University of Illinois ArcGIS Online organization and can be directly loaded into ArcGIS Pro without having to go through a download / unzip process needed with shapefiles.
ModelBuilder Diagram
The following is the sequence of tools in this example:
- Select the specific type of plant with the Select tool.
- Input Feature Class: Find the Minn 2020 Power Plants feature service in ArcGIS Online.
- Output Feature Class: Power_Plants
- Expression: Where Coal_MW > 0
- Sum the installed capacity by state using the Spatial Join tool.
- Target Features: Find the Minn 2015-2019 ACS States feature service in ArcGIS Online.
- Join Features: Power_Plants
- Output Feature Class: Power_States
- Fields: Remove all fields except:
- Name
- Total_Population
- Installed_Nameplate_MW (Merge Rule: Sum)
- Calculate per capita values with the Calculate Field tool.
- Input Table: Power_States
- Field Name: KW_Per_Capita
- Field Type: Double
- Expression: !Installed_Nameplate_MW! * 1000 / !Total_Population!
- Run ModelBuilder.
Map and Layout
Unless you set an output feature class to Add to Display, the ModelBuilder run will not change your map. Since ModelBuilder cannot change map symbology, you have to style the map manually anyway.
- Add the new feature class to a map.
- Style the map symbology.
- Note that ModelBuilder calculated fields may not show up in the field list and you will need to create a custom expression.
- Change the name from Custom to something meaningful for the legend (KW Coal per Capita).
- Insert a new figure layout (6 x 4).
- Add map frame.
- Hide the base map service credits.
- Add and format the legend.
- Export to PNG (Power_States.png).
- Import into Word.
- Rename the model, map, and layout (Power_States) in case you add additional items and need to be able to keep track of what goes with what.
Example Spatial Selection: Construction
This example demonstrates spatial selection in a scenario where you want to select address points around planned street construction in order to inform residents and businesses about potential traffic disruptions.
Feature Service Endpoints
The data used in this example will be address points and street centerlines from the Lake County, Illinois Open Data and Records Hub https://data-lakecountyil.opendata.arcgis.com/.
Because these data sets are large, this example will access this data using feature services provided on the hub page. This data is also available as zipped shapefiles in case you need a fixed snapshot of the data.
- Search for Address Points.
- Select I want to use this at the bottom of the information pane.
- Go to the View API Resources and copy the GeoService endpoint API URL.
- Repeat for Street Centerlines.
To use these endpoint URLs in the tools below, you will need to remove the query strings.
The endpoint URL provided by the data portal will look something like this:
https://services3.arcgis.com/HESxeTbDliKKvec2/arcgis/rest/services/LakeCounty_Transportation/FeatureServer/1/query?outFields=*&where=1%3D1
When you remove the query information, it should look something like this:
https://services3.arcgis.com/HESxeTbDliKKvec2/arcgis/rest/services/LakeCounty_Transportation/FeatureServer/1/
ModelBuilder Diagram
The following is the sequence of tools in this example:
- Create a feature class of streets under construction with the Select tool.
- Input Features: Copy the street centerlines feature service endpoint from the data portal. Remove the query string as demonstrated above.
- Output Features: Construction
- Expression:
- WHOLE_NAME is equal to N Butrick St
- AND Left FROM Address >= 700
- AND Left FROM Address <= 999
- AND Incorporated Municipality Left = WAUKEGAN
- Find the affected addresses using the Select Layer By Location tool.
- Input Features: Copy the address points feature service endpoint from the data portal. Remove the query string as demonstrated above.
- Relationship: Within a distance geodesic
- Selecting Features: Construction
- Distance: 50 meters
- Create a feature class of the affected addresses using the Export Features tool
- Input Features: Address_Points
- Output Features: Affected
- Right click on Affected and select Add to Display so the affected addresses are shown on the map.
- Under the ModelBuilder ribbon, select Run.
Map and Layout
Unfortunately, ModelBuilder does not provide the ability to create new maps or layouts, and does not provide the ability automate map or layout formatting. You will need to symbolize and lay out the map manually.
- Add the construction street and affected address points.
- Style the map symbology (red dots, navy 2px street).
- Insert a new figure layout (6 x 4).
- Add map frame.
- Hide the base map service credits.
- Add and format the legend.
- Export to PNG (construction.png).
- Import into Word.
- To rename a diagram, View the Catalog Pane, find the model in Toolbox, right-click on Properties (Construction).
Diagram Export
ModelBuilder diagrams can be exported to SVG and PDF files. Unfortunately, neither of those formats can be directly imported into Word documents.
The closest workaround is to take a screenshot of the diagram (using the PrtScr button on your keyboard), paste it into the document, and then crop to show only the diagram. The diagram will be fuzzy when printed, and getting a better quality document involves doing a conversion from SVG or PDF into PNG using an external program.
Project Packages
ModelBuilder uses a toolbox that must be included in your project package if you want to be able to use this diagram on a different machine.
Make sure to check both share outside organization and include toolboxes when sharing a project package or the packaging may fail with an unhelpful failure message.
By default, data sets used or created in modelbuilder will be packaged in the project package. For feature services with large amounts of data (like the street centerlines and address points above) this will require significant time to package and upload.
Error 001659: consolidating toolbox
Error 001659: consolidating toolbox can occur when the project package contains large data sets, like the Lake County address points and street centerlines.
The workaround is to Save package to file and then upload the package file (.ppkx) to ArcGIS Online through your My Content page in a browser.
\\192.168.100.3\DeptUsers\minn2\Documents\ArcGIS\Projects\Model Builder\Model Builder.atbx Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:39 Status: InProgress StatusMessage: Successfully wrote sharing info file Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:39 Status: InProgress StatusMessage: Creating thumbnail from map Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:39 Status: InProgress StatusMessage: About to start the external packaging process Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:39 Status: Pending StatusMessage: Sharing process started Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:39 Status: InProgress StatusMessage: Sharing process started Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:39 Status: InProgress StatusMessage: Reading thumbnail from file Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:39 Status: InProgress StatusMessage: Packaging in progress Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:40 Status: InProgress StatusMessage: Creating a project package and uploading it to the portal Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:40 Status: InProgress StatusMessage: Compiling packaging parameters Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:40 Status: InProgress StatusMessage: Initiating the packager Model_Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 21:49:40 Status: InProgress StatusMessage: The project package tool has started Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 22:01:27 Status: Failed ErrorMessage: ERROR 001659: Consolidating toolbox \\192.168.100.3\DeptUsers\minn2\Documents\ArcGIS\Projects\Model Builder\Model Builder.atbx Model Builder.ppkx 176 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 22:01:29 Status: Failed ErrorMessage: Failed to package.
General Function Failure
The General Function Failure seems to occur if you share a project package without saving the diagram from the ModelBuilder ribbon with the Save button.
In some cases you might also need to completely close and restart ArcGIS Pro, reopen the project, and try sharing the package again.
It may also be necessary to close the ModelBuilder diagram before sharing.
Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:08 Status: InProgress StatusMessage: Successfully wrote sharing info file Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:08 Status: InProgress StatusMessage: Creating thumbnail from map Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:08 Status: InProgress StatusMessage: About to start the external packaging process Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:08 Status: Pending StatusMessage: Sharing process started Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:08 Status: InProgress StatusMessage: Sharing process started Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:08 Status: InProgress StatusMessage: Reading thumbnail from file Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:09 Status: InProgress StatusMessage: Packaging in progress Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:09 Status: InProgress StatusMessage: Creating a project package and uploading it to the portal Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:09 Status: InProgress StatusMessage: Compiling packaging parameters Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:09 Status: InProgress StatusMessage: Initiating the packager Model_Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:09 Status: InProgress StatusMessage: The project package tool has started Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:16 Status: Failed ErrorMessage: General function failure Model Builder.ppkx 178 ProjectPackage University of Illinois https://univofillinois.maps.arcgis.com/ minn2@illinois.edu_UnivofIllinois_1190444167 2022-10-23 23:08:18 Status: Failed ErrorMessage: Failed to package.
Database Not Found
The cryptic the database was not found packaging failure message apparently occurs because the feature classes created by modelbuilder are placed in the toolbox geodatabase rather than the project geodatabase.
If the Include Toolboxes option is not checked. the ModelBuilder toolbox (and its database) are not included in the project, share outside organization cannot include all feature classes used in project maps, and the packaging fails.
\\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:26 status: inprogress statusmessage: successfully wrote sharing info file \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:26 status: inprogress statusmessage: creating thumbnail from map \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:26 status: inprogress statusmessage: about to start the external packaging process \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:26 status: pending statusmessage: sharing process started \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:26 status: inprogress statusmessage: sharing process started \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:26 status: inprogress statusmessage: reading thumbnail from file \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:26 status: inprogress statusmessage: packaging in progress \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:28 status: inprogress statusmessage: creating a project package and saving it locally \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:28 status: inprogress statusmessage: compiling packaging parameters \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:28 status: inprogress statusmessage: initiating the packager \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:28 status: inprogress statusmessage: the project package tool has started \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:40 status: failed errormessage: the database was not found. \\192.168.100.3\deptusers\minn2\documents\arcgis\model builder.ppkx 173 projectpackage 2022-10-23 20:38:42 status: failed errormessage: failed to package.
Debugging Packaging Errors
Creating the package with ArcPy using arcpy.management.ProjectPackage() is touted as a debugging technique, but the output about missing tools is equally cryptic.
arcpy.management.PackageProject('\\\\192.168.100.3\\DeptUsers\\minn2\\Documents\\ArcGIS\\Projects\\Model Builder\\Model Builder.aprx', 'temp.ppkx')
Traceback (most recent call last):
File "", line 1, in
File "C:\Program Files\ArcGIS\Pro\Resources\ArcPy\arcpy\management.py", line 12554, in PackageProject
raise e
File "C:\Program Files\ArcGIS\Pro\Resources\ArcPy\arcpy\management.py", line 12551, in PackageProject
retval = convertArcObjectToPythonObject(gp.PackageProject_management(*gp_fixargs((in_project, output_file, sharing_internal, package_as_template, extent, apply_extent_to_arcsde, additional_files, summary, tags, version, include_toolboxes, include_history_items, read_only, select_related_rows, preserve_sqlite), True)))
File "C:\Program Files\ArcGIS\Pro\Resources\ArcPy\arcpy\geoprocessing\_base.py", line 512, in
return lambda *args: val(*gp_fixargs(args, True))
arcgisscripting.ExecuteError: ERROR 002700: At version 2.2 the "ExportFeatures (conversion)" tool is not available
ERROR 003498: At version 2.2 the "SelectLayerByLocation (management)" tool's "Input Features" parameter's multiValue has changed
Failed to execute (PackageProject).