Status Timestamp Plug-in

Contents

Introduction

This article introduces the Status Timestamp Plug-in. This plug-in inserts the date (and time) that a record reached a specified Status into a Date or Datetime field.

Plug-in file

The packaged sample plug-in zip file can be downloaded from the Releases page (External link) on GitHub.
Install the plug-in into your domain by following the plug-in installation guide on the Help page (External link) .
You can then add the plug-in to a specific App by following the plug-in adding guide on the Help page (External link) .

Overview

To set up the plug-in, the Kintone App must first have a Date field or Datetime field in its form.

The first setting on the settings page specifies which Date or Datetime field to display the timestamp in. The second setting specifies which Status to display the timestamp of.

If the Status to display the timestamp of is set to Approved, the Date or Datetime field will fill with the current Date or Datetime when the status becomes Approved.

File structure

The sample codes used in the plug-in are listed under the src file in our Github repository (External link) .
The plug-in is created with the following file structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

plug-in/
├── html/
│       └──── config.html
├── css/
│       ├──── 51-modern-default.css
│       └──── config.css
├── js/
│       ├──── config.js
│       ├──── desktop.js
│       └──── kintone-config-helper.js
├── image/
│       └──── clock.png
└── manifest.json

config.html (External link)

This file builds the HTML of the plug-in settings page. Each "kintoneplugin-row" div represents 1 row of related HTML elements.

The first "kintoneplugin-row" div contains the HTML of the first settings, where the user chooses which Date or Datetime field to hold the current date or datetime. A select tag is stated, that creates a drop-down field with a value of "-----". This drop-down field is later populated by the config.js file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<div class="kintoneplugin-row">
  <label for="select-date-field" class="kintoneplugin-label">Date or Datetime Field
    <span class="kintoneplugin-require">*</span>
  </label>
  <p class="kintoneplugin-desc">Select a Date or Datetime field to show the timestamp in.</p>
  <div class="kintoneplugin-select-outer">
    <div class="kintoneplugin-select">
      <select name="js-select-date-field" id="select-date-field" required>
        <option value="">-----</option>
      </select>
    </div>
  </div>
</div>

The second "kintoneplugin-row" div contains the HTML of the second settings, where the user chooses the Status to record the date or datetime of when reached. Again, a select tag is stated, that creates a drop-down field with a value of "-----". This drop-down field is later populated by the config.js file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<div class="kintoneplugin-row">
  <label for="select-status" class="kintoneplugin-label">Status
    <span class="kintoneplugin-require">*</span>
  </label>
  <p class="kintoneplugin-desc">Select a status to record the timestamp of.</p>
  <div class="kintoneplugin-select-outer">
    <div class="kintoneplugin-select">
      <select name="js-select-status" id="select-status" required>
        <option value="">-----</option>
      </select>
    </div>
  </div>
</div>

The Date or Datetime field select element and the Status select element have ids allocated to them, so that they can be controlled by the config.js file.

51-modern-default.css (External link)

The CSS file provided on GitHub (External link) . This file styles HTML elements on the plug-in config page to fit in with Kintone's UI. It is recommended that changes are not made to 51-modern-default.css. If additional elements need to be styled, or default styles need to be over-ridden, those changes should be added into config.css.

config.css (External link)

This supporting CSS file is used to style some areas of the plug-in config page that 51-modern-default.css doesn't cover.

config.js (External link)

This file is used to populate the drop-down fields on the plug-in config page, and to also save the data inputted by the user. The functions setDateDropDown and setStatusDropDown are called when the plug-in setting page loads. Date and Datetime field information is retrievable with the kintone-config-helper library (External link) , but Process Management Status information is not. Therefore, the Get Process Management Settings API is used to retrieve the available Statuses and the functions to display the Date and Status drop-down settings must be separated.

1
2

setDateDropDown();
setStatusDropDown();
setDateDropDown()

This function calls the KintoneConfigHelper.getFields method from the kintone-config-helper library.
By passing ['DATETIME', 'DATE'] as the parameter, an array of field information of all Date, and Datetime fields is returned.

1
2
3

KintoneConfigHelper.getFields(['DATETIME', 'DATE']).then(function(resp) {
  // ...
});

The returned array is used to create a list of Datetime and Date fields, which is appended to the element with the names js-select-date-field, stored in the previously defined variable, $date.

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

var $dateDropDown = $date;
resp.forEach(function(respField) {
  var $option = $('<option></option>');
  switch (respField.type) {
    case 'DATE':
      $option.attr('value', respField.code + ',DATE');
      $option.text(respField.label);
      $dateDropDown.append($option.clone());
      break;
    case 'DATETIME':
      $option.attr('value', respField.code + ',DATETIME');
      $option.text(respField.label);
      $dateDropDown.append($option.clone());
      break;
    default:
      break;
  }
});

At the end of the setDateDropDown function, the code looks through the CONF object where any saved setting data are stored. If it's the first time for the user to use the plug-in, there are no saved values, thus no values are placed in the settings. If the user has saved any settings before in the plug-in (which is stored using Kintone's setConfig API), then that saved value (the specified Date or Datetime field) is inserted into the designated plug-in settings.

1
2
3

if (CONF.date) {
  $dateDropDown.val(CONF.date + ',' + CONF.fieldType);
}
setStatusDropDown()

This function calls the Kintone REST API Request to run the Get Process Management Settings API. The response object contains information on the current App's process management settings, including the available Statuses.

1
2
3
4
5
6

return kintone.api(kintone.api.url('/k/v1/preview/app/status.json', true), 'GET', statusGetBody, function(resp) {
  // ...
}, function() {
  // Error
  alert('There was an error retrieving the Status information.');
});

The response object is used to create an array of Statuses which is appended to the element with the name js-select-status, stored in the previously defined variable $status.

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

var $statusDropDown = $status;
if (resp.enable) {
  var statuses = [];
  resp.actions.forEach(function(respStatus) {
    var status = respStatus.to;
    var $option = $('<option></option>');
    if (!statuses.includes(status)) {
      statuses.push(status);
      $option.attr('value', status);
      $option.text(status);
      $statusDropDown.append($option.clone());
    }
  });
  // ...
}

At the end of the setStatusDropDown function, the code looks through the CONF object where any saved setting data are stored. If it's the first time for the user to use the plug-in, there are no saved values, thus no values are placed in the settings. If the user has saved any settings before in the plug-in (which is stored using Kintone's setConfig API), then that saved value (the specified Status) is inserted into the designated plug-in settings.

1
2
3

if (CONF.status) {
  $status.val(CONF.status);
}

desktop.js (External link)

This file runs the regular pages of the App, such as the Record List and Record Details pages, but not on the plug-in config page. The code first waits for the process management status to change using the Proceed Process event. When the event kicks off, the code creates a new date object containing the current datetime, stored in a variable called currenttime. The datetime is then turned into an ISO string and stored in a variable called timestamp, and a date containing only the current year, month, and day which is stored in a separate variable called currentdate.

1
2
3
4
5
6
7

var statusEvents = ['app.record.detail.process.proceed'];
kintone.events.on(statusEvents, function(event) {
  var currenttime = new Date();
  var timestamp = currenttime.toISOString();
  var currentdate = currenttime.getFullYear() + '-' + (currenttime.getMonth() + 1) + '-' + currenttime.getDate();
  // ...
});

An if statement checks to see that the timestamp field is set in the plug-in settings. If it is correctly set up, the code then checks to see if the current Status matches the Status set in the plug-in settings, and if they match, determines whether the timestamp field is a Datetime field or a Date field. If the field is a Datetime field, the ISO string is entered. If the field is a Date field, the date containing only the year, month, and day is entered. Finally, the event object is returned to display the change in the record.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

if (!TIMESTAMP_FIELD) {
  alert('Status Timestamp Plug-in Warning:\nThe datetime field is not defined in the plug-in settings.');
} else if (status === STATUS_NAME) {
  if (FIELD_TYPE === 'DATETIME') {
    dateFieldSetting.value = timestamp;
  } else if (FIELD_TYPE === 'DATE') {
    dateFieldSetting.value = currentdate;
  }
}
return event;

kintone-config-helper.js (External link)

The kintone-config-helper.js file is a library that supports the development of the plug-in config page. View the Introduction to Kintone Config Helper article for more details.

manifest.json (External link)

The manifest file states the paths of the files that will be used in the plug-in. It also links to the jQuery library hosted on the Kintone CDN and the kintone-config-helper library so that it can be called on the config page.

1
2
3
4
5
6
7
8

"config": {
  "html": "html/config.html",
  "js": [
    "https://js.kintone.com/jquery/3.3.1/jquery.min.js",
    "js/kintone-config-helper.js",
    "js/config.js"
  ]
// ...

The array in the value of the required_params key states which settings in the plug-in config page are required. If these settings are not saved using the setConfig API, errors will be displayed on other pages of the App, stating that the plug-in settings have not been configured yet.

1
2
3
4
5

"required_params": [
  "date",
  "fieldType",
  "status"
]

The name, description, and homepage_url key-value pairs are labels and links displayed in the plug-in settings.

1
2
3
4
5
6
7
8
9

"name": {
  "en": "Status Timestamp Plug-in"
},
"description": {
  "en": "This plug-in inserts the date (and time) that a record reached a specified Status into a Date or Datetime field."
},
"homepage_url": {
  "en": "https://kintone.dev/en/plugins/simple-samples/status-timestamp-plug-in/"
}

Finally

Licenses

This plug-in is open sourced under the MIT License (External link) . It allows open- or closed-sourced distribution, including commercial use.
If you would like to add more functionality to the plug-in, you are welcome to clone our repository to make your own changes and redistribute it. We generally do not accept external pull requests for the sample plug-in as this repository exists for educational purposes.
If you have any questions related to building Kintone plug-ins, please post your question in the Kintone Developer Program Community Forum (External link) .