The public API is delivered in v1.18.0 or higher of the add-on.
Resources
/rest/idalko-igrid/1.0/grid/
Methods
Obtain Grid List GET /rest/idalko-igrid/1.0/grid/list
Returns a list of TGE customfields in the JIRA instance. Only available for admins
available response representations:
200 (success) - application/json. Response example:
[ {"id": "10001", name: "TGE"}, {"id": "10002", name: "Sandwich Order"}, {"id": "10003", name: "Purchase"} ]
403 (forbidden). Returned if:
- the user has no permissions to get this info
- 401 (not authorised)
500 (server error)
Obtain Grid Datasource Info GET /rest/idalko-igrid/1.0/grid/{gridId}/datasource
Returns the table name, data source and connection url for a grid table.
template parameters
parameter | value | required | description |
---|---|---|---|
gridId | long | + | id of the TGE customfield |
available response representations:
200 (success) - application/json. Response example:
{ "configurationTableName": "actions", "databaseTableName": "actions_c10200", "connectionUrl": "jdbc:mysql://localhost:3306/jiradb?useUnicode=true&characterEncoding=UTF8&sessionVariables=storage_engine=InnoDB" }
403 (forbidden). Returned if:
- the user has no permissions to get this info
- 400 (bad request). Returned if:
- the specified customfield id exists but it is not a TGE customfield
- 404 (not found). Returned if:
- customfield with the specified id does not exist
- 401 (not authorised)
- 500 (server error)
Obtain Number of Rows GET /rest/idalko-igrid/1.0/grid/{gridId}[/issue/{issueId}]/rowcount
Returns the number of rows of the grid across all the issues or only in a certain issue
Note
If a user does not have permissions to see all the projects with the configured grids, he will see a number of rows only in issues invisible to his projects.
template parameters
parameter | value | required | description |
---|---|---|---|
gridId | long | + | id of the TGE customfield |
issueId | long | - | id of the issue |
available response representations:
200 (success) - application/json. Response example:
{ "rowCount": 12 }
403 (forbidden). Returned if:
- the user has no permissions to view specified issue
- 400 (bad request). Returned if:
- the specified customfield id exists but it is not a TGE customfield
- 404 (not found). Returned if:
- customfield with the specified id does not exist
- issue with the specified id does not exist
- 401 (not authorised)
- 500 (server error)
Reload Grid POST /rest/idalko-igrid/1.0/grid/issue/{issueId}/reload
Reloads a single grid or multiple grids at once
template parameters
parameter | value | required | description |
---|---|---|---|
issueId | long | + | id of the issue |
acceptable request representations:
{ "gridIds" : [10101, 10102] }
available response representations:
- 200 (success)
- 403 (forbidden). Returned if:
- the user has no permissions for the specified issue
- 400 (bad request). Returned if:
invalid custom field context, i.e this issue is not applicable to the context of the specified grid
the specified customfield(s) id exists but it is not a TGE customfield
- 404 (not found). Returned if:
- the specified issueId doesn't exist
- TGE customfield with the specified id does not exist
- 401 (not authorised)
- 500 (server error)
Clear Grid Data PUT /rest/idalko-igrid/1.0/grid/{gridId}/issue/{issueId}/clear
Clears all the data from the specified grid in the specified issue
template parameters
parameter | value | required | description |
---|---|---|---|
issueId | long | + | id of the issue |
gridId | long | + | id of the TGE customfield |
available response representations:
- 200 (success)
- 403 (forbidden). Returned if:
- the user has no permissions for the specified issue
- 400 (bad request). Returned if:
invalid custom field context, i.e this issue is not applicable to the context of the specified grid
the specified customfield(s) id exists but it is not a TGE customfield
- 404 (not found). Returned if:
- the specified issueId doesn't exist
- TGE customfield with the specified id does not exist
- 401 (not authorised)
- 500 (server error)
Clear All Duplicates PUT /rest/idalko-igrid/1.0/grid/{gridId}/issue/{issueId}/clearDuplicates
Removes duplicate rows from the specified grid in the specified issue
template parameters
parameter | value | required | description |
---|---|---|---|
issueId | long | + | id of the issue |
gridId | long | + | id of the TGE customfield |
available response representations:
- 200 (success)
- 403 (forbidden). Returned if:
- the user has no permissions for the specified issue
- 400 (bad request). Returned if:
invalid custom field context, i.e this issue is not applicable to the context of the specified grid
the specified customfield(s) id exists but it is not a TGE customfield
- 404 (not found). Returned if:
- the specified issueId doesn't exist
- TGE customfield with the specified id does not exist
- 401 (not authorised)
- 500 (server error)
Clear All Not Modified PUT /rest/idalko-igrid/1.0/grid/{gridId}/issue/{issueId}/clearNotModified
Removes all non-modified rows from the specified grid in the specified issue
template parameters
parameter | value | required | description |
---|---|---|---|
issueId | long | + | id of the issue |
gridId | long | + | id of the TGE customfield |
available response representations:
- 200 (success)
- 403 (forbidden). Returned if:
- the user has no permissions for the specified issue
- 400 (bad request). Returned if:
invalid custom field context, i.e this issue is not applicable to the context of the specified grid
the specified customfield(s) id exists but it is not a TGE customfield
- 404 (not found). Returned if:
- the specified issueId doesn't exist
- TGE customfield with the specified id does not exist
- 401 (not authorised)
- 500 (server error)
Read Grid Data GET /rest/idalko-igrid/1.0/grid/{gridId}/issue/{issueId}/[row/{rowId}]?columns&startAt&maxResults
Returns grid data for the issue
template parameters
parameter | value | required | description |
---|---|---|---|
gridId | long | + | id of the TGE customfield |
issueId | long | + | id of the issue |
rowId | long | - | id of the row in grid. Optional. If specified, only data for this row is returned. |
query parameters
parameter | value | required | description |
---|---|---|---|
columns | string | - | coma-separated list of columns as configured in the grid definition. If omitted - all columns are returned |
startAt | integer | - | startAt pagination parameter. See pagination |
maxResults | integer | - | maxResults pagination parameter. See pagination |
available response representations:
200 (success) - application/json. Given the grid configuration similar to the Family List the example of request and response are:
/rest/idalko-igrid/1.0/grid/10301/issue/11359
{ "startAt" : 0, "maxResults" : 10, "total": 200, "values": [ { "id": 1, "issueId": 10173, "modified": 1, "name": "brad", "dob": -32756400000, "gender": "M", "relation": { "name": "Father", "value": "Dad" }, "hobbies": "Likes: Acting, Art, Basketball, Golf" }, { "id": 2, "issueId": 10173, "modified": 1, "name": "angelina", "dob": 171064800, "gender": "F", "relation": { "name": "Mother", "value": "Mom" } //... ] }
if columns are specified it could be
/rest/idalko-igrid/1.0/grid/10301/issue/11359?columns=name,dob
{ "startAt" : 0, "maxResults" : 10, "total": 200, "values": [ {"id": 1, "issueId": 10173, "modified": 1, "name": "brad", "dob": -32752800}, {"id": 2, "issueId": 10173, "modified": 1, "name": "angelina", "dob": 171064800} //... ] }
if a special column like list is specified - the response contains all the data related to this column. For example,
/rest/idalko-igrid/1.0/grid/10301/issue/11359?columns=relation
{ "startAt" : 0, "maxResults" : 10, "total": 200, "values": [ { "id": 1, "issueId": 10173, "modified": 1, "relation": { "value": "Dad", "name": "Father" }, }, { "id": 2, "issueId": 10173, "modified": 1, "relation": { "value": "Mom", "name": "Mother" } } //... ] }
*NOTE*: the dob field in the example actually has to contain time in milliseconds instead of date string - to be done
403 (forbidden). Returned if:
- the user has no permissions for the specified issue
- 400 (bad request). Returned if:
invalid custom field context, i.e this issue is not applicable to the context of the specified grid
the specified customfield id exists but it is not a TGE customfield
specified column name(s) does not exist
- 404 (not found). Returned if:
- the specified issueId doesn't exist
- TGE customfield with the specified id does not exist
- 401 (not authorised)
- 500 (server error)
Read Grid Data for all issues GET /rest/idalko-igrid/1.0/grid/{gridId}/issues?startAt&maxResults&rowId&columns
Returns grid data for all issues
template parameters
parameter | value | required | description |
---|---|---|---|
gridId | long | + | id of the TGE customfield |
query parameters
parameter | value | required | description |
---|---|---|---|
columns | string | - | coma-separated list of columns as configured in the grid definition. If omitted - all columns are returned |
startAt | integer | - | startAt pagination parameter. See pagination |
maxResults | integer | - | maxResults pagination parameter. See pagination |
rowId | long | - | rowId of particular issue with grid data |
available response representations:
200 (success) - application/json. Given the grid configuration similar to the Family List the example of request and response are:
/rest/idalko-igrid/1.0/grid/10011/issues
Response{ "startAt":0, "maxResults":10, "total":2, "values": [ { "issueId":10001, "values": [ {"island":"Baynham Island","latitude":99.1,"modified":1,"location": {"name":"North","value":"N"}, "treasure":"Gold","id":1,"longitude":23.3}, {"island":"Triangle Island","latitude":11.1,"modified":1,"location":{"name":"East","value":"E"},"treasure":"Nobody knows:)","id":2, "longitude":2121.1} ] }, { "issueId":10002, "values": [ {"island":"Mansell Island","latitude":1241.1,"modified":1,"location":{"name":"South","value":"South"},"treasure":"jewelry", "id":3,"longitude":142123.11}, {"island":"Goat Island","latitude":1231.11,"modified":1,"location":{"name":"East","value":"E"},"treasure":"Goats","id":5, "longitude":5431.132}]} ] } }
if columns are specified it could be
/rest/idalko-igrid/1.0/grid/10011/issues?columns=island,treasure
Response{ "startAt":0, "maxResults":10, "total":2, "values": [ { "issueId":10001, "values": [ {"island":"Baynham Island","modified":1,"treasure":"Gold","id":1}, {"island":"Triangle Island","modified":1,"treasure":"Nobody knows:)","id":2} ] }, { "issueId":10002, "values": [ {"island":"Mansell Island","modified":1,"treasure":"jewelry","id":3}, {"island":"Goat Island","modified":1,"treasure":"Goats","id":5} ] } }
403 (forbidden). Returned if:
- the user has no permissions for the specified issue
- 400 (bad request). Returned if:
invalid custom field context, i.e this issue is not applicable to the context of the specified grid
the specified customfield id exists but it is not a TGE customfield
specified column name(s) does not exist
- 404 (not found). Returned if:
- TGE customfield with the specified id does not exist
- 401 (not authorised)
- 500 (server error)
Add Rows POST /rest/idalko-igrid/1.0/grid/{gridId}/issue/{issueId}
Add rows to the grid
template parameters
parameter | value | required | description |
---|---|---|---|
gridId | long | + | id of the TGE customfield |
issueId | long | + | id of the issue |
{ "rows": [ {"foo": "bar 1", "bar": "foo 1", "anumber": 1}, {"foo": "bar 2", "anumber": 2}, {"foo": "bar 3", "bar": "foo 3"} ] }
Note
The API user does not have to specify all columns of the grid. Omitted columns will be set to null if they are not required
available response representations:
201 (success) - application/json.
[79, 80, 81]
403 (forbidden). Returned if:
- the user has no permissions for the specified issue
- 400 (bad request). Returned if:
invalid custom field context, i.e this issue is not applicable to the context of the specified grid
the specified customfield id exists but it is not a TGE customfield
specified column name(s) does not exist
invalid value for some column. For example, a non-number for number field
the column which is required is not specified
- 404 (not found). Returned if:
- the specified issueId doesn't exist
- TGE customfield with the specified id does not exist
- the column used in the request does not exist
- 401 (not authorised)
- 500 (server error)
Edit Rows PUT /rest/idalko-igrid/1.0/grid/{gridId}/issue/{issueId}
Edit grid data
template parameters
parameter | value | required | description |
---|---|---|---|
gridId | long | + | id of the TGE customfield |
issueId | long | + | id of the issue |
{ "rows": [ { "rowId": 79, "values": { "foo": "bar 1" } }, { "rowId": 80, "values": { "foo": "bar 2", "anumber": null } }, { "rowId": 81, "values": { "foo": "bar 3", "bar": "" } } ] }
The API user does not have to specify all columns of the grid. Only the specified columns values will be updated. Other columns will be left intact.
We have to treat carefully null and empty string values and values for the specific type, like a string, so that the REST call cannot break the TGE, the JQL searchers, etc.
available response representations:
200 (success)
403 (forbidden). Returned if:
- the user has no permissions for the specified issue
- 400 (bad request). Returned if:
- invalid custom field context, i.e this issue is not applicable to the context of the specified grid
- the specified customfield id exists but it is not a TGE customfield
- invalid value for some column. For example, a non-number for number field
- null or empty value for the required field
- 404 (not found). Returned if:
the specified issueId doesn't exist
TGE customfield with the specified id does not exist
the specified rowId does not exist
- specified column name(s) does not exist
- 401 (not authorised)
- 500 (server error)
Remove Rows DELETE /rest/idalko-igrid/1.0/grid/{gridId}/issue/{issueId}
Delete grid rows
template parameters
parameter | value | required | description |
---|---|---|---|
gridId | long | + | id of the TGE customfield |
issueId | long | + | id of the issue |
{ "rows": [79, 80, 81] }
{ "rows": "all" }
available response representations:
204 (success)
403 (forbidden). Returned if:
- the user has no permissions for the specified issue
- 400 (bad request). Returned if:
- invalid custom field context, i.e this issue is not applicable to the context of the specified grid
- the specified customfield id exists but it is not a TGE customfield
- 404 (not found). Returned if:
the specified issueId doesn't exist
TGE customfield with the specified id does not exist
the specified rowId does not exist
- 401 (not authorised)
- 500 (server error)
Synchronize Custom Field Values PUT /rest/idalko-igrid/1.0/grid/synchronize
Synchronize custom field values of all grids in all issues after the direct import of the grid data using SQL query.
Available only since TGE v1.19.0
Request body is ignored.
available response representations:
204 (success). Returns the ID of the synchronization background task. May be used in future releases of the API to track the synchronization progress when an appropriate call is added.
403 (forbidden). Returned if:
- the user is not a sysadmin
- 401 (not authorised)
- 500 (server error)