AppConfig

What is AppConfig?

The AppConfig object in ArcGIS Experience Builder is a JSON-based configuration for an experience. It contains all the essential settings and elements that define the application's behavior, layout, appearance, and data connections. This also includes properties for managing pages, layouts, widgets, data sources, and more.

AppConfig serves as a repository for all configurations related to the experience allowing developers to easily manage and customize the application. It is created when a new experience is initialized and is stored in the appConfig property of the application state.

How to update AppConfig

The AppConfig is immutable object. You update any configuration values by programmatically creating a new appConfig instance with the updated settings.

Below is an example of how to update the appConfig using the jimu-core library during the widget runtime. You can programmatically dispatch the appConfigChanged() action to update the appConfig.

1
2
3
4
5
6
7
8
import { appActions, ReactRedux } from "jimu-core"

// get the appConfig
const appConfig = ReactRedux.useSelector((state: IMState) => state.appConfig)

// modify the appConfig
const newAppConfig = appConfig.setIn(["pages", pageId, "label"], theNewLabel)
dispatch(appActions.appConfigChanged(newAppConfig))

The most common way to update the appConfig is to update the widget config in the widget setting page where you programmatically call the props.onSettingChange(). This function handles changes in the widget settings, and takes an object with the id of the widget and the new widget config as parameters.

1
2
3
4
props.onSettingChange({
  id: widgetId,
  config: newWidgetConfig
})

AppConfig structure

The AppConfig object is a comprehensive JSON-based configuration that defines the entire structure and behavior of an experience. Here are some of its main properties:

Below is an example of a basic AppConfig structure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "connections": [],
  "controllerPanels": [],
  "dataSources": {},
  "dialogs": {},
  "exbVersion": "1.0.0",
  "footer": {},
  "forBuilderAttributes": {},
  "header": {},
  "historyLabels": {},
  "layouts": {},
  "mainSizeMode": "desktop",
  "messageConfigs": {},
  "name": "My Experience",
  "originExbVersion": "1.0.0",
  "pages": [],
  "pageStructure": {},
  "preloadWidgets": [],
  "publishTimestamp": "",
  "screenGroups": [],
  "screens": [],
  "sections": {},
  "template": "",
  "theme": "",
  "timestamp": "",
  "useAutoSortInFixedLayout": true,
  "useCachedManifest": true,
  "views": [],
  "widgets": {},
  "widgetsManifest": {}
}

Draft and published versions

In ArcGIS Experience Builder, the AppConfig object is used to manage both the draft and published versions of an experience. The draft version is typically the working version that the app author uses to make changes, while the published version is the final version that users interact with.

For ArcGIS Online and ArcGIS Enterprise, the draft version of the AppConfig object is stored in the app item resource while the published version is stored in the item data. This allows the app author to work on changes without affecting the live experience until they are ready to publish.

For the Experience Builder Developer Edition, the draft version is saved in the public/apps/<appid>/resources/config/config.json file, and the published version is saved in the public/apps/<appid>/config.json file.