2021-09-16 / Questetra Developers Blog /

Keeping user information registered within Questetra BPM Suite always in line with the employee directory manually would be quite cumbersome. Even though it is good enough to add new users manually when new employees come in, or manually delete them when employees leave your company, it will be much easier to manage if it synchronizes automatically with the current employee directory. This article introduces a Java program that synchronizes Questetra BPM Suite user information with local TSV (Tab-separated values) data.

About Questetra BPM Suite Web API

Questetra BPM Suite provides a Web API that allows external programs to manipulate system settings. Using this API, you can change the system settings without operating Questetra BPM Suite from the browser. We will create a program to manipulate user information using this API. By importing the Java library prepared here, useful classes for API access will become available.

In addition, when accessing the system setting API from an external program, authentication by Basic authentication or OAuth is required. Since we will use Basic authentication, I will also show the procedure for enabling Basic authentication in the System Settings of Questetra BPM Suite in advance.

Development environment

We will use Java 1.8 and Maven 3 and also import the following Questetra BPM Suite API client library using Maven.

Enabling Basic Authentication on Questetra BPM Suite

We will use Basic Authentication as authentication for accessing Questetra BPM Suite from an external program. Since Basic authentication is disabled by default in Questetra BPM Suite, you need to enable it in your Settings.

Enabling Basic authentication requires System Administrator authority which is one of the system privileges. Also, to manipulate user information on Questetra BPM Suite, you need User Manager authority. You can confirm which account has each system authority from “System Settings > System Authorization”.

First, open “System Settings > API Clients” using an account with System Administrator authority, and check on “Enable API access with Basic Authentication” and save.

When Basic Authentication is enabled, you can confirm the password for Basic authentication at “Account settings” > “Password” on an account with User Manager authority.

On and after that, you can use the email address of the account with User Manager authority and the password for Basic authentication of that account, as Basic authentication information when using Questetra BPM Suite API.

Creating a new project in Maven

In this article, Maven 3 is used to create Java programs. Please install it if you haven’t yet done so.

When it is ready, create a new project in Maven. It is recommended to use an IDE (Integrated Development Environment) that is compatible with Maven, such as “Eclipse” and “IntelliJ IDEA”.

Editing POM.xml

In the Maven project, the library to be used must be described in POM.xml. Add com.questetra.bpms.client.swagger, the Questetra BPM Suite API client library mentioned above, to POM.xml. POM.xml is directly under the project directory.

<!--?xml version="1.0" encoding="UTF-8"?-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelversion>4.0.0</modelversion>

    <groupId>questetra</groupId>
    <artifactId>swagger-java</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.questetra</groupId>
            <artifactId>bpms.client.swagger</artifactId>
            <version>12.3.1</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

</project>

The “dependency” element in bold is an additional part.

Implementing a class to search users

Now, let’s try to actually utilize the API from Questetra BPM Suite. We will start with the retrieval of the User with a Java program, before updating the User information on Questetra BPM Suite.

In com.questetra.bpms.client.swagger the QuserApi class is provided which is for manipulating user information.

Using this class, implement the UserDataManager class that is for performing various operations of Basic authentication → User information. In the Maven project, place the code under {PROJECT DIRECTORY}/src/main/java/. There, create UserDataManager.java as well. Note that when using this example code rewrite the URL, email address, and password for Basic authentication according to your environment. The email address and password for Basic authentication must be those of an account with user management authority as mentioned in the Basic authentication section.

// {PROJECT DIRECTORY}/src/main/java/UserDataManager.java
import com.questetra.bpms.client.swagger.model.*;
import com.questetra.bpms.client.swagger.ApiClient;
import com.questetra.bpms.client.swagger.ApiException;
import com.questetra.bpms.client.swagger.Configuration;
import com.questetra.bpms.client.swagger.auth.*;
import com.questetra.bpms.client.swagger.api.QuserApi;

class UserDataManager {
    private final QuserApi apiInstance;

    public UserDataManager() {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // Set URL
        defaultClient.setBasePath("https://example.questetra.net/");

        // Basic Authentication
        HttpBasicAuth basic 
                = (HttpBasicAuth) defaultClient.getAuthentication("basic");
        basic.setUsername("{EMAIL ADDRESS}");
        basic.setPassword("{BASIC AUTHENTICATION PASSWORD}");

        this.apiInstance = new QuserApi();
    }

    /**
     * Search specified users from users registered in Questetra BPM Suite. Throws an exception if not found.
     * @param id: User ID. Pass {@code null} if unknown. If passes other than {@code null}, it takes precedence over {@code email}.
     * @param email: Registered email address. Passes {@code null} if unknown.
     * @return QuserWithPrimaryQgroupWrapper: Retrieved user.
     */
    public QuserWithPrimaryQgroupWrapper find(Long id, String email) {
        QuserWithPrimaryQgroupWrapper result = new QuserWithPrimaryQgroupWrapper();
        try {
            // Search user
            result = this.apiInstance.findQuser(id, email);
        } catch (ApiException e) {
            // Exception handling
            System.err.println("Exception when calling QuserApi#find");
            e.printStackTrace();
        }
        return result;
    }
}

The find method of the UserDataManager class searches for a User by User ID (Long) or email address (String). The findQuser method of the QuserApi class is used for User searches.

Let’s actually search for a User using this find method. Create a Test class like the following.

// {PROJECT DIRECTORY}/src/main/java/Test.java
import com.questetra.bpms.client.swagger.model.*;

class Test {
    public static void main(String[] args) {
        UserDataManager test = new UserDataManager();
        QuserWithPrimaryQgroupWrapper user = test.find(null, "{EMAIL ADDRESS OF THE USER}");
        System.out.println(user);
    }
}

It creates an instance of the UserDataManager class and executes the find method. Since email address is easier to understand than user ID, in the sample code input the email address and leave the user ID as null. If the corresponding user is found, the user information is displayed on stdout. Let’s build and run it.

> class QuserWithPrimaryQgroupWrapper {
>     quser: class QuserWithPrimaryQgroup {
>         email: questetra+Canarias@gmail.com
>         id: 11
>         name: Canarias
>         primaryQgroup: class Qgroup {
>             email: 
>             id: 2
>             name: 10 Management Department
>             parentQgroupEmail: 
>             parentQgroupId: 1
>             parentQgroupName: 00 Whole Company
>         }
>     }
> }

Did you get the display like above? If the corresponding User is not found, an exception is thrown.

In this way, importing com.questetra.bpms.client.swagger makes it possible to use the Questetra BPM Suite API. In the next article, I will add the method required for User account information operation to this UserDataManager class, and implement a new class that synchronizes user account information in a local CSV file with Questetra BPM Suite.

Next: Synchronizing User Information with Local Data (User Information Chapter)

%d bloggers like this: