Update Graph Settings

Updates the Graph (External link) settings of the App.

This API updates the pre-live settings. After using this API, use the Deploy App Settings API to deploy the settings to the live App.

MethodPUT
URLhttps://{subdomain}.kintone.com/k/v1/preview/app/reports.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/app/reports.json
Authentication Password Authentication, API Token Authentication, Session Authentication
Content-Typeapplication/json

Contents

Permissions

  • App Management Permissions are needed.

Request Parameters

Parameter Type Required Description
app Integer or String Yes The App ID.
reports Object Yes An object listing Graph information.

The key of the object is the graph's unique identifier, which is equal to the name of the graph in its default language settings. The values of the key are the various graph settings associated with that graph.
reports.{graphname} Object An object listing Graph information of 1 graph.

If graphname is equal to the name of an existing graph, the graph will be updated with the values in the object.
If graphname is not equal to a name of an existing graph, a new graph will be created with the values in the object.
Any existing graphs that are not set for this parameter will be deleted.
reports.{graphname}.chartType String Conditional The chart type (External link) of the graph.
  • BAR: Bar chart
  • COLUMN: Column chart
  • PIE: Pie chart
  • LINE: Line chart
  • PIVOT_TABLE: Pivot Table
  • TABLE: Table
  • AREA: Area chart
  • SPLINE: Spline chart
  • SPLINE_AREA: Spline area chart
Required when updating an existing graph, or creating a new graph.
reports.{graphname}.chartMode String Conditional The display mode (External link) of the graph.
  • NORMAL: Clustered graph or Non-stacked graph
  • STACKED: Stacked graph
  • PERCENTAGE: 100% stacked graph
If the reports.{graphname}.chartType parameter is set to BAR or COLUMN, NORMAL refers to "Clustered graph" display mode.
If the reports.{graphname}.chartType parameter is set to AREA or SPLINE_AREA, NORMAL refers to "Non-stacked graph" display mode.

Required when the reports.{graphname}.chartType parameter is set to BAR, COLUMN, AREA, or SPLINE_AREA.
reports.{graphname}.name String Conditional The name of the graph.
1 to 64 characters can be specified.

When adding a new graph, the request will fail if the value of this parameter is not the same as reports.{graphname}.

Required when adding a new graph.
reports.{graphname}.index Integer or String Conditional The order of the graphs.
The graph is sorted in ascending order, starting from 0.
The request will fail if there are duplicate values.

Required when updating an existing graph, or creating a new graph.
reports.{graphname}.groups Array Conditional An array of objects containing the "Group by" options.
The order of the objects are in the order of "Level 1", "Level 2", and "Level 3".

The request will fail if the reports.{graphname}.chartType parameter is set to PIVOT_TABLE and reports.{graphname}.groups has less than one object.

Required when adding a new graph.
reports.{graphname}.groups[].code String Conditional The field code of the field used to determine the "Group by" option.

Required when specifying the reports.{graphname}.groups parameter.
reports.{graphname}.groups[].per String Conditional The time unit used for the "Group by" option.
  • YEAR: by the year
  • QUARTER: by the quarter
  • MONTH: by the month
  • WEEK: by the week
  • DAY: by the day
  • HOUR: by the hour
  • MINUTE: by the minute
The following time units ​​can be specified for each field type set to reports.{graphname}.groups[].code:
  • Created datetime: All values
  • Updated datetime: All values
  • Date and time: All values
  • Date: YEAR, QUARTER, MONTH, WEEK, or DAY
  • Time: HOUR or MINUTE
Required if one of the fields above is specified in reports.{graphname}.groups[].code.
reports.{graphname}.aggregations Array Conditional An array of objects containing the "Function" options.
The maximum limit is 10 elements in the array.

If the reports.{graphname}.chartType parameter is set to PIVOT_TABLE, only 1 element can be set in the array.

Required when adding a new graph.
reports.{graphname}.aggregations[].type String Conditional The type of the "Function" option.
  • COUNT: number of records
  • SUM: Total
  • AVERAGE: Average
  • MAX: Maximum
  • MIN: Minimum
Required when specifying the reports.{graphname}.aggregations parameter.
reports.{graphname}.aggregations[].code String Conditional The field code of the field to be used in the "Function" option.

Elements with type set to SUM or AVERAGE can specify the following fields:
  • Number fields
  • Calculated fields (Number)
  • Calculated fields (Number with thousands separator)
  • Calculated fields (Hours & minutes) within tables
  • Calculated fields (Days & hours & minutes) within tables
  • Lookup fields with the Key Field set as a Number field
Elements with type set to MAX or MIN can specify the following fields:
  • Number field
  • Calculated fields (Number)
  • Calculated fields (Number with thousands separator)
  • Calculated fields (Date & time) within tables
  • Calculated fields (Date) within tables
  • Calculated fields (Time) within tables
  • Calculated fields (Hours & minutes) within tables
  • Calculated fields (Days & hours & minutes) within tables
  • Date fields within tables
  • Date and time fields within tables
  • Time fields within tables
  • Created datetime fields within tables
  • Updated datetime fields within tables
  • Lookup fields with the Key Field set as a Number field
Required for each element of the reports.{graphname}.aggregations parameter, except for elements with type set to COUNT.
reports.{graphname}.filterCond String The record's filter condition in query string format that reflects the "Filter" option.
For more information, refer to the Sample Requests (Query String) section.

If this parameter is ignored for a new graph, it is the same as when "All records" is specified.

If this parameter is ignored for an existing graph, the filter setting will not be changed.

The request will fail if a deleted User, Group, or Organization is specified in the filter condition.
reports.{graphname}.sorts Array Conditional An array of objects containing the "Sort by" options.
The maximum limit is 3 elements in the array.

Required when adding a new graph.
reports.{graphname}.sorts[].by String Conditional How the graph is sorted.
  • TOTAL: Total
  • GROUP1: Level 1
  • GROUP2: Level 2
  • GROUP3: Level 3
Required when specifying the reports.{graphname}.sorts parameter.
reports.{graphname}.sorts[].order String Conditional The order of sorting.
  • ASC: Ascending order
  • DESC: Descending order
Required when specifying the reports.{graphname}.sorts parameter.
reports.{graphname}.periodicReport Object An object containing the "Periodic Reports" options.

If the "Periodic Reports" option is active, no graph settings can be updated except for the following:
  • reports.{graphname}.name
  • reports.{graphname}.index
  • reports.{graphname}.periodicReport.active
If this parameter is ignored, no changes will be made to the "Periodic Reports" options.
reports.{graphname}.periodicReport.active Boolean or String The activation status of the "Periodic Reports" option.
  • true: Active
  • false: Inactive
If this parameter is ignored when creating a new Periodic Report, this value is set to true.

If this parameter is ignored when updating an existing Periodic Report, this value is not updated.
reports.{graphname}.periodicReport.period Object Conditional An object containing the "Period" options.

When updating the Periodic Report, either ignore this parameter or keep the parameters the same. Otherwise, an error will be returned.

Required when adding a new graph.
reports.{graphname}.periodicReport.period.every String Conditional The time interval type used to determine when to generate the Periodic Reports.
  • YEAR: by the year
  • QUARTER: by the quarter
  • MONTH: by the month
  • WEEK: by the week
  • DAY: by the day
  • HOUR: by the hour
Required when specifying the reports.{graphname}.periodicReport.period parameter.
reports.{graphname}.periodicReport.period.month Integer or String Conditional The month when the Periodic Report will be generated.
Specify the month as an integer, ranging from 1 (January) to 12 (December).

Required when the reports.{graphname}.periodicReport.period.every parameter is set to YEAR.
reports.{graphname}.periodicReport.period.time String Conditional The time when the Periodic Report will be generated.
Input the time in HH:MM format.

Required when the reports.{graphname}.periodicReport.period.every parameter is set to YEAR, QUARTER, MONTH, WEEK, or DAY.
reports.{graphname}.periodicReport.period.pattern String Conditional The months when the quarterly Periodic Report will be generated.
  • JAN_APR_JUL_OCT: January, April, July, October
  • FEB_MAY_AUG_NOV: February, May, August, November
  • MAR_JUN_SEP_DEC: March, June, September, December
Required when the reports.{graphname}.periodicReport.period.every parameter is set to QUARTER.
reports.{graphname}.periodicReport.period.dayOfMonth String Conditional The day when the Periodic Report will be generated.
  • Integers from 1 to 31: The specific day of the month
  • END_OF_MONTH: The last day of the month*
*Only if reports.{graphname}.periodicReport.period.every parameter is set to QUARTER or MONTH.

Required when the reports.{graphname}.periodicReport.period.every parameter is set to YEAR, QUARTER, or MONTH.
reports.{graphname}.periodicReport.period.dayOfWeek String Conditional The day of the week when the Periodic Report will be generated.
  • SUNDAY
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
Required when the reports.{graphname}.periodicReport.period.every parameter is set to WEEK.
reports.{graphname}.periodicReport.period.minute Integer or String Conditional The minute when the hourly Periodic Report will be generated.
Set as "0", "10", "20", "30", "40" or "50".

Required when the reports.{graphname}.periodicReport.period.every parameter is set to HOUR.
revision Integer or String Specify the revision number of the settings that will be deployed.
The request will fail if the revision number is not the latest revision.
The revision will not be checked if this parameter is ignored or -1 is specified.

Sample Request

JavaScript (using Kintone REST API Request)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
var body = {
  'app': kintone.app.getId(),
  'reports': {
    'Graph1 (Default Settings)': {
      'chartType': 'BAR',
      'chartMode': 'NORMAL',
      'name': 'Graph1 (Default Settings)',
      'index': '0',
      'groups': [{
        'code': 'Created_by'
      }],
      'aggregations': [{
        'type': 'COUNT'
      }],
      'filterCond': '',
      'sorts': [{
        'by': 'TOTAL',
        'order': 'DESC'
      }],
      'periodicReport': null
    },
    'Graph2 (Table)': {
      'chartType': 'TABLE',
      'name': 'Graph2 (Table)',
      'index': '1',
      'groups': [{
        'code': 'Radio_button'
      },
      {
        'code': 'Created_datetime',
        'per': 'YEAR'
      },
      {
        'code': 'Time',
        'per': 'MINUTE'
      }
      ],
      'aggregations': [{
        'type': 'COUNT'
      },
      {
        'type': 'SUM',
        'code': 'Number'
      },
      {
        'type': 'AVERAGE',
        'code': 'Calculated'
      },
      {
        'type': 'MAX',
        'code': 'Created_datetime'
      },
      {
        'type': 'MIN',
        'code': 'Time'
      }
      ],
      'filterCond': 'Record_number = \'1\' and Rich_text like \'aaa\'',
      'sorts': [{
        'by': 'TOTAL',
        'order': 'DESC'
      },
      {
        'by': 'GROUP1',
        'order': 'ASC'
      },
      {
        'by': 'GROUP2',
        'order': 'DESC'
      }
      ],
      'periodicReport': null
    },
    'Graph3 (Periodic report ON)': {
      'chartType': 'BAR',
      'chartMode': 'NORMAL',
      'name': 'Graph3 (Periodic report ON)',
      'index': '2',
      'groups': [{
        'code': 'Radio_button'
      }],
      'aggregations': [{
        'type': 'COUNT'
      }],
      'filterCond': '',
      'sorts': [{
        'by': 'TOTAL',
        'order': 'DESC'
      }],
      'periodicReport': {
        'active': true,
        'period': {
          'every': 'QUARTER',
          'pattern': 'JAN_APR_JUL_OCT',
          'dayOfMonth': 'END_OF_MONTH',
          'time': '23:30'
        }
      }
    }
  },
  'revision': '2'
};

kintone.api(kintone.api.url('/k/v1/preview/app/reports.json', true), 'PUT', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

XMLHttpRequest

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
var body = {
  'app': kintone.app.getId(),
  'reports': {
    'Graph1 (Default Settings)': {
      'chartType': 'BAR',
      'chartMode': 'NORMAL',
      'name': 'Graph1 (Default Settings)',
      'index': '0',
      'groups': [{
        'code': 'Created_by'
      }],
      'aggregations': [{
        'type': 'COUNT'
      }],
      'filterCond': '',
      'sorts': [{
        'by': 'TOTAL',
        'order': 'DESC'
      }],
      'periodicReport': null
    },
    'Graph2 (Table)': {
      'chartType': 'TABLE',
      'name': 'Graph2 (Table)',
      'index': '1',
      'groups': [{
        'code': 'Radio_button'
      },
      {
        'code': 'Created_datetime',
        'per': 'YEAR'
      },
      {
        'code': 'Time',
        'per': 'MINUTE'
      }
      ],
      'aggregations': [{
        'type': 'COUNT'
      },
      {
        'type': 'SUM',
        'code': 'Number'
      },
      {
        'type': 'AVERAGE',
        'code': 'Calculated'
      },
      {
        'type': 'MAX',
        'code': 'Created_datetime'
      },
      {
        'type': 'MIN',
        'code': 'Time'
      }
      ],
      'filterCond': 'Record_number = \'1\' and Rich_text like \'aaa\'',
      'sorts': [{
        'by': 'TOTAL',
        'order': 'DESC'
      },
      {
        'by': 'GROUP1',
        'order': 'ASC'
      },
      {
        'by': 'GROUP2',
        'order': 'DESC'
      }
      ],
      'periodicReport': null
    },
    'Graph3 (Periodic report ON)': {
      'chartType': 'BAR',
      'chartMode': 'NORMAL',
      'name': 'Graph3 (Periodic report ON)',
      'index': '2',
      'groups': [{
        'code': 'Radio_button'
      }],
      'aggregations': [{
        'type': 'COUNT'
      }],
      'filterCond': '',
      'sorts': [{
        'by': 'TOTAL',
        'order': 'DESC'
      }],
      'periodicReport': {
        'active': true,
        'period': {
          'every': 'QUARTER',
          'pattern': 'JAN_APR_JUL_OCT',
          'dayOfMonth': 'END_OF_MONTH',
          'time': '23:30'
        }
      }
    }
  },
  'revision': '2',
  // CSRF TOKEN: used for all APIs that have an HTTP method of POST, PUT, and DELETE on Kintone.
  '__REQUEST_TOKEN__': kintone.getRequestToken()
};

var url = 'https://{subdomain}.kintone.com/k/v1/preview/app/reports.json';
var xhr = new XMLHttpRequest();
xhr.open('PUT', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send(JSON.stringify(body));

Response Parameters

Parameter Type Description
revision String The revision number of the App settings.
reports Object An object listing Graph information.
reports.{graphname}.id String The ID of the graph.

Sample Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "revision": "2",
  "reports": {
    "Graph1 (Default Settings)": {
      "id": "7319"
    },
    "Graph2 (Table)": {
      "id": "7321"
    },
    "Graph3 (Periodic report ON)": {
      "id": "7323"
    }
  }
}

Limitations

If multiple graphs have (or will result in having) the same name within the same App, this API will return an error.