Meegle API Setting Relationship Settings

Meegle API — Setting (Relationship Settings)

APIs under this skill: Get the List of Work Item Relationships, Create Work Item Relationships, Update Work Item Relationships, Delete Work Item Relationships.

Get the List of Work Item Relationships

Obtain the list of work item association relationships under the specified space. Response follows the WorkItemRelation structure (id, name, relation_type, work_item_type_key/name, relation_details). Permission: Permission Management – Work Item Instances.

When to Use

• When building relationship configuration UIs or listing which work item types are linked (e.g. story → sprint)
• When you need relationship id or relation_type for Create/Update/Delete Work Item Relationships or for work_item_relation_uuid in custom fields
• When displaying relation_details (project_key, project_name, work_item_type_key, work_item_type_name) per relation

API Spec: get_list_of_work_item_relationships

name: get_list_of_work_item_relationships
type: api
description: >
  Obtain the list of work item association relationships under the space.
  Returns WorkItemRelation list: id, name, disabled, relation_type, work_item_type_key/name, relation_details.

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

http:
  method: GET
  url: https://{domain}/open_api/{project_key}/work_item/relation
  headers:
    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).

outputs:
  data:
    type: array
    description: >
      List of WorkItemRelation. Each has id, name, disabled, relation_type,
      work_item_type_key, work_item_type_name, relation_details (array of
      project_key, project_name, work_item_type_key, work_item_type_name).

constraints:
  - Permission: Permission Management – Work Item Instances

error_mapping:
  1000052062: Project key is wrong (project_key incorrect; provide correct value)

Usage notes

• data items: Use id when creating/updating/deleting work item relationships or when referencing in custom field work_item_relation_uuid. relation_type and relation_details describe the link (source type and target project/type per detail).
• relation_details: Each entry gives the target space (project_key, project_name) and target work item type (work_item_type_key, work_item_type_name) for that relation.

Create Work Item Relationships

Add a work item association relationship under the specified space. Returns the new relationship relation_id (UUID). Permission: Permission Management – Work Item Instances. For details, see Permission Management.

When to Use

• When creating a new work item relationship (e.g. story → story in same or another space)
• When defining relation_details (target project_key and work_item_type_key per link)
• When you need the returned relation_id for custom fields (work_item_relation_uuid) or for Update/Delete Work Item Relationships

API Spec: create_work_item_relationships

name: create_work_item_relationships
type: api
description: >
  Add a work item association relationship under the space. Returns relation_id (UUID).
  Requires project_key, work_item_type_key (source type), name, and relation_details.

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

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

path_params: {}

inputs:
  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 (source). Obtain via Get work item types in space.
  name:
    type: string
    required: true
    description: Relationship name; must not duplicate an existing relationship name.
  relation_details:
    type: array
    required: true
    description: List of relationship details. Each must have project_key and work_item_type_key.
    items:
      type: object
      properties:
        project_key: { type: string }
        work_item_type_key: { type: string }

outputs:
  data:
    type: object
    description: relation_id (UUID of the newly added work item relationship).

constraints:
  - Permission: Permission Management – Work Item Instances
  - Operating user must have space administrator privileges (else 10001)

error_mapping:
  50006: Relationship name cannot be repeated (name unavailable or duplicate)
  10001: Invalid request (operating user is not admin of the space; contact admin for permissions)

Usage notes

• relation_details: Each element specifies a target: project_key (target space) and work_item_type_key (target work item type). Same space or cross-space links are defined by these entries.
• name: Must be unique among work item relationships in the space; duplicate or invalid name returns 50006.
• data.relation_id: Use this UUID when creating custom fields of type work_item_related_select / work_item_related_multi_select (work_item_relation_uuid) or when updating/deleting this relationship.
• Space administrator permission is required (10001 if user is not admin of the space).

Update Work Item Relationships

Update the configuration of the specified work item relationship. This interface performs overwrite updates (full replace of name and relation_details). Permission: Permission Management – Work Item Instance. For details, see Permission Management.

Points to note

• This interface is for overwrite updates: the provided name and relation_details replace the existing configuration for the given relation_id.

When to Use

• When changing the relationship name or the list of relation_details (target project_key and work_item_type_key) for an existing relationship
• When syncing relationship configuration from external config; use relation_id from Get the List of Work Item Relationships

API Spec: update_work_item_relationships

name: update_work_item_relationships
type: api
description: >
  Update the specified work item relationship (overwrite). Requires relation_id
  from Get the List of Work Item Relationships, plus project_key, work_item_type_key,
  name, and relation_details.

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

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

path_params: {}

inputs:
  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.
  name:
    type: string
    required: true
    description: Relationship name; must not duplicate another relationship name.
  relation_id:
    type: string
    required: true
    description: Work item relationship ID from Get the List of Work Item Relationships.
  relation_details:
    type: array
    required: true
    description: List of relationship details. Each must have project_key and work_item_type_key.
    items:
      type: object
      properties:
        project_key: { type: string }
        work_item_type_key: { type: string }
        project_name: { type: string }
        work_item_type_name: { type: string }

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

constraints:
  - Permission: Permission Management – Work Item Instance
  - Operating user must have space administrator privileges (else 10001)

error_mapping:
  50006: Relationship name cannot be repeated (name unavailable or duplicate)
  10001: Invalid request (operating user is not admin; contact admin for permissions)

Usage notes

• relation_id: From Get the List of Work Item Relationships (data[].id). Identifies which relationship to update.
• Overwrite: The entire relationship config is replaced; send the full name and full relation_details list you want after the update.
• relation_details: Same structure as Create; each entry has project_key and work_item_type_key (and optionally project_name, work_item_type_name). Duplicate or invalid name returns 50006.
• Space administrator permission is required (10001 if not admin).

Delete Work Item Relationships

Delete the work item association relationship identified by relation_id under the specified space. Permission: Permission Management – Work Item Instance. For details, see Permission Management.

When to Use

• When removing a work item relationship (e.g. story → sprint) from the space
• When relation_id comes from Get the List of Work Item Relationships
• When cleaning up or reconfiguring relationships (delete then recreate if needed)

API Spec: delete_work_item_relationships

name: delete_work_item_relationships
type: api
description: >
  Delete the work item association relationship under the space. Requires
  project_key and relation_id from Get the List of Work Item Relationships.

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

http:
  method: DELETE
  url: https://{domain}/open_api/work_item/relation/delete
  headers:
    Content-Type: application/json
    X-Plugin-Token: "{{resolved_token}}"
    X-User-Key: "{{user_key}}"

path_params: {}

inputs:
  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).
  relation_id:
    type: string
    required: true
    description: Work item relationship ID from Get the List of Work Item Relationships.

outputs:
  data:
    type: string
    description: Null or empty on success.

constraints:
  - Permission: Permission Management – Work Item Instance

error_mapping:
  50006: RPC call error (relationship already deleted or does not exist; confirm relation_id)

Usage notes

• relation_id: Use the id from Get the List of Work Item Relationships (data[].id). If the relationship was already deleted or does not exist, 50006 is returned (err.msg may indicate "关系已经被删除" / relationship already deleted).
• Success response has empty or null data; check err_code 0.