How to use

 Home > Connect > kintone > How to use

Add the Cloud BOT Connector to an app

1. Select "Plug-ins" from the App Settings screen.

2.  Click "Add Plug-in", select the check box next to the Cloud BOT Connector, then click the "Add" button.

Plug-in settings

Connection settings

In order to use the Cloud BOT Connector, Cloud BOT account connection must be configured.

1. Click the cog mark (settings) for the Cloud BOT Connector.

2. Generate and paste the API Token to the "API Token" field on the setting. 
>> Click here about how to generate the API Token.

3. Click the "Authorize" button.

4. Log in to Cloud BOT with an account to connect.
Logging into Cloud BOT automatically connects the account.

When the status changes from "Not authorized" to "Authorized", the process is complete.

Run settings

Configure the BOT’s run settings.
* Set the run settings for multiple BOTs by clicking "+ Add bot settings" to add the settings.

BOT to execute

Select the BOT to execute. 
*It is necessary to publish the API of the target BOT on the Cloud BOT service.

Execution status storage destination

Select the destination to store the BOT’s execution status. The execution status is visible on the record screen.
Select only a Text field.
>>For information about status, click here.
* Not selecting this item means the BOT’s execution status will not be visible (but the BOT can still be run).

Destination for storing execution results

Outputs the results of the BOT execution and the log of data stored in the records of the kintone application to the specified fields.
The only field that can be selected is the Text field.
>>For more information about the output format of the execution results, click here.
* If not selected, no log is output.

Execution timing

Select the timing to run the BOT.

- "Execute" button
The "Execute" button is placed on the record screen, and BOT is executed by clicking it.

- Webhook
Execute BOT under certain conditions.
Following conditions are available:

• When a record is added
• When a record is edited
• When a record is deleted
• When a comment is posted
• When a status is updated*

* Enable "process management" in the app settings.

Webhook registration is required to set these conditions.
>> For information on registering a webhook, click here.

Option

Set the following options.

- Do not display on detail screen
Not displayed on the detail screen.
* Not available when "Execute button" execution timing is enabled.

- Check input values before execution
After clicking the "Execute" button, you will be prompted to confirm the input values before running the BOT.

- Do not allow viewing of BOT execution screen
Prohibit viewing of the execution screen while the BOT is running.

- Open BOT browsing screen at runtime
Clicking the "Execute" button opens the BOT browsing screen. (The page will open in a separate window)
* If the "Do not allow viewing of BOT execution screen" option is enabled, this feature cannot be used.

BOT input values settings

Specify the input values assigned to the BOT.

Form values

Specifies the fields of kintone app. 
>> For Cloud BOT's data types to kintone's field types mapping, click here.

Properties

Specifies the properties of kintone app.

• Comment
• Comment contributor(Login name:Display name)
• Comment contributor(Login name)
• Comment contributor(Display name)
• Comment number
• Status
• Record id
• Record number
• Revision
• Updated by(Login name:Display name)
• Updated by(Login name)
• Updated by(Display name)
• Updated datetime
• Assignee(Login name:Display name)
• Assignee(Login name)
• Assignee(Display name)
• Created datetime
• Execution timing

Others

Specify other values.

• Not entered
• Fixed value

* Input a value directly for “Fixed value”.

BOT output value storage destination setting

Set this when you want to store the BOT output value in a record of a kintone app.
Select the field of the destination kintone app and the BOT output value to be stored.

Store in the same record

Store the output value in the same record.

Destination field and value to be stored

An arbitrary number of destination fields can be set. Click "+Add field" to add a setting.

kintone app field

Specify the destination field in the kintone app field.

BOT output data

Specify the value to be stored in the BOT output data.

- Output data
Specify the BOT's output data.
>> For the Cloud BOT’s data types to kintone’s field types mapping, click here.
* If "Group data row" is chosen under "Number of record add," only group data may be chosen as BOT output data.

- Others

Table update mode

Select the update mode for the "Table" field to specify whether to overwrite all rows or append them as new rows.
This option is displayed when a "Table" field is specified in the kintone app field.

The update mode for the table allows the following options:

• Overwrite
• Append

- Overwrite
Deletes all existing rows and overwrites them with new rows.

- Append
Leaves the existing rows as they are and appends new rows.

Store in the specified app record

Store the output value in the record of the specified app.
Settings can be added by clicking "Add storage destination."

Storage destination

Filter by space and select an app.

Number records to add

- 1record
Creates one new record.

- Group data row
Creates records for the number of rows in group data.

Set the destination field and value to store

An arbitrary number of destination fields can be set. Clicking "+ Add field" allows for the inclusion of additional settings.

kintone app field

Specify the destination field in the kintone app field.

BOT output data

Specify the value to be stored in the BOT output data.
>> For information on what items can be entered, click here.

Storage method

The following options can be specified for the storage method:

Table update mode

Select the update mode for the "Table" field to specify whether to overwrite all rows or append them as new rows.
This option is displayed when a "Table" field is specified in the kintone app field.

The update mode for the table allows the following options:

• Overwrite
• Append

- Overwrite
Deletes all existing rows and overwrites them with new rows.

- Append
Leaves the existing rows as they are and appends new rows.

Update condition

It is displayed only when "Update" or "New & Update" is specified as the storage method.

Specify the first update condition.
For the first update condition, specify a field in the kintone application that identifies the record to be updated and the BOT output data to be used as the key.
* All specified update conditions must match in order for the record to be updated.

kintone app field

Specify record to update in identifiable field.

• Record ID
• Text
• Number

* The target is the "Text" and "Number" fields set to "Required field" and "Prohibit duplicate values".

Operator

• = (equal to)

Specify an operator that compares the value of a field in the kintone application with the value of the BOT output data.

BOT output data

Specify the BOT output data to be used as the key.
>> For the output data that can be specified, click here.
* Only text type output data can be specified for output data.

Notes on storing records

The conditions for storing records differ depending on the fields specified in the fields of the kintone application.

The case of "Update" storage method.

The case of "New & Update" storage method.

Add condition

Click "Add condition" to add a condition.

kintone app field

Specify fields to filter.
Specify the kintone field type that corresponds to the BOT's text type.
>> For the Cloud BOT’s data types to kintone’s field types mapping, click here.

Operator

Specify the operator to filter the values of kintone app fields and the BOT's output data values.

・= (equal to)
・≠ (not equal to)
・≤ (less than or equal to)
・< (less than)
・≥ (greater than or equal to)
・> (greater than)

BOT output data

Specify the BOT's output data to be filtered.
>> For information on which output data can be specified, click here.
* Only text type output data can be specified for the output data.

Input another API Token

If a different app is specified as the storage destination, an API Token is required for each app.
When a Lookup field is used in the storage destination field, the API Token of the app associated through the Lookup field's settings is needed.
* The API Token for the app connected via a Lookup field must have "View records" permissions.
Specify an API Token for each app.
>> For details on generating an API Token, click here.

Save / Update plug-in settings

1. After setting, click the "Save" button.

Click the "Update App" button to reflect the settings to the operational environment.

How to run the connected BOT

Execute button

Clicking the "Execute" button executes the BOT any time.

Check input values before execution

By selecting "Check input values before execution" in the options of Execute settings, a confirmation dialog will be displayed before the BOT run.

Open BOT browsing screen at runtime

By selecting "Open BOT browsing screen at runtime" in the run setting option, the preview of the run screen will open in a separate window.

Run with a webhook

The conditions under which the BOT is executed are displayed.

• Added: When a record is added
• Edited: When a record is edited
• Deleted: When a record is deleted
• Commented: When a comment is posted
• Status updated: When a status is updated

Status

The execution status is displayed. Click the report icon next to the status to open the Cloud BOT execution logs screen in a separate window.

The status changes as follows.

Status when the BOT execution starts

Status when the BOT execution

Generate the API Token

1. Go to the API Token page from the link under the "API Token" column in the connection settings.

2. Click the "Generate" button. "View records", "Add records", and "Edit records” access rights are required.

Be careful not to let others know the generated API Token.

3. Click "Save" on the top left. The API Token settings are saved.

4. Click the "Update App" button to reflect the settings to the operational environment.

Register the webhook

By registering a Webhook, you can run the BOT when a specific event occurs.

1. Select "Webhook" on the "Execution settings" in the Cloud BOT Connector settings screen. Webhook URL is displayed.

2. Copy the Webhook URL then click the webhook registration page link. 

3. A separate window is open. Click "+" at the top right to add the webhook.

4. A separate window is open. Paste the copied URL in the "Webhook Endpoint" field.

5. Specify all "Events".

6. Finally, select [Activate this webhook] and click the [Save] button to register the webhook.

Supplementary note

Cloud BOT’s data types to kintone’s field types mapping

Output format of execution results

Outputs BOT execution results and logs with data stored in the kintone application records.
* Items with no data to display will not be displayed.

Bot execution result :
　Status : Succeeded
　Code : 201
　Bot name : Customer List
　Start time : 2012-12-12 13:00:00
　Elapsed time : 15
　Message :
Storage List :
 - Destination : Customer Management Group data rows Customer Registration
　Number of processing results :
　　Success :
　　　Number of additions : 1
　　　Number of updates : 1
　　　Number of filters : 1
　　Error :
　　　Number of addition errors : 1
　　　Number of update errors : 1
　　　Number of skips : 0
　　Total : 5
　success :
　　Keys of added records :
　　　- 101
　　Keys of updated records :
　　　- 102
　　Keys of filtered records :
　　　- 103
　Error :
　　Update failed record keys :
　　　- 104
　　Addition failed record keys :
　　　- 105
　Error message : Missing or invalid input.
　Error details :
　 - Key : 104
　　Row number : 3
　　Contents :
　　　mail address :
　　　　- E-mail address format is not valid.
　　　Table
　　　　Row number : 11
　　　　Contents :
　　　　　add :
　　　　　　- This value already exists in another record.

BOT execution results

Output the results of the BOT execution.

Storage List

Outputs a log containing the BOT output data in the kintone application record.

- Destination

Outputs a log with data stored in the records of the kintone application.

- Number of processing results

Outputs the number of processing results.

Success

- Number of additions

Outputs the number of records added.

- Number of updates

Outputs the number of records updated.

- Number of filters

Outputs the number of cases that did not match the "update conditions" and were not stored.

Error

- Number of addition errors

Outputs the number of failed record additions.

- Number of update errors

Outputs the number of failed record updates.

- Number of skips

Outputs the number of cases that failed to be stored and were not yet processed.

Total

Outputs the total number of successes and failures.

success

- Keys of added records

Outputs the key of the added record.

- Keys of updated records

Outputs the key of the updated record.

- Keys of filtered records

Outputs the keys of records that did not match the "update conditions" and were not stored.
* If the "Storage Method" is "New & Update" and does not match the "Update Condition", a new record is created without filtering.

Error

- Addition failed record keys

Outputs the keys of records that failed to be added.

- Update failed record keys

Outputs the keys of records that failed to update.

Total

- Number of successes

Output the number of successes.

- Number of errors

Outputs the number of errors.

Error message

Output error messages.

Error details

- Key

Outputs the keys of records that failed to be stored.

- Row number

Outputs line numbers that result in an error in storing the number of group data lines.
* The "number of additional records" from the setting of "store in the record of the specified application" in the destination setting of the BOT output value is output only for the setting of "group data row".

- Contents

Store the BOT output data in the kintone application record and output the name of the field that causes the error and the cause.
* If the field in the kintone application that causes an error is a field in a table, the table name and the number of the row that causes the error are also output.

Execution timing restrictions

If the following conditions are met at execution timing, the input value to the kintone app field will be "not specified".