Record Create Events

Onload Event (desktop) - app.record.create.show

An event triggered after the record create page is displayed on the desktop.

Function

app.record.create.show

Triggered Timing

• After the record create page is displayed, i.e. when there is an /edit in the URL of the page. This can be displayed in the following ways:
  • by clicking the New record icon (the plus icon) on either the record list page or record details page.
  • by clicking the Duplicate icon (the paper icon) on the record details page.

Properties of the Event Object

Available Event Object Actions

• Overwrite field values
• Enable/Disable field edits
• Show field errors
• Show record errors
• Run Lookup fields
• Clear copied Lookup field values
• By returning a kintone.Promise object in the event handler, event object actions can be processed after waiting for asynchronous processes in the event handler to finish.

Onload Event (mobile) - mobile.app.record.create.show

An event triggered after the record create page is displayed on the mobile.

Function

mobile.app.record.create.show

Triggered Timing

• After the record create page is displayed on the mobile. This can be displayed in the following ways:
  • by clicking the "New" icon (the plus icon) on the record list page.
  • by clicking the "Duplicate" icon (the paper icon) on the record details page.

Properties of the Event Object

Available Event Object Actions

• Overwrite field values
• Enable/Disable field edits
• Show field errors
• Show record errors
• Run Lookup fields
• Clear copied Lookup field values
• By returning a kintone.Promise object in the event handler, event object actions can be processed after waiting for asynchronous processes in the event handler to finish.

Save Submit Event - app.record.create.submit

An event triggered when the save button is clicked on the record create page.
This event does not hold the Record ID in the event object - use the Save Submit Success Event instead to obtain the Record ID of the created record.

Function

Desktop

app.record.create.submit

Mobile

mobile.app.record.create.submit

Properties of the Event Object

Available Event Object Actions

• Overwrite field values
• Show field errors
• Show record errors

Running actions after waiting for asynchronous operations to finish

By returning a kintone.Promise object, you can run actions after waiting for asynchronous operations to finish. If an error occurs and the Thenable object is rejected, the event will be cancelled.

Sample Request using the kintone.Promise object returned by the kintone.api()

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

kintone.events.on('app.record.create.submit', function(event) {
  var record = event.record;
  var companyName = record.company_name.value || '';
  var masterAppId = 21; // App ID of a different app
  var query = 'company_name="' + companyName + '"';
  var params = {app: masterAppId, query: query};

  return kintone.api('/k/v1/records', 'GET', params).then(function(resp) {
    // Check that the company name exists in the master app
    if (!resp.records.length) { // Set an error message on the field
      record.company_name.error = 'Company name does not exist.';
    } else { // The record will save when the alert window closes
      alert('Found company');
    }
    return event;
  }, function(resp) { // Dealing with errors received by the system
    var errmsg = 'There was an error when retrieving the data.';
    if (resp.message) {
      errmsg += '\n' + resp.message;
    }
    alert(errmsg);
  });
});

Sample Request using the kintone.Promise Constructor

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

kintone.events.on('app.record.create.submit', function(event) {
  var record = event.record;
  var companyName = record.company_name.value;
  var masterAppId = 21; // App ID of a different app
  var query = 'company_name="' + companyName + '"';
  return new kintone.Promise(function(resolve, reject) {
    var params = {app: masterAppId, query: query};
    kintone.api('/k/v1/records', 'GET', params, function(resp) {
      resolve(resp);
    });
  }).then(function(resp) {
    if (!resp.records.length) {
      record.company_name.error = 'Company name does not exist.';
    }
    return event;
  });
});

Limitations

Refer to the Limitations section of the Event Handling page.

Save Submit Success Event - app.record.create.submit.success

An event triggered after the record has been successfully saved after clicking the save button on the record create page or the record duplicate page.
This event holds the Record ID of the created record in the Event Object.

Function

Desktop

app.record.create.submit.success

Mobile

mobile.app.record.create.submit.success

Properties of the Event Object

Available Event Object Actions

None

Sample showing the record ID saved

1
2
3
4
5

// Display the record ID published after saving.
kintone.events.on('app.record.create.submit.success', function(ev) {
  var record = ev.record;
  alert('The record ID is ' + record.$id.value + '.');
});

Sample showing a redirect to a user specified URL after saving

If a redirect URL is specified, the event handler will redirect the page to the specified URL after returning the event object. If null, or no value is specified, the page will not redirect.

1
2
3
4
5

// Redirect the user's web browser to the specified URL after saving
kintone.events.on('app.record.create.submit.success', (event) => {
  event.url = 'http://kintone.dev';
  return event;
});

Notes

• This event cannot be used with an app embedded on a space.
• The event will not trigger if the record does not successfully save.

Field Change Event - app.record.create.change.(fieldcode)

An event triggered when a specified field value changes when creating a new record.

Function

Desktop

app.record.create.change.(fieldcode)

Mobile

mobile.app.record.create.change.(fieldcode)

Fields that can be Specified

• Radio button
• Drop-down
• Check box
• Multi-choice
• User selection
• Date
• Time
• Date and time
• Single-line text
• Number
• Table

Make sure to specify the field codes of these fields. Nothing will happen if the field code does not exist, or a field that is not in the above list is specified.

*The timing of the event for the Single-line text and Number field are as below:

• when the focus leaves the field.
• when the Lookup field mappings have been run.
• after calculations have been applied to a Single-line text field that has the Calculate automatically option turned on.

*The timing of the event for the Table is as below:

• when a new row is added to the table
• when a row is deleted from the table

Properties of the Event Object

Notes

The change in value of the trigger field cannot be cancelled.

Available Event Object Actions

• Enable/Disable field edits
• Show field errors
• Show record errors
• Run Lookup fields
• Clear copied Lookup field values
• Get the object of the edited field or table row

Limitations

Refer to the Limitations section of the Event Handling page.

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.

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.

Sample

When adding a new record, overwrite the field "text_0" with a specified string, overwrite the first line of the table "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 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.

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.

• Calculated
• The Field Mappings targets of the Lookup field
• Attachment

Notes

• If an empty string is specified for the Radio button field, the default value of the field will be inputted.
• Values of the fields can be overwritten, even if the editing of the field has been disabled.
• If you do not have permission to add values to a particular field, the field change written in the script will not take effect for that field.
• If the handler does not return the event object, the fields will not be updated.
• If there are several handlers, the returned values from the last handler will take effect.

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.
Nothing will happen if this is applied to a field where you have no editing permissions.

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.

• Calculated
• The Field Mappings targets of the Lookup field

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 overwriting of field values and the enabling/disabling of field edits 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 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 overwriting of field values and the enabling/disabling of field edits are canceled.

Sample

Show an error message for the record when changing a drop down field during a 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 true is entered into the lookup property, the Lookup field runs when the event is returned.

Sample

When adding a new 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.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.

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;
});