API Docs

Event Object Actions

Contents

Event Object Actions

It is possible to perform actions such as disabling a field or displaying an error on a field by changing the properties of the event object and returning it. This section explains the available actions.

Record List Events

Onload Event Inline Edit Event Field Change Event Save Event Save Success Event Delete Event
Overwrite field values no no yes yes no no
Enable/Disable field edits no yes yes no no no
Show field errors no no yes yes no no
Show record errors no no yes yes no yes
Set a Redirect URL no no no no yes no
Use Promises yes yes no yes no yes

Overwrite Field Values

If the event handler overwrites values in the fields of the record object and returns the event object, the record is saved with those values in the object.

  • Record edit permission is required to change a value.
  • Even when the field is set to be disabled for editing, the value can still be overwritten:
    Enable/Disable field edits
  • If multiple handlers of the same event type are registered, the value returned by the last handler will be used. If the last handler does not return an event object, the field value will not be changed.
Sample

When saving an inline edit of a record, overwrite the field text_0 and text_in_table_0 with a specified string. text_in_table_0 is a field that lies within a table with field code of table_0.

1
2
3
4
5
6

kintone.events.on('app.record.index.edit.submit', function(event) {
  var record = event.record;
  record.text_0.value = 'Overwrite with this string';
  record.table_0.value[0].value.text_in_table_0.value = 'Overwrite first record in table';
  return event;
});
Fields that cannot be overwritten

Even if the below fields are overwritten in the handler and returned, they will not take effect on the record itself

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated
  • Text Fields with the "Calculate automatically" option
  • Attachment
  • Lookup
  • The Field Mappings targets of the Lookup field

Enable/Disable Field Edits

If the event handler inputs true/false in the disabled of a field of the record object and returns the event object, editing of those fields will become enabled/disabled.

Sample

Disable the editing of the text_0 field when a value is selected in the drop down field dropdown_0, during an inline edit of a record.

1
2
3
4
5

kintone.events.on('app.record.index.edit.change.dropdown_0', function(event) {
  var record = event.record;
  record.text_0.disabled = true;
  return event;
});
Fields where editing cannot be enabled/disabled

Even if the below fields are returned with the disabled as true/false, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated
  • Text Fields with the "Calculate automatically" option

Show Field Errors

If the event handler inputs an error message in the error of a field of the record object and returns the event object, an error message is displayed for the corresponding field.
In this case, the following are canceled:

To remove error messages from fields, input null into the error of the field, and return the event object.

Sample

Show an error message for the fields text_0 and dropdown_0 when saving an inline edit for a record.

1
2
3
4
5
6

kintone.events.on('app.record.index.edit.submit', function(event) {
  var record = event.record;
  record.text_0.error = 'This is an error message';
  record.dropdown_0.error = 'This is also an error';
  return event;
});
Fields that don't show error messages

Even if the below fields have error messages inputted by the handler and the object is returned, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated

Show Record Errors

If the event handler inputs an error message in the error of the event object and returns the event object, an error message is displayed for the record.
In this case, the following are canceled:

Sample

Show an error message for the record when changing a drop-down field during an inline edit of a record.

1
2
3
4

kintone.events.on('app.record.index.edit.change.dropdown_0', function(event) {
  event.error = 'This is an Error Message!';
  return event;
});

Set a Redirect URL

If a redirect URL is specified, the event handler will redirect the page to the specified URL after returning the event object.

If null is specified, the page will not redirect.

Sample

Redirect the user's web browser to "https://kintone.dev" after the record is saved.

1
2
3
4

kintone.events.on('app.record.index.edit.submit.success', (event) => {
  event.url = 'https://kintone.dev';
  return event;
});

Action Limitations

These actions are only available on the Desktop, and not on the mobile.

Record Details Event

Onload Event Delete Event Update Status Event
Overwrite field values no no yes
Show field errors no yes yes
Use Promises yes yes yes

Overwrite Field Values

If the event handler overwrites values in the fields of the record object and returns the event object, the fields of the record are updated with those values in the object.

  • Record edit permission is required to change a value.
  • If an empty string is specified for the Radio button field, the default value of the field will be inputted.
  • If multiple handlers of the same event type are registered, the value returned by the last handler will be used. If the last handler does not return an event object, the field value will not be changed.
Sample

When the process has progressed, overwrite the field text_0 with a specified string, overwrite the first line of the table, and add values into text_in_table and number_in_table that are inside a table, as a new line.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

kintone.events.on('app.record.detail.process.proceed', function(event) {
  var record = event.record;
  record.text_0.value = 'Overwrite with this value';
  record.Table.value[0].value.text_in_table.value = 'Overwrite first line of the table';

  // Add a row to the end of a Table field
  var newRow = {
    value: {
      text_in_table: {
        type: 'SINGLE_LINE_TEXT',
        value: 'New value for new row'
      },
      number_in_table: {
        type: 'NUMBER',
        value: '777'
      }
    }
  };
  record.Table.value.push(newRow);
  return event;
});

Note that when adding a new row to the table, all fields in the table must be specified, and the type of each field must also be specified.

Fields that cannot be overwritten

Even if the below fields are overwritten in the handler and returned, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated
  • Text Fields with the "Calculate automatically" option
  • Attachment
  • Lookup
  • The Field Mappings targets of the Lookup field

Show Field Errors

A field error message is displayed, if the even handler inputs a message in the error property of a field in the record object, and the object is returned. In this case, the following is canceled:

To remove error messages from fields, input null into the error of the field, and return the event object.

Record Create Events

Onload Event Field Change Event Save Event Save Success Event
Overwrite field values yes yes yes no
Enable/Disable field edits yes yes no no
Show field errors yes yes yes no
Show record errors yes yes yes no
Run Lookup fields yes yes no no
Clear copied Lookup field values yes yes no no
Get the object of the edited field or table row no yes no no
Set a Redirect URL no no no yes
Use Promises yes no yes yes

Overwrite Field Values

If the event handler overwrites values in the fields of the record object and returns the event object, the fields of the record are updated with those values in the object.

  • Record edit permission is required to change a value.
  • Even when the field is set to be disabled for editing, the value can still be overwritten:
    Enable/Disable field edits
  • If multiple handlers of the same event type are registered, the value returned by the last handler will be used. If the last handler does not return an event object, the field value will not be changed.
  • If an empty string is specified for the Radio button field, the default value of the field will be inputted.
Sample

When adding a new record, overwrite the field text_0 with a specified string, overwrite the first line of the table, and add values into text_in_table and number_in_table that are inside a table, as a new line.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

kintone.events.on('app.record.create.show', function(event) {
  var record = event.record;
  record.text_0.value = 'Overwrite with this value';
  record.Table.value[0].value.text_in_table.value = 'Overwrite first line of the table';

  // Add a row to the end of a sub-table
  var newRow = {
    value: {
      text_in_table: {
        type: 'SINGLE_LINE_TEXT',
        value: 'New value for new row'
      },
      number_in_table: {
        type: 'NUMBER',
        value: '777'
      }
    }
  };
  record.Table.value.push(newRow);
  return event;
});

Note that when adding a new row to the table, all fields in the table must be specified, and the type of each field must also be specified.

Fields that cannot be overwritten

Even if the below fields are overwritten in the handler and returned, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated
  • Text Fields with the "Calculate automatically" option
  • Attachment
  • Lookup
  • The Field Mappings targets of the Lookup field

Enable/Disable Field Edits

If the event handler inputs true/false in the disabled of a field of the record object and returns the event object, editing of those fields will become enabled/disabled.

Sample

When adding a new record, disable the editing of the text_0 field when a value is selected in the drop down field dropdown_0.

1
2
3
4
5

kintone.events.on('app.record.create.change.dropdown_0', function(event) {
  var record = event.record;
  record.text_0.disabled = true;
  return event;
});

Fields where editing cannot be enabled/disabled

Even if the below fields are returned with the disabled as true/false, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated
  • Text Fields with the "Calculate automatically" option

Show Field Errors

If the event handler inputs an error message in the error of a field of the record object and returns the event object, an error message is displayed for the corresponding field.
In this case, the following are canceled:

To remove error messages from fields, input null into the error of the field, and return the event object.

Sample

Show an error message for the fields text_0 and dropdown_0 when changing the value of a drop down field.

1
2
3
4
5
6

kintone.events.on('app.record.create.change.dropdown_0', function(event) {
  var record = event.record;
  record.text_0.error = 'This is an error';
  record.Table.value[0].value.text_in_table.error = 'This is another error';
  return event;
});

Fields that don't show error messages

Even if the below fields have error messages inputted by the handler and the object are returned, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated

Show Record Errors

If the event handler inputs an error message in the error of the event object and returns the event object, an error message is displayed for the record.
In this case, the following are canceled:

This is available for both desktop and mobile.

Sample

Show an error message for the record when changing a drop down field during the creation of a new record.

1
2
3
4

kintone.events.on('app.record.create.change.dropdown_0', function(event) {
  event.error = 'Your error message here!';
  return event;
});

Run Lookup Fields

If UPDATE or true is entered into the lookup property, the Lookup field runs when the event is returned.

  • The Lookup field can only run if there is only one lookup result.
  • This is available for both desktop and mobile.
Sample

When adding a new record, the lookup value is set into the Lookup field, and the value is looked up. Any field mappings that were set in the Lookup field settings also take place.

1
2
3
4
5
6

kintone.events.on('app.record.create.show', function(event) {
  var record = event.record;
  record.lookup_0.value = '0001'; // The Lookup field value
  record.lookup_0.lookup = true;
  return event;
});

Clear Copied Lookup Field Values

If CLEAR is entered into the lookup property of the Lookup field, the values copied from the source App due to the Lookup field settings are cleared when the event is returned.

Sample

When editing a record, the values copied from the source App due to the Lookup field settings are cleared.

1
2
3
4
5

kintone.events.on('app.record.edit.show', function(event) {
  var record = event.record;
  record.lookup_0.lookup = 'CLEAR';
  return event;
});

Get the Object of the Edited Field or Table Row

An object containing data of an edited field and edited table row is retrieved.

  • The row property can only be retrieved when an event occurs within the table.
  • When a row is deleted from the table, the row property becomes null.
Sample

Retrieve the object data of the field dropdown_0 that exists inside a table, and the object data of the table row of the changed dropdown_0 field, when the value of dropdown_0 changes while creating a new record.

1
2
3
4

kintone.events.on('app.record.create.change.dropdown_0', function(event) {
  var row = event.changes.row;
  var field = event.changes.field;
});

Set a Redirect URL

If a redirect URL is specified, the event handler will redirect the page to the specified URL after returning the event object.

If null is specified, the page will not redirect.

Sample

Redirect the user's web browser to "https://kintone.dev" after the record is saved.

1
2
3
4

kintone.events.on('app.record.create.submit.success', (event) => {
  event.url = 'https://kintone.dev';
  return event;
});

Notes on Non-numeric Values in the Number Field

  • #INVALID will be returned in event objects if non-numeric values are set in Number fields
  • Setting the value with an invalid value using Event Objects or JavaScript API will result in an error.
  • If the value is set to #INVALID!, the value will not change.
  • In the mobile view, if whitespaces are entered before or after a value, they will be sanitized.
  • When whitespaces are sanitized, as long as the final value does not change, events will not be triggered.

Record Edit Events

Onload Event Field Change Event Save Event Save Success Event
Overwrite field values yes yes yes no
Enable/Disable field edits yes yes no no
Show field errors yes yes yes no
Show record errors yes yes yes no
Run Lookup fields yes yes no no
Clear copied Lookup field values yes yes no no
Get the object of the edited field or table row no yes no no
Set a Redirect URL no no no yes
Use Promises yes no yes yes

Overwrite Field Values

If the event handler overwrites values in the fields of the record object and returns the event object, the fields of the record are updated with those values in the object.

  • Record edit permission is required to change a value.
  • Even when the field is set to be disabled for editing, the value can still be overwritten:
    Enable/Disable field edits
  • If multiple handlers of the same event type are registered, the value returned by the last handler will be used. If the last handler does not return an event object, the field value will not be changed.
  • If an empty string is specified for the Radio button field, the default value of the field will be inputted.
Sample

After opening the record edit page, overwrite the field text_0 with a specified string, overwrite the first line of the table, and add values into text_in_table and number_in_table that are inside a table, as a new line.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

kintone.events.on('app.record.edit.show', function(event) {
  var record = event.record;
  record.text_0.value = 'Overwrite with this value';
  record.Table.value[0].value.text_in_table.value = 'Overwrite first line of the table';

  // Add a row to the end of a subtable
  var newRow = {
    value: {
      text_in_table: {
        type: 'SINGLE_LINE_TEXT',
        value: 'New value for new row'
      },
      number_in_table: {
        type: 'NUMBER',
        value: '777'
      }
    }
  };
  record.Table.value.push(newRow);
  return event;
});

Note that when adding a new row to the table, all fields in the table must be specified, and the type of each field must also be specified.
Also, if the first line of the table does not exist when you start editing, the code will not be able to find the first line, and will stop the script.

Fields that cannot be overwritten

Even if the below fields are overwritten in the handler and returned, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated
  • Text Fields with the "Calculate automatically" option
  • Attachment
  • Lookup
  • The Field Mappings targets of the Lookup field

Enable/Disable Field Edits

If the event handler inputs true/false in the disabled of a field of the record object and returns the event object, editing of those fields will become enabled/disabled.

Sample

When editing a record, disable the editing of the text_0 field when a value is selected in the drop down field dropdown_0.

1
2
3
4
5
6
7

(function() {
  kintone.events.on('app.record.edit.change.dropdown_0', function(event) {
    var record = event.record;
    record.text_0.disabled = true;
    return event;
  });
})();

Fields where editing cannot be enabled/disabled

Even if the below fields are returned with the disabled as true/false, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated
  • Text Fields with the "Calculate automatically" option

Show Field Errors

If the event handler inputs an error message in the error of a field of the record object and returns the event object, an error message is displayed for the corresponding field.
In this case, the following are canceled:

To remove error messages from fields, input null into the error of the field, and return the event object.

Sample

Show an error message for the fields text_0 and dropdown_0 when changing the value of a drop down field.

1
2
3
4
5
6

kintone.events.on('app.record.edit.change.dropdown_0', function(event) {
  var record = event.record;
  record.text_0.error = 'This is an error';
  record.Table.value[0].value.text_in_table.error = 'This is another error';
  return event;
});

Fields that don't show error messages

Even if the below fields have error messages inputted by the handler and the object is returned, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee
  • Calculated

Show Record Errors

If the event handler inputs an error message in the error of the event object and returns the event object, an error message is displayed for the record.
In this case, the following are canceled:

This is available for both desktop and mobile.

Sample

Show an error message for the record when changing a drop down field during an edit of a record.

1
2
3
4

kintone.events.on('app.record.edit.change.dropdown_0', function(event) {
  event.error = 'Your have selected the wrong option!';
  return event;
});

Run Lookup Fields

If UPDATE or true is entered into the lookup property of the Lookup field, the Lookup field runs when the event is returned.

  • The Lookup field can only run if there is only one lookup result.
  • This is available for both desktop and mobile.
Sample

When editing a record, the lookup a value is set into the Lookup field, and the value is looked up. Any field mappings that were set in the Lookup field settings also take place.

1
2
3
4
5
6

kintone.events.on('app.record.edit.show', function(event) {
  var record = event.record;
  record.lookup_0.value = '0015'; // The Lookup field value
  record.lookup_0.lookup = true; // or record.'lookup_0'.'lookup' = 'UPDATE';
  return event;
});

Clear Copied Lookup Field Values

If CLEAR is entered into the lookup property of the Lookup field, the values copied from the source App due to the Lookup field settings are cleared when the event is returned.

  • This is available for both desktop and mobile.
Sample

When editing a record, the values copied from the source App due to the Lookup field settings are cleared.

1
2
3
4
5

kintone.events.on('app.record.edit.show', function(event) {
  var record = event.record;
  record.lookup_0.lookup = 'CLEAR';
  return event;
});

Get the Object of the Edited Field or Table Row

An object containing data of an edited field and edited table row is retrieved.

  • The row property can only be retrieved when an event occurs within the table.
  • When a row is deleted from the table, the row property becomes null.
Sample

Retrieve the object data of the field dropdown_0 that exists inside a table, and the object data of the table row of the changed dropdown_0 field, when the value of dropdown_0 changes while editing a record.

1
2
3
4

kintone.events.on('app.record.edit.change.dropdown_0', function(event) {
  var row = event.changes.row;
  var field = event.changes.field;
});

Set a Redirect URL

If a redirect URL is specified, the event handler will redirect the page to the specified URL after returning the event object.

If null is specified, the page will not redirect.

Sample

Redirect the user's web browser to "https://kintone.dev" after the record is saved.

1
2
3
4

kintone.events.on('app.record.edit.submit.success', (event) => {
  event.url = 'https://kintone.dev';
  return event;
});

Notes on Non-numeric Values in the Number Field

  • #INVALID will be returned in event objects if non-numeric values are set in Number fields
  • Setting the value with invalid values using Event Objects or JavaScript API will result in errors.
  • If the value is set to #INVALID!, the value will not change.
  • In the mobile view, if whitespaces are entered before or after a value, they will be sanitized.
  • When whitespaces are sanitized, as long as the final value does not change, events will not be triggered.

Notes

Number Fields

The following non-numeric values can be used when updating the value in the Number fields:

  • undefined, null: The value in the Number field will become empty.
  • #INVALID!: The value in the Number field will not be changed.

Other non-numeric values are treated as invalid values in the Number field.

Use Promises

By returning the Web browser Promise, the next operations can be processed after waiting for asynchronous processes. When multiple event handlers are registered for the same Kintone event, if an error occurs and the Thenable object is rejected, subsequent event handlers will be canceled.