Using Employee Data From a kintone App as Choices

kintone is a cloud database service provided by Cybozu, Inc. You can create and operate a business database tailored to the needs of your company or department. In this article, we will introduce how to retrieve data on a kintone app with Questetra BPM Suite and create a “Choice Master” based on it.

If a list of choices is saved as a choice master, it can be used as the master data for multiple Select-type Data Items. For example, if you save customer data as a choice master, you can use the customer data as a choice in any Select-type Data Item.

Target kintone App

In this article, we will create a workflow app that creates/updates a choice master based on data obtained from the kintone app employee roster. The same procedure can be used to create an app for the kintone app you are currently using.

Workflow App Settings

Workflow Diagram

Now, let’s create an app that retrieves data from the kintone app and updates (creates) the choice master. Create a new app named “kintone: Choice Retrieval Test”.

Once the modeler is activated, the first step is to create a workflow diagram.

The first Human Task is named “Master Data Creation” and the second Human Task is named “Data Authentication”.

Two types of automatic processes are used: [kintone: Search Records] and [Update Choices]. There is a separate item called [kintone: Get Record], so be careful not to get them mixed up.

Data Item Settings

Next, let’s prepare the data items to be used.

Detailed settings are required for the two Select-type Data Items. Click on the Edit button to open the settings window. Change the default selection for the Type of data source from Fixed choice list to String type data item. A drop-down menu for specifying the String-type data item for Choice ID and Label will appear, so specify “Record ID” for both data items in the Choice ID field. For the Label field, specify “Choice Label: Name” in Name Master and “Choice Label: Team Affiliation” in Team Information.

“Record ID”, “Choice Label: “Name”, and “Choice Label: Team Affiliation”, which are String-type Data Items, store the kintone app data retrieved via [kintone: Search Records] one row by one. “Name Master” is a Select-type Data Item consisting of “Record ID” and “Choice Label: Name”, and “Team Information” is a Select-type Data Item consisting of “Record ID” and “Choice Label: Team Affiliation”.

[kintone: Search Records] Settings

We will set up “kintone: Search Records”, which is an important modeling element for this App.

HTTP Authorization Settings

HTTP Authorization settings must be configured so that Questetra BPM Suite can retrieve data from the kintone app. Open the properties of [kintone: Search Records] and click the [Set up Setting] button in the “C1: Authorization Setting in which API Token is set *” section.

A button opens the HTTP Authorization Settings page in a new tab. Click the [+Add] button to create a new HTTP authentication setting, even if another user’s settings are displayed in the list. Click [+Add] to open a new tab, and select “Token Fixed Value” from the drop-down menu that is displaying “OAuth2” as default at the top. The screen will switch to two settings: Name and Token. For “Name,” enter an appropriate name such as “Connect as {kintone user’s name}”. In the “Token” field, enter the API token issued by the kintone app.

When you return to the modeler and reload the page, you should see the name of the HTTP Authorization Setting you created in the “C1: Authorization Setting in which API Token is set” drop-down menu. Select it and your HTTP Authorization Setting will be complete.

kintone App Token

Select the target application from the kintone portal and open [Customization and Integration] > [API Token] under App Settings.

If the API Token section shows “No API Token”, click the Generate button. Make a note of the string displayed and enter it into the HTTP Authorization Settings as described above. Under Permission, “View Records” is checked, which is sufficient for this article, but check further items if needed for other purposes.

If an API token has already been issued, you can use that, or you can add a new API token using [Generate]. Please note that API tokens that have already been issued should not be deleted. If someone else is using it, it will cease to work.

Once you have written down the API token, click the Save button in the upper left corner to close the screen. Don’t forget to click the “Update App” button on the following app settings screen. If you do not update your app, the API token you were issued will not function.

Domain and App ID

Enter your registered kintone domain in the [C3: Domain] field. The kintone domain is “XXXXXXXXXXXXXX.cybozu.com” as shown below. (“XXXXXXXXXXXXXX.kintone.com” may also be used.)

Enter the ID of the target app in [C5: App ID]. The number after “app=” in the URL listed on the API Token page is the ID of the target app.

Record ID

A unique Record ID is automatically assigned to each record stored in kintone. This Record ID is obtained and used as the choice ID in Questetra’s choice master.

Specify a String-type (multiple lines) Data Item [Choice ID] from the drop-down menu for [C7: Data item to save Record IDs].

Field Code, Data item to save Values

In the C8F: Field Code 1 and C8V: Data item to save Values of Field Code 1, the “Field code to specify the item to be acquired in the record” and “Data item to save the acquired data” are specified as pair. For the field code, see the [Form Settings] screen of the kintone app. Here, enter “staffName” as the field code and specify the Data Item [Choice Label: Name] as the save destination from the drop-down menu.

Similarly, specify [C9F: Field Code 2] for the field code of the second data item to be retrieved, “Team Name” and [C9V: Data item to save Values of Field Code 2] for “Choice Label: Team Affiliation”.

Finally, turn on the “Token will move to Error Boundary Event when processing fails” switch above the C1 item. The service task icon will change and a pink circle Error Boundary Event will appear. The token will be moved to this event when an error occurs in the [Get data] step. The error ends with a connection to an End Event.

In this way, the process can be terminated without updating the choice master when the process fails, such as when data could not be retrieved from the kintone app.

[Choice Master Update] Settings

Choice Masters are a type of Add-on that can be used in an app, and can be referred to by the app as a choice for Select-type Data Items. If this Choice Master is registered in Questetra BPM Suite as an App Shared Add-on all apps will be able to reference the registered master data. To create/update the Choice Master, use [Choice Master Update].

Type of Add-on to be Updated

Specify either Choice Master (app-shared add-on) or Choice Master (add-on). Since this app is for testing, the Choice Master (add-on) is specified.

User who Updates Choice

Press the “Me” button to specify your account. You must have system administration privileges (as annotated in the modeler) when updating the App Sharing add-on.

Select the data item whose choices will be saved

Specify the Select-type Data Item to store the list of choices. Select [Name Master] and [Team Information], which store data retrieved from the kintone app, respectively.

Name when Saving as Add-on

Name them “Name Master” and “Team Data”.

Operation Check

Now let’s save and release the app and see how it actually works.

If you wait a little after completing the Create Master Data task, you should be assigned the Data Verification task. Look at the displayed String-type Data Items “Choice ID”, “Choice Label: Name”, and “Choice Label: Team Affiliation” and confirm that you are getting the data from the kintone app. If everything looks fine, complete the Data Verification task and wait for the process to finish.

Saved Choice Master can be viewed from [▼Appl] > [Manage Add-on] > [Master file of Select type data item].

If It Doesn’t Work Properly

If a confirmation task is not assigned, check to see if the token has progressed to the Error Boundary Event. You can view the status of the Process from the [Workflow] > [Started Processes], etc.

If the token has reached the End Event via the Error Boundary Event instead of the confirmation task, you must check what kind of error occurred in the Update Choices Service task. To check the log of a task that performs automatic processing, use the Administrator Mode in the Process Details or Task Details.

If you check the “Administrator Mode” checkbox, automatic Steps that were not displayed before will also be displayed in the Operation History. You will be able to check the Automatic-processing log of [kintone: Search Records], so you can see the error contents.

The message says “Field Code: StaffName does not exist in the app.” In this example, the wrong field code (the first letter is capitalized) was entered on purpose to generate an error. As a result, the target of the data acquisition could not be determined, resulting in this error log. If the app is not working properly, check the Auto-Process log.

Appendix

Set up Automatic Entry of Team Affiliation when Name is Selected

Two Choice Masters have been created up to this point. However, even if we set up a Select-type Data Item that refers to each Choice Master, we will not be able to use the information about who is on which team, since the “Name” and “Team Affiliation” will be selected separately.

If your Questetra BPM Suite is the Professional Edition, the Team will be automatically selected when you select [Name] using the Questetra Form JavaScript API.

App Changes

Let’s add the settings to the app that has been verified to work as described above and see how it actually works.

Open the App editor, add a [Swimlane] and place the item as shown below.

Add two more Data Items, the first one is a Select-type (select) and the item name is “Name”. The second is a Select-type (search select) and the item name is “Team Affiliation”. As the add-on file can be selected by specifying the Choice Master (add-on) in the “Type of data source” field, specify “Name Master” for “Name” and “Team Data” for “Team Affiliation”.

Script

When you have finished adding the Data Items, write the following script in the Description field of the Data Item Setup screen. It can be either of the added Data Items.

<script>

// Processing to be executed when the form is displayed (ready)
// Call a function to register an event handler for the change event
qbpms.form.on('ready', user_eventActivation);


// Processing when change event occurs
function user_formSelectSet() {

  // Getting values from selected fields
  const choice = qbpms.form.get('q_nameMaster');
  //  Extract choice IDs for Select-type Data Items
  let id = choice[0].value;

  // Assigned to the "Team Affiliation" option ID
  qbpms.form.set('q_teamMaster', id);
}


// Function to register an event handler for the change event of the data item "Name"
function user_eventActivation(){
  qbpms.form.on('change', 'q_nameMaster', user_formSelectSet);
}

</script>

Let’s look at the form preview of the [Select] step after saving with Apply and Close.

When you select “Name” in this way, “Team Affiliation” will be displayed automatically.