This article introduces how to create and upload a Kintone plug-in using plug-in packer and plug-in uploader.

It is recommended to read the following article and set up the environment before this current article:
Get Started with Developing Plug-ins

An "Input value check plug-in" will be created, which will validate data that users input into an App's record.

First, create a new Kintone App. From the Kintone Marketplace, choose Customer Database.

For more information on adding an App from the Kintone Marketplace, refer to the following article:
Adding a Sample App

Next, prepare the necessary files for the Kintone plug-in. Create a directory with the following structure.

1
2
3

sample-plugin
├── image
└── js

Prepare an icon file for the plug-in. Set the image under the "image" directory with the file name "check.png".

Prepare a JavaScript file that will run for desktop browsers. This is where the main Kintone customization codes will be written.

In the following sample code, the customization checks the values when a field value changes and the record is saved. Since this article aims to understand the process of creating a plug-in, the Plug-in settings page will not be configured in this sample. Therefore, the field codes are hard-coded.

Copy the sample code below, save the file as "desktop.js", and place it under the "js" directory.

 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

(() => {
  'use strict';

  // field codes
  const telFieldCode = 'telephone_number';
  const mailFieldCode = 'email';

  // check the Telephone value
  const validateTel = (event) => {
    // set the telephone pattern, number must be 10 or 11 digits
    const telPattern = /^\d{10,11}$/;
    // get the record data
    const record = event.record;
    record[telFieldCode].error = null;

    // check the input value
    const telFieldValue = record[telFieldCode].value;
    if (telFieldValue) {
      if (!(telFieldValue.match(telPattern))) {
        // error if the input value does not match the pattern
        record[telFieldCode].error = 'Telephone number must be 10 or 11 digits.';
      }
    }
  };

  // check the Email value
  const validateMail = (event) => {
    // set the email pattern
    const mailPattern = /^([a-zA-Z0-9])+([a-zA-Z0-9._-])*@([a-zA-Z0-9_-])+([a-zA-Z0-9._-]+)+$/;
    const record = event.record;
    record[mailFieldCode].error = null;
    // check the input value
    const mailFieldValue = record[mailFieldCode].value;
    if (mailFieldValue) {
      if (!(mailFieldValue.match(mailPattern))) {
        // error if the input value does not match the pattern
        record[mailFieldCode].error = 'Invalid email address.';
      }
    }
  };

  // Telephone field change event
  kintone.events.on([
    'app.record.create.change.' + telFieldCode,
    'app.record.edit.change.' + telFieldCode,
    'app.record.index.edit.change.' + telFieldCode
  ], (event) => {
    validateTel(event);
    return event;
  });

  // Email field change event
  kintone.events.on([
    'app.record.create.change.' + mailFieldCode,
    'app.record.edit.change.' + mailFieldCode,
    'app.record.index.edit.change.' + mailFieldCode
  ], (event) => {
    validateMail(event);
    return event;
  });

  // record save events
  kintone.events.on([
    'app.record.create.submit',
    'app.record.edit.submit',
    'app.record.index.edit.submit'
  ], (event) => {
    validateTel(event);
    validateMail(event);
    return event;
  });
})();

The manifest file is a configuration file that contains all the file information needed to create the plug-in. Save the following sample as "manifest.json" and place it under the "sample-plugin" directory.

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

{
  "manifest_version": 1,
  "version": "1.0.0",
  "type": "APP",
  "name": {
    "en": "Input value check plug-in"
  },
  "description": {
    "en": "This plug-in checks telephone number and e-mail address"
  },
  "icon": "image/check.png",
  "homepage_url": {
    "en": "https://kintone.dev/en/plugins/development-guide/how-to-create-plugins"
  },
  "desktop": {
    "js": [
      "js/desktop.js"
    ]
  }
}

Refer to the following article for other parameters in the manifest file:
The Manifest File

Once all the files are prepared, the file tree should now look like the following structure:

1
2
3
4
5
6

sample-plugin
├── image
|    └── check.png
├── js
|    └── desktop.js
└── manifest.json

1. Install plugin-packer using npm.

   1	npm install -g @kintone/plugin-packer

2. Move up a directory from the "sample-plugin" directory. Run the following command to package the files.

   1	kintone-plugin-packer sample-plugin

   If the packaging is successful, the following message will be displayed.

   1	Succeeded: DIRECTORY_PATH/plugin.zip

3. If the command execution succeeds, a plug-in file (plugin.zip) and a private key file (ppk file) will be generated. The private key file name "pluggemelniigegboedcjdggddigldbla" in the following example is the plug-in ID. This is a randomly assigned unique ID.

   1 2 3 4 5 6 7 8 9

   work ├── plugin.zip ├── plggemelniigegboedcjdggddigldbla.ppk └── sample-plugin ├── image | └── check.png ├── js | └── desktop.js └── manifest.json

Note

There is also a web version of plugin-packer to package plug-ins. For more information, refer to the following article:
Plugin-packer (web version)

Kintone Administrator permission is required to add plug-in files to Kintone. For more information, refer to the following article.
Kintone Administrator

1. Install plugin-uploader using the following command.

   1	npm install -g @kintone/plugin-uploader

2. Run the following command to add the plug-in file to Kintone.

   1	kintone-plugin-uploader plugin.zip

3. Enter your Kintone subdomain, login name, and password.

   1 2 3 4 5 6 7 8

   ? Input your kintone's domain (example.kintone.com): <subdomain>.kintone.com ? Input your username: <user name> ? Input your password: <user password> > Open https://<subdomain>.kintone.com/login?saml=off > Trying to log-in... > Navigate to https://<subdomain>.kintone.com/k/admin/system/plugin/ > Trying to upload plugin.zip > plugin.zip has been uploaded!

4. Next, navigate to Kintone on the browser and check if the plug-in has been uploaded. Open the Kintone Administration page and click on Plug-ins. "Input value check plug-in" should be added to the Imported Plug-ins list.

   

Note

Plug-in files can also be added from the Kintone Administration page. For more information, refer to the following article on the Kintone Help site:
Adding plug-ins by importing plug-in files .

Add the plug-in to the Customer Database App created in STEP 1 .

1. In the Customer Database App, go to App Settings and open Plug-ins.
2. Click the Add Plug-in button.

   

3. Check the box next to "Input value check plug-in" and click the Add button at the bottom right of the page.

   

4. Navigate back to the App Settings page and click Update App.

If a plug-in with the same Plug-in ID is uploaded, it will automatically overwrite the plug-in, and will take effect on all apps that are using that plug-in.

Go to the App and add a new record. Enter data into the Email and Telephone Number fields. The data will be validated, and will show field errors if the data is invalid.

Now that the plug-in has been created, the next tutorial will guide through the process of implementing its settings page. Follow the step-by-step guides in the following article for instructions on how to create plug-ins settings:

How to Create a Settings Page