Update Occupant Features (Indoors Tools)

Summary

Updates the Occupants feature class that conforms to the ArcGIS Indoors Information Model.

This tool updates the Occupants feature class created using the Create Indoors Database tool. Updating occupant features may be necessary when new occupants need to be added, existing occupants need to be deleted, or existing occupant information needs to be modified based on changes to seating assignments or floor plans. The updated Occupants feature class can be used to support indoor analysis and functionality—such as searching, routing, and workspace reservations in Indoors Viewer and Indoors Mobile—and space planning in Indoors Space Planner.

Usage

The input occupant table must include the KNOWNAS and EMAIL fields. You can also include the following fields to enhance the Space Planner app experience or additional fields that include information you want to be populated and maintained in the Occupants layer: ORG_LEVEL_1, ORG_LEVEL_2, JOB_TITLE, START_DATE, and SITE_ID.

The table below lists the required and optional fields for the input occupant table.


Field	Description	Is required
`KNOWNAS`	The first and last name most likely to be used when searching for an occupant.	Yes
`EMAIL`	The occupant's email address.	Yes
`ORG_LEVEL_1`	The occupant's department.	No
`ORG_LEVEL_2`	The occupant's team.	No
`JOB_TITLE`	The occupant's job title.	No
`START_DATE`	The occupant's start date.	No
`SITE_ID`	The occupant's associated site. Values in this field must match those in the `SITE_ID` field in the Sites feature class from the Indoors model.	No

Note:

The SITE_ID field will only be populated if you map the SITE_ID field using the Occupant Attributes Mapping parameter. If this field is not mapped, the occupant SITE_ID field value will remain NULL. All other fields will be mapped by default if the name of the field in the input table matches the name of the field in the Occupants layer.

Learn more about loading occupant data

You can store multiple assignments for occupants in multiple columns in the input occupant table. The following is an example of an assignment with multiple columns:
The tool supports loading occupants that are not assigned to a space. If the field identified in the Unit Identifier (Input Occupant Table) parameter has a NULL or empty value, the occupant will be loaded as unassigned (they will not be assigned to a unit). Occupants assigned to units in the input occupant table that are defined as hotels, hot desks, or not assignable units in the Units feature class will also be loaded as unassigned.

Note:

If the Occupant Unit Identifier Field parameter is empty (for a .csv file or an Excel sheet) or <NULL> (for a geodatabase table) and no home office is defined for the occupant, the occupant will be loaded as unassigned.
The Home Office Identifier parameter supports loading occupants that are assigned to a home office. Use this parameter to define the field and field values in the input occupant table that indicates an occupant is assigned to a home office.

If the Home Office Identifier parameter is specified and the Target Occupant Features parameter value contains occupants who are assigned to a home office, they will be updated based on the information in the input table. If no parameter value is provided, occupants assigned to home offices in the Occupants layer will not be updated when you run the tool.

You can also use Space Planner to manage home office assignments.
A user can be assigned to multiple units in a single tool run.
Occupant information is added, deleted, and modified based on the unique occupant identifier field value.

Note:

The occupant identifier can be any field that contains information to uniquely identify each occupant. The recommended field is EMAIL.
The Target Occupant Features parameter value will have the following fields populated with corresponding values from the Input Occupant Table parameter value based on seating assignment changes or floor plan changes:
- UNIT_ID
- UNIT_NAME (If the field exists in the Target Occupant Features parameter value.)
- LEVEL_ID
- SITE_ID (The field can be mapped with values from the input occupant table in the Occupant Attributes Mapping parameter.)
Note:

If no value is provided for the Unit Identifier (Input Occupant Table) parameter, only fields mapped in the Occupant Attributes Mapping parameter will be updated.
The Units layer's ASSIGNMENT_TYPE value will be updated to display the occupancy status of the unit. If an occupant feature is assigned to a unit, that unit's ASSIGNMENT_TYPE value is set to Office. This field is used by Space Planner.
If an update is made to the floor plan data after adding occupants to the Indoors model, the following occurs when the Update Occupant Features tool is run again:
- If a unit no longer exists after a floor plan update, any occupants that are assigned to that unit will be unassigned.
- If a unit's ASSIGNMENT_TYPE field value has changed to Not Assignable after a floor plan update, any occupants assigned to the unit will be unassigned.
- If an occupant feature is no longer located within the unit to which they are assigned after a floor plan update, the occupant feature will be moved back to the assigned unit centroid.
Note:

Updating occupant data to align with an updated floor plan does not require an input to the Input Occupant Table parameter.
You can run the tool periodically to update occupant data and change seating assignments or floor plans. You can also publish the tool as a geoprocessing service and run the tool using Microsoft Scheduler or CRON.
This tool creates a summary text file in the temp directory that is valid in the ArcGIS Pro session. To maintain a permanent record of the summary text file, you must save it in a folder outside the ArcGIS Pro session.

Label	Explanation	Data type
Target Occupant Features	The target feature layer, feature class, or feature service to which occupant records will be added, updated, or deleted. The input must contain unique values that identify each occupant and must conform to the Occupants feature class in the Indoors model.	Feature Layer
Input Unit Features (Optional)	The input polygon features representing building spaces that may be occupied. The input must be a feature layer, feature class, or feature service that conforms to the Units feature class in the Indoors model. The centroid of each space will be used as the point location of the occupant or occupants.	Feature Layer
Input Occupant Table (Optional)	The input table that contains information about building occupants. The input table must be a geodatabase table, a sheet in a Microsoft Excel workbook (`.xls` or `.xlsx` file), a comma-delimited text file (`.csv`), or an OLE DB table.	Table View
Occupant Identifier (Target Occupant Features) (Optional)	The field in the Target Occupant Features parameter value that will be used as the primary key to associate occupants with the Input Occupant Table parameter values. The field values must be unique.	Field
Occupant Identifier (Input Occupant Table) (Optional)	The field in the Input Occupant Table parameter value that will be used as the primary key to associate occupants with the Target Occupant Features parameter values. The field values must be unique.	Field
Unit Identifier (Input Units Features) (Optional)	The field in the Input Unit Features parameter value that stores the unique space identification information that will match the unit identifier from the Input Occupant Table parameter value. The field values must be unique.	Field
Unit Identifier (Input Occupant Table) (Optional)	The field or fields in the Input Occupant Table parameter value that will be used as the primary key to associate occupant space assignment with the Input Unit Features parameter value. If a field value is empty, the occupant will be loaded as unassigned. This parameter supports multiple fields from an input occupant table that stores more than one space assignment of an occupant. Only the fields provided will be used to update the Occupants feature class. If no parameter value is provided, the occupant's seating assignments will not be updated in the Occupants feature class. Instead, the records in the Occupants feature class will be matched to records in the input occupant table, and attributes mapped in the Occupant Attributes Mapping parameter will be updated.	Field
Occupant Attributes Mapping (Optional)	The attribute fields in the Target Occupant Features parameter value that will be populated with field values from the Input Occupant Table parameter value. The fields must exist in the Target Occupant Features parameter value before running the tool. It is recommended that you map fields from the Input Occupant Table parameter value to fields from the Target Occupant Features parameter value that have the same field type.	Field Mappings
Insert new occupants (Optional)	Specifies whether unmatched occupant records for the Input Occupant Table parameter value will be added to the target occupant features layer. Checked—Unmatched occupant records will be added to the target occupant features layer. This is the default. Unchecked—Unmatched occupant records will not be added to the target occupant features layer.	Boolean
Delete occupants not included in the Input Occupant Table (Optional)	Specifies whether unmatched occupant records for the Input Occupant Table parameter value will be deleted from the target occupant features layer. Checked—Unmatched occupant records will be deleted from the target occupant features layer. This is the default. Unchecked—Unmatched occupant records will not be deleted from the target occupant features layer.	Boolean
Home Office Identifier (Optional)	A SQL query that defines the field and field value from the input occupant table that indicates an occupant is assigned to a home office.	SQL Expression

Derived output

Label	Explanation	Data type
Updated Occupant Features	The updated version of the target occupant features used for this tool.	Feature Layer

arcpy.indoors.UpdateOccupantFeatures(target_occupant_features, {in_unit_features}, {in_occupant_table}, {occupant_id_from_target_occupant_features}, {occupant_id_from_input_table}, {unit_id_from_units_features}, {unit_id_from_input_table}, {occupant_attributes_mapping}, {allow_insert}, {allow_delete}, {home_office_identifier})

Name	Explanation	Data type
target_occupant_features	The target feature layer, feature class, or feature service to which occupant records will be added, updated, or deleted. The input must contain unique values that identify each occupant and must conform to the Occupants feature class in the Indoors model.	Feature Layer
in_unit_features (Optional)	The input polygon features representing building spaces that may be occupied. The input must be a feature layer, feature class, or feature service that conforms to the Units feature class in the Indoors model. The centroid of each space will be used as the point location of the occupant or occupants.	Feature Layer
in_occupant_table (Optional)	The input table that contains information about building occupants. The input table must be a geodatabase table, a sheet in a Microsoft Excel workbook (`.xls` or `.xlsx` file), a comma-delimited text file (`.csv`), or an OLE DB table.	Table View
occupant_id_from_target_occupant_features (Optional)	The field in the `target_occupant_features` parameter value that will be used as the primary key to associate occupants with the `in_occupant_table` parameter values. The field values must be unique.	Field
occupant_id_from_input_table (Optional)	The field in the `in_occupant_table` parameter value that will be used as the primary key to associate occupants with the `target_occupant_features` parameter values. The field values must be unique.	Field
unit_id_from_units_features (Optional)	The field in the `in_unit_features` parameter value that stores the unique space identification information that will match the unit identifier from the `in_occupant_table` parameter value. The field values must be unique.	Field
unit_id_from_input_table [unit_id_from_input_table,...] (Optional)	The field or fields in the `in_occupant_table` parameter value that will be used as the primary key to associate occupant space assignment with the `in_unit_features` parameter value. If a field value is empty, the occupant will be loaded as unassigned. This parameter supports multiple fields from an input occupant table that stores more than one space assignment of an occupant. Only the fields provided will be used to update the Occupants feature class. If no parameter value is provided, the occupant's seating assignments will not be updated in the Occupants feature class. Instead, the records in the Occupants feature class will be matched to records in the input occupant table, and attributes mapped in the `occupant_attributes_mapping` parameter will be updated.	Field
occupant_attributes_mapping (Optional)	The attribute fields in the `target_occupant_features` parameter value that will be populated with field values from the `in_occupant_table` parameter value. The fields must exist in the `target_occupant_features` parameter value before running the tool. It is recommended that you map fields from the `in_occupant_table` parameter value to fields from the `target_occupant_features` parameter value that have the same field type.	Field Mappings
allow_insert (Optional)	Specifies whether unmatched occupant records for the `in_occupant_table` parameter value will be added to the target occupant features layer. `INSERT_OCCUPANTS`—Unmatched occupant records will be added to the target occupant features layer. This is the default. `NO_INSERT_OCCUPANTS`—Unmatched occupant records will not be added to the target occupant features layer.	Boolean
allow_delete (Optional)	Specifies whether unmatched occupant records for the `in_occupant_table` parameter value will be deleted from the target occupant features layer. `DELETE_OCCUPANTS`—Unmatched occupant records will be deleted from the target occupant features layer. This is the default. `NO_DELETE_OCCUPANTS`—Unmatched occupant records will not be deleted from the target occupant features layer.	Boolean
home_office_identifier (Optional)	A SQL query that defines the field and field value from the input occupant table that indicates an occupant is assigned to a home office.	SQL Expression

Derived output

Name	Explanation	Data type
updated_occupant_features	The updated version of the target occupant features used for this tool.	Feature Layer

Code sample

UpdateOccupantFeatures example 1 (Python window)

The following Python window script demonstrates how to use the UpdateOccupantFeatures function in immediate mode. In this example, the inputs and outputs are all in the same geodatabase.

import arcpy
arcpy.indoors.UpdateOccupantFeatures('C:/ExampleCampus.gdb/Indoors/Occupants',
                                     'C:/ExampleCampus.gdb/Indoors/Units', 'C:/OccupantsData/2022Occupants.xlsx/2022Q2$',
                                     'EMAIL', 'EMAIL',
                                     'UNIT_ID', 'SPACE_ASSIGNMENT',
                                     'KNOWNAS "Known As" true false false 255 Text 0 0,First,#,C:/OccupantsData/2022Occupants.xlsx/2022Q2$,KNOWNAS,0,255;SITE_ID "Site ID" true true false 255 Text 0 0,First,#',
                                     True, True, "HOME_OFFICE IS NOT NULL")

UpdateOccupantFeatures example 2 (stand-alone script)

The following stand-alone script demonstrates how to use the UpdateOccupantFeatures function.

# Import system modules
import arcpy

# Set local variables
target_occupant_features = r'C:\ExampleCampus.gdb\Indoors\Occupants'
in_unit_features = r'C:\ExampleCampus.gdb\Indoors\Units'
in_occupant_table = r'C:\OccupantSpreadsheets\BuildingL.xlsx\OccupantsSeatingAssignment$'
occupant_id_from_target_occupant_features = 'EMAIL'
occupant_id_from_input_table = 'EMAIL'
unit_id_from_units_features = 'UNIT_ID'
unit_id_from_input_table = "SPACE_ASSIGNMENT"
occupant_attributes_mapping = 'KNOWNAS "Known As" true false false 255 Text 0 0,First,#,' \
'C:\OccupantSpreadsheets\BuildingL.xlsx\OccupantsSeatingAssignment$,KNOWNAS,0,255;CONTACT_PHONE "Contact Phone" true true false 255 Text 0 0,First,#,' \
'C:\OccupantSpreadsheets\BuildingL.xlsx\OccupantsSeatingAssignment$,CONTACT_PHONE,0,255;CONTACT_EXTENSION "Contact Extension" true true false 255 Text 0 0,First,#,' \
'C:\OccupantSpreadsheets\BuildingL.xlsx\OccupantsSeatingAssignment$,CONTACT_EXTENSION,-1,-1;SITE_ID "Site ID" true true false 255 Text 0 0,First,#;JOB_TITLE "Job Title" true true false 255 Text 0 0,First,#,' \
'C:\OccupantSpreadsheets\BuildingL.xlsx\OccupantsSeatingAssignment$,JOB_TITLE,0,255;ORG_LEVEL_1 "Department" true true false 255 Text 0 0,First,#,' \
'C:\OccupantSpreadsheets\BuildingL.xlsx\OccupantsSeatingAssignment$,ORG_LEVEL_1,0,255;ORG_LEVEL_2 "Team" true true false 255 Text 0 0,First,#,' \
'C:\OccupantSpreadsheets\BuildingL.xlsx\OccupantsSeatingAssignment$,ORG_LEVEL_2,0,255;START_DATE "Start Date" true true false 8 Date 0 0,First,#,' \
'C:\OccupantSpreadsheets\BuildingL.xlsx\OccupantsSeatingAssignment$,START_DATE,-1,-1'

allow_insert = True
allow_delete = True

#Set the query for occupants that are assigned to a home office
home_office_identifier = "SPACE_ASSIGNMENT LIKE ‘%HOME OFFICE%’"

# Run the tool
arcpy.indoors.UpdateOccupantFeatures(target_occupant_features, in_unit_features, in_occupant_table,
                                     occupant_id_from_target_occupant_features, occupant_id_from_input_table,
                                     unit_id_from_units_features, unit_id_from_input_table, occupant_attributes_mapping,
                                     allow_insert, allow_delete, home_office_identifier)

Environments

Current Workspace

Licensing information

Basic: No
Standard: No
Advanced: Requires ArcGIS Indoors Pro or ArcGIS Indoors Maps

Update Occupant Features (Indoors Tools)

Summary

Usage

Note:

Note:

Note:

Note:

Note:

Parameters

Derived output

Environments

Licensing information

Related topics