Getting started with legacy custom objects

Note: There is a new custom objects experience. See theCustom Object APIs.

The Zendesk REST API provides many object types for storing and managing your customer data, from tickets, users, organizations, and more. However, it can't provide every possible object type that your organization might need. For example, you might want to associate each new ticket with a retail store to get a better picture of the customer and of the store.

Use the Legacy Custom Objects API to define a new object type in Zendesk, then create objects from the new object type. A custom object can be just about anything, including service contracts, products, households, or customer visits. The API lets you create, read, update, or delete the objects.

你可以用你的遗产int定制对象egrations or with the Zendesk Apps framework to extend existing Zendesk product functionality.

This guide shows you how to create and use legacy custom objects with the Zendesk API. The example takes an IT team that maintains the computers of company employees. The IT team wants to include details about each computer in the support tickets that employees submit when they have trouble with one of them. You can define a new computer object type in Zendesk, then create an object for each computer to store details about each one. You can also associate computers with tickets to monitor their reliability.

Enabling legacy custom objects

传统习俗objects are only available to customers who were using them prior to September 2023 and can't be turned on now. If you're new to custom objects, see the latestCustom Objects APIsinstead.

Defining a legacy custom object type

At its most basic, a legacy object type consists of akeyand aschemathat describes the data. The key is the name you want to use to identify the object type. Example: "computer".

After discussions with the IT team, you agree to define a legacy object type for all the personal computers (PCs) in the company. Each PC should be represented as an object record with the following very basic properties:

Name	Type	Mandatory	Comment
id	string	yes	Unique identifier assigned to the computer by IT
model	string	no	Make and model of the computer
is_laptop	boolean	no	Whether or not the computer is is_laptop

These details make up your schema. Notice that the schema doesn't contain any PC information. It just describes that information. To learn more, seeCreating a schema for a custom object.

To create the "pc" object type, include the schema in a POST request to the following endpoint:

POST /api/sunshine/objects/types

Note: The Legacy Custom Objects API introduces a new Zendesk API design. For example, the paths don't have a version number and the resources don't have.jsonextensions. The existing v2 APIs are unaffected.

Try it yourself

Save the following JSON object in a file namedpc_object_type.json.

               
                {"data":{"key":"pc","schema":{"properties":{"id":{"type":"string","description":"Unique identifier assigned to the computer by IT"},"model":{"type":"string","description":"Make and model of the computer"},"is_laptop":{"type":"boolean","description":"Whether or not the computer is a laptop"}},"required":["id","model"]}}}

Thedataobject consists of akeyand aschema. You'll use thekeyto identify the legacy object type in other endpoints. For example, when you create a pc object record later in this tutorial, you'll set thetypeto "pc" as follows:

               
                {"data":{"type":"pc","attributes":{"id":"ASSET-2018pc32","model":"Apple MacBook Pro","is_laptop":true}}}

Your key must meet the following requirements:

是独一无二的
Only contain alphanumeric characters (a-z, 0-9), underscores (_) and dashes (-)
Have a minimum of 2 characters and maximum of 32 characters

The system changes all uppercase characters in the key to lowercase.

In your command-line interface, navigate to the folder containingpc_object_type.json.

Paste the following curl command into your command-line interface and press Enter.

               
                curl https://{subdomain}.亚博.com/api/sunshine/对象/types \-d @pc_object_type.json \-H"Content-Type: application/json"\-v-u{email_address}:{password}-XPOST

Make sure to replace the placeholder values with your own.

Windows users: Replace the line-continuation backslashes (\) in this and the other examples with caret () characters.

Example response:

               
                {"data":{"key":"pc","schema":{"properties":{"id":{"type":"string","description":"Unique name assigned to the computer by IT"},"model":{"type":"string","description":"Make and model of the computer"},"is_laptop":{"type":"boolean","description":"Whether or not the computer is a laptop"}},"required":["id","model"]},"created_at":"2018-10-28T18:13:26.003Z","updated_at":"2018-10-28T18:13:26.003Z"}}

To learn more, seeCreate Legacy Object Typein the API docs.

Adding legacy object records

Once the pc object type is created in your Zendesk Support instance, you can use the Zendesk API to create, read, update, and delete individual pc object records. Legacy object records are nothing more than data objects with defined properties.

The first task is to create an object record for each PC. You can use theCreate Legacy Object Recordendpoint:

POST /api/sunshine/objects/records

The data you include in the request is defined by the object type you defined, which for the pc type consists of attributes named "id", "model", and "is_laptop". Example:

             
              {"data":{"type":"pc","attributes":{"id":"ASSET-2018pc32","model":"Apple MacBook Pro","is_laptop":true}}}

The legacy objects are stored in the Zendesk infrastructure. You can use the Zendesk API to access them.

If you want to use the data, you can use several different GET endpoints to retrieve your legacy objects. See theLegacy Object RecordsAPI docs.
If your IT team makes a change to the PC, you can use theUpdate Legacy Object Recordendpoint to update the object for that PC in Zendesk.
If IT gets rid of the PC, you can use theDelete Legacy Object Recordendpoint.
If IT adds another PC, you can use theCreate Legacy Object Recordendpoint.

Try it yourself

Save the following JSON object in a file namedobj_pc.json:

               
                {"data":{"type":"pc","attributes":{"id":"ASSET-2018pc32","model":"Apple MacBook Pro","is_laptop":true}}}

You must specify "pc" as the object type.

In your command-line interface, navigate to the folder containingobj_pc.jsonand run the following curl command:

               
                curl https://{subdomain}.亚博.com/api/sunshine/对象/records \-d @obj_pc.json \-H"Content-Type: application/json"\-v-u{email_address}:{password}-XPOST

Replace the placeholder values with your own.

The response will include an id for the object record:

               
                {"data":{"type":"pc","id":"5d0daa84-aec0-11e7-9a70-416881d66b6d",...}}

Don't confuse the legacy object record id ("id":"5d0daa84...") with theidattribute in your legacy custom object ("id":"ASSET-2018pc32").

You can use the legacy object record id to make a GET request for the legacy object, as follows:

             
              curl https://{subdomain}.亚博.com/api/sunshine/对象/records/5d0daa84-aec0-11e7-9a70-416881d66b6d \-v-u{email_address}:{password}

To learn more, seeCreate Legacy Object RecordandShow Legacy Object Recordin the API docs.

Modeling your data

After adding pc objects to your Zendesk Support instance, you can establish relationships with other objects in Zendesk to use the data in more meaningful ways. For example, information about a particular PC is not very useful to an IT manager unless it's associated with tickets that employees submitted about the PC.

传统习俗objects support several legacy relationship types:

One-to-one- Both object types can have only one object on either side of the relationship. For example, a ticket would only be associated with a unique PC, and a PC would only be associated with a unique ticket. This isn't a viable option in the IT department example. The number of pc objects would have to equal the number of ticket objects.
One-to-many- Each object of the first object type relates to none, one, or many objects of the second object type. For example, a PC can be associated with none, one, or many tickets.
Many-to-many- Each object of the first object type relates to none, one, or many objects of the second object type, and each object of the second object type relates to none, one, or many objects of the first object type. You define a many-to-many relationship type with two one-to-many relationship types.

A legacy relationship type can be between:

two legacy custom object types (between "pc" and "office_location" object types, for example)
one legacy custom object type and any of the following standard Zendesk object types: tickets, users, articles, organizations, groups, or chats
two standard Zendesk object types

To define a legacy relationship type, you make a POST request to theCreate Legacy Relationship Typeendpoint:

POST /api/sunshine/relationships/types

定义一个遗产类型不创建的关系an association between two specific objects. It just describes the relationship record. To associate two objects, you must create arelationship recordbetween the two objects. That's covered later inAssociating related legacy objects.

Try it yourself

For the IT department, you decide to define a one-to-many relationship type between PCs and tickets. Each ticket can be associated with only one PC, but each PC can be associated with many tickets.

Save the following JSON object in a file namedrelationship_type.json.
```
               
                {"data":{"key":"pc_has_many_tickets","source":"pc","target":["zen:ticket"]}}
               
```
Choose a uniquekeyvalue (here, "pc_has_many_tickets") for each relationship type you define.
The square brackets around the target["zen:ticket"]sets the "many" side of the one-to-many relationship type. Omit the brackets to define a one-to-one relationship type.
The definition reads as follows: A PC can be associated with many tickets, but a ticket can be associated with only one PC.
Use the 'zen:' prefix to specify one of the Zendesk object types. Examples:
- "zen:ticket"
- "zen:user"
- "zen:article"
- "zen:organization"
- "zen:group"
- "zen:chat"
- "zen:lead"
- "zen:contact"
- "zen:deal"
Note: You can't modify the legacy relationship type once it's created. You'll need to delete it and create another one. SeeLegacy Relationship Typesin the API docs.

In your command-line interface, navigate to the folder containingrelationship_type.jsonand run the following curl command:

               
                curl https://{subdomain}.亚博.com/api/sunshine/relationships/types \-d @relationship_type.json \-H"Content-Type: application/json"\-v-u{email_address}:{password}-XPOST

Replace the placeholder values with your own.

To learn more, seeCreate Legacy Relationship Typein the API docs.

Once you've defined a legacy relationship type, you can start associating related objects.

You associate a legacy object of one object type to a legacy object of another object type by creating arelationship record(not to be confused with a relationship type). For your IT department, you can create a relationship record between a particular ticket and a particular PC.

A legacy relationship record consists of the ids of the two related objects and their relationship type. The record doesn't contain any actual object data. Instead, you use the ids in the relationship record to retrieve the related data (covered inRetrieving related objectslater).

A legacy relationship record is governed by a relationship type you created. So far you created a one-to-many type named "pc_has_many_tickets" where each ticket can be associated with only one PC, but each PC can be associated with many tickets.

To create a legacy relationship record, make a POST request to theCreate Legacy Relationship Recordendpoint:

POST /api/sunshine/relationships/records

The JSON object you include in the request must specify the legacy relationship type, as well as the ids of thesourceandtarget对象. Example:

             
              {"data":{"relationship_type":"pc_has_many_tickets","source":"1c771ee0-2c3f-11e7-bf60-e5c3f630b5aa","target":"zen:ticket:35437746"}}

For"relationship_type", you must specify the key you chose when creating the relationship type -- in this case "pc_has_many_tickets".

Note: After creation, you can't modify the legacy relationship record because of the underlying legacy relationship type. You must delete the legacy relationship record and create another one.

Try it yourself

Find or create a test ticket in your Zendesk Support instance. Example:

               
                {"ticket":{"id":35437746,"subject":"My computer is on fire!",...}}

Get the id of the related pc object in your Zendesk Support instance. Example:

               
                {"data":{"type":"pc","id":"5d0daa84-aec0-11e7-9a70-416881d66b6d","attributes":{"id":"ASSET-2018pc32","model":"Apple MacBook Pro","is_laptop":true},...}}

SeeLegacy Object Recordsin the API docs for the various GET requests you can make.

Save the following JSON in a file namedrelationship_record.json, replacing the ids with your own:

               
                {"data":{"relationship_type":"pc_has_many_tickets","source":"5d0daa84-aec0-11e7-9a70-416881d66b6d","target":"zen:ticket:35437746"}}

The example creates a legacy relationship record between a particular PC and a particular ticket. The source and target ids should correspond to the source and target object types in the legacy relationship record type -- in this case, pc id and ticket id.

In your command-line interface, navigate to the folder containingrelationship_record.jsonand run the following command:

               
                curl https://{subdomain}.亚博.com/api/sunshine/relationships/records \-d @relationship_record.json \-H"Content-Type: application/json"\-v-u{email_address}:{password}-XPOST

Example response:

               
                {"data":{"id":"5d3484b5-aec6-11e7-9a70-a12d6a7d800c","relationship_record_type":"pc_has_many_tickets","source":"5d0daa84-aec0-11e7-9a70-416881d66b6d","target":"zen:ticket:35437746","created_at":"2018-09-28T21:52:22.709Z"}}

Use theList Legacy Relationship Records by Object Recordendpoint to retrieve the relationship records:

GET /api/sunshine/objects/records/{resource_id}/relationships/{relationship_type_key}

For example, to get all the related tickets for the PC with the id of "5d0daa84-aec0-11e7-9a70-416881d66b6d", you'd make the following GET request:

             
              curl https://{subdomain}.亚博.com/api/sunshine/对象/records/5d0daa84-aec0-11e7-9a70-416881d66b6d/relationships/pc_has_many_tickets \-v-u{email_address}:{password}

Example response:

             
              {"data":[{"id":"c5477230-2e98-11e7-acd9-9dbd5d6450d8","target":"zen:ticket:35438118","ref":"/api/v2/tickets/35438118"},{"id":"5d3484b5-aec6-11e7-9a70-a12d6a7d800c","target":"zen:ticket:35437746","ref":"/api/v2/tickets/35437746"}],"links":{"previous":null,"next":null}}

Putting it all together

You can use your legacy custom objects and relationship records to solve real-world problems, to improve existing processes, or simply to get a better picture of your customers. For example, you could use the pc objects to build a Zendesk app that shows details about a computer to the agent working on a ticket.

One approach to building this app would be toadd a dropdown listto the ticket form in Help Center that lets users select a PC when they submit a ticket. When designing the ticket field, you'd use the object ids of the pcs as the option values (or "tags", in Zendesk terms). For example, "5d0daa84-aec0-11e7-9a70-416881d66b6d". You could thenbuild a sidebar appin the agent interface to display the computer details. The app would take the option value from the ticket tomake an API requestto get the computer details.

The app could also make an API request tocreate a legacy relationship recordbetween the PC and the ticket when the agent changes the ticket status from New to Open. You could then use the Zendesk API in your system to generate reliability reports that list all the tickets for each PC.

Join the discussionabout this article in the community.