Add Form Fields
Adds fields to a form of an App.
This API updates the pre-live settings.
After using this API, use the following API to deploy the settings to the live App:
Deploy App Settings
Method | POST |
---|---|
URL | https://{subdomain}.kintone.com/k/v1/preview/app/form/fields.json |
URL(guest space) | https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/app/form/fields.json |
Authentication | Password Authentication , API Token Authentication , Session Authentication |
Content-Type | application/json |
Contents
Permissions
- Permission to Manage App is needed.
Request Parameters
Parameters that are ignored will not be updated.
Parameter | Value | Required | Description |
---|---|---|---|
app | Integer or String | Yes | The App ID. |
properties | Object | Yes | An object with data of the field settings. |
properties.{fieldcode} | Object | Yes | An object with data of the field settings of the field specified in {fieldcode} .To update a field code, state the current field code in {fieldcode} , and state the new field code in properties.{fieldcode}.code .For the characters that can be used for field codes, refer to the following document: Valid characters |
properties.{fieldcode}.label | String | Yes | The field name. |
properties.{fieldcode}.code | String | Yes | The field code of the field. Field codes have the following limitations:
|
properties.{fieldcode}.type | String | Yes | The field type.
|
properties.{fieldcode}.noLabel | Boolean or String | The Hide field name option.
false will be set. |
|
properties.{fieldcode}.required | Boolean or String | The Required field option.
false will be set. |
|
properties.{fieldcode}.unique | Boolean or String | The Prohibit duplicate values option.
false will be set. |
|
properties.{fieldcode}.maxValue | Integer or String | The maximum number of characters for the field. | |
properties.{fieldcode}.minValue | Integer or String | The minimum number of characters for the field. | |
properties.{fieldcode}.maxLength | Integer or String | The maximum number of digits for the field. | |
properties.{fieldcode}.minLength | Integer or String | The minimum number of digits for the field. | |
properties.{fieldcode}.defaultValue | String or Array | The default value. For fields that can set multiple default values, specify the value as an array. The defaultNowValue will take priority if it is also specified.For the User selection, Group selection, and Department selection fields, an array of objects that include code and type is required. |
|
properties.{fieldcode}.defaultValue[].type | String | Conditional | The type of the default value of the User selection, Group selection, or Department selection field. Required if setting the defaultValue parameter.
|
properties.{fieldcode}.defaultValue[].code | String | Conditional | The code for the default value of User selection, Group selection, or Department selection field. Required if setting the defaultValue parameter.
|
properties.{fieldcode}.defaultNowValue | Boolean or String | The Default to the record creation date option.
false will be set. |
|
properties.{fieldcode}.options | Object | Conditional | An object including data of the field's options. Required for fields that allow selections, such as Radio button. |
properties.{fieldcode}.options.{optionname} | Object | Conditional | An object with data of the settings of the options. Specify the current option names for this parameter. Options that are not specified will be deleted. Required if setting the properties.{fieldcode}.options parameter.If a new option is specified for this parameter, it will be treated as a new option. |
properties.{fieldcode}.options.{optionname}.label | String | Conditional | The display name of the option. Specify the same value as {optionname} .Required if setting the properties.{fieldcode}.options parameter. |
properties.{fieldcode}.options.{optionname}.index | Integer or String | Conditional | The display order (ascending) of the option, when listed with the other options. Required if setting the properties.{fieldcode}.options parameter. |
properties.{fieldcode}.align | String | The layout of the options.
HORIZONTAL will be set. |
|
properties.{fieldcode}.expression | String | Conditional | The formula expression used in the field. Required in the Calculated field. |
properties.{fieldcode}.hideExpression | Boolean or String | The Hide formula settings for the field.
false will be set. |
|
properties.{fieldcode}.digit | Boolean or String | The Use thousands separators option.
false will be set. |
|
properties.{fieldcode}.thumbnailSize | Integer or String | The size of the image thumbnail in pixels. Specify one of the following:
|
|
properties.{fieldcode}.protocol | String | Conditional | The Link type settings for the field. Required in the Link field.
|
properties.{fieldcode}.format | String | The display format for fields with calculations:
NUMBER will be set. |
|
properties.{fieldcode}.displayScale | Integer or String | The number of decimal places to display for the field. | |
properties.{fieldcode}.unit | String | The Currency settings of the field. | |
properties.{fieldcode}.unitPosition | String | The display position of the Currency.
BEFORE will be set. |
|
properties.{fieldcode}.entities | Array of Objects | An array listing the preset users for the User selection, Group selection, and Department selection field. | |
properties.{fieldcode}.entities[].code | String | Conditional | The code of the User/Group/Department. Required if setting the entities .
|
properties.{fieldcode}.entities[].type | String | Conditional | The entity type.
Required if setting the entities parameter. |
properties.{fieldcode}.referenceTable | Object | Conditional | An object containing the settings of the Related Records field. Required when adding a Related Records field. |
properties.{fieldcode}.referenceTable.relatedApp | Object | Conditional | An object containing data of the Datasource App setting. If this parameter is specified, all settings for this Related Records field except for the Datasource App setting will return to the default settings. Required if setting the referenceTable parameter. |
properties.{fieldcode}.referenceTable.relatedApp.app | Integer or String | Conditional | The App ID of the Datasource App. If the relatedApp parameter is specified, either this parameter or properties.{fieldcode}.referenceTable.relatedApp.code will be required.If both parameters are set, properties.{fieldcode}.referenceTable.relatedApp.code will take priority. |
properties.{fieldcode}.referenceTable.relatedApp.code | String | Conditional | The App Code of the Datasource App. If the relatedApp parameter is specified, either this parameter or properties.{fieldcode}.referenceTable.relatedApp.app will be required.If both parameters are set, properties.{fieldcode}.referenceTable.relatedApp.code will take priority. |
properties.{fieldcode}.referenceTable.condition | Object | Conditional | An object containing data of the Fetch Criteria setting. Required if setting the referenceTable parameter. |
properties.{fieldcode}.referenceTable.condition.field | String | Conditional | The field code of the field selected for Field in this app. Required if setting the referenceTable parameter. |
properties.{fieldcode}.referenceTable.condition.relatedField | String | Conditional | The field code of the field selected for Field in datasource app. Required if setting the referenceTable parameter. |
properties.{fieldcode}.referenceTable.filterCond | String | The Filter setting, in a query format. For more data on query formats refer to the following document: Query String |
|
properties.{fieldcode}.referenceTable.displayFields | Array of Strings | Conditional | A list of field codes of fields specified in the Datasource App Fields to Display setting. Required if setting the referenceTable parameter. |
properties.{fieldcode}.referenceTable.sort | String | Conditional | The Display Order setting, in a query format. For more data on query formats refer to the following document: Query String |
properties.{fieldcode}.referenceTable.size | Integer or String | The Max Records to Display at a Time setting. Specify one of the following:
5 will be set. |
|
properties.{fieldcode}.lookup | Object | An object containing the settings of the Lookup field. Required if adding a Lookup field. |
|
properties.{fieldcode}.lookup.relatedApp | Object | Conditional | An object containing the settings of the related App of the Lookup field. Required if setting the lookup parameter. |
properties.{fieldcode}.lookup.relatedApp.app | Integer or String | Conditional | The App ID of the related App of the Lookup field. Either this parameter or the lookup.relatedApp.code parameter is required if setting the lookup parameter. If both parameters are set, the lookup.relatedApp.code parameter takes priority. |
properties.{fieldcode}.lookup.relatedApp.code | String | Conditional | The App Code of the related App of the Lookup field. Either this parameter or the lookup.relatedApp.app parameter is required if setting the lookup parameter. If both parameters are set, this parameter takes priority. |
properties.{fieldcode}.lookup.relatedKeyField | String | Conditional | The field code of the Lookup field. Required if setting the lookup parameter. |
properties.{fieldcode}.lookup.fieldMappings | Array of Objects | A list of data set for the Field Mappings setting. | |
properties.{fieldcode}.lookup.fieldMappings[].field | String | Conditional | The field code of the field set for the mapping endpoint. Required if setting the lookup.fieldMappings[] parameter. |
properties.{fieldcode}.lookup.fieldMappings[].relatedField | String | Conditional | The field code of the field set for the mapping source. Required if setting the lookup.fieldMappings[] parameter. |
properties.{fieldcode}.lookup.lookupPickerFields | Array of Strings | A list of field codes of fields set for the Fields Shown in Lookup Picker setting. | |
properties.{fieldcode}.lookup.filterCond | String | The default filter query for the Filter setting. Specify in query format. For more data on query formats refer to the following document: Query String |
|
properties.{fieldcode}.lookup.sort | String | The default sort order for the Filter setting. Specify in query format. For more data on query formats refer to the following document: Query String |
|
properties.{fieldcode}.openGroup | Boolean or String | The Show fields in this group option.
false will be set. |
|
properties.{fieldcode}.fields | Object | An object containing data of fields in a table. The parameters of this object are the same as the properties parameter.Required when adding a table. |
|
revision | Integer or String | Specify the revision number of the settings that will be deployed. The request will fail if the revision number is not the latest revision. The revision will not be checked if this parameter is ignored, or -1 is specified. |
Sample Request
|
|
XMLHttpRequest
|
|
Response Parameters
Parameter | Type | Description |
---|---|---|
revision | String | The revision number of the App settings. |
Sample Response
|
|
Limitations
The field codes of the following fields cannot be added:
- Status
- Assignee
- Category