Meegle API Setting Field Settings

Meegle API — Setting (Field Settings)

APIs under this skill: Get Field Information, Create Custom Field, Update Custom Field.

Get Field Information

Obtain the basic information of all fields under the specified space or, when work_item_type_key is provided, under that work item type. Response follows the SimpleField structure (field_key, field_type_key, options for select, compound_fields for compound_field). Permission: Permission Management – Configuration.

When to Use

• When building field selectors or form UIs that need field keys, types, aliases, and scopes (work_item_scopes)
• When you need option lists for select-type fields (label, value, order, is_disabled, etc.) or sub-fields for compound_field
• When resolving field_key for Update Work Item Basic Information Settings (schedule_field_key, estimate_point_field_key, actual_work_time_field_key) or for work item read/write APIs

API Spec: get_field_information

name: get_field_information
type: api
description: >
  Obtain all fields under the space or under a work item type. Returns SimpleField
  list: field_key, field_type_key, field_alias, field_name, is_custom_field,
  work_item_scopes, value_generate_mode, relation_id; options for select; compound_fields for compound_field.

auth:
  type: plugin_access_token
  header: X-Plugin-Token
  user_header: X-User-Key

http:
  method: POST
  url: https://{domain}/open_api/{project_key}/field/all
  headers:
    Content-Type: application/json
    X-Plugin-Token: "{{resolved_token}}"
    X-User-Key: "{{user_key}}"

path_params:
  project_key:
    type: string
    required: true
    description: >
      Space ID (project_key) or space domain name (simple_name).
      project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).

inputs:
  work_item_type_key:
    type: string
    required: false
    description: Work item type. Obtain via Get work item types in space. Omit to get all fields in space.

outputs:
  data:
    type: array
    description: >
      List of SimpleField. Each has field_key, field_type_key, field_alias, field_name,
      is_custom_field, work_item_scopes, value_generate_mode, relation_id. Select-type
      fields include options (order, color, is_visibility, is_disabled, label, value,
      work_item_type_key). compound_field type includes compound_fields (array of
      field objects with field_key, field_type_key, field_name, etc.).

constraints:
  - Permission: Permission Management – Configuration

error_mapping:
  30001: Data not found (project_key does not match work_item_type_key; no such work item type in this space)

Usage notes

• work_item_type_key: Omit to return all fields in the space; set to a type (e.g. story, chart) to return only fields scoped to that type. If the type does not exist in the space, 30001 is returned.
• data items: Use field_key when updating work item type settings (schedule_field_key, etc.) or when sending field values in work item APIs. field_type_key (e.g. multi_text, select, compound_field) determines value shape.
• options: For select (and similar) fields; value is what to send in API payloads; label is display. compound_fields: For compound_field type; each sub-field has its own field_key and field_type_key.

Create Custom Field

Create a new custom field under the specified work item type. Returns the new field_key. Permission: Permission Management – Work Item Instances. For feature details, see Permission Management.

Points to note

• Work item relationship field default data visibility is fixed; conditional data range cannot be modified.
• Default values are not supported for attachment type or for external system signal / multi-value external system signal.
• Modifying field validity (default valid) is not supported.
• Updating work item type, creator, submission time, completion time, and business line fields is not supported.
• Voting fields are not supported.

When to Use

• When adding a new custom field (text, select, date, user, number, link, etc.) to a work item type
• When reusing options from another field (value_type 1 + reference_work_item_type_key, reference_field_key) or defining custom options (field_value)
• When configuring team_option for cascading single/multi-select (tree_select, tree_multi_select); mutually exclusive with field_value

API Spec: create_custom_field

name: create_custom_field
type: api
description: >
  Create a custom field under the specified work item type. Returns field_key.
  Supports text, select, tree_select, date, user, number, link, multi_file, bool,
  work_item_related_select, etc. field_value and team_option are mutually exclusive.

auth:
  type: plugin_access_token
  header: X-Plugin-Token
  user_header: X-User-Key

http:
  method: POST
  url: https://{domain}/open_api/{project_key}/field/{work_item_type_key}/create
  headers:
    Content-Type: application/json
    X-Plugin-Token: "{{resolved_token}}"
    X-User-Key: "{{user_key}}"

path_params:
  project_key:
    type: string
    required: true
    description: >
      Space ID (project_key) or space domain name (simple_name).
      project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
  work_item_type_key:
    type: string
    required: true
    description: Work item type. Obtain via Get work item types in space.

inputs:
  field_name:
    type: string
    required: true
    description: Field name; must not duplicate other fields.
  field_alias:
    type: string
    required: false
    description: Field alias; cannot duplicate other fields of the same work item type.
  field_type_key:
    type: string
    required: true
    description: >
      Field type. See Attributes and fields. Supported: text, multi_text, select,
      multi_select, tree_select, tree_multi_select, radio, user, multi_user, date,
      schedule, link, number, multi_file, bool, signal, work_item_related_select,
      work_item_related_multi_select.
  value_type:
    type: integer
    required: false
    description: >
      Option source for select/multi_select/tree_select/tree_multi_select/radio.
      0: Custom (default); 1: Reuse. When 1, reference_work_item_type_key and reference_field_key required.
  field_value:
    type: object
    required: false
    description: >
      Option values; structure per Attributes and fields. For select, multi_select,
      tree_select, tree_multi_select, radio. Mutually exclusive with team_option.
  reference_work_item_type_key:
    type: string
    required: false
    description: Required when value_type = 1.
  reference_field_key:
    type: string
    required: false
    description: Required when value_type = 1.
  is_multi:
    type: boolean
    required: false
    description: For text: true = multi-line; false = single-line (default).
  format:
    type: boolean
    required: false
    description: For date: true = date only; false = date + time (default).
  free_add:
    type: integer
    required: false
    description: For select/tree_select etc.: 1 = allow users to add options; 2 = No (default).
  work_item_relation_uuid:
    type: string
    required: false
    description: Work item relationship ID from Get field information. Required for work_item_related_select / work_item_related_multi_select.
  default_value:
    type: object
    required: false
    description: >
      Default value; structure per field type (Attributes and fields). Not supported
      for attachment, external system signal, multi-value external system signal.
  help_description:
    type: string
    required: false
    description: Help instructions.
  authorized_roles:
    type: array
    items: string
    required: false
    description: >
      Roles or system keys that can access/operate this field. Default "Anyone".
      e.g. _master (Administrator), _owner (Creator), _role (Requirement-related person).
  team_option:
    type: object
    required: false
    description: >
      Team scope per TeamOption. Only for tree_select, tree_multi_select.
      Mutually exclusive with field_value.

outputs:
  data:
    type: string
    description: Created field key (e.g. field_73jds7).

constraints:
  - Permission: Permission Management – Work Item Instances
  - field_value and team_option cannot both be sent

error_mapping:
  1000051468: Field alias repeated (field_alias duplicate)
  1000051469: Invalid update version (field being concurrently updated)
  1000051750: Field name has been used (field_name duplicate)
  1000053603: Field name length exceeded (max characters for field name)

Usage notes

• field_type_key: Use supported API types (e.g. text, select, date, user, number, link, multi_file, bool, work_item_related_select, work_item_related_multi_select). See Attributes and fields and the field type support list in the product docs.
• field_value vs team_option: Use field_value for custom/reused option values for select/tree_select etc.; use team_option only for cascading single/multi-select with team scope. Do not send both.
• value_type 1: Set reference_work_item_type_key and reference_field_key to reuse options from another field.
• work_item_relation_uuid: From Get Field Information (relation or work item relation fields). Required for work_item_related_select / work_item_related_multi_select.
• Default values are not supported for attachment, external system signal, or multi-value external system signal fields.

Update Custom Field

Update the configuration of the specified custom field. Identify the field by field_key in the body. Permission: Permission Management – Configuration. For details, see Permission Management.

Points to note

• Work item relationship field default data visibility is fixed; conditional data range cannot be modified.
• Default values are not supported for attachment type or for external system signal / multi-value external system signal.
• Modifying field validity (default valid) is not supported.
• Updating work item type, creator, submission time, completion time, and business line fields is not supported.
• Voting fields are not supported.
• When modifying or adding sub-options (cascading options), parent_value is required.

When to Use

• When changing field name, alias, help description, default value, authorized roles, or option list (field_value with action add/modify/delete)
• When updating team scope (team_option) for cascading single/multi-select; mutually exclusive with field_value
• When updating a composite field: pass parent field_key to change only field_name, field_alias, help_description; pass child field_key to update all attributes

API Spec: update_custom_field

name: update_custom_field
type: api
description: >
  Update configuration of the specified custom field. field_key in body identifies
  the field. field_value supports option actions (add/modify/delete); parent_value
  required for sub-options. field_value and team_option are mutually exclusive.

auth:
  type: plugin_access_token
  header: X-Plugin-Token
  user_header: X-User-Key

http:
  method: PUT
  url: https://{domain}/open_api/{project_key}/field/{work_item_type_key}
  headers:
    Content-Type: application/json
    X-Plugin-Token: "{{resolved_token}}"
    X-User-Key: "{{user_key}}"

path_params:
  project_key:
    type: string
    required: true
    description: >
      Space ID (project_key) or space domain name (simple_name).
      project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
  work_item_type_key:
    type: string
    required: true
    description: Work item type. Obtain via Get work item types in space.

inputs:
  field_key:
    type: string
    required: false
    description: >
      Unique identifier of the field from Get Field Information. For composite
      fields: parent field_key allows only field_name, field_alias, help_description;
      child field_key allows all attributes.
  field_name:
    type: string
    required: false
    description: Field name.
  field_value:
    type: array
    required: false
    description: >
      Option updates. Each item: label, value (option id), action (0 add, 1 modify, 2 delete).
      For sub-options include parent_value. Structure per Attributes and fields.
      Mutually exclusive with team_option.
  free_add:
    type: integer
    required: false
    description: 1 = allow users to add options; 2 = No (default). For select/tree_select etc.
  work_item_relation_uuid:
    type: string
    required: false
    description: Work item relationship ID from Get Field Information. For work_item_related_select / work_item_related_multi_select.
  default_value:
    type: object
    required: false
    description: Default value; structure per field type. Not supported for attachment, signal, multi-value signal.
  field_alias:
    type: string
    required: false
    description: Field alias; cannot duplicate other fields of same work item type.
  help_description:
    type: string
    required: false
    description: Help instructions.
  authorized_roles:
    type: array
    items: string
    required: false
    description: Role or system keys (e.g. _master, _owner, _role). Default "Anyone".
  team_option:
    type: object
    required: false
    description: Team scope per TeamOption. Only for tree_select, tree_multi_select. Mutually exclusive with field_value.

outputs:
  data:
    type: object
    description: Empty on success (no data in response).

constraints:
  - Permission: Permission Management – Configuration
  - field_value and team_option cannot both be sent

error_mapping:
  1000051468: Field alias repeated (replace field_alias)
  1000051750: Field name has been used (replace field_name)
  1000050746: Field type not supported
  1000053603: Field name length exceeded (max 255 characters)
  1000053604: Field description length exceeded (max 255 characters)
  1000053605: Option count exceeded (up to {Number} options)

Usage notes

• field_key: Required to identify which field to update; from Get Field Information. For compound_field: use parent field_key to change only name/alias/help_description; use child field_key to update all attributes.
• field_value option actions: action 0 = add option, 1 = modify option, 2 = delete option. Include parent_value when adding or modifying sub-options (cascading).
• field_value vs team_option: Do not send both. Use field_value for option list changes; use team_option for team scope on tree_select / tree_multi_select.
• Default values are not supported for attachment, external system signal, or multi-value external system signal.