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
|