Custom properties
A custom property is an extra field that cards can carry, such as Priority, Target or Go-live date. One record holds the whole definition: the name, the type and, for a select property, the list of options users pick from.
type decides how the property behaves and which extra settings it needs: options for select and multi_select, vote_variant with data for vote, and directory_ref for directory. The value a card has is not here but in the properties of cards, keyed by the external_id of the property; the files of an attachment property are attachments with property_ref. Without space_refs the property is available in all spaces; show_on_facade puts the value on the card face.
A select property with two options. The options come in the order users see them:
{
"external_id": "cp-priority",
"name": "Priority",
"type": "select",
"options": [
{ "external_id": "sv-high", "value": "High", "color": "#e53935" },
{ "external_id": "sv-low", "value": "Low" }
]
}A card picks an option by its external_id in its properties (only that field of the card is shown):
{
"external_id": "k-mrr",
"properties": { "cp-priority": "sv-high" }
}Files in the package
List every file of this entity in resource_files of the manifest, with "resource": "custom_properties". An entity can have any number of files. See Bundle format.
[
{
"resource": "custom_properties",
"path": "resources/custom_properties.json"
}
]Fields
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string (ExternalId) | Yes | Your own identifier of the record, for example k-mrr, unique within the resource across all of its files and case sensitive. Other records refer to this one by it. The import also keeps it as the external id of the object it creates.Constraints: 1–512 characters. |
name | string | Yes | Name of the property as users see it, for example Priority. Up to 255 characters.Constraints: 1–255 characters. |
type | enum | Yes | What the property holds: attachment, checkbox, date, directory, email, multi_select, multi_user, multiline_string, number, phone, select, string, url, user or vote.Constraints: one of attachment, checkbox, date, directory, email, multi_select, multi_user, multiline_string, number, phone, select, string, url, user, vote. |
data | object | When type is vote | For a vote property, the settings of its vote_variant. For rating, the number of points and the emoji of one point, for example {"count": 5, "emoji": "⭐"}. For emoji_set, the emojis to choose from, for example {"emojis": ["👍", "👎"]}. Required for vote and not allowed for other types.Rule: Only for vote; matches vote_variant. |
data.count | integer | When vote_variant is rating | How many points the rating has, from 2 to 10, for example 5. The card shows this many emojis, and a user rates by clicking one of them: the third gives 3.Constraints: minimum 2; maximum 10. |
data.emoji | string | When vote_variant is rating | Emoji that stands for one rating point. Constraints: at least 1 character. |
data.emojis | string[] | When vote_variant is emoji_set | Emojis a voter can choose from, 2 to 10 different ones. Constraints: 2–10 items; items are unique. |
directory_ref | Ref<custom_directories> refers to Custom directories | When type is directory | For a directory property, the directory whose rows users pick as the value, by the external_id of a custom_directories record. Required for directory and not allowed for other types.Rule: Only for directory. |
vote_variant | enum | When type is vote | For a vote property, how users vote: rating (from 1 up to a number of points shown as emojis, like 4 of 5 stars) or emoji_set (one emoji out of a set). It decides the shape of data. Required for vote and not allowed for other types.Constraints: one of rating, emoji_set. Rule: Only for vote. |
author_ref | Ref<users>? refers to Users | No | The user who created the property, shown in the Author column of the list of properties, by the external_id of a users record, for example u-ava. Left out or null, the author is the user who runs the import. |
condition | enum | No | Whether the property is in use: active (the default) or inactive. An inactive property can't be added to cards, and the values cards already have stay visible but can't be edited.Constraints: one of active, inactive. Default: |
options | object[] | No | For a select or multi_select property, the options users can pick, in the order they are listed: the first item is the first option in the property's list of options and in the list users pick from on a card. Not allowed for other types. Left out, the property has no options.Rule: Only for select and multi_select. |
options[].external_id | string (ExternalId) | Yes | Your own identifier of the option, for example sv-priority-high, unique among the options of all properties of the package and case sensitive. Cards and directory records name the option by it. The import also keeps it as the external id of the option it creates.Constraints: 1–512 characters. |
options[].value | string | Yes | What users see for the option, for example High. Values are distinct within the property without regard to case.Constraints: 1–512 characters. |
options[].color | #RRGGBB? | No | Color of the option as #RRGGBB, for example #e53935; the nearest color of the app's palette is used. The option is shown in this color in the property's list of options and on cards. Left out or null, the option has no color.Constraints: the nearest color of the target palette is used. |
options[].condition | enum | No | Whether the option is in use: active (the default) or inactive. An inactive option is listed apart, among the deactivated options of the property, and is not offered when users fill in the field on a card.Constraints: one of active, inactive. |
show_on_facade | boolean | No | Whether the value is also shown on the card itself on the board, not only when the card is opened. Default: |
space_refs | Ref<spaces>[] refers to Spaces | No | The spaces where the property can be added to cards, including everything inside them, by the external_id of spaces records. Leave it out to make the property available everywhere. Cards that already have a value keep showing it.Constraints: items are unique. |
values_creatable_by_users | boolean | No | For select and multi_select: whether users may add a new option while filling in the field on a card. Otherwise they pick only from the existing options.Default: Rule: Meaningful for select and multi_select. |
References
Referenced by
- Attachments:
property_ref - Card types:
card_properties[].property_ref - Cards:
properties - Custom directories:
fields[].custom_property_ref - Custom directory records:
values
Custom properties
Refers to
author_ref→ Usersdirectory_ref→ Custom directoriesspace_refs→ Spaces
Show on the entity map
Example
A record of this entity:
{
"external_id": "cp-priority",
"name": "Priority",
"type": "select",
"options": [
{
"external_id": "sv-priority-high",
"value": "High",
"color": "#e53935"
},
{
"external_id": "sv-priority-medium",
"value": "Medium",
"color": "#fb8c00"
},
{
"external_id": "sv-priority-low",
"value": "Low",
"color": "#43a047"
}
],
"show_on_facade": true,
"values_creatable_by_users": true,
"space_refs": [
"s-kpi"
]
}Rules
- vote_variant only for vote, and required there.
- data only for vote, and required there.
- data has the shape of vote_variant: count and emoji for rating, emojis for emoji_set.
- options only for select and multi_select.
- directory_ref only for directory, and required there.
- Among the items of
optionsof one record,valuemust be unique without regard to case.
Related entities
Attachments, Cards, Custom directories
Check after the import
After the import, the records of this entity can be checked on Custom properties › Get list of properties and Custom property select values › Get list of select values.
JSON Schema
custom_properties.json
