Starting Processes According to Records Shown in kintone Calendar

In this article we describe how to start a Questetra Process and perform automatic processing by using the date and time data of a kintone record as a trigger.

kintone is a cloud database service provided by Cybozu. It allows you to create and operate a business database that meets the needs of your company or department. You can also use APIs to perform various operations, and the auto-Steps we will introduce here also use APIs.

For more information about kintone, please visit the official kintone help page.

About Each Auto-Step

In Questetra there are various auto-Steps related to kintone: Start: kintone: Record’s Datetime Field, Search Records, Download File, Upload File, Add New Record, Delete Record, Get Record and Update Record. In this article we will focus on three of them: Start: kintone: Record’s Datetime Field, Get Record and Update Record.

First, we will briefly explain each process.

Start: kintone: Record’s Datetime Field

This is a start event that automatically starts a Questetra Process, triggered by the date and time field of a kintone record. Specify the target kintone app and the date and time fields in the start event. The Questetra Process starts automatically when there is a record that has passed the time in the date and time field. It is also possible to specify “Created datetime” and “Updated datetime” as the date and time fields.

The kintone app has a calendar format display (see below) which allows records to display on the calendar according to the date and time fields you have specified. In other words, you can use this event to automatically launch processes according to the records displayed in the calendar.

kintone: Get Record

This Task gets the record/business data of the kintone application/database. The data in the specified field is saved in each respective Data Item.

kintone: Update Record

This Task updates a record in a kintone application. Specify the record ID of the record to be updated in the Data Item in the Task.

Setting up a link between kintone and Questetra

To use the auto-Steps you need to generate an API token in the kintone app and save it in Questetra’s authentication settings.

First you need to generate an API token in your kintone app. The steps required for the sample app in this article will be explained later, but for general instructions on API token generation please refer to the following page.

Generating API Tokens

In the properties screen of the kintone auto-Step in Questetra select the “Set up Setting” button under “C1: Authorization Setting in which API token is set”.

Next, click the “Add” button to set up the HTTP authentication for kintone. Select “Token Fixed Value” from the drop-down list. Enter an appropriate name in the “Name” field and the token you have just generated in the kintone app in the “Token” field, then click “Save”.

Overview of the Sample App

This App is for sending a billing amount notification to a billing address by email at a scheduled date and time. Saving billing data in kintone has the advantage that it is easy to search and refer to in a list. By using Questetra’s [Throwing Message Intermediate Event (Email)] you can send a bill when the scheduled billing date arrives.

Setting up the Sample App (kintone side)

In order to be able to check the processed/unprocessed status from kintone, you should save the URL to check the process details of Questetra in the record.

1. Create a kintone app

Click the “+” button in the app block of the kintone portal.

In this article we will create the app from scratch, so select “Create App from Scratch”.

Drag and drop each of the fields in the table below onto the form, and set the field name, field code, and other settings.

Reference: Procedure for setting the field code

Field name	Field type	Field code	Other settings
Billing amount*	Number	Billing amount	Check the “Required field” box
Company name	Text (single line)	Company name
Contact information*	Link	Contact information	Check the “Required field” box and select “Email address” for “Type of input value”
Scheduled billing date and time*	Date time	Scheduled billing date and time	Check the “Required field” box
Process URL	Link	Process URL	Select “Website Address” for “Input Value Type”

2. Create an API token

Create an API Token for linking kintone and Questetra. Open the App Settings tab of the app settings screen, and go to “API Token”.

Check the “View records” and “Edit records” boxes, click “Generate” and make a note of the following three pieces of information.

• API Token
• Domain (xxxxx.kintone.com or xxxxx.cybozu.com)
• App ID (number)

Then remember to click “Save”.

Don’t forget to click “Update App” on the next screen (otherwise the API token will not be saved).

Setting the Calendar Format Display

Go to “Application Settings”, open “List” and click the “+” button.

Select “Calendar” from “Record List Display Format” and save the date as “Scheduled Invoice Date” and the title as “Company Name”.

Setting up the Sample App (Questetra side)

Create an App and set the workflow diagram and Data Items as follows.

The leftmost [Start: kintone: Record’s Datetime Field] is in the Start Event palette. The third one from the left, [Throwing Message Intermediate Event (Mail)] is in the Intermediate Event palette.

Data Item	Type	Required	Description
Title	–	–	The Process title
Record ID	String (single line)	–	Data Item to save the ID of the kintone record in the “Start Process” process. The saved ID will be used in “Get Record” and “Update Record”.
Company name	String (single line)	–	This Data Item is used to save the company name in the “Get Record” process. The saved company name will be used in the body of the email in the [Throwing Message Intermediate Event (Email)].
Scheduled billing date and time	Datetime	–	Data Item to save the scheduled billing date and time in the “Start Process” step.
Billing amount	Numeric	–	Data Item to save the billing amount in the “Get Record” process. The saved invoice amount will be used in the body of the email in the [Throwing Message Intermediate Event (Email)].
Contact	String (single line)	–	This Data Item is used to store the contact information/e-mail address in the “Get Record” process. The saved email address will be used as the destination in the [Throwing Message Intermediate Event (Email)].

First, in the “Start Process” step (see Start: kintone: Record’s Datetime Field) start the process for records that past the scheduled billing date and time.

Item name	Required	Description
C1: Authentication Settings with API Token Setting*	Yes	Specify the authentication settings for connecting to kintone. Please refer to “Setting up a link between kintone and Questetra” for how to set this up.
C2: Domain*	Yes	Specify the kintone domain
C4: App ID*	Yes	Specify the kintone App ID
C5: Field code of the date/time field to be checked*	Yes	Specify the field code of the date/time field to be checked when polling the kintone app. In this case, specify “Expected billing date and time”.
C6: Search query	No	You can specify a search query. In this case, we only want to search for records with an empty process URL, so we will enter “Process_URL = “””. For more information on operators and functions that can be used in search queries, please refer to the kintone reference.
C7: Data Item to Store Record ID*	Yes	Specify a character type data item to store the ID of the record that started the process. In this case, “Record ID” is specified.
C8: Data Item to store date/time data	No	Specify a date/time type data item to store the value of the date/time field that started the process. In this case, we will specify “Scheduled Invoice Date”.

In the following “Get Record” process (see kintone: Get Record) we will retrieve the kintone record

Item name	Required	Description
C1: Authentication Settings with API Token Setting*	Yes	Specify the authentication settings to be used for connecting to kintone. Please refer to “Setting up kintone and Questetra Integration” for how to set up.
C2:Domain*	Yes	Specify the kintone domain
C4: App ID*	Yes	Specify the kintone app
C5: Record ID*	Yes	Specify the ID of the kintone record you want to retrieve data from as a character type data item. In this case, specify “Record ID”.
C6F: Field code_1	No	Specify the field code in the kintone application for the data you want to retrieve. In this case, enter the field code “Invoice Amount” for the field where the invoice amount is stored.
C6V: Data item to save the value_1	No	Specify the data item to save the data of the field specified in C6F: Field Code_1. In this case, specify “Invoice Amount”.
C7F: Field code_2	No	Specify the field code in the kintone app for the data you want to retrieve. In this case, enter the field code “Contact” for the field where the contact information is stored.
C7V: Data item to store the value_2	No	Specify the data item to store the data of the field specified in C7F: Field Code_2. In this case, specify “Contact”.
C8F: Field code_3	No	Specify the field code in the kintone app for the data you want to retrieve. In this case, enter the field code “Company Name” for the field where the company name is stored.
C8V: Data item to save the value_3	No	Specify the data item to save the data of the field specified in C8F: field code_2. In this case, specify “Company Name”.

Then, in the “Send Email” process (see [Throwing Message Intermediate Event (Email)]) send an email to the billing address.

Item name	Required	Description
From	No	Specify the sender of the email. This time, select “Process Start User” from “Insert Reference” to embed the reference. In this way, the sender will be displayed in the From field of the outgoing email in the form of “User Name “.
To: contact*	Yes	Specify the destination of the email. This time, select the data item “Contact” from “Insert Reference” and embed the reference.
Email subject*	Yes	Specify the subject of the email. In this case, we will enter “Billing Information”.
Body:	No	Specify the body of the email. In this case, it is “#{company name EL expression}”. We will inform you of the billing amount. For more information on the formatting of EL expressions, please refer to here. As with From and To, you can also embed them from “Insert Reference”.

You can now send a billing email to a recipient.

After completing the [Throwing Message Intermediate Event (Email)] process, proceed to the next [Update Record] process (see kintone: Update Record). By doing this you will be able to see the records that have been contacted with the invoice amount from the kintone application.

Item name	Required	Description
C1: Authentication settings with API token set*	Yes	Specify the authentication settings to be used for connecting to kintone. Please refer to “Setting up kintone and Questetra Integration” for how to set up.
C2: Domain*	Yes	Specify the kintone domain
C4: App ID*	Yes	Specify the kintone app ID
C5: Record ID*	Yes	Specify the ID of the record to be updated. In this case, specify the “Record ID”.
C6F: Field code_1	No	Specify the field code of the kintone app to update the data. In this case, enter the field code “Process_URL” for the field that stores the process URL.
C6V: New Value_1	No	Specify the value of the data to be saved in the field specified in C6F: Field Code_1. In this case, we want to save the process reference URL, so enter “${var[applicationRoot]}OR/ProcessInstance/listView?processInstanceId=#{processInstanceId}”.

Once the record update is complete, the entire process is finished.

This time, using a search query in the “Start Process” Step, we set only kintone records with an empty process URL to be targeted to trigger the Process, and the URL is set to be saved in the kintone record processed in the “Update Record” Step.

This method has the following advantages:

• Even if the date/time data of a processed kintone record is changed later, duplicate Processes will not be started.
• You can see the status of processed/unprocessed records from kintone, and you can refer to the processed records from the saved process URL.

That’s all for now.