Plug-in JavaScript API

Last Updated:
Follow

Set Config kintone.plugin.app.setConfig()

Saves the plug-in 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 plug-in list page after saving the configurations.

Response

None

Available Pages

This method can be used in the following pages:

  • Plug-in Settings

Sample

Error Samples

The following formats are not applicable for the config parameter.

Error case 1: Using nested objects

Error case 2: Using integers as values

Get Config kintone.plugin.app.getConfig()

Retrieves the plug-in configuration settings.

Function

kintone.plugin.app.getConfig(pluginId)

Parameters

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

Response

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

Sample Response

Available Pages

This method can be used in the following pages:

Desktop pages:

  • Record List
  • Record Details
  • Record Create
  • Record Edit
  • Graph
  • Plug-in Settings

 

Mobile pages:

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

Sample

Kintone Plug-in Proxy kintone.plugin.app.proxy()

Runs an external REST API from a plug-in.
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, to 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 plug-in ID of the plug-in 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 plug-in 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 was saved in the plug-in 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 plug-in proxy API.

Response

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

Available Pages

This method can be used in the following pages:

Desktop pages:

  • Record List
  • Record Details
  • Record Create
  • Record Edit
  • Graph
  • Print

 

Mobile pages:

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

Sample Request

Sample Request using Promises

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

Saves the plug-in 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 Conditions for Saved Data to be Added to the Request 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 plug-in list page and display a message stating the settings have finished.
If a callback function is specified, the page will not move to the plug-in list page.

Response

None

Available Pages

This method can be used in the following pages:

  • Plug-in Settings

Sample

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 plug-in, 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 Plug-ins 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 plug-in,

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 plug-in (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 plug-in, 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 plug-in:

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(). This information will first need to be saved 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

Available Pages

This method can be used in the following pages:

  • Plug-in Settings

Sample

Kintone Plug-in Proxy Upload kintone.plugin.app.proxy.upload()

Upload a file to outside of Kintone from a plug-in.
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 to save and get these data for the external REST API.

Function

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

Parameters

PARAMETER TYPE REQUIRED DESCRIPTION
pluginId Object Yes The Plug-in ID of the Plug-in that will run the API.
url String Yes The request URL.
method String Yes The HTTP method. Specify one of the following: POST / PUT.
headers Object Yes Specify the request header as an object. To ignore this parameter, input {}. Sample: {'Content-Type': 'application/json'}
data Object Yes The data that will be sent in the request.
{ 'format': format to be uploaded to the external service. 'value': data to be uploaded }
For format, you can only specify the string "RAW".
For value, specify the value of the Blob type (including File type). The maximum size is 200MB.
callback Function Optional The callback function that will run when the request to the external service has finished. It will receive the response body (string), the status code (number) and the response header (object) as parameters from the external service.
If this parameter is ignored, a kintone.Promise object will be returned that can be fulfilled with an array containing a Response body (string), Status code (number) and Response header (object).
error Function Optional The callback function that will run when the API request to the external service fails. It will receive the response body (string) as the parameter from the external service.
If this parameter is ignored, a kintone.Promise object will be returned that can be rejected with the response body (string) from this API.

Response

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

Available Pages

This method can be used in the following pages:

Desktop pages:

  • Record List
  • Record Details
  • Record Create
  • Record Edit
  • Record Print
  • Graph
  • File Import
  • File Export

 

Mobile pages:

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

Sample Request

Sample Request using Promises

Limitations

  • Compatible browsers are: Internet Explorer 11, Mozilla Firefox(latest version), Google Chrome(latest version), Safari(latest version), iOS Safari (latest version), and Android Chrome(latest version).

Notes on Saved Data used with Kintone Plug-in Proxy

The Request Header sent when using Kintone Plug-in Proxy

The request header that will be sent is the contents of the request header specified in the Kintone Plug-in Proxy plus the saved plug-in 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 Plug-in Proxy, the request header will become {k1: 'v1', k2: 'v2'} .

The Data sent when using Kintone Plug-in 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 Plug-in Proxy plus the saved plug-in data that was saved with setProxyConfig() will be sent.
If the data format is a string, only the data specified in the Kintone Plug-in Proxy will be sent.

When the HTTP method is GET/DELETE, the plug-in data saved with setProxyConfig() will be added as a Query String to the end of the specified url parameter of the Kintone Plug-in 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 Plug-in 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 Plug-in 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 Plug-in 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 Plug-in 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 Plug-in 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 Plug-in 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
Do you have any questions or issues related to this article?
Please share your views with us in the Community forums!