Object

Danger

Adjusting objects via API can cause serious issues with your instance. Proceed with absolute caution and ensure to adjust any of Zammads default fields.

If you want to hide fields, consider Core Workflows instead. For states and priorities use either API endpoints or rails console.

List

Required permission: admin.object

GET-Request sent: /api/v1/object_manager_attributes

Response:

# HTTP-Code 200 Ok

[
   {
      "id": 2,
      "name": "customer_id",
      "display": "Customer",
      "data_type": "user_autocompletion",
      "data_option": {
         "relation": "User",
         "autocapitalize": false,
         "multiple": false,
         "guess": true,
         "null": false,
         "limit": 200,
         "placeholder": "Enter Person or Organization/Company",
         "minLengt": 2,
         "translate": false,
         "permission": [
            "ticket.agent"
         ]
      },
      "data_option_new": {},
      "editable": false,
      "active": true,
      "screens": {
         "create_top": {
            "-all-": {
               "null": false
            }
         },
         "edit": {}
      },
      "to_create": false,
      "to_migrate": false,
      "to_delete": false,
      "to_config": false,
      "position": 10,
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2021-11-09T13:12:32.677Z",
      "updated_at": "2021-11-09T13:12:32.677Z",
      "object": "Ticket",
      "deletable": false,
      "not_deletable_reason": "This attribute is referenced by Overview: My Tickets and thus cannot be deleted!"
   },
   {
      "id": 1,
      "name": "title",
      "display": "Title",
      "data_type": "input",
      "data_option": {
         "type": "text",
         "maxlength": 200,
         "null": false,
         "translate": false
      },
      "data_option_new": {},
      "editable": false,
      "active": true,
      "screens": {
         "create_top": {
            "-all-": {
               "null": false
            }
         },
         "edit": {}
      },
      "to_create": false,
      "to_migrate": false,
      "to_delete": false,
      "to_config": false,
      "position": 15,
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2021-11-09T13:12:32.671Z",
      "updated_at": "2021-11-09T13:12:32.671Z",
      "object": "Ticket",
      "deletable": false
   },
   {
      "id": 3,
      "name": "type",
      "display": "Type",
      "data_type": "select",
      "data_option": {
         "default": "",
         "options": {
            "Incident": "Incident",
            "Problem": "Problem",
            "Request for Change": "Request for Change"
         },
         "nulloption": true,
         "multiple": false,
         "null": true,
         "translate": true,
         "maxlength": 255
      },
      "data_option_new": {},
      "editable": true,
      "active": false,
      "screens": {
         "create_middle": {
            "-all-": {
               "null": false,
               "item_class": "column"
            }
         },
         "edit": {
            "ticket.agent": {
               "null": false
            }
         }
      },
      "to_create": false,
      "to_migrate": false,
      "to_delete": false,
      "to_config": false,
      "position": 20,
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2021-11-09T13:12:32.686Z",
      "updated_at": "2021-11-09T13:12:32.686Z",
      "object": "Ticket",
      "deletable": true
   },
   {
      "id": 4,
      "name": "group_id",
      "display": "Group",
      "data_type": "select",
      "data_option": {
         "default": "",
         "relation": "Group",
         "relation_condition": {
            "access": "full"
         },
         "nulloption": true,
         "multiple": false,
         "null": false,
         "translate": false,
         "only_shown_if_selectable": true,
         "permission": [
            "ticket.agent",
            "ticket.customer"
         ],
         "maxlength": 255
      },
      "data_option_new": {},
      "editable": false,
      "active": true,
      "screens": {
         "create_middle": {
            "-all-": {
               "null": false,
               "item_class": "column"
            }
         },
         "edit": {
            "ticket.agent": {
               "null": false
            }
         }
      },
      "to_create": false,
      "to_migrate": false,
      "to_delete": false,
      "to_config": false,
      "position": 25,
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2021-11-09T13:12:32.690Z",
      "updated_at": "2021-11-09T13:12:32.690Z",
      "object": "Ticket",
      "deletable": false
   },
   {
      "id": 5,
      "name": "owner_id",
      "display": "Owner",
      "data_type": "select",
      "data_option": {
         "default": "",
         "relation": "User",
         "relation_condition": {
            "roles": "Agent"
         },
         "nulloption": true,
         "multiple": false,
         "null": true,
         "translate": false,
         "permission": [
            "ticket.agent"
         ],
         "maxlength": 255
      },
      "data_option_new": {},
      "editable": false,
      "active": true,
      "screens": {
         "create_middle": {
            "-all-": {
               "null": true,
               "item_class": "column"
            }
         },
         "edit": {
            "-all-": {
               "null": true
            }
         }
      },
      "to_create": false,
      "to_migrate": false,
      "to_delete": false,
      "to_config": false,
      "position": 30,
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2021-11-09T13:12:32.694Z",
      "updated_at": "2021-11-09T13:12:32.694Z",
      "object": "Ticket",
      "deletable": false,
      "not_deletable_reason": "This attribute is referenced by Trigger: customer notification (on owner change); Overview: My assigned Tickets,My pending reached Tickets,Unassigned & Open and thus cannot be deleted!"
   },
   {
      "id": 6,
      "name": "state_id",
      "display": "State",
      "data_type": "select",
      "data_option": {
         "relation": "TicketState",
         "nulloption": true,
         "multiple": false,
         "null": false,
         "default": 2,
         "translate": true,
         "filter": [
            2,
            1,
            3,
            4,
            6,
            7
         ],
         "maxlength": 255
      },
      "data_option_new": {},
      "editable": false,
      "active": true,
      "screens": {
         "create_middle": {
            "ticket.agent": {
               "null": false,
               "item_class": "column",
               "filter": [
                  2,
                  1,
                  3,
                  4,
                  7
               ]
            },
            "ticket.customer": {
               "item_class": "column",
               "nulloption": false,
               "null": true,
               "filter": [
                  1,
                  4
               ],
               "default": 1
            }
         },
         "edit": {
            "ticket.agent": {
               "nulloption": false,
               "null": false,
               "filter": [
                  2,
                  3,
                  4,
                  7
               ]
            },
            "ticket.customer": {
               "nulloption": false,
               "null": true,
               "filter": [
                  2,
                  4
               ],
               "default": 2
            }
         }
      },
      "to_create": false,
      "to_migrate": false,
      "to_delete": false,
      "to_config": false,
      "position": 40,
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2021-11-09T13:12:32.706Z",
      "updated_at": "2021-11-09T13:12:32.706Z",
      "object": "Ticket",
      "deletable": false,
      "not_deletable_reason": "This attribute is referenced by Trigger: auto reply (on new tickets); Overview: My Organization Tickets,My Tickets,My assigned Tickets,My pending reached Tickets,My replacement Tickets,Open,Open Banana Items,Pending reached,Unassigned & Open,VIP Customers and thus cannot be deleted!"
   },
   {
      "id": 7,
      "name": "pending_time",
      "display": "Pending till",
      "data_type": "datetime",
      "data_option": {
         "future": true,
         "past": false,
         "diff": 24,
         "null": true,
         "translate": true,
         "permission": [
            "ticket.agent"
         ]
      },
      "data_option_new": {},
      "editable": false,
      "active": true,
      "screens": {
         "create_middle": {
            "-all-": {
               "null": false,
               "item_class": "column"
            }
         },
         "edit": {
            "-all-": {
               "null": false
            }
         }
      },
      "to_create": false,
      "to_migrate": false,
      "to_delete": false,
      "to_config": false,
      "position": 41,
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2021-11-09T13:12:32.713Z",
      "updated_at": "2021-11-09T13:12:32.713Z",
      "object": "Ticket",
      "deletable": false,
      "not_deletable_reason": "This attribute is referenced by Overview: My pending reached Tickets,Pending reached and thus cannot be deleted!"
   },
   {
      "id": 8,
      "name": "priority_id",
      "display": "Priority",
      "data_type": "select",
      "data_option": {
         "relation": "TicketPriority",
         "nulloption": false,
         "multiple": false,
         "null": false,
         "default": 2,
         "translate": true,
         "maxlength": 255
      },
      "data_option_new": {},
      "editable": false,
      "active": true,
      "screens": {
         "create_middle": {
            "ticket.agent": {
               "null": false,
               "item_class": "column"
            }
         },
         "edit": {
            "ticket.agent": {
               "null": false
            }
         }
      },
      "to_create": false,
      "to_migrate": false,
      "to_delete": false,
      "to_config": false,
      "position": 80,
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2021-11-09T13:12:32.718Z",
      "updated_at": "2021-11-09T13:12:32.718Z",
      "object": "Ticket",
      "deletable": false
   },

   [ ... ]
]

Show

Required permission: admin.object

GET-Request sent: /api/v1/object_manager_attributes/{id}

Response:

# HTTP-Code 200 Ok

{
   "id": 18,
   "object_lookup_id": 1,
   "name": "email",
   "display": "Email",
   "data_type": "input",
   "data_option": {
      "type": "email",
      "maxlength": 150,
      "null": true,
      "item_class": "formGroup--halfSize"
   },
   "data_option_new": {},
   "editable": false,
   "active": true,
   "screens": {
      "signup": {
         "-all-": {
            "null": false
         }
      },
      "invite_agent": {
         "-all-": {
            "null": false
         }
      },
      "invite_customer": {
         "-all-": {
            "null": false
         }
      },
      "edit": {
         "-all-": {
            "null": true
         }
      },
      "create": {
         "-all-": {
            "null": true
         }
      },
      "view": {
         "-all-": {
            "shown": true
         }
      }
   },
   "to_create": false,
   "to_migrate": false,
   "to_delete": false,
   "to_config": false,
   "position": 400,
   "created_by_id": 1,
   "updated_by_id": 1,
   "created_at": "2021-11-09T13:12:32.784Z",
   "updated_at": "2021-11-09T13:12:32.784Z"
}

Create

Required permission: admin.object

POST-Request sent: /api/v1/object_manager_attributes

Payload:

{
   "name": "sample_boolean",
   "object": "Ticket",
   "display": "Sample Boolean",
   "active": true,
   "position": 1550,
   "data_type": "boolean",
   "data_option": {
      "options": {
         "true": "very correct indeed",
         "false": "very incorrect indeed"
      }
   },
   "screens": {
      "create_middle": {
         "ticket.customer": {
            "shown": true,
            "required": false,
            "item_class": "column"
         },
         "ticket.agent": {
            "shown": true,
            "required": false,
            "item_class": "column"
         }
      },
      "edit": {
         "ticket.customer": {
            "shown": true,
            "required": false
         },
         "ticket.agent": {
            "shown": true,
            "required": true
         }
      }
   }
}

Response:

# HTTP-Code 201 Created

{
   "id": 50,
   "object_lookup_id": 2,
   "name": "sample_boolean",
   "display": "Sample Boolean",
   "data_type": "boolean",
   "data_option": {
      "options": {
         "false": "very incorrect indeed",
         "true": "very correct indeed"
      },
      "default": null,
      "null": true,
      "relation": ""
   },
   "data_option_new": {},
   "editable": true,
   "active": true,
   "screens": {
      "create_middle": {
         "ticket.customer": {
            "shown": true,
            "required": false,
            "item_class": "column"
         },
         "ticket.agent": {
            "shown": true,
            "required": false,
            "item_class": "column"
         }
      },
      "edit": {
         "ticket.customer": {
            "shown": true,
            "required": false
         },
         "ticket.agent": {
            "shown": true,
            "required": true
         }
      }
   },
   "to_create": true,
   "to_migrate": true,
   "to_delete": false,
   "to_config": false,
   "position": 1550,
   "created_by_id": 3,
   "updated_by_id": 3,
   "created_at": "2021-11-12T18:18:23.208Z",
   "updated_at": "2021-11-12T18:18:23.208Z"
}

Note

Please note that above payloads cover ticket objects. This is fine in most situations, except if you’re looking at the default object permissions. This is why we’re listing these separate for you to view.

The attribute object controls which context is being used:

  • Ticket

  • User

  • Organisation

  • Group

"screens": {
   "create_middle": {
      "ticket.customer": {
         "shown": true,
         "required": false,
         "item_class": "column"
      },
      "ticket.agent": {
         "shown": true,
         "required": false,
         "item_class": "column"
      }
   },
   "edit": {
      "ticket.customer": {
         "shown": true,
         "required": false
      },
      "ticket.agent": {
         "shown": true,
         "required": true
      }
   }
}

Update

Required permission: admin.object

Except on the request method, payloads or updating and creating objects are identical. For full payload samples thus scroll up to Create.

Zammad will return two attributes during update: data_option and data_option_new. The first attribute contains the current active values and the second one the new to be values (they’ll become active after executing the database migrations).

PUT-Request sent: /api/v1/object_manager_attributes/{id}

{
   "id": 50,
   "name": "sample_boolean",
   "object": "Ticket",
   "display": "Sample Boolean",
   "data_type": "boolean",
   "position": 1200,
   "data_option": {
      "options": {
         "true": "yes",
         "false": "no"
      },
      "default": "false"
   }
}

Note

Ensure to provide data_option. Zammad is very picky if you leave out this attribute. Please note that changing the object type after creation is not possible.

Response:

# HTTP-Code 200 Ok

{
   "name": "sample_boolean",
   "display": "Sample Boolean",
   "data_type": "boolean",
   "position": 1200,
   "data_option_new": {
      "options": {
         "false": "no",
         "true": "yes"
      },
      "default": false,
      "null": true,
      "relation": ""
   },
   "data_option": {
      "options": {
         "false": "very incorrect indeed",
         "true": "very correct indeed"
      },
      "default": null,
      "null": true,
      "relation": ""
   },
   "object_lookup_id": 2,
   "to_config": true,
   "editable": true,
   "id": 50,
   "updated_by_id": 3,
   "active": true,
   "screens": {
      "create_middle": {
         "ticket.customer": {
            "shown": true,
            "required": false,
            "item_class": "column"
         },
         "ticket.agent": {
            "shown": true,
            "required": false,
            "item_class": "column"
         }
      },
      "edit": {
         "ticket.customer": {
            "shown": true,
            "required": false
         },
         "ticket.agent": {
            "shown": true,
            "required": true
         }
      }
   },
   "to_create": false,
   "to_migrate": false,
   "to_delete": false,
   "created_by_id": 3,
   "created_at": "2021-11-12T18:18:23.208Z",
   "updated_at": "2021-11-12T19:30:20.883Z"
}

Delete

Required permission: admin.object

DELETE-Request sent: /api/v1/object_manager_attributes/{id}

Response:

# HTTP-Code 200 Ok

{}

Execute Database Migrations

Required permission: admin.object

Warning

After executing the database migrations a restart of Zammad is mandatory. If configured Zammad also can restart automatically (this is the case on Hosted environments) – expect a short downtime.

POST-Request sent: /api/v1/object_manager_attributes_execute_migrations

Response:

# HTTP-Code 200 Ok

{}