Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 29 Next »

You can use Jira's REST API to view, create or change data within the STAGIL Table field. The following section will help you to set up your API requests.

Note to syntax: our URL examples use this syntax {{key}} to indicate that “key” is a variable. If you are using Postman you can use this syntax for advanced variable handling.

Content

Table

Get Table

Method: GET

Use this request to get all tabular data from a specific table. You will need the issue ID or key from the issue you want to pull the data from and the custom field ID:

https://JiraURL/rest/api/2/issue/{{issueID}}?fields={{customfieldID}}&expand=renderedFields
 Status: 200

{
"expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
"id": "118610",
"self": "https://jira-test.stagil.com/rest/api/2/issue/118610",
"key": "SDS-66",
"fields": {
"customfield_11827": [
{
"orderPosition": 0,
"id": 37241,
"field-443": "Hello world :)",
"field-443-html": "<p>Hello world <img class=\"emoticon\" src=\"https://jira-test.stagil.com/images/icons/emoticons/smile.png\\" height=\"16\" width=\"16\" align=\"absmiddle\" alt=\"\" border=\"0\"/></p>",
"field-477": [
279
],
"field-477-name": [
"3"
],
"field-495": "2023-07-12",
"field-501": "TPLR-50",
"field-966": [
"agrant-sd-demo"
],
"field-966-name": [
"Alana Grant"
],
"field-1080": [
561
],
"field-1080-name": [
"3"
]
},
{
"orderPosition": 1,
"id": 37242,
"field-443": "Hello world :)",
"field-443-html": "<p>Hello world <img class=\"emoticon\" src=\"https://jira-test.stagil.com/images/icons/emoticons/smile.png\\" height=\"16\" width=\"16\" align=\"absmiddle\" alt=\"\" border=\"0\"/></p>",
"field-477": [
280
],
"field-477-name": [
"4"
],
"field-495": "2023-07-12",
"field-501": "TPLR-31",
"field-966": [
"mheather"
],
"field-966-name": [
"Mark Heather "
],
"field-1080": [
560
],
"field-1080-name": [
"4"
]
}
]
}
}

Update Table

Method: PUT

Updating the entire table is possible via Jira’s REST API.

Request: 

BaseURL/rest/api/2/issue/{issueIdOrKey}
 Body example: Update table (existing rows) 
{
   "fields":{
      "customfield_id":"{\"values\":[
         {
            \"field-191\":[104],
            \"field-219\":\"text\",
            \"field-192\":\"BD-7\",
            \"field-190\":[\"vkisil\"],
            \"field-247\":8.5,
            \"field-248\":1028.5,
            \"orderPosition\":0,
            \"field-189\":false,
            \"id\":-1
         }
      ]}"
   }
}

 Body example: Update table (add new row)

{
"fields":{
"customfield_id":"{\"values\":[
{
\"field-191\":[104],
\"field-219\":\"text\",
\"field-192\":\"BD-7\",
\"field-190\":[\"vkisil\"],
\"field-247\":8.5,
\"field-248\":1028.5,
\"orderPosition\":0,
\"field-189\":false,
\"id\":-1 //add new row
}
]}"
}
}

Table Sum

Method: GET

Returns a sum from the number column from a specific table.

https://JiraURL/rest/stj/1.0/api/table/sum/customfield/{{customFieldId}}/issue/{{issueIdOrKey}}
 Status: 200

{
"field-1081": 8.0
}

Table configuration

Method: GET

This request can be used to get information about the configuration of a STAGIL Tables custom field. This means you will get information like id, default value, column type, max/min values, read-only etc., for each row in a table.

https://JiraURL/rest/stj/1.0/api/table/fields/{{fieldConfigId}}
 Status 200

[
{
"columnWidth": 120,
"defaultValue": "",
"fieldName": "text",
"fieldType": "text",
"formula": "text",
"id": 443,
"issueDisplay": "key_summary",
"mandatory": false,
"maxLength": 450,
"maxNumberUser": 1,
"minLength": 0,
"readonly": false,
"regexp": "",
"regexpError": "",
"showWikiEditor": false,
"storeValue": false,
"sumNumber": false,
"wrapText": true
},
{
"columnWidth": 120,
"decimalPlace": 0,
"defaultValue": "",
"fieldName": "Number ",
"fieldType": "simple_number",
"formula": "Number ",
"id": 1081,
"mandatory": false,
"maxValue": 9223372036854775807,
"minValue": -9223372036854775808,
"readonly": false,
"showWikiEditor": false,
"storeValue": false,
"sumNumber": true,
"wrapText": false
},
{
"columnWidth": 120,
"defaultValue": "",
"fieldName": "Select List 1",
"fieldOptions": [
{
"disabled": false,
"id": 272,
"optionValue": "Option 1",
"orderPosition": 0
},
{
"disabled": false,
"id": 273,
"optionValue": "Option 2",
"orderPosition": 1
},
{
"disabled": false,
"id": 279,
"optionValue": "3",
"orderPosition": 2
}
],
"fieldType": "single_select",
"formula": "Select List 1",
"id": 477,
"issueDisplay": "key_summary",
"mandatory": false,
"maxNumberUser": 1,
"maxSelection": 1,
"readonly": false,
"showWikiEditor": false,
"storeValue": false,
"sumNumber": false,
"uniqueValues": false,
"wrapText": false
},
{
"columnWidth": 120,
"defaultValue": "",
"fieldName": "Date",
"fieldType": "date_picker",
"formula": "Date",
"id": 495,
"issueDisplay": "key_summary",
"mandatory": false,
"maxNumberUser": 1,
"readonly": false,
"regexp": "%e/%b/%y",
"showWikiEditor": false,
"storeValue": false,
"sumNumber": false,
"wrapText": false
},
{
"columnWidth": 120,
"fieldName": "Issue picker ",
"fieldType": "issue_picker",
"formula": "Issue picker ",
"id": 501,
"issueDisplay": "key_summary",
"mandatory": false,
"maxNumberUser": 1,
"readonly": false,
"showWikiEditor": false,
"storeValue": false,
"sumNumber": false,
"wrapText": false
},
{
"columnWidth": 120,
"defaultValue": "",
"fieldName": "Child select",
"fieldOptions": [
{
"dependentOptions": "280",
"disabled": false,
"id": 560,
"optionValue": "4",
"orderPosition": 1
},
{
"dependentOptions": "279",
"disabled": false,
"id": 561,
"optionValue": "3",
"orderPosition": 2
}
],
"fieldType": "single_select",
"formula": "Child select",
"id": 1080,
"issueDisplay": "key_summary",
"mandatory": false,
"maxNumberUser": 1,
"maxSelection": 1,
"parentSelectList": 477,
"readonly": false,
"showWikiEditor": false,
"storeValue": false,
"sumNumber": false,
"uniqueValues": false,
"wrapText": false
},
{
"columnWidth": 120,
"fieldName": "User Picker",
"fieldType": "user_picker",
"formula": "User Picker",
"id": 966,
"issueDisplay": "key_summary",
"mandatory": false,
"maxNumberUser": 1,
"mentionUser": false,
"readonly": false,
"showWikiEditor": false,
"storeValue": false,
"sumNumber": false,
"wrapText": false
}
]

GET FIELD SUM

If you want to get the sum of just one field you can use the following request url:

BASEURL/rest/stj/1.0/api/table/sum/customfield/{{customFieldId}}/issue/{{issueIdOrKey}}/field/{{fieldId}}

You can retrieve the field ID from the table field configuration screen.

Example URL:

http://yourjiraURL/rest/stj/1.0/api/table/sum/customfield/22007/issue/DEMO-4/field/10

Response:

Table History

Method: GET
Description: provides data about changes in the STAGIL Tables & Checklist field or Table History.

API call: http://yourjiraURL/rest/stj/1.0/api/table/history/customField/{{customfieldID}}/issue/{{issuekey}}

 Parameters

{{customfieldID}} - STAGIL Tables & Checklists custom field ID.

{{issuekey}} - issue key of a target Jira issue.

 Response: 200

Table in CSV format

Method: GET

Returns table values in a CSV format

https://JiraURL/rest/stj/1.0/api/table/{{fieldConfigId}}/{{issueIdOrKey}}/COMMA/csv
 Status: 200

Text,Number ,Select List 1,Date,Issue picker ,Child select,User Picker
Hello world :),4,3,12/Jul/23,TPLR-50,3,agrant
Hello world :),4,4,12/Jul/23,TPLR-31,4,mheather

UPDATE ROW

Method: PUT

When you want to change certain rows of your table, you need to use the following API call configuration:

  • URL: https://yourjiraURL.xyz/rest/stj/1.0/api/table/data/customField/{{customFieldId}}/issue/{{issuekey}}/row/row/ID

  • Headers:

    • Your type of authorization

    • Content-Type: application/json;charset=UTF-8;

    • Accept: application/json;

  • You can get the row ID from the GET request, looking at the "id" of the row you want to modify.

  • URL example: http://localhost:8080/rest/stj/1.0/api/table/data/customField/25504/issue/KEY-4/row/123

  • With the GET request you can also see all the available fields and the structure of the table data. When you have drop-down, text or user columns, you only need the "field-1" part of the body. The "field-1-html" or "field-1-name" is not needed and will be added automatically. At the end of the body you don't need to add the custom field ID and the issue ID.

  • Example body: {"field-1": "Customer 7", "field-3": [2], "field-5": "anorth", "field-6": [8]}
    This structure is simply retrieved from the GET request and you only modify the fields that you want to change. In this example, field-1 is a text field, field-3 and field-6 are select lists and field-5 is a user picker.

  • For select list it is possible to use just "field-1-name": [“option1“, “option2“].

  • Please make sure to include all the used columns of your row in your PUT request. Missing columns will be overwritten with empty values!

Create row

Method: POST 

https://jiraURL/rest/stj/1.0/api/table/data/customField/{{customFieldId}}/issue/{{issueIdOrKey}}

(info) Fill out the body of the request with values for the new row. Use the JSON snippet below as an example.

 JSON example

// values for the ‘orderPosition’ and id can be skipped. In this case, the new row will be automatically added to the end of the table.

{

"field-35": 2,

"field-34": "Lorem Ipsum",

"field-36": 22.2,

"field-37": "TestUser",

"field-38": "2021-02-10"

}

Delete row

Method: DELETE

Removes a single row from the table

https://jiraURL/rest/stj/1.0/api/table/data/customField/{{customFieldId}}/issue/{{issueId}}/row/23

Column configuration

Select List column options

Get a list of configured select list options

Method: GET

Returns the list of select list options and their configuration. 

http://yourjiraURL/rest/stj/1.0/api/table/fieldConfig/{{fieldConfigId}}/field/{{fieldId}}/options
 Response: 200

[
{
"disabled": false,
"id": 105,
"optionValue": "Option 1",
"orderPosition": 0
},
{
"disabled": false,
"id": 106,
"optionValue": "Option 2",
"orderPosition": 1
},
{
"disabled": false,
"id": 107,
"optionValue": "Option 3",
"orderPosition": 2
}
]

It is also possible to get a single option by id 

http://yourJiraURL/rest/stj/1.0/api/table/fieldConfig/{{fieldConfigId}}/field/{{fieldId}}/options/{{optionId}}
 Response: 200

{
"disabled": false,
"id": 107,
"optionValue": "Option 3",
"orderPosition": 2
}

Create new option

Method: POST

Allows to create a new select list option with the following configurations:

  • enabled / disabled (for selection)

  • order position in the select list drop-down

  • include the option in the cascading select hierarchy, i.e. set the option as a dependent from an option in another (parent) select list column. 

https://yourJiraURL/rest/stj/1.0/api/table/fieldConfig/{{fieldConfigId}}/field/{{fieldId}}/option
 Body example
{
        "dependentOptions": "optionid", // is not mandatory
        "disabled": false, // is not mandatory
        "optionValue": "Option name", // required
        "orderPosition": 0 // is not mandatory
    }

 Response: 200
{
    "disabled": false,
    "id": 117,
    "optionValue": "Option 4",
    "orderPosition": 3
}

Update an option

Method: PUT

Allows to update the configuration of an existing option 

https://yourJiraURL/rest/stj/1.0/api/table/fieldConfig/{{fieldConfigId}}/field/{{fieldId}}/option/{{optionId}}
https://yourJiraURL/rest/stj/1.0/api/table/fieldConfig/fieldConfigId/field/fieldId/option/optionId
 Body example
{
        "dependentOptions": "optionid", // is not mandatory
        "disabled": false, // is not mandatory
        "optionValue": "Option name", // required
        "orderPosition": 0 // is not mandatory
    }
 Response: 200
{
    "disabled": false,
    "id": 107,
    "optionValue": "Option name updated",
    "orderPosition": 0
}

Delete option

Method: DELETE

Allows to remove an option from a select list column configuration

https://yourJiraURL/rest/stj/1.0/api/table/fieldConfig/{{fieldConfigId}}/field/{{fieldId}}/option/{{optionId}}

Variables

fieldConfigId

Stands for an ID of a table custom field.

To retrieve, follow the following steps:

  1. Navigate to Settings () > Issues > Custom fields under the Fields section

  2. Click on the More (⋯) icon to the right of the custom field you are obtaining the ID

  3. The next page will list all the context for the current table field. Click ‘Edit STAGIL Tables and Checklists Configuration’.

  4. The URL of the next page will be quite long. Closer to the end you will find the fieldConfigId value.

In the above example, the custom field ID is 12039.

fieldId

Stands for the ID of a table column. Every column that is created is assigned an individual column id, regardless of the table context. To retrieve it, go to the table configuration page. The column id is displayed as a number before the column name.

optionID

Stand for an ID of an option within a Select List column. To retrieve, use an API call that returns select list option’s IDs within a specific table https://stagil.atlassian.net/wiki/spaces/STJ/pages/1598914569/REST+API+from+2.1.3#Select-List-column-options.

  • No labels

© 2023, STAGIL