Custom Ticket Template

How to create a template for your custom tickets

F
Written by Faisal Ramady
Updated over a week ago

3D Repo allows for the creation of "Custom Tickets" which are based around form templates. Templates are assigned to a Teamspace and each Teamspace can hold any number of templates. Once a template has been created users of the Teamspace can create new instances of the ticket based on the template. It is possible to update templates without affecting previously created tickets.

In this guide we will demonstrate how to create a template using the API, what fields are allowed and what modules you can use out of the box.


The Request

Templates are added to a teamspace using a POST request as detailed in the interactive 3D Repo Swagger API documents linked below:

Below is an example of a CURL request posting a new ticket template to a designated teamspace. As you can see you will need to provide a json body with a schema as detailed in the next section, along with your teamspace name and API key. Only teamspace admins can create new tickets. The .json body is composed of arrays that are inside square brackets [] and objects inside of the curved brackets {}. The name, code and configuration make up the settings of the custom ticket. When creating a custom ticket template, a name and three letter code must be specified. In the ticket configuration, specify whether you want to include comments, issue properties, default viewpoints, images, and pins by assigning them either true or false. Note that if you set DefaultView to true, defaultImage is ignored.

Custom ticket templates cannot be deleted once posted to 3D Repo, they must be “deprecated” to be hidden from view. To deprecate a custom ticket template, include the key “deprecated” and set value to true. It is also possible to deprecate any module or field within a module if necessary. Below is an example of a CURL request posting a new ticket template to a designated teamspace (to view how to post a request to create a custom ticket, refer to this article.)

curl --location --request POST 'https://www.3drepo.io/api/v5/teamspaces/{teamspace}/settings/tickets/templates?key={API Key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Test",
"code": "XYZ",
"config": {
"comments": true,
"issueProperties": true,
"defaultView": true,
"defaultImage": true,
"pin": true,
"attachments": true },
"deprecated": false
}'

The response to posting a new ticket template will be a template ID, you can use this ID to update the template at a later date using the Update Template API call, and you can always recover the list of all the templates on a project using the Ticket Template list API call. To view how to update an existing custom ticket with a template ID refer to this article.

The Schema

Below is an example ticket schema, underneath config you can see a “modules” array, in this example, it consists of a standard Safetibase module, and a custom module named “Accordian Header 1”. “Accordian header 1” custom module is composed of all the custom field types that currently available in custom tickets. You can use these custom field types to curate your own custom modules in any combination. Each custom module should include a name and properties. Provide a name for your custom module and include your custom fields inside the properties array. Note also that custom fields can be used inside the properties of the standard Safetibase module. Definitions of all the terms found inside settings, config and modules can be found here.

{
"name":"Example Ticket",
"code":"EXT",
"config":{
"issueProperties":true,
"defaultView":true,
"defaultImage":true,
"pin":true
},
"deprecated":false,
"modules":[
{
"name":"Accordian Header 1",
"deprecated":false,
"properties":[
{
"type":"safetibase",
"properties":[]

},

{
"name":"Required Text Field",
"type":"text",
"deprecated":false,
"required":true
},
{
"name":"Long Text Field",
"type":"longText",
"deprecated":false
},
{
"name":"Boolean Switch",
"type":"boolean",
"deprecated":false
},
{
"name":"Number Field",
"type":"number",
"deprecated":false
},
{
"name":"Drop Down single select",
"type":"oneOf",
"deprecated":false,
"values":[
"Option 1",
"Option 2",
"Option 3"
]
},
{
"name":"Drop Down multiple select",
"type":"manyOf",
"deprecated":false,
"values":[
"Option 1",
"Option 2",
"Option 3"
]
},
{
"name":"Drop Down user select",
"type":"manyOf",
"deprecated":false,
"values":"jobsAndUsers"
},
{
"name":"Image field",
"type":"image",
"deprecated":false
},
{
"name":"Date Field",
"type":"date",
"deprecated":false
},
{
"name":"Viewpoint field",
"type":"view",
"deprecated":false
},
{
"name":"Pin field",
"type":"coords",
"deprecated":false
},
{
"name":"Second Pin field",
"type":"coords",
"deprecated":false
}
]
}
]
}

Settings

name

string

The name of the given template.

code

3 char string

The prefix given to all tickets using this template.

config

object

The configuration of the standard custom tickets modules. (see below table)

deprecated

boolean

If true then the template will no longer be available for users inside the teamspace.

module (optional)

list

Additional data grouped into modules, each of which is placed within an accordion in the 3D Repo ticket creation screen (see below table)

Config

issueProperties

boolean

Whether the 3D Repo default issue properties (Priority, Assignee, Due Date and Status) are used in this ticket.

defaultView

boolean

Whether a default viewpoint is used in this ticket (additional views can be included in custom modules)

defaultImage

boolean

Whether a default image is used in this ticket (additional images can be included in custom modules)

pin

boolean

Whether the user can place a pin when creating a ticket

Modules

name

string

The name of the given module. This appears as the title of the accordion

deprecated

boolean

If true then the module will no longer be available for users inside the teamspace.

properties

list

A list of form fields to be shown in the module using. Please see the Custom Tickets Properties article for information

Did this answer your question?