Confluence has been updated to version 6.15.9

Page tree
Skip to end of metadata
Go to start of metadata


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

parametervaluerequireddescription
gridIdlong+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

parametervaluerequireddescription
gridIdlong+id of the TGE customfield
issueIdlong-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

parametervaluerequireddescription
issueIdlong+id of the issue

 

acceptable request representations:

Request body is a JSON with array of ids of grids to reload
{ "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

parametervaluerequireddescription
issueIdlong+id of the issue
gridIdlong+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

parametervaluerequireddescription
issueIdlong+id of the issue
gridIdlong+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

parametervaluerequireddescription
issueIdlong+id of the issue
gridIdlong+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

parametervaluerequireddescription
gridIdlong+id of the TGE customfield
issueIdlong+id of the issue
rowIdlong-id of the row in grid. Optional. If specified, only data for this row is returned. 


query parameters

parametervaluerequireddescription
columnsstring-coma-separated list of columns as configured in the grid definition. If omitted - all columns are returned
startAtinteger-startAt pagination parameter. See pagination
maxResultsinteger-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

parametervaluerequireddescription
gridIdlong+id of the TGE customfield


query parameters

parametervaluerequireddescription
columnsstring-coma-separated list of columns as configured in the grid definition. If omitted - all columns are returned
startAtinteger-startAt pagination parameter. See pagination
maxResultsinteger-maxResults pagination parameter. See pagination 
rowIdlong-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

parametervaluerequireddescription
gridIdlong+id of the TGE customfield
issueIdlong+id of the issue

 


Request body is a JSON array with column names and values
{
	"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

parametervaluerequireddescription
gridIdlong+id of the TGE customfield
issueIdlong+id of the issue

 

Request body is a JSON array with rowId, column names, and values.
{
	"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

parametervaluerequireddescription
gridIdlong+id of the TGE customfield
issueIdlong+id of the issue

 

Request body is a json with a list of rowIds to delete.
{
  "rows": [79, 80, 81]
}


use following request body to delete all rows of the grid for the issue
{
  "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)


  • No labels