Synchronizing User Information with Local Data (Preparatory Chapter)

Keeping user information registered with 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. 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, so you need to enable it in your Setting.

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

First, open “System Settings > API Clients” as 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 if you have not yet.

When it is ready, create a new project in Maven. It is recommended to use 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 immediate 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>11.8.0</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

</project>

“dependency” element in bold is the additional part.

Implementing a class to search users

Now, let’s try to utilize the API from Questetra BPM Suite actually. 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, which is a Questetra BPM Suite API client library, QuserApi class which is for manipulating user information is provided.

Using this class, implement UserDataManager class that is for performing various operations of Basic authentication → user information. In Maven project, place codes under {PROJECT DIRECTORY}/src/main/java/. There, create UserDataManager.java as well. Note that when using this example code as it is, 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 section of Basic authentication.

// {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.find(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). Method find of QuserApi class is used for user search.

Let’s actually search for a user using this find method. Create 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 TO SEARCH}");
        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, so in the sample code, the user ID is null and inputs email address. 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 local CSV file with Questetra BPM Suite.

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

2 thoughts on “Synchronizing User Information with Local Data (Preparatory Chapter)”

  1. Pingback: Synchronizing User Information with Local Data (User Information Chapter) – Questetra Support

  2. Pingback: Downloading Process and Task List Using Workflow API – Questetra Support

Comments are closed.

%d bloggers like this: