Explore associations using toolkit | ArcGIS Maps SDK for Kotlin

ArcGIS Maps SDK for Kotlin Toolkit supports utility network associations directly in the FeatureForm component. If a user is editing a feature that is part of a utility network, the feature form can display and manage utility network associations for that feature. This enables users to view utility network associations for the feature currently being edited, navigate to the associated element (which then becomes the current feature in the feature form), delete a utility network association for the current feature, and create a new association between the current feature and another element in the utility network.

For information about utility network associations in general, see Get utility network associations.

Create a feature form with utility network associations

Creating a feature form that supports utility network associations is similar to creating any other feature form. The key requirements are:

The feature you are editing must belong to a feature layer that is part of a utility network.
The form definition for the layer must include a formUtilityNetworkAssociationsElement.

Once these conditions are met, you can create and display the feature form using the toolkit component for your platform. The utility network associations element will automatically appear in the form UI, allowing users to view and manage associations for the selected feature.

To create a feature form that supports utility associations, follow these steps:

Instantiate the FeatureForm class that is defined in the Kotlin Maps SDK API, passing in an ArcGISFeature. The feature must belong to a feature layer that is part of a utility network.
Instantiate the FeatureFormState class, which is defined in the ArcGIS Maps SDK for Kotlin toolkit, to manage the form's state.
Call the FeatureForm composable in the ArcGIS Maps SDK for Kotlin toolkit. The default value of the isNavigationEnabled parameter is true, which allows the user to navigate to associated features. Implement the onDismiss callback to handle closing the form.
Verify that the web map you access in your application includes in its JSON a formUtilityNetworkAssociationsElement in the formInfo (also known as the feature form definition) for the feature layer. This element enables the display and management of utility associations in the feature form. Normally, the data author adds this element when configuring the web map in ArcGIS Online or ArcGIS Enterprise.

Use dark colors for code blocksCopy
FeatureForm(
    featureFormState = FeatureFormState(
        featureForm = featureForm,
        coroutineScope = scope
    ),
    modifier = Modifier
        .fillMaxSize(),

    // Enable navigation to associated features.
    isNavigationEnabled = true,
    // Handle dismiss (close icon).
    onDismiss = { /* Remove form from UI */ },

)

Include associations element in form definition

A prerequisite for displaying any feature form is that the feature layer you are using has a feature form definition. A data designer can create this definition using Form builder in Map Viewer . If your organization does not have a data designer, you can do this task yourself. To access Form builder, open the feature layer or a web map containing the feature layer in Map Viewer and click the Configure editing button. After arranging the visual elements on the canvas, save the feature form. Form builder generates the form definition and store it within the feature layer's JSON. Alternatively, you can access Form builder in Field Maps Designer.

If you are defining a feature form for a utility network layer, you can include a utility network associations element in the Form builder canvas. Internally, the JSON will include a formInfo element that contains a JSON object of type formUtilityNetworkAssociationsElement. This element has a "type" property with the value "utilityNetworkAssociations" and an array containing one or more associationTypes objects. This is automatically created by the data designer in Map Viewer or Field Maps Designer. When this feature form is opened in an ArcGIS Maps SDK for Kotlin Toolkit component, the association elements will display utility network associations on the edited feature, grouped first by association type and then by network source. For more information about this and other elements used in a feature form definition, see formUtilityNetworkAssociationsElement and formInfo in the Web Map Specification.

Network association types in JSON
Expand
Use dark colors for code blocksCopy
					{
						"associationTypes": [
							{
								"title": "Connectivity",
								"type": "connectivity"
							},
							{
								"title": "Attachment",
								"type": "attachment"
							},
							{
								"title": "Structure",
								"type": "structure"
							},
							{
								"title": "Container",
								"type": "container"
							},
							{
								"title": "Content",
								"type": "content"
							}
						],
						"editableExpression": "expr/system/true",
						"label": "Association",
						"type": "utilityNetworkAssociations",
						"visibilityExpression": "expr/system/true"
					}
Expand

A feature in a utility network can have multiple associations of different types with associated features in different network sources. The formUtilityNetworkAssociationsElement allows you to filter these associations, controlling which associations are displayed in the feature form.

The associationTypes array allows you to filter associations by type and further filter them by network source, asset group, and/or asset type. Each object in the array must have a type property, which can be one of: connectivity, container, content, structure, or attachment. These values correspond to the UtilityAssociationsFilterType enumeration in the Kotlin Maps SDK API. In addition to the type property, you can further restrict the set of associations shown by specifying values for the optional properties associatedNetworkSourceId, associatedAssetGroup, and associatedAssetType.

Absence of associations element

If the form definition does not contain a formUtilityNetworkAssociationsElement, then no associations will be displayed in the feature form. If the JSON for the layer of the feature being edited contains no form definition at all, then ArcGIS Maps SDK for Kotlin generates a default form definition and uses it when you create a FeatureForm using that feature.

When editing a feature that is part of a utility network, a user can perform these actions in the feature form:

View utility network associations: Displays grouped utility network associations by type and network source.
Navigate to associated feature: Tap an association to navigate to the associated feature. Back navigation is supported.
Delete a utility network association: If supported by the utility network configuration, delete an association for the current feature.
Add a utility network association: If supported by the utility network configuration, create a new association between the current feature and another feature in the utility network. The user will be presented with list of candidate features to associate with the current feature, based on the utility network rules.

View utility network associations

The feature form provides access to the utility network associations for the feature currently being edited. The display starts with a list of expandable "groups": container, content, structure,attachment, connectivity. These groups are the same as the type values discussed above. The count of associations in each group is shown in parentheses.

utility network associations form element in a feature form. Two association types are displayed, each in its own row: Connected and Container.

Tapping a group expands it to show the network sources that contain associated features of the selected type.

Tapping a network source further expands to show individual associations.

Selecting an association will display that feature in the feature form. To view the association details, tap the three-dots icon, and then tap More information from the popup menu.

Navigate to associated feature

When viewing the individual associations, the user can tap to navigate to the associated feature, which now becomes the current feature in the feature form. If there are unsaved edits in the current form, the user must save or discard them before navigating. An alert tells the user to choose one of the following options: save edits, discard edits, or continue editing the current feature. Back navigation is supported to return to the previous feature. The user can invoke the system back action, such as tapping the back arrow, to navigate back to previous feature.

The FeatureFormState.activeFeatureForm property is automatically updated to reflect the currently displayed feature in the form as the user navigates the utility network using associations. To prevent navigation to associated features, pass false as the isNavigationEnabled parameter when you call the toolkit's FeatureForm composable. This disables the ability to tap an association to navigate to the associated feature, while still allowing users to view association details.

Delete a utility network association

(Advanced Editing license required) A Delete button to delete the association appears on the association details screen. Tapping this button removes the association from the current feature, and the user must save the edits in the form to persist the change. Deleting an association only removes the link between the two features; the associated feature itself remains unchanged.

Add a utility network association

(Advanced Editing license required) When the user selects an association type, a screen appears that lists the current associations of that type and also presents an Add Associations button to create a new association of that type. Tapping the Add Associations button displays a popup menu, allowing users to select From Network Data Source, which displays list of all network sources with which the current feature can create an association according to the utility network rules. Selecting a network source displays the list of all supported asset types allowed by the rules. Selecting a network asset type will display a list of all features in the web map that can be associated with the current feature, according to the network rules. A new association is created between the current feature and the selected feature. A Save button allows the user to save edits to local geodatabase. If your app connects to a feature service, then you must also call ServiceGeodatabase.applyEdits() to apply the edits to the service, thus persisting the new association on the server.

For more information specific to feature forms in Kotlin Maps SDK, see the FeatureForm documentation in the toolkit and the FeatureForms microapp.