|
1
|
# JSON API: Tickets |
|
2
|
([⬑JSON API Index](index.md)) |
|
3
|
|
|
4
|
Jump to: |
|
5
|
|
|
6
|
* [Ticket Reports](#reports) |
|
7
|
* [Fetch a Report](#report-get) |
|
8
|
* [List Reports](#report-list) |
|
9
|
* [Run a Report](#report-run) |
|
10
|
|
|
11
|
|
|
12
|
--- |
|
13
|
|
|
14
|
# Tickets |
|
15
|
|
|
16
|
This API is incomplete. It is missing at least the following features: |
|
17
|
|
|
18
|
- Content for a given ticket ID |
|
19
|
- History for a given ticket ID? |
|
20
|
- An option to enable/disable the generation of hyperlinks, as links |
|
21
|
won't be useful in most non-browser clients. |
|
22
|
|
|
23
|
|
|
24
|
<a id="reports"></a> |
|
25
|
# Ticket Reports |
|
26
|
|
|
27
|
<a id="report-get"></a> |
|
28
|
## Fetch a Report |
|
29
|
|
|
30
|
**Status:** implemented 20111008 |
|
31
|
|
|
32
|
**Required privileges:** "t" (the thinking being that only those |
|
33
|
permitted to create reports should be able to read their SQL code) |
|
34
|
|
|
35
|
**Request:** `/json/report/get[/REPORT_NUMBER]` |
|
36
|
|
|
37
|
**Request options:** |
|
38
|
|
|
39
|
- `report=number` The report number to fetch.\ |
|
40
|
CLI: `-report|-r` \ |
|
41
|
(Design note: `--number/-n` was not used because that parameter has a |
|
42
|
different meaning (limit response count) in several commands.) May |
|
43
|
optionally be defined via the 4th GET path element or CLI arg. |
|
44
|
|
|
45
|
**Response payload example:** |
|
46
|
|
|
47
|
```json |
|
48
|
{ |
|
49
|
"report":1, |
|
50
|
"owner":"drh", |
|
51
|
"title":"All Tickets", |
|
52
|
"timestamp":"112443570187200", |
|
53
|
"columns":"#ffffff Key:\r\n#f2dcdc Active\r\n...", |
|
54
|
"sqlCode":"..." |
|
55
|
} |
|
56
|
``` |
|
57
|
|
|
58
|
<a id="report-list"></a> |
|
59
|
## List Reports |
|
60
|
|
|
61
|
**Status:** implemented 20111008 |
|
62
|
|
|
63
|
**Required privileges:** "r" or "n" |
|
64
|
|
|
65
|
**Request:** `/json/report/list` |
|
66
|
|
|
67
|
**Response payload example:** |
|
68
|
|
|
69
|
```json |
|
70
|
[ |
|
71
|
{ |
|
72
|
"report":1, |
|
73
|
"title":"All Tickets", |
|
74
|
"owner":"drh" |
|
75
|
}, |
|
76
|
… |
|
77
|
] |
|
78
|
``` |
|
79
|
|
|
80
|
<a id="report-run"></a> |
|
81
|
## Run a Report |
|
82
|
|
|
83
|
**Status:** implemented 20111008 |
|
84
|
|
|
85
|
**Required privileges:** "r" or "n" |
|
86
|
|
|
87
|
**Request:** `/json/report/run[/REPORT_NUMBER]` |
|
88
|
|
|
89
|
Request options: |
|
90
|
|
|
91
|
- `report|-r=int` Specifies which report to run. May optionally be |
|
92
|
supplied as the 4th CLI arg or URL path element. |
|
93
|
- `format|-f=string` (default="o") Specifies "array" or "object" output |
|
94
|
format. |
|
95
|
|
|
96
|
**Response payload example:** |
|
97
|
|
|
98
|
```json |
|
99
|
{ |
|
100
|
"report":1, |
|
101
|
"title":"All Tickets", |
|
102
|
"sqlcode": "only set if requester has 't' privileges.", |
|
103
|
"columnNames":[ … list of column names … ], |
|
104
|
"tickets":[ |
|
105
|
{ |
|
106
|
"bgcolor":"#cfe8bd", |
|
107
|
"#":"fc825dcf52", |
|
108
|
"timestamp":"112443570187200", |
|
109
|
"type":"Code_Defect", |
|
110
|
"status":"Fixed", |
|
111
|
"subsystem":null, |
|
112
|
"title":"\"config pull all\" asks to approve ssl cert" |
|
113
|
}, |
|
114
|
… |
|
115
|
] |
|
116
|
} |
|
117
|
``` |
|
118
|
|
|
119
|
Note that the column names of ticket reports are determined by the |
|
120
|
reports themselves, and not C code. That means that we cannot return a |
|
121
|
standard set of column names here. Fossil requires certain column naming |
|
122
|
conventions for purposes of styling the HTML interface, e.g. the "\#" |
|
123
|
column is always the uuid of the record and "bgcolor" (note the |
|
124
|
different casing than bgColor used throughout the rest of this API!) has |
|
125
|
a specific meaning to the HTML report browser. Fossil also allows the |
|
126
|
tickets to be extended with client-specified fields, so we cannot |
|
127
|
generically make these results fit into the API-wide naming scheme. Full |
|
128
|
details are here: |
|
129
|
|
|
130
|
[](/doc/trunk/www/custom_ticket.wiki) |
|
131
|
|
|
132
|
and: |
|
133
|
|
|
134
|
[](/rptsql?rn=1) |
|
135
|
|
|
136
|
(That one may require non-default permission.) |
|
137
|
|