Append Routes (Location Referencing)

Available with Location Referencing license.

Summary

Appends routes from an input polyline into an LRS Network.

Note:

When the target layer is a feature service layer, the validation results for this tool are written to the ArcGIS Server directory. This file is automatically cleaned up in 10 minutes by default, which may not be enough time to process all of the validations and write them to your workstation running ArcGIS Pro. For larger data loads, it is recommended that you adjust the maximum file age to at least one hour.

Learn more about adjusting this server directory setting in Manager

Usage

• An LRS dataset is required to run this tool. To create an LRS dataset, add the calibration point, centerline, and redline layers to a feature dataset; then run the Modify LRS tool with the geodatabase as the input.

• This tool will create centerlines in the target LRS dataset as well as routes in the target LRS Network.

• The output routes will have x-, y-, and z-values from the input polyline vertices, but no m-values will be appended.

• If your source polyline feature class has editor tracking enabled, map the source editor tracking fields to the fields you will use for editor tracking in the LRS Network while editor tracking is disabled in the target.

• Any new fields that will be used for field mapping should be created in the underlying LRS Network feature class before appending routes.

• The spatial reference, XY resolution, and XY tolerance of the input polyline feature class and the target LRS Network must match.

• A text log is written locally that states that the tool has been executed and contains information on any routes that failed validation. The tool messages provide the location of the text log, which is in the temporary directory.

• The output of this tool is a modified LRS Network that has had routes appended and centerline features created.

• When conflict prevention is enabled, the following are supported:

  • If the routes to be appended are new, no locks will be acquired for those routes.
  • For other load types, such as RETIRE_BY_ROUTE_ID and REPLACE_BY_ROUTE_ID, locks will be automatically acquired, if available.
  • If the locks cannot be acquired, the tool will not run and will provide the text file of offending locks.
  • If working in the default version, the locks acquired are released automatically when the tool finishes running successfully.
  • If working in a child version, the acquired locks will remain in ON POST status after the tool completes. Post or delete the version to release the locks.
  • If working in a child version and the execution of the tool is canceled by interruption, the locks are acquired and remain with the releasable status as Yes. The lock owner can release the lock.

    Learn more about releasing locks in Pipeline Referencing or releasing locks in Roads and Highways.

  Learn more about conflict prevention in Pipeline Referencing or conflict prevention in Roads and Highways.

• If the target LRS Network is configured as a line network with support for a multifield route ID, the following parameters are not required for appending routes:

  • Route Name Field
  • Line Name Field

Parameters

Dialog

Label	Explanation	Data Type
Source Routes	The input from which the routes will be derived. The input can be a polyline feature class, shapefile, feature service, or LRS Network feature class.	Feature Layer
LRS Network	The target LRS Network into which the routes will be loaded.	Feature Layer
Route ID Field	The field in the input polyline feature class that will be mapped to the LRS Network route ID. The field type must match the RouteID field type of the target LRS Network and must be either a string or GUID field type. If it is a text field, the field length must be shorter than or equal to the length of the target RouteID field.	Field
Route Name Field	The field in the input polyline feature class that will be mapped as the LRS Network route name. The field must be a string field, and the field length must be shorter than or equal to the length of the target route name field.	Field
From Date Field (Optional)	A date field in the input polyline feature class that will be mapped as the From Date Field in the LRS Network . If the field is not mapped, a null value representing the beginning of time will be provided for all appended routes.	Field
To Date Field (Optional)	A date field in the input polyline feature class that will be mapped as the To date in the LRS Network. If a To date field is not mapped, a null value representing the end of time will be provided for all appended routes.	Field
Line ID Field (Optional)	The field in the input polyline feature class that will be mapped as the LRS Network line ID. This parameter is only used if the target is an LRS line network. The field type must match the RouteID field type of the centerline sequence table and must be either a string of exactly 38 characters or a GUID field type.	Field
Line Name Field (Optional)	The string field in the input polyline feature class that will be mapped as the LRS Network line name. This parameter is only used if the target is an LRS line network.	Field
Line Order Field (Optional)	The long integer field in the input polyline feature class that will be mapped as the LRS Network line order. This parameter is only used if the target is an LRS line network. Learn more about line networks and line order in Pipeline Referencing or line networks and line order in Roads and Highways.	Field
Field Map (Optional)	Controls how attribute information in the source route fields is transferred to the input LRS Network. Fields cannot be added to or removed from the target LRS Network because the data of the source routes is appended to an existing LRS Network that has a predefined schema. While you can set merge rules for each output field, the tool will ignore those rules.	Field Mappings
Load Type (Optional)	Specifies how appended routes with measure or temporality overlaps with identical route IDs as Target Network records are loaded into the network feature class. Add —The appended routes are loaded into the target LRS Network. If any route ID in the source routes already exists in the target LRS Network with the same temporality, it will be written to the output log as a duplicate route and must be corrected or filtered out before completing the loading process. This is the default. Retire by route ID —The appended routes are loaded into the target LRS Network and any routes in the target LRS Network that have the same route ID and temporality overlap as the appended routes are retired. If the appended route eclipses a target route with the same route ID, the target route is deleted. Replace by route ID —The appended routes are loaded into the target LRS Network and any routes in the target LRS Network with the same route ID as the appended routes are deleted.	String

Derived Output

Label	Explanation	Data Type
LRS Network	The updated LRS Network feature layer.	Feature Layer
Output Results File	The text file that details changes made by the tool.	Text File

Python

arcpy.locref.AppendRoutes(source_routes, in_lrs_network, route_id_field, route_name_field, {from_date_field}, {to_date_field}, {line_id_field}, {line_name_field}, {line_order_field}, {field_map}, {load_type})

Name	Explanation	Data Type
source_routes	The input from which the routes will be derived. The input can be a polyline feature class, shapefile, feature service, or LRS Network feature class.	Feature Layer
in_lrs_network	The target LRS Network into which the routes will be loaded.	Feature Layer
route_id_field	The field in the input polyline feature class that will be mapped to the LRS Network route ID. The field type must match the RouteID field type of the target LRS Network and must be either a string or GUID field type. If it is a text field, the field length must be shorter than or equal to the length of the target RouteID field.	Field
route_name_field	The field in the input polyline feature class that will be mapped as the LRS Network route name. The field must be a string field, and the field length must be shorter than or equal to the length of the target route name field.	Field
from_date_field (Optional)	A date field in the input polyline feature class that will be mapped as the From Date Field in the LRS Network . If the field is not mapped, a null value representing the beginning of time will be provided for all appended routes.	Field
to_date_field (Optional)	A date field in the input polyline feature class that will be mapped as the To date in the LRS Network. If a To date field is not mapped, a null value representing the end of time will be provided for all appended routes.	Field
line_id_field (Optional)	The field in the input polyline feature class that will be mapped as the LRS Network line ID. This parameter is only used if the target is an LRS line network. The field type must match the RouteID field type of the centerline sequence table and must be either a string of exactly 38 characters or a GUID field type.	Field
line_name_field (Optional)	The string field in the input polyline feature class that will be mapped as the LRS Network line name. This parameter is only used if the target is an LRS line network.	Field
line_order_field (Optional)	The long integer field in the input polyline feature class that will be mapped as the LRS Network line order. This parameter is only used if the target is an LRS line network. Learn more about line networks and line order in Pipeline Referencing or line networks and line order in Roads and Highways.	Field
field_map (Optional)	Controls how attribute information in the source route fields is transferred to the input LRS Network. Fields cannot be added to or removed from the target LRS Network because the data of the source routes is appended into an existing LRS Network that has a predefined schema (field definitions). While you can set merge rules for each output field, the tool will ignore those rules. The ArcPy FieldMappings class can be used to define this parameter.	Field Mappings
load_type (Optional)	Specifies how appended routes with measure or temporality overlaps with identical route IDs as Target Network records are loaded into the network feature class. ADD —The appended routes are loaded into the target LRS Network. If any route ID in the source routes already exists in the target LRS Network with the same temporality, it will be written to the output log as a duplicate route and must be corrected or filtered out before completing the loading process. This is the default. RETIRE_BY_ROUTE_ID —The appended routes are loaded into the target LRS Network and any routes in the target LRS Network that have the same route ID and temporality overlap as the appended routes are retired. If the appended route eclipses a target route with the same route ID, the target route is deleted. REPLACE_BY_ROUTE_ID —The appended routes are loaded into the target LRS Network and any routes in the target LRS Network with the same route ID as the appended routes are deleted.	String

Derived Output

Name	Explanation	Data Type
out_lrs_network	The updated LRS Network feature layer.	Feature Layer
out_details_file	The text file that details changes made by the tool.	Text File

Code sample

AppendRoutes example 1 (Python window)

Demonstrates how to use the AppendRoutes function in the Python window to append routes into an existing LRS Network, replacing those routes where an overlap occurs.

# Name: AppendRoutes_ex1.py
# Description: Append routes into an existing LRS Network, replacing those routes where an overlap occurs.
# Requires: ArcGIS Location Referencing

# Check out license
arcpy.CheckOutExtension("LocationReferencing")

# Set tool variables
source_routes = r"C:\Data\UPDM.gdb\LRS\EngineeringNetwork"
in_lrs_network = r"C:\Data\NY_Data.gdb\LRS\P_Integrity\P_EngineeringNetwork"
route_id_field = "RouteId"
route_name_field = "RouteName"
from_date_field = "FromDate"
to_date_field = "ToDate"
line_id_field = "LineId"
line_name_field = "LineName"
line_order_field = "LineOrder"
field_map = None
load_type = "REPLACE_BY_ROUTE_ID"

# Execute the tool
arcpy.AppendRoutes_locref(source_routes, in_lrs_network, route_id_field, route_name_field, from_date_field, to_date_field, line_id_field, line_name_field, line_order_field, field_map, load_type)

# Check in license
arcpy.CheckInExtension('LocationReferencing')

AppendRoutes example 2 (stand-alone script)

Demonstrates how to use the AppendRoutes function as a stand-alone Python script.

# Name: AppendRoutes_ex2.py
# Description: Append records into an existing network feature class without performing any attribute field mapping.
# Requires: ArcGIS Location Referencing

# Import arcpy module
import arcpy

# Check out license
arcpy.CheckOutExtension("LocationReferencing")

# Local variables:
SourceRoutes = r"C:\Data\UPDM.gdb\LRS\EngineeringNetwork"
TargetNetwork = r"C:\Data\NY_Data.gdb\LRS\P_Integrity\P_EngineeringNetwork"
Route_ID = "RouteId"
Route_Name = "RouteName"
From_Date = "FromDate"
To_Date = "ToDate"
Line_ID = "LineId"
Line_Name = "LineName"
Line_Order = "LineOrder"

# Process: Append Routes
arcpy.AppendRoutes_locref(SourceRoutes, TargetNetwork, "RouteId", "RouteName", "FromDate", "ToDate", "LineId", "LineName", "LineOrder", None, "ADD")

# Check in license
arcpy.CheckInExtension('LocationReferencing')

AppendRoutes example 3 (stand-alone script)

Demonstrates how to use the AppendRoutes function as a stand-alone Python script for a user-generated route ID network.

# Name: AppendRoutes_ex3.py
# Description: Append records into an existing usergenerated routeId network feature class in a stand-alone script.
# Source fields : RS and RN, Target fields : RouteSystem and RouteNumber
# Requires: ArcGIS Location Referencing 

# Import arcpy module
import arcpy

# Check out license
arcpy.CheckOutExtension("LocationReferencing")

# Local variables:
SourceRoutes = r"C:\Data\DOT.gdb\LRS\RoutestoAppend"
TargetNetwork = r"C:\Data\DOT.gdb\LRS\StateRoutes"
RouteId = "RouteId"
RouteName = ""
FromDate = "FromDate"
ToDate = "ToDate"
LineId = ""
LineName = ""
LineOrder = ""
loadtype = "ADD"

# Define field mappings object
fieldMappings = arcpy.FieldMappings()  

# Add input fields
fldmap1 = arcpy.FieldMap()
fldmap1.addInputField(SourceRoutes, "RS")

fldmap2 = arcpy.FieldMap()
fldmap2.addInputField(SourceRoutes, "RN")

# Set output fields
fld1 = fldmap1.outputField  
fld1.name = "RouteSystem"
fld1.aliasName = "RouteSystem"
fldmap1.outputField = fld1

fld2 = fldmap2.outputField  
fld2.name = "RouteNumber"
fld2.aliasName = "RouteNumber"
fldmap2.outputField = fld2

# Add output fields to field mappings object
fieldMappings.addFieldMap(fldmap1)
fieldMappings.addFieldMap(fldmap2)

# Execute: Append Routes
arcpy.AppendRoutes_locref(SourceRoutes, TargetNetwork, RouteId, RouteName, FromDate, ToDate, LineId, LineName, LineOrder, fieldMappings, loadtype)

# Check in license
arcpy.CheckInExtension('LocationReferencing')

AppendRoutes example 4 (stand-alone script)

Demonstrates how to use the AppendRoutes function as a stand-alone Python script in a feature service.

# Name: AppendRoutes_Pro_Ex4.py
# Description: Append routes using a feature service in a standa-alone script. It is recommended to work in a version and post it into the default version.
# Requires: ArcGIS Location Referencing

# Import arcpy module.
import arcpy

# Check out any necessary licenses.
arcpy.CheckOutExtension("LocationReferencing")

# Set tool variables.
sourceroute = r"C:\LocationReferencing\LR.gdb\LRS\routes"
route_name_field = "ROUTENAME"
from_date_field = "FROMDATE"
to_date_field = "TODATE"
line_id_field = "LINEID"
line_name_field = "LINENAME"
line_order_field = "ORDERID"
field_mapping = r'CREATIONUSER "Creation User" true true false 50 Text 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,CREATIONUSER,0,50;DATECREATED "Date Created" true true false 8 Date 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,DATECREATED,-1,-1;DATEMODIFIED "Date Modified" true true false 8 Date 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,DATEMODIFIED,-1,-1;LASTUSER "Last User" true true false 50 Text 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,LASTUSER,0,50;EVENTSOURCE "Event Source" true true false 50 Text 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,EVENTSOURCE,0,50;LEGACYID "Legacy ID" true true false 38 Text 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,LEGACYID,0,38;ENGFROMM "ENGFROMM" true true false 0 Double 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,ENGFROMM,-1,-1;ENGTOM "ENGTOM" true true false 0 Double 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,ENGTOM,-1,-1;OBJECTSTATUS "Object Status" true true false 20 Text 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,OBJECTSTATUS,0,20;CONTINFROMM "Continuous from Measure" true true false 0 Double 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,CONTINFROMM,-1,-1;CONTINTOM "Continuous to Measure" true true false 0 Double 0 0,First,#,C:\LocationReferencing\LR.gdb\LRS\routes,CONTINTOM,-1,-1'
load_type = "REPLACE_BY_ROUTE_ID"

## Target Route  is in feature service. Signing in portal is required to access the feature service.
arcpy.SignInToPortal('https://yourdomain.com/portal', 'username', 'password')

## Map the target route network from the feature service.Here, 18 corresponds to the target route network.
targetroute_network = r"https://yourdomain.com/server/rest/services/FeatureServiceName/FeatureServer/18"

# Process: Append Routes.
arcpy.locref.AppendRoutes(sourceroute, targetroute_network, route_id_field, route_name_field, from_date_field, to_date_field, line_id_field, line_name_field, line_order_field, field_mapping, load_type)

# Check in licenses
arcpy.CheckInExtension('LocationReferencing')

Environments

Current Workspace

Licensing information

• Basic: Requires ArcGIS Location Referencing
• Standard: Requires ArcGIS Location Referencing
• Advanced: Requires ArcGIS Location Referencing