Back to Top

Project JSON

In this topic

  1. Basemap
  2. Data sources
  3. Preferences
  4. Template groups
  5. Templates
  6. Field variables
  7. User input variable
  8. Location sharing

Projects are typically configured in the ArcGIS QuickCapture designer using a graphical interface, but you can also change the project's JSON code.

When editing the project's JSON, you can modify the following properties:

  • basemap—Map displayed when reviewing data.
  • dataSources—Lists the feature layers used by buttons in the project.
  • preferences—Applicable to all records captured in a project.
  • templateGroups—Represents a group of buttons.
  • templates—Represents a button.
    • cameraInfo—How photos and video are captured for the record.
    • captureInfo—How data is captured when a button is selected. Configure to display the map after capture (for location editing) and customize the display text and hint that is shown on the map page.
    • displayInfo—How a button will look.
    • fieldInfos—The attribute values that will be captured for the record.
  • tracking—Represents the location sharing layer used by the project.
  • userInput—User-supplied string that can be used to populate attributes of a record.

Some of these properties are arrays of additional properties. The following subsections describe details of the property arrays.

Basemap

By default, the map of a new project will match the default basemap of the organization. When signed in to the app with an organization account, the user will see the current default organization basemap in that project. If the user is signed out of the app, the Esri World Topographic map is displayed.

The following properties are used to identify a map to be used in a project:

PropertyDescriptionField type
type

WebMap, MMPK, VTPK, or TPK. When null, Esri World Topographic map is used.

String

itemId

The item ID of the map.

String

useDefaultBasemap

True (default) or false.

Boolean

Project authors can override the default behavior by selecting an online or offline map of their choice. If useDefaultBasemap is set to false and the itemId is null, the project will use the Esri World Topographic map.

The following example shows a required web map that is only available to the user who downloaded it:

{
   "basemap":{
      "type":"WebMap",
      "itemId":fae788aa91e54244b161b59725dcbb2a,
      "useDefaultBasemap":false,
      "required":true,
      "zoomLevel":null
   }
}

To show users the previously submitted data on a map in your project, you can configure a web map that contains the project data and nominate it as the basemap.

  • The web map should at least contain the same layers as the project. Other layers can also be included.
  • The symbology defined in the web map will be used to symbolize the sent features.
  • Data captured on the device that has not been sent will be symbolized using the default QuickCapture symbology. For example, points will be symbolized with the blue marker.

Note:

Only maps with Web Mercator spatial reference are supported.

Data sources

The following properties are used to identify a feature layer in a project:

PropertyDescriptionField type
dataSourceId

A unique number assigned by QuickCapture to this project to identify this layer in the array. This is not the index of the layer in the feature service. One project can have layers from different feature services.

Integer

featureServiceItemId

The item ID of the feature service that contains this layer.

String

URL

The URL of the feature layer REST endpoint (…/FeatureServer/0). This URL must include the full URL, down to the layer index.

String

One or more data sources can be listed in the dataSource property. In the following example, two layers that come from two different feature services are listed:

{
   "basemap":{

   },
   "dataSources":[
      {
         "featureServiceItemId":"1f683747c06c4a7e9843a477b2ab41e0",
         "dataSourceId":0,
         "url":"https://services1.arcgis.com/e7dVfn25KpfE6dDd/arcgis/rest/services/LayerOne/FeatureServer/0"
      },
      {
         "featureServiceItemId":"2b313747c06c4a7e9843a477b2ab41e0",
         "dataSourceId":1,
         "url":"https://services1.arcgis.com/b45KpfE6dEf121/arcgis/rest/services/LayerTwo/FeatureServer/1"
      }
   ],
   "itemId":"",
   "preferences":{

   },
   "templateGroups":[

   ],
   "userInputs":[

   ],
   "version":""
}

Preferences

The following properties are applicable to the project or all records captured in a project:

PropertyDescriptionField type
backgroundColor

Project background color as an HTML hexadecimal value.

String

splitScreen

Show the buttons and map side by side.

Boolean

horizontalAccuracyWarning

A decimal value, in meters, defining a recommended threshold above which the horizontal accuracy is no longer considered sufficient. This is used to change the color of the horizontal accuracy display on the project page. This property accepts a maximum value of 999 meters.

Decimal

horizontalAccuracyError

A decimal value, in meters, defining a required threshold above which the horizontal accuracy is no longer considered sufficient. This is used to prevent the user from capturing records or vertices if the threshold is not met. This property accepts a maximum value of 999 meters.

Decimal

allowEditLocation

Allow location of a point to be updated, within a limited time after capture.

Boolean

distanceThreshold

The minimum movement distance in meters from the last vertex or point captured before a new vertex or point can be captured. The default distance is 10 meters.

Decimal

undoThreshold

The time in seconds after capture in which records can be deleted or have their location updated.

Decimal

adminEmail

Specifies the recipient of data recovery files generated by the mobile app.

String

coordinateNotationFormat

Set the project coordinate notation format displayed in the mobile app. Supported values are UTM, USNG, MGRS, DD, DDM, and DMS. Default is DD.

Double

While thresholds can be set for both horizontalAccuracyWarning and horizontalAccuracyError, the horizontalAccuracyWarning value must always be lower than the error. For example, if you set a recommended horizontal accuracy of 10 meters and a required horizontal accuracy of 30 meters, and your device returns an accuracy of 20 meters, you will see a warning. If your device returns an accuracy of 40 meters, you will be unable to capture a record.

The following example shows preferences set with a gray background, the recommended horizontal accuracy of 10 meters, no distance threshold, and an admin email address of quickcapture@esri.com:

{
   "basemap":{

   },
   "dataSources":[

   ],
   "itemId":"",
   "preferences":{
      "splitScreen":false,
      "backgroundColor":"#f3f3f4",
      "horizontalAccuracyError":null,
      "horizontalAccuracyWarning":10,
      "distanceThreshold":null,
      "undoThreshold":10,
      "adminEmail":"quickcapture@esri.com"
   },
   "templateGroups":[

   ],
   "userInputs":[

   ],
   "version":""
}
Note:

Decimal values must use a period as the decimal separator, and thousand separators should not be used. Commas are not accepted in the JSON editor.

Template groups

The following properties are used to define how a group of buttons is displayed in a project. Each group of buttons can use different properties.

PropertyDescriptionField type
name

Name of the group.

String

label

Label shown in the project for the group.

String

columns

Number of columns in the group.

Integer

columnSpacing

Spacing between the columns.

Decimal

rowSpacing

Spacing between the rows.

Decimal

backgroundColor

Background color of the group as an HTML hexadecimal value.

String

outlineColor

Outline color of the group as an HTML hexadecimal value.

String

expanded

Default is true.

Boolean

labelColor

Color of the group label as an HTML hexadecimal value.

String

Templates

The following properties are used to identify the feature layer that's related to a button:

PropertyDescriptionField type
id

The UUID for the button.

Text

dataSourceId

References the target layer where data is stored. The ID refers to a data source in the data sources array.

Integer

captureInfo

The following properties describe how data is to be captured:

PropertyDescriptionField type
exclusivityGroup

A value defining an exclusivity group. All templates with the same value are grouped, with exclusive set to true. When set, only one button with the value can be active at a time.

Text

type

esriGeometryPoint, esriGeometryPolyline, or esriGeometryPolygon.

String

continuous

Always true for lines and polygons.

Boolean

editMap

Options for edit map. Choose to show after capture (default is false), customize the map title (default is null), or customize the map hint (default is null).

String

displayInfo

The following properties describe how a button will look:

PropertyDescriptionField type
label

The label on the button.

String

shape

Rectangle, rounded, or circle.

String

size

Small, medium, large, xlarge, or xxlarge.

String

color

Color of the button background as an HTML hexadecimal value.

String

outlineColor

Color of the button outline as an HTML hexadecimal value.

String

outlineWidth

Width of the button outline.

Decimal

labelColor

Color of the button label as an HTML hexadecimal value.

String

labelFontSize

Font size for the button label.

Integer

labelFontWeight

Bold or regular.

String

shadowColor

When no value is provided, the app will use the same backgroundColor value as the group. This means the shadow will not be visible.

String

image

Image to be shown with the button in PNG, JPG, or SVG format. All images are stored as resources of the item in the images folder.

String

fieldInfos

The following properties describe attribute information that is entered into the feature service when a button is tapped. Typically, a project author will use predefined text or field variables to populate fields of the record collected.

PropertyDescriptionField type
fieldName

Name of the field.

String

value

Can contain any of the properties listed in this topic.

String

cameraInfo

The following properties describe how photos or video can be captured and saved in a project. By default, if you enable photos to be captured for a button, the photo is always required. You can make photo capture optional by changing the required property to be false and minMedia to be 0. You can also specify photo quality by changing the imageSize property. (The default maximum length for video is 10 seconds.)

PropertyDescriptionField type
mode

None (default)—No photo or video is associated with the feature.

Automatic—A photo is taken without confirmation from the user as soon as the button is selected.

Manual—Camera preview is displayed and the user controls the capture of a photo.

String

imageSize

Small (320 pixels on longest edge), medium (640 pixels on longest edge), large (default, 1280 pixels on longest edge), or unrestricted (no size limit). If the image is resized by the app, the aspect ratio of the captured image will be maintained.

String

required

True (default) or false.

Boolean

captureVideo

True or false (default).

Boolean

capturePhoto

True (default) or false.

Boolean

maxMedia

Maximum number of photos or video captured by a button. The maximum limit is 5 for photos and 1 for video.

Integer

minMedia

Minimum number of photos or video captured by a button.

Integer

In the following example, an optional photo with no size limit is taken without preview confirmation: 

{
   "cameraInfo": {
      "mode": "automatic",
      "imageSize": "unrestricted",
      "required": false,
      "captureVideo": false,
      "capturePhoto": true,
      "maxMedia": 1,
      "minMedia": 0
   },

notificationsInfo

The following properties are used to configure notifications within a project. Currently, the only supported notification is a webhook.

PropertyDescriptionField type
id

Unique ID of the webhook (within the project).

String

name

Name of the webhook.

String

active

True or false (default).

Boolean

created

Date and time when the webhook was created.

Date

modified

Date and time when the webhook was last modified.

Date

events

Event type that triggers the webhook. Only the addData event is supported.

String

targetLayerUrl

Feature service layer (including layer index) against which the webhook has been configured. The addData events will be triggered by updates to this layer.

String

webhookUrl

Webhook URL to which the payload will be sent.

String

includePortalInfo

True (default) or false.

Boolean

includeProjectInfo

True (default) or false.

Boolean

includeServiceRequest

True (default) or false.

Boolean

includeServiceResponse

True (default) or false.

Boolean

In the following example, a single webhook is shown, but more than one can be configured in a single project:

 "notificationsInfo": {
    "webhooks": [
      {
        "active": true,
        "created": 1502880915000,
        "events": [
          "addData"
        ],
        "id": "ByCjvHpPz",
        "includePortalInfo": true,
        "includeProjectInfo": true,
        "includeServiceRequest": true,
        "includeServiceResponse": true,
        "includeUserInfo": true,
        "modified": 1502881754000,
        "name": "Display name",
        "targetLayerUrl": "https://<serviceurl including layer index>",
        "webhookUrl": "https://<webhookserviceurl>"
      }
    ]
  }

Field variables

When using these variables in the JSON editor, you must enter the variable name in the format of ${variable_name}. In the following example, the username variable is assigned to a field named NameOfUser:

"fieldInfos": [
 {
   "fieldName": "NameOfUser",
   "value": "${username}"
 },

User input variable

The userInput variable value is populated by the app user and can be applied to one or more buttons in a project. The app user enters the value; however, the project author must define the buttons and fields to which the variable will apply.

In the project JSON, user inputs are defined in the userInputs array and then referenced by "fieldInfos" using the id property.

PropertyDescriptionField type
Id

Unique ID of the user input.

String

label

The label is displayed in the mobile app to describe the expected input value from the end user. For example, the label might be RouteNo, CostCenter, or RouteNo-CostCenter.

String

fieldType

The type of field to which the user input value can be written. Options are limited to esriFieldTypeString, esriFieldTypeDouble, and esriFieldTypeInteger.

String

required

Specifies whether the user input value must be provided by the end user of the mobile app before (project mode) or after (button mode) a button can be pressed.

Boolean

domain

Controls user input and is limited to a numerical range (range), list of predefined values (codedValue), or text input, optionally using an input mask (userDefined).

String

mode

Controls whether the user is prompted for input when the project is launched (project) or when a button is pressed (button).

String

multiline

Allows entry of multiple lines of text. This is only applicable when domain is userDefined.

Boolean

autoCompleteMaxEntries

Specifies the number of user-entered values that are cached for a project user input.

Integer

showEvent

Controls whether the button user input dialog box is shown at the beginning of record capture or the end. Options are onStart and onEnd. The default is onEnd. This is only applicable when domain is userDefined.

String

showScanner

Controls whether the barcode scanner is shown in the user input. The default is false. This is only applicable when domain is userDefined.

Boolean

dateTime

Controls input of date and time. This is only applicable when domain is userDefined. Can be constrained by the following: defaultValue, displayTime, maxValue, and minValue.

Date

To learn when to use each mode, see Project user input variable or Button user input variable.

It is recommended that domains be managed in the feature service. The web designer reads domain information directly from the feature service to create the user input. Domain information is not automatically written into the project JSON.

The mobile app reads domain information directly from the feature service and stores it locally on the device. If you add or modify domain values in the feature service, you must resave the project to prompt the user to update the project and see the changes.

Caution:

A project author can choose to manually define domain information directly with the project JSON. This will override anything that is read from the feature service. It is the responsibility of the author to ensure that any values defined are within the limits of those defined in the feature service. An example of when you might choose to do this is to define a subset of coded values in the project from a much longer list in the feature service.

The following example shows how a range domain user input is defined to restrict data entry to a number between 1 and 100:

{
   "userInputs":[
      {
         "autoCompleteMaxEntries":5,
         "id":"001",
         "label":"Enter route number",
         "fieldType":"esriFieldTypeInteger",
         "required":true,
         "mode":"project",
         "domain":{
            "type":"range",
            "name":"route no",
            "range":[
               1,
               100
            ]
         }
      }
   ]
}

The following example shows how a codedValue domain user input is defined to limit data entry to the selection of one of three values:

{
   "userInputs":[
      {
         "autoCompleteMaxEntries":5,
         "id":"001",
         "label":"Enter class",
         "fieldType":"esriFieldTypeString",
         "required":true,
         "mode":"project",
         "domain":{
            "type":"codedValue",
            "name":"Class",
            "codedValues":[
               {
                  "name":"Principle",
                  "code":"Principle"
               },
               {
                  "name":"Classified (Non-principle)",
                  "code":"Classified"
               },
               {
                  "name":"Unclassified",
                  "code":"Unclassified"
               }
            ]
         }
      }
   ]
}

The following example shows how a userDefined text user input is defined to allow for scanning a QR code at the commencement of capturing a line:

{
   "userInputs":[
      {
         "id":"001",
         "label":"Scan QR code",
         "fieldType":"esriFieldTypeString",
         "required":true,
         "mode":"button",
         "domain":{
            "type":"userDefined",
            "name":"line identifier",
            "multiline":false,
            "showScanner":true,
            "showEvent":"onStart"
            "hint":"Scan QR code or type the identifier of the line to be captured"
         }
      }
   ]
}

The following example shows how a userDefined domain user input is defined to allow data entry of a date between June and December 2022:

{
   "userInputs":[
      {
         "id":"001",
         "label":"Enter date",
         "fieldType":"esriFieldTypeDate",
         "required":true,
         "mode":"button",
         "domain":{
            "type":"userDefined",
            "name":"followup date",
            "multiline":false,
            "hint":"Enter date between June and December 2022",
            "dateTime": {
               "defaultValue": "${captureTime}",
               "displayTime": true,
               "maxValue": "2022-06-01T00:00:00.000Z",
               "minValue": "2022-12-31T24:59:00.000Z"
            }
         }
      }
   ]
}

The following example shows how a userDefined domain user input is defined to restrict data entry to a four-digit route ID:

{
   "userInputs":[
      {
         "id":"001",
         "label":"Enter route number",
         "fieldType":"esriFieldTypeString",
         "required":true,
         "mode":"button",
         "domain":{
            "type":"userDefined",
            "name":"route no",
            "inputMask":"9999",
            "multiline":false,
            "hint":"Enter a four digit route id"
         }
      }
   ]
}

Once userInput is defined, the project author can assign it for use in a field. The following shows userInput with an ID of 001 being used to populate a field named routeNo:

{
   "fieldInfos":[
      {
         "fieldName":"routeNo",
         "value":"${userInput:001}"
      }
   ]
}

Input mask

An input mask defines the format for data entry by using characters and symbols as part of a user input variable. When you apply an input mask to a user input variable, values entered by the user must follow the specific pattern defined by the input mask.

To apply an input mask to your user input variable, define the mask in the userInputs.domain.inputMask property.

See Input masks for a list of all masks and examples that can be applied to user input variables.

Location sharing

The following properties are used to identify the location sharing layers:

PropertyDescriptionField type
enabled

Enable tracking for the project. The default is false.

Boolean

required

Require that tracking is enabled to use the project. The default is false.

Boolean

lastKnownLocationsUpdateInterval

Frequency (in seconds) at which the last known location layer is updated. The default is 60 seconds. The minimum is 5 seconds.

Decimal

tracksUploadInterval

Frequency (in seconds) at which the tracks layer is updated. The default is -1 (off). Alternatively, it can be set to 600 seconds.

Decimal

tracksCategory

Define the value to be written to the category field of the tracks layer. It can be the project name, fixed value, or value of a project user input. The default is the project name.

Text

lastKnownLocationsCategory

Define the value to be written to the category field of the last known locations layer. It can be the project name, fixed value, or value of a project user input. The default is the project name.

Text

The following example shows location sharing is enabled, but is not required to use the project. The last known location will be updated every 60 seconds, and tracks will be updated every 600 seconds. The project name will be written to the category field of the last known locations layer and the tracks layer.

{
   "tracking": {
      "enabled": true,
      "required": false,
      "lastKnownLocationsUpdateInterval": 60,
      "tracksUploadInterval": 600,
      "tracksCategory": "${projectName}",
      "lastKnownLocationsCategory": "${projectName}"
   }
}

Feedback on this topic?

In this topic
  1. Basemap
  2. Data sources
  3. Preferences
  4. Template groups
  5. Templates
  6. Field variables
  7. User input variable
  8. Location sharing