Summary
Converts a nonspatial table to point features based on x,y-coordinates or street addresses and updates an existing dataset with the new or updated record information from the table.
Usage
A point feature class or feature layer must exist where records from the input table will be appended or updated.
You can use tabular data exported from your computer-aided dispatch system or records management system in this tool.
This tool supports the following table formats as input:
- Geodatabase
- dBASE (.dbf)
- Comma-separated values (.csv or .txt)
- Microsoft Excel worksheets (.xls or .xlsx)
- In-memory table views
For file input (.csv or .txt), the first row of the input file is used as the field names on the output table. Field names cannot contain spaces or special characters (such as $ or *), and you will receive an error if the first row of the input file contains spaces or special characters.
Performing geocoding operations using the ArcGIS World Geocoding Service requires an ArcGIS Online organizational subscription and consumes credits. The organizational account must have enough credits to complete the entire geocoding request.
When the optional Invalid Records Table parameter table is created, the table contains records that were not processed as new or updated features. The complete input table record will be added to the Invalid Records Table parameter table as well as an INV_REASON field. The INV_REASON field will include a code identifying the reason the record could not be processed as new or updated features.
The INV_REASON field is added to the Invalid Records Table with the following codes:
- NULL_ADDR—All address fields in the input table record contain null values.
- NULL_ID—The input ID fields of the input table record contain null values.
- NULL_XY—The input table's x- and y-coordinate fields contain a null value.
- BAD_DATE—The input date of the input table record is null or could not be converted to a valid date.
- BAD_ADDR—The address candidate from the input table record is unmatched.
- BAD_FM—The field mapping of the input table record was unsuccessful because a value could not be added to the output field. For example, text values cannot be added to numeric fields, and text values cannot be added to text fields when the values are longer than the field length.
- DUP_ID—The input table record has a duplicate ID and has not been updated to the target features because it is older than the existing record or a newer record exists. This is determined by the last modified date. If the last modified date is not used, it is determine by the highest OBJECTID value.
When the Invalid Records Table parameter is empty, an invalid_records_<timestamp>.fid file is created in your scratch workspace environment. This file will contain the OBJECTID value of each Input Table record that could not be added or updated in the Target Features parameter.
When both the Update Existing Target Features and Update Geometry for Existing Features parameters are checked (update_target = "UPDATE" in Python and update_geometry = "UPDATE_GEOMETRY" in Python, respectively), location fields in the Input Table parameter are compared to the location fields in the Target Features parameter to determine whether the geometry will be updated in the Target Feature parameter. When Location Type is set to Addresses, the Address Fields values are compared. If a difference is detected between the Input Table record and the Target Features parameter values, the Target Features geometry is updated with the geocoded position based on the address fields in the Input Table record. The Input Table record will not be geocoded if no difference is detected.
Syntax
arcpy.ca.UpdateFeaturesWithIncidentRecords(in_table, target_features, location_type, {x_field}, {y_field}, {coordinate_system}, {address_locator}, {address_type}, {address_fields}, {invalid_records_table}, {where_clause}, {update_target}, {match_fields}, {in_date_field}, {target_date_field}, {update_matching}, {update_geometry}, {field_matching_type}, {field_mapping}, time_format)| Parameter | Explanation | Data Type |
in_table | The table containing the x- and y-coordinates or addresses that define the locations of the records. | Table View |
target_features | The point feature class or feature layer to be updated. | Feature Layer |
location_type | Specifies whether features will be created using x,y-coordinates or addresses.
| String |
x_field (Optional) | The field in the input table that contains the x-coordinates (or longitude). This parameter is only enabled when the location_type parameter is set to COORDINATES. | Field |
y_field (Optional) | The field in the input table that contains the y-coordinates (or latitude). This parameter is only enabled when the location_type parameter is set to COORDINATES. | Field |
coordinate_system (Optional) | The coordinate system of the x- and y-coordinates. This parameter is only enabled when the location_type parameter is set to COORDINATES. | Coordinate System |
address_locator (Optional) | The address locator to use to geocode the table of addresses. When this parameter is set to use ArcGIS World Geocoding Service, this operation may consume credits. Note:When using a local address locator, adding the .loc extension after the locator name at the end of the locator path is optional. This parameter is only enabled when the location_type parameter is set to ADDRESSES. | Address Locator |
address_type (Optional) | Specifies how address fields used by the address locator will be mapped to fields in the input table of addresses.
Select SINGLE_FIELD_ADDRESS if the complete address is stored in one field in the input table, for example, 303 Peachtree St NE, Atlanta, GA 30308. Select MULTI_FIELD_ADDRESS if the input addresses are split into multiple fields such as Address, City, State, and ZIP for a general United States address. This parameter is only enabled when the location_type parameter is set to ADDRESSES. | String |
address_fields [address_fields,...] (Optional) | The input table fields that correspond to the locator address fields of the address locator. Some locators support multiple input address fields, such as Address, Address2, and Address3. In this case, the address component can be separated into multiple fields, and the address fields will be concatenated at the time of geocoding. For example, 100, Main st, and Apt 140 across three fields, or 100 Main st and Apt 140 across two fields, both become 100 Main st Apt 140 when geocoding. If you choose not to map an optional input address field used by the address locator to a field in the input table of addresses, specify that there is no mapping by leaving the field name blank. This parameter is only enabled when the location_type parameter is set to ADDRESSES. | Value Table |
invalid_records_table (Optional) | The output table containing a list of invalid records and associated invalidation codes. | Table |
where_clause (Optional) |
The SQL expression used to select a subset of the input datasets' records. If multiple input datasets are specified, they will all be evaluated using the expression. If no records match the expression for an input dataset, no records from that dataset will be appended to the target. For more information about SQL syntax, see SQL reference for query expressions used in ArcGIS. | SQL Expression |
update_target (Optional) | Specifies whether existing records will be updated in the target_features parameter.
| Boolean |
match_fields [match_fields,...] (Optional) | The ID field or fields that will be used to determine matches between the in_table values and the target_features values. This parameter is only enabled when the update_target parameter is set to UPDATE. | Value Table |
in_date_field (Optional) | The last modified date of the in_table records. Date and string field types are supported. This parameter is only enabled when the update_target parameter is set to UPDATE. | Field |
target_date_field (Optional) |
The field containing the last modified date of the target_features records. This field must be a date field type. This parameter is only enabled when the update_target parameter is set to UPDATE. | Field |
update_matching (Optional) | Specifies whether only existing records will be updated or existing records will be updated and new records will be added.
This parameter is only enabled when the update_target parameter is set to UPDATE. | Boolean |
update_geometry (Optional) | Specifies whether the geometry of existing features will be updated.
This parameter is only enabled when the update_target parameter is set to UPDATE. | Boolean |
field_matching_type (Optional) |
Specifies whether the fields of the input table must match the fields of the target features for data to be appended.
| String |
field_mapping (Optional) | Controls how the attribute fields from the input table will be transferred or mapped to the target features. This parameter is only enabled if the field_matching_type parameter is FIELD_MAP. Because the input table values are appended to an existing target feature that has predefined fields, you cannot add, remove, or change the type of the fields in the field map. You can, however, set merge rules for each output field. Merge rules allow you to specify how values from two or more input fields are merged or combined into a single output value. There are several merge rules you can use to determine how the output field will be populated with values.
In Python, you can use the FieldMappings class to define this parameter. | Field Mappings |
time_format |
The format of the input field containing the time values. The type can be short, long, float, double, text, or date. You can either choose a standard time format from the drop-down list or enter a custom format. Note:The format strings are case sensitive.
Learn more about custom dates and time formats This parameter is only enabled when the in_date_field parameter value is a text field and the target_date_field parameter value is a date field, or the field_mapping parameter input value is a text field and the output value is a date field This parameter is only enabled when the update_target parameter is set to UPDATE. | String |
Derived Output
| Name | Explanation | Data Type |
| updated_target_features | The updated target features. | Feature Layer |
Code sample
The following script demonstrates how to use the UpdateFeaturesWithIncidentRecords function in immediate mode.
import arcpy
arcpy.env.workspace = r"C:\data\city_pd.gdb"
arcpy.ca.UpdateFeaturesWithIncidentRecords("C:/data/calls_for_service_records.csv",
"calls_for_service_features",
"COORDINATES",
"Longitude",
"Latitude",
4326)The stand-alone script below is an example of how to use the UpdateFeaturesWithIncidentRecords function in a script:
# Name: UpdateFeaturesWithIncidentRecords.py
# Description: Update the calls for service feature class with new updates from the records management system (RMS).
# Import script modules
import arcpy
# Set the workspace
arcpy.env.workspace = r"C:/data/city_pd.gdb"
# Address Field Pairs formatted as ["Locator Address Field Name", "Input Field Name"]
address_field_pairs = [
["Address", "locdesc"],
["Address2", ""],
["Address3", ""],
["Neighborhood", ""],
["City", "municipality"],
["Subregion", ""],
["Region", "state"],
["Postal", "zip5"],
["PostalExt", ""],
["CountryCode", ""]
]
arcpy.ca.UpdateFeaturesWithIncidentRecords("C:/data/calls_for_service_records.csv",
"calls_for_service_features",
location_type="ADDRESSES",
address_locator="https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service",
address_type="MULTI_FIELD_ADDRESS",
address_fields=address_field_pairs,
update_target="UPDATE",
match_fields=[["callid", "callid"]],
update_matching="UPSERT",
update_geometry="UPDATE_GEOMETRY",
field_matching_type="AUTOMATIC")Environments
Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes