kintone developer network

Plugin JavaScript API

Follow

Set Config kintone.plugin.app.setConfig()

Saves the Plugin configuration settings as an object with a set of keys and values inside.
Only the last saved settings are saved.

Function

kintone.plugin.app.setConfig(config,callback)

Parameters

PARAMETER TYPE REQUIRED DESCRIPTION
config Object yes Specify the configuration as an object, with a set of key and values inside. Specify the values as strings.
Example: { "key1": "value1", "key2": "value2" }
callback Function optional Specify a function to be called when the configurations have been saved. If this parameter is ignored, the page will move to the plugin list page after saving the configurations.

Response

None

Available Pages

  • Plugin Settings

Sample

var config = {
    "Number Field Code": "number_field",
    "Font Color": "#8bc534"
};
kintone.plugin.app.setConfig(config);

Get Config kintone.plugin.app.getConfig()

Retrieves the Plugin configuration settings.

Function

kintone.plugin.app.getConfig(pluginId)

Parameters

PARAMETER TYPE REQUIRED DESCRIPTION
pluginId String Yes Specify the Plugin ID of the Plugin you want to retrieve details from.

Response

An object with the plugin settings information will be returned, with the key and the value as a set.
Null is returned when it cannot be used.

Sample Response

{
    "Number Field Code": "number_field",
    "Font Color": "#8bc534"
}

Available Pages

The following desktop pages:

  • Record List
  • Record Details
  • Record Create
  • Record Edit
  • Graph
  • File Import
  • File Export
  • Plugin Settings

 

The following smartphone pages:

  • Record List
  • Record Details
  • Record Create
  • Record Edit

Sample

var config = kintone.plugin.app.getConfig('ghjdjfpgeoghqsmczgajibgpxoffmgaa');
console.log(config);

kintone Plugin Proxy kintone.plugin.app.proxy()

Runs an external REST API from a plugin.
If your external REST API requires sensitive information such as secret keys, use the Set Config for proxy() API and Get Config for proxy() API mentioned later on save and get these data for the external REST API.

Function

kintone.plugin.app.proxy(pluginId, url, method, headers, data, callback, error)

Parameters

PARAMETER TYPE REQUIRED DESCRIPTION
pluginId Object Yes The Plugin ID of the Plugin that will run the API.
url String Yes The URL of the REST API that you will run.
method String Yes The HTTP method. Specify one of the following: GET / POST / PUT / DELETE.
headers Object Yes The request header.
The parameters specified here will be sent with the parameters that were saved in the plugin by the kintone.plugin.app.setProxyConfig() function.
data Object/String Yes The request data. To ignore this parameter, input {}.
The data specified here will be sent with the data that were saved in the plugin by the kintone.plugin.app.setProxyConfig() function.
Applied only for POST/PUT requests. Ignored for GET/DELETE requests.
For GET/DELETE requests, set the parameter on the QueryString of the URL instead.
callback Function Optional The function that will run after the request has finished. The following three data will be passed as the parameters:
  • First parameter: Response body (String)
  • Second parameter: Status code (number)
  • Third parameter: Response header (Object)
If ignored, a kintone.Promise object will be returned that can be fulfilled with an array containing the Response body (string), Status code (number) and Response header (Object) mentioned above.
error Function Optional The function that will run when the request fails. The response body will be passed to the function parameter as a string.
If the callback is ignored, a kintone.Promise object will be returned that can be fulfilled with the Response body (string) from the kintone plugin proxy API.

Response

A kintone.Promise object will be returned if the callback parameter is ignored. Otherwise, there will be no response.

Available Pages

The following desktop pages:

  • Record List
  • Record Details
  • Record Create
  • Record Edit
  • Graph
  • File Import
  • File Export
  • Plugin Settings

 

The following smartphone pages:

  • Record List
  • Record Details
  • Record Create
  • Record Edit

Sample Request

kintone.plugin.app.proxy('ghjdjfpgeoghqsmczgajibgpxoffmgaa', 'https://api.example.com', 'GET', {}, {}, function(body, status, headers) {
    console.log(status, JSON.parse(body), headers);
}, function(error) {
    console.log(error);  //Display the response body (string) from the proxy API
};

Sample Request using Promises

kintone.plugin.app.proxy('ghjdjfpgeoghqsmczgajibgpxoffmgaa', 'https://api.example.com', 'GET', {}, {}).then(function(args) {
    /*  args[0] -> body(String)
     *  args[1] -> status(Number)
     *  args[2] -> headers(Object)
     */
    console.log(args[1], JSON.parse(args[0]), args[2]);
}, function(error) {
    console.log(error);  //Display the response body (string) from the proxy API
});

Set Config for proxy() kintone.plugin.app.setProxyConfig()

Saves the Plugin configuration settings that can be later retrieved with the kintone.plugin.app.proxy() API

Function

kintone.plugin.app.setProxyConfig(url, method, headers, data, callback)

Parameters

PARAMETER TYPE REQUIRED DESCRIPTION
url String Yes Part or all of the REST API URL.
Check here (**LINK**) for conditions for data to be added to the API request.
method String Yes The HTTP method. Specify one of the following: GET / POST / PUT / DELETE.
headers Object Yes The parameters that will be added to the request header of the API.
If parameter names overlap with paramaters specified with kintone.plugin.app.proxy() , then the paramaters specified here will take priority.
Leave this as {} if not parameters are needed.
data Object Yes Specify data that will be added to the API request data, as an object with a set of key and values inside.
If key names overlap with keys specified with kintone.plugin.app.proxy() , then the keys specified here will take priority.
Leave this as {} if not keys are needed.
callback Function Optional The function to be called after the settings have been successfully saved. There are no parameters. If this is undefined, null or is not specified, the page will move to the plugin list page and display a message stating the settings have finished.
If a callback function is specified, the page will not move to the plugin list page.

Response

None

Available Pages

  • Plugin Settings

Sample

var headers = {
    "Content-Type": "application/json",
    "Authorization": "777-777-abcded-ghijkl"
};
var data = {
    "key1": "secretValue"
};
kintone.plugin.app.setProxyConfig('https://api.example.com', "GET", headers, data);

After the above settings have been saved, let's say you used "kintone.plugin.app.proxy()" to run an API, with the URL "https://api.example.com/rest/operate.json" and a header of "{}".
In this case, the request header that will be sent will become:

{"Content-Type": "application/json","Authorization":"777-777-abcded-ghijkl"}

Saved Format

The data saved by this API will be saved in the following format:

  • URL
  • HTTP Method (GET/POST/PUT/DELETE)
  • Saved Data
  • An object will be saved with a set of keys and values including the following:
    • Request Header
    • Request Data

If you specify a URL and HTTP method set that's already been saved to the plugin, the new information will override it.

Conditions for Saved Data to be Added to the Request

The saved information will be added to the requests that use kintone.plugin.app.proxy(), and also meet all of the following conditions:

  • The apps are the same
  • The Plugins are the same
  • The HTTP method is the same
  • The URL of the API that is called forward matches

Forward matching URL examples

Example 1

For example, if the below API and URL is used to save settings to the plugin,

kintone.plugin.app.setProxyConfig()
https://api.example.com/

and the below API and URL is called to run an external REST API,

kintone.plugin.app.proxy()
https://api.example.com/operate.json

then the URLs will forward match, and the data saved in the plugin (saved by kintone.plugin.app.setProxyConfig() ) will be added to the request.
Note that the URLs are case sensitive.

 

Example 2

If you've saved several settings to the plugin, the URL in the settings that match the most characters with the URL called by kintone.plugin.app.proxy() will be prioritized.
For example, let's say we used "kintone.plugin.app.setProxyConfig()" to save the following two settings to the Plugin:

Setting 1
URL:https://api.example.com/
Header:{"Content-Type": "application/x-www-form-urlencoded"}

Setting 2 URL:https://api.example.com/rest/ Header:{"Content-Type": "application/json"}

If we call kintone.plugin.app.proxy() to run an external REST API with the following information,

URL:https://api.example.com/rest/operate.json
Header:{}

the request header that will be sent by the API will become:

{"Content-Type": "application/json"}

Get Config for proxy() kintone.plugin.app.getProxyConfig()

Retrieves the headers and data that will be added to the request when running a REST API with kintone.plugin.app.proxy(). These information will first need to be save using the kintone.plugin.app.setProxyConfig() API.

Function

kintone.plugin.app.getProxyConfig(url, method)

Parameters

PARAMETER TYPE REQUIRED DESCRIPTION
url String Yes The REST API and URL
method String Yes The HTTP method. Specify one of the following: GET / POST / PUT / DELETE.

Response

{
    "headers": {
        "Content-Type": "application/json",
        "Authorization": "1234567890abcdefg"
    },
    "data": {
         
    }
}

Available Pages

  • Plugin Settings

Sample

var config = kintone.plugin.app.getProxyConfig("https://api.example.com", "GET");
console.log(config);

Notes on Saved Data used with kintone Plugin Proxy

The Request Header sent when using kintone Plugin Proxy

The request header sent that will be sent is the contents of the request header specified in the kintone Plugin Proxy plus the Saved Plugin data that was saved with setProxyConfig().

Example:
If {k1: 'v1'} was specified in the request header for setProxyConfig(), and {k2: 'v2'} was specified in the request header for kintone Plugin Proxy, the request header will become {k1: 'v1', k2: 'v2'} .

The Data sent when using kintone Plugin Proxy

When the HTTP method is POST/PUT, the data sent will depend on the data format.
If the data format is an object, the data specified in the kintone Plugin Proxy plus the Saved Plugin data that was saved with setProxyConfig() will be sent.
If the data format is a string, only the data specified in the kintone Plugin Proxy will be sent.

When the HTTP method is GET/DELETE, the Plugin data saved with setProxyConfig() will be added as a Query String to the end of the specified url parameter of the kintone Plugin Proxy.
If "?" is not included in the specified url parameter, this will also be added.

Example:
If {k1: 'v1', k2: 'v2'} was specified in the data for setProxyConfig(), and 'https://api.github.com?k=v' was specified in the url for kintone Plugin Proxy, the url will become 'https://api.github.com?k=v&k1=v1&k2=v2'

When two saved settings have the same keys

If setProxyConfig() is used to save two different settings that use the same named keys, the settings with the URL that most matches the URL specified in the kintone Plugin Proxy will take priority.

Example:
If setProxyConfig() is used to save two different settings as below,

url: 'https://api.github.com'
headers:  {k1: 'v1', k2: 'v2'}

and

url: 'https://api.github.com/'
headers: {k2: 'v2-1', k3: 'v3'}

then, if the kintone Plugin Proxy is used with the url as https://api.github.com/ , the request header will become

{k1: 'v1', k2: 'v2-1', k3: 'v3'}

When a saved setting and the kintone Plugin Proxy have the same keys

As explained in the parameter descriptions in the table for the setProxyConfig(), if the keys in the saved settings use the same named keys as the ones in the kintone Plugin Proxy, the saved keys will take priority.
If the HTTP method is GET/DELETE, the overlapping of keys is not checked.

Example:
If setProxyConfig() is used to save settings as below,

headers: {k1: 'v1', k2: 'v2'}

and kintone Plugin Proxy is used with

headers: {k2: 'v2-1', k3: 'v3'}

then in this case, both headers contain the k2 value, but the saved settings will take priority, thus the request header will become

{k1: 'v1', k2: 'v2', k3: 'v3'}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request
Comments