ESRI Toolbox Scripts, Custom Ribbon, and ModelBuilder

Using Toolbox Scripts and ModelBuilder for Assetic Integration

Introduction

The Assetic ESRI Python SDK may be used by the ESRI ModelBuilder as part of a geoprocessing process that includes adding or updating Assets in Assetic.

Refer to the overview article ESRI-Integration-Intoduction for details on how to implement the Assetic ESRI Python SDK. This article assumes that it is already installed and configured.

This article details step by step how to setup a basic Model using ModelBuilder in ArcMap for Asset creation in Assetic. This approach may also be used for asset updates in Assetic using the sample script provided in this article

Sample Scripts

The following scripts are available to assist with the processes described in this article. These scripts will update the designated attribute of the selected features with the Assetic ID or internal GUID depending on configuration. To enable this, an edit session is created and the edits performed with the edit session. This provides support for versioned geodatabase environments. When executing the scripts ensure you are not already in an edit session.

Note: Feature edits made by the integration scripts (such as updating a feature's attribute with an Assetic ID or internal GUID) can sometimes not be seen locally for ESRI web feature layers. This can be due to layer caching options in ArcGIS Pro. Disabling caching for a layer or refreshing the layer cache can resolve this and ensure the local layer view reflects the current state of the layer data. See the ESRI article on how to Set Cache Options for more information.

Create Asset

There are 2 toolbox scripts available for download to initiate 'Asset Creation' and 'Asset Update'.

Note: You may need to right click and 'Save As' to download.

The following 2 scripts are for use within an ArcMap Edit Session, or ArcGIS Pro if the layer is not a versioned geodatabase.

Create Functional Location

There are 2 toolbox scripts available for download to initiate 'Functional Location Creation' and 'Functional Location Update'.

Note: You may need to right click and 'Save As' to download.

The following 2 scripts are for use within an ArcMap Edit Session, or ArcGIS Pro if the layer is not a versioned geodatabase.

Create Toolbox

The first step is to create a toolbox from the Catalog pane.

ArcMap
Create a new toolbox called "Assetic.tbx" by right clicking on 'My Toolboxes' and choosing the menu option 'New'->'Toolbox'.
ArcGIS Pro
Create a new toolbox called "Assetic.atbx" by right clicking on 'Toolboxes' and choosing the menu option 'New Toolbox (.atbx)'.

If you already have a custom toolbox you could choose to use it for the remaining steps. Alternatively, a toolbox may be provided for you in which case it can be imported into the project by choosing "Add Toolbox" from the right click menu.

Add Script Tool (ArcMap)

Right click on the Assetic.tbx toolbox select ‘Add’->’Script’

A new dialog window titled ‘Add Script’ will appear. Enter the name of the script tool without spaces, and then a user-friendly label for the tool. Finally add a Description for the tool. You may optionally choose ‘Store relative path names’.

Finally choose the ‘Next’ button.

The ‘Add Script’ dialog window will next allow you to choose the script file. Choose the file Assetic.CreateAssetsTbxScript.py and then choose the ‘Next’ button.

The ‘Add Script’ dialog window will show a parameter list. Enter ‘layer’ for the display name, and ‘Layer’ as the data type. When the tool is run, it will be expecting a layer to passed in. This is the layer to be processed. Choose Finish to complete creation of the tool.

Add Script Tool (ArcGIS Pro)

Right click on the "Assetic.atbx" toolbox select 'New' -> 'Script'

A new dialog window titled 'New Script' will appear.

In the General tab enter a name for the script tool without spaces as a unique identifier, a user-friendly label for the tool and finally a Description.

In the Parameters tab, enter a parameter with the label and name ‘layer’, and then choose ‘Layer’ from the dropdown for the Data Type. When the tool is run, it will be expecting a layer to passed in, which is the layer that will be processed.

The Execution tab will allow you to browse and choose the script file. Choose the file Assetic.CreateAssetsTbxScript.py to import the script data.

Optionally, the "Embed script into tool" option can be selected in the Execution tab to import the script's data as an embedded copy. When embedded, any changes to the external script file do not affect the script saved within the Toolbox, as it is now an unconnected copy.

Select "OK" to complete the addition of the new toolbox script.

The above process can be repeated for any additional scripts that need to be added to a Toolbox.

Custom Ribbon Tab in ArcGIS Pro

The ArcGIS Pro ribbon can be customized with new custom tabs allowing users to choose which commands appear on them. Custom groups for the tab can also be added with user specified names in order to bundle commands with interconnected functionality, or by some other logical grouping aspect.

Any Python script added to a toolbox in an ArcGIS Pro project is considered a 'geoprocessing tool', which is a command or function that performs an operation on GIS data. As such, it is possible to add any Assetic toolbox scripts that have been created and added to a project toolbox to a custom ribbon tab. This allows the scripts to be alternatively launched and executed from the main ArcGIS Pro ribbon interface, instead of from the toolbox hierarchy in the Catalog view.

An example custom ribbon tab, with groups to bundle integration processes, can be seen below:

Custom Command Icons

Models and script tools, which have been added as commands on an ArcGIS Pro custom ribbon tab, can be further customized to have a custom icon for display in ribbon user interface.

Note: Customizing Model and Script tools to use custom icons in the ribbon requires ArcGIS Pro v3.2 or greater, and the Assetic toolbox scripts must be added to the ArcGIS Pro toolbox with the ".atbx" format.

If intending to use custom icon images for the ArcGIS ribbon, it is recommended to apply the images to the script or model prior to configuring and assigning the command on a custom ribbon tab. From experience, the ESRI default script tool image () can sometimes remain cached and prove difficult to refresh with a custom image if the icon is changed after the command has already been assigned to a custom tab.

To add the custom icons, first ensure that the Assetic toolbox scripts have been added to a toolbox (.atbx) in the current ArcGIS Pro project. Then, for each script tool that requires a custom image icon, from the Catalog pane right click the script within the toolbox and choose properties.

Within the 'General' tab of the properties, the default script icon can be selected to prompt users to browse to a custom image with either the ".jpg", or the ".png" format.

A collection of custom script icons created by Brightly for use in Assetic ESRI script tools can be downloaded below:

Create Custom Ribbon Tab

To create a new custom ribbon tab, access the ArcGIS Pro 'Options' through the 'Project' tab and then locate the 'Customize the Ribbon' tab. Alternatively, right click on any existing ribbon tab in the user interface and choose 'Customize the Ribbon'.

In the 'Customize the Ribbon' tab choose the 'New Tab' dropdown. To create a custom ribbon tab that is always displayed choose the 'New Tab' option from the dropdown.

Alternatively, a contextual tab can be created by scrolling further down the on the list of existing tabs and then selecting an existing contextual tab (e.g. Table) and choosing the 'New Tab with Context' option. This will configure the custom ribbon tab to only display when the application is in a particular state, such as when an attribute table is the active view.

Once a new tab has been created, it can be found in the list of tabs and can be renamed to something appropriate, such as 'Assetic'. Optionally, while the tab is selected, groups can be added using the 'New Group' button if there is the desire to group the Assetic script tools into smaller subsets.

The below example shows a new tab that has been added, with two new groups:

After the tab has been created with any desired groups, the existing Assetic script tools that have been added prior to a project toolbox can be assigned to the custom tab.

Select the 'All Geoprocessing Tools' options from the command filtering dropdown, and search for the toolbox scripts based on either their label or using the name of the toolbox.

Select a script tool as an input, then select the desired destination tab or tab group, and choose the 'Add' button to assign it to that location on the custom ribbon tab. Repeat for each script to add it to an appropriate tab location.

When finished, select OK to finalise the creation of the Custom Ribbon Tab.

The ESRI Customize the ribbon options help article also covers the above process and contains additional details on the options available to users when configuring a custom ribbon tab.

ModelBuilder Create Asset Model

Having created an Assetic asset creation integration tool, a model that utilises the tool may be optionally built.

New Model

The first step is to create a new model. Right click on the Assetic.tbx, or the toolbox containing the integration scripts, and choose ‘New’->’Model’.

An empty model designer window will appear when the model is created.

Model Design

Drag the previously created "Create Assets" toolbox script from the toolbox into the model.

Then, using the ModelBuilder tools tab, insert a variable of data type 'Layer'. Right click the new variable and set it as a parameter, and then rename the variable as 'Input Layer'.

An alternative, simpler way to do this is to drag in an existing layer from the project and then rename the object to ‘Input Layer’ and then clear the layer name from the variable's properties.

To ensure that only features which are new and don't already have a corresponding asset already created are passed in to Assetic, include the tool 'Select Layer By Attribute'. This is a system tool and can be found by searching for it either from the Tools dropdown in the ModelBuilder tab, or in the Geoprocessing window search.

Note: there is also check by the Assetic ESRI Python SDK package to make sure the asset ID does not already exist before trying to create the asset in Assetic.

Drag the 'Select Layer By Attribute' tool on to the Model canvas to add it.

Then click and drag an input arrow from the 'Input Layer' variable to the 'Select Layer By Attribute' variable to set 'Input Layer' as the 'Input Rows' for the tool.

Double click the 'Select Layer By Attribute' variable to open the properties.

In the screenshot below a filter of 'ASSET_ID IS NULL' ensures that only features that don’t already have an existing Asset Id in Assetic are passed in for asset creation.

Note: In order to set the expression, you may need to temporarily choose an existing feature layer for the 'Input Rows' property. After the expression is set, the 'Input Rows' property can be set back to the 'Input Layer' variable.

The 'Selection Type' parameter can be modified depending on requirements, where 'New selection' would select all features from the input layer that don't yet have a corresponding Assetic asset. For more control, a different 'Selection Type' (e.g. subset from current selection) can be chosen so only features from the current feature selection are used as input rows.

Select 'OK' to set the properties for the 'Select Layer By Attribute' tool.

Then set the 'Input Layer' variable as the input for ‘Create Asset’ variable.

Finally, ensure that the 'Select Layer By Attribute' tool is run first by setting it as a precondition. This is done either in the properties of the 'Create Asset' tool by double clicking it, or by dragging a line from the 'Updated Layer or Table View' variable to the 'Create Asset' variable and selecting 'Precondition'.

Model Properties

Set the properties of the model including a name without spaces and user-friendly label and description.

Select 'Save' from the 'ModelBuilder' ribbon tab to finalise the creation of the Model.

Final Model Overview

Toolbox Scripts

Assetic.CreateAssetsTbxScript.py

The following script can be used as a toolbox script for creating assets in Assetic that correspond with new features in ArcMap. The asset is created with a status of 'Active'

"""
Assetic.CreateAssetsTbxScript.py
Script to setup as a toolbox script for use in Model Builder
create assets in Assetic from the selected features in ArcGIS layer
Assume Model Builder model has applied a feature selection
This example assumes script is run in an edit session
Requires assetic_esri v1.0.1.4 or later
"""
import arcpy
import assetic_esri
import os
  
layer = arcpy.GetParameter(0)
  
  
def main(layer):
  """
    For the given layer's selected features
    create a corresponding asset in Assetic and update the feature with
    the asset friendly asset id, or the assetic internal asset guid.
    Assumes the xml config file has the layer name (as appears in the TOC)
    :param layer: the layer to process
    """
  # Initialise the assetic_esri library.  It will read the config files etc
  if  not initasseticesri():
  return
  
  # initialise assetic esri tools for layers
    tools = assetic_esri.LayerTools()
  # Uncomment to following if using arcMap and you don't want messages to
  # go to pythonaddins.MessageBox(), assetic_esri instead uses
  # arcpy.AdMessage() to send messages
  #assetic_esri.config.force_use_arcpy_addmessage = True
  
  # get record count
    count = len(layer.getSelectionSet())
  
  # execute asset creation
    arcpy.AddMessage("Processing layer: {0}, {1} Selected Features".format(
        layer.name, count))
    tools.create_asset(layer)
  
  # uncomment if arcMap to reset message output in case addin is used next
  #assetic_esri.config.force_use_arcpy_addmessage = False
  
  
def initasseticesri():
  """
    initialise the helper module assetic_esri
    sets the paths to the xml config and ini files
    """
    appdata = os.environ.get("APPDATA")
    inifile = os.path.abspath(appdata +  "\\Assetic\\assetic.ini")
    logfile = os.path.abspath(appdata +  "\\Assetic\\addin.log")
    xmlfile = os.path.abspath(appdata +  "\\Assetic\\arcmap_edit_config.xml")
  try:
        ae = assetic_esri.Initialise(xmlfile, inifile, logfile,  "Info")
  except  Exception  as ex:
        arcpy.AddError("Error initialising assetic_esri: {0}".format(ex))
  return  False
  return  True
  
  
if __name__ ==  "__main__":
    main(layer)

Assetic.UpdateAssetsTbxScript.py

The following script can be used as a toolbox script for updating assets in Assetic that correspond with features in ArcMap

"""
Assetic.UpdateAssetsTbxScript.py
Script to setup as a toolbox script for use in Model Builder
update assets in Assetic from the selected features in ArcGIS layer
Assume Model Builder model has applied a feature selection
This example assumes there is no geoadatabase versioning and will not initiate
an edit session to perform edits
Requires assetic_esri v1.0.1.4 or later
"""
import arcpy
import assetic_esri
import os
  
layer = arcpy.GetParameter(0)
  
  
def main(layer):
  """
    For the given layer's selected features
    update the corresponding asset in Assetic
    Versioned editing is assumed.
    A new edit session is opened for the layer
    edit
    Assumes the xml config file has the layer name (as appears in the TOC)
    :param layer: the layer to process
    """
  # Initialise the assetic_esri library.  It will read the config files etc
  if  not initasseticesri():
  return
  
  # Uncomment to following if using arcMap and you don't want messages to
  # go to pythonaddins.MessageBox(), assetic_esri instead uses
  # arcpy.AdMessage() to send messages
  #assetic_esri.config.force_use_arcpy_addmessage = False
  
  # initialise assetic esri tools for layers
    tools = assetic_esri.LayerTools()
  
  
  # get record count
    count = len(layer.getSelectionSet())
  
  # execute asset update
    arcpy.AddMessage("Processing layer: {0}, {1} Selected Features".format(
        layer.name, count))
    tools.update_assets(layer)
  
  # uncomment if arcMap to reset message output in case addin is used next
  #assetic_esri.config.force_use_arcpy_addmessage = False
  
  
def initasseticesri():
  """
    initialise the helper module assetic_esri
    sets the paths to the xml config and ini files
    """
    appdata = os.environ.get("APPDATA")
    inifile = os.path.abspath(appdata +  "\\Assetic\\assetic.ini")
    logfile = os.path.abspath(appdata +  "\\Assetic\\addin.log")
    xmlfile = os.path.abspath(appdata +  "\\Assetic\\arcmap_edit_config.xml")
  try:
        ae = assetic_esri.Initialise(xmlfile, inifile, logfile,  "Info")
  except  Exception  as ex:
        arcpy.AddError("Error initialising assetic_esri: {0}".format(ex))
  return  False
  return  True
  
  
if __name__ ==  "__main__":
    main(layer)