Update Graph Settings

Updates the Graph 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.
Method PUT
URL https://{subdomain}.kintone.com/k/v1/preview/app/reports.json
URL(guest space) https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/app/reports.json
Authentication API Token Authentication , Password Authentication
Content-Type application/json

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 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 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 creating a new graph, the request will fail if the value of this parameter is not the same as reports.{graphname}.

Required when creating 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 creating 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 creating 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 creating 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 creating 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)

XMLHttpRequest

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

Was this article helpful?
0 out of 0 found this helpful
Do you have any questions or issues related to this article?
Please share your views with us in the Community forums!