Install and use CloudFlow SDK for Java - CloudFlow - Alibaba Cloud Documentation Center

This topic describes how to install CloudFlow SDK for Java and provides examples on how to use the SDK to call CloudFlow API operations. In the following examples, CloudFlow SDK for Java is used to call CloudFlow API operations to create a workflow, query the information about a workflow, and asynchronously start the execution of a workflow. This topic also provides the complete SDK integration steps.

Prerequisites

An AccessKey pair is configured. Make sure that an AccessKey pair is created. For more information, see Create an AccessKey pair. To prevent credential leaks, you can write the credentials into environment variables. For more information, see Best practices for using an access credential to call API operations.

Environment requirements

Java 8 or later is used.

Step 1: Import CloudFlow SDK for Java to your project

Alibaba Cloud SDK allows you to initiate generic and specialized calls. For more information, see Generic calls and specialized calls. The SDK that you need to import varies based on the call type.

Specialized calls

You can visit OpenAPI Explorer, find the service that you want to use, and view the supported languages and installation methods. Then, import the SDK of the service to your project. In this example, CloudFlow SDK for Java is imported. Perform the following steps to import the SDK:

Go to the CloudFlow SDK page in OpenAPI Explorer.
In the All languages field, select Java.
In the Installation Method section, select an installation method and then copy the installation code to your project.
Add the dependency to your project.

In this example, Apache Maven is used to add the dependency:

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>fnf20190315</artifactId>
  <version>1.1.2</version>
</dependency>

Generic calls

You do not need to install a service-specific SDK to initiate generic calls. You need to only import the com.aliyun.tea-openapi core package. For information about the latest version of the core package, see tea-openapi. Add the following Maven dependency to your Java project:

    <dependency>
      <groupId>com.aliyun</groupId>
      <artifactId>tea-openapi</artifactId>
      <version>0.2.8</version>
    </dependency>

Step 2: Initialize a client

Specify the endpoint of CloudFlow based on the region in which you want to use CloudFlow. For information about the endpoint of CloudFlow in each region, see Regions.

The following section provides sample code on how to initialize a client for specialized calls. For information about how to initiate generic calls, see Generic calls and specialized calls.

Use an AccessKey pair

Note

The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey pair to perform operations is a high-risk operation. We recommend that you use a Resource Access Management (RAM) user to call API operations or perform routine O&M. We recommend that you do not save the AccessKey ID and AccessKey secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources that belong to your account may be compromised.

In this example, the AccessKey pair is obtained from the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to implement identity authentication.

For more information about how to configure authentication information, see Manage access credentials.
The method for configuring environment variables varies based on the operating system. For more information, see Configure environment variables in Linux, macOS, and Windows.

import com.aliyun.tea.*;

public class Sample {
    /**
     * <b>description</b> :
     * <p>Use your AccessKey ID and AccessKey secret to initialize the client.</p>
     * @return Client
     * @throws Exception
     */
    public static com.aliyun.fnf20190315.Client createClient() throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable is configured. 
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable is configured. 
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
                
        config.endpoint = "cn-hangzhou.fnf.aliyuncs.com";
        return new com.aliyun.fnf20190315.Client(config);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.fnf20190315.Client client = Sample.createClient();
    }
}

Step 3: Use the initialized client to call CloudFlow API operations

Note

After you initialize a client, you can use the client to call CloudFlow API operations.

API operation: CreateFlow

Call the CreateFlow operation to create a workflow. When you call the operation, create a request and configure parameters and runtime settings based on your business requirements. You can also customize runtime settings to meet specific requirements.

// Create a request.
  com.aliyun.fnf20190315.models.CreateFlowRequest createFlowRequest = new com.aliyun.fnf20190315.models.CreateFlowRequest()
                // Specify a name for the workflow that you want to create.
                .setName("your_flow_name")
                // Define the workflow in conformance with the FDL syntax standard. To ensure forward compatibility, the system supports the old and new versions of workflow definition specifications. 
                .setDefinition("The old version:
\"
type: flow
version: v1
name: my_flow_name
steps:
  - type: pass
    name: mypass
\"

The new version:
\"
Type: StateMachine
SpecVersion: v1
Name: my_flow_name
StartAt: my_state
States:
  - Type: Pass
    Name: my_state
    End: true
\"")            
                // Specify a description for the workflow.
                .setDescription("my test flow")
                // Specify the type of the workflow.
                .setType("FDL");
        // Configure runtime settings.        
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();

The following sample code provides a complete example on how to create a workflow by using an AccessKey pair:

package com.aliyun.sample;

import com.aliyun.tea.*;

public class Sample {

    /**
     * <b>description</b> :
     * <p>Use your AccessKey ID and AccessKey secret to initialize the client.</p>
     * @return Client
     * 
     * @throws Exception
     */
    public static com.aliyun.fnf20190315.Client createClient() throws Exception {

        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable is configured. 
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable is configured. 
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.endpoint = "cn-hangzhou.fnf.aliyuncs.com";
        return new com.aliyun.fnf20190315.Client(config);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.fnf20190315.Client client = Sample.createClient();
        // Create a request.
        com.aliyun.fnf20190315.models.CreateFlowRequest createFlowRequest = new com.aliyun.fnf20190315.models.CreateFlowRequest()
                // Specify a name for the workflow that you want to create.
                .setName("your_flow_name")
                // Define the workflow in conformance with the FDL syntax standard. To ensure forward compatibility, the system supports the old and new versions of workflow definition specifications. 
                .setDefinition("The old version:
\"
type: flow
version: v1
name: my_flow_name
steps:
  - type: pass
    name: mypass
\"

The new version:
\"
Type: StateMachine
SpecVersion: v1
Name: my_flow_name
StartAt: my_state
States:
  - Type: Pass
    Name: my_state
    End: true
\"")            
                // Specify a description for the workflow.
                .setDescription("my test flow")
                // Specify the type of the workflow.
                .setType("FDL");
        // Configure runtime settings.        
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            // Write your code to print the response of the API operation if necessary.
            client.createFlowWithOptions(createFlowRequest, runtime);
        } catch (TeaException error) {
            // Handle exceptions with caution in your actual business scenario and do not ignore exceptions in your project. In this example, error messages are printed for reference only. 
            // Display error messages.
            System.out.println(error.getMessage());
            // Provide the URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // Handle exceptions with caution in your actual business scenario and do not ignore exceptions in your project. In this example, error messages are printed for reference only. 
            // Display error messages.
            System.out.println(error.getMessage());
            // Provide the URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }        
    }
}

API operation: DescribeFlow

Call the DescribeFlow operation to query the information about a workflow. When you call the operation, create a request and configure parameters and runtime settings based on your business requirements. You can also customize runtime settings to meet specific requirements.

// Create a request.
com.aliyun.fnf20190315.models.DescribeFlowRequest describeFlowRequest = new com.aliyun.fnf20190315.models.DescribeFlowRequest()
                 // Specify the name of the workflow that you want to query.
                .setName("your_flow_name");
        // Configure runtime settings.        
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();

The following sample code provides a complete example on how to query the information about a workflow by using an AccessKey pair:

package com.aliyun.sample;

import com.aliyun.tea.*;

public class Sample {

    /**
     * <b>description</b> :
     * <p>Use your AccessKey ID and AccessKey secret to initialize the client.</p>
     * @return Client
     * 
     * @throws Exception
     */
    public static com.aliyun.fnf20190315.Client createClient() throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable is configured. 
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable is configured. 
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
    
        config.endpoint = "cn-hangzhou.fnf.aliyuncs.com";
        return new com.aliyun.fnf20190315.Client(config);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.fnf20190315.Client client = Sample.createClient();
        // Create a request.
        com.aliyun.fnf20190315.models.DescribeFlowRequest describeFlowRequest = new com.aliyun.fnf20190315.models.DescribeFlowRequest()
                 // Specify the request parameters.
                .setName("your_flow_name");
        // Configure runtime settings.        
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            // Write your code to print the response of the API operation if necessary.
            client.describeFlowWithOptions(describeFlowRequest, runtime);
        } catch (TeaException error) {
            // Handle exceptions with caution in your actual business scenario and do not ignore exceptions in your project. In this example, error messages are printed for reference only. 
            // Display error messages.
            System.out.println(error.getMessage());
            // Provide the URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // Handle exceptions with caution in your actual business scenario and do not ignore exceptions in your project. In this example, error messages are printed for reference only. 
            // Display error messages.
            System.out.println(error.getMessage());
            // Provide the URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }        
    }
}

API operation: StartExecution

Call the operation to start the execution of a workflow. The StartExecution operation is an asynchronous operation. When you call the StartExecution operation, create a request and configure parameters and runtime settings based on your business requirements. You can also customize runtime settings to meet specific requirements.

// Create a request.
com.aliyun.fnf20190315.models.StartExecutionRequest startExecutionRequest = new com.aliyun.fnf20190315.models.StartExecutionRequest()
                // Specify the name of the workflow that you want to execute.
                .setFlowName("your_flow_name")
                // Specify a name for the execution.
                .setExecutionName("your_exec_name")
                // Specify the input of the execution.
                .setInput("{\"key\":\"value\"}")
                // Call back TaskToken-related tasks after the workflow execution ends.
                .setCallbackFnFTaskToken("12");
        // Configure runtime settings.        
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();

The following sample code provides a complete example on how to use the AccessKey pair to call the StartExecution operation to start the execution of a workflow:

package com.aliyun.sample;

import com.aliyun.tea.*;

public class Sample {

    /**
     * <b>description</b> :
     * <p>Use your AccessKey ID and AccessKey secret to initialize the client.</p>
     * @return Client
     * 
     * @throws Exception
     */
    public static com.aliyun.fnf20190315.Client createClient() throws Exception {
 
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable is configured. 
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable is configured. 
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.endpoint = "cn-hangzhou.fnf.aliyuncs.com";
        return new com.aliyun.fnf20190315.Client(config);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.fnf20190315.Client client = Sample.createClient();
        // Create a request.
        com.aliyun.fnf20190315.models.StartExecutionRequest startExecutionRequest = new com.aliyun.fnf20190315.models.StartExecutionRequest()
                // Specify the name of the workflow that you want to execute.
                .setFlowName("your_flow_name")
                // Specify a name for the execution.
                .setExecutionName("your_exec_name")
                // Specify the input of the execution.
                .setInput("{\"key\":\"value\"}")
                // Call back TaskToken-related tasks after the workflow execution ends.
                .setCallbackFnFTaskToken("12");
        // Configure runtime settings.        
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            // Write your code to print the response of the API operation if necessary.
            client.startExecutionWithOptions(startExecutionRequest, runtime);
        } catch (TeaException error) {
            // Handle exceptions with caution in your actual business scenario and do not ignore exceptions in your project. In this example, error messages are printed for reference only. 
            // Display error messages.
            System.out.println(error.getMessage());
            // Provide the URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // Handle exceptions with caution in your actual business scenario and do not ignore exceptions in your project. In this example, error messages are printed for reference only. 
            // Display error messages.
            System.out.println(error.getMessage());
            // Provide the URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }        
    }
}

SDK call example

You can use the API-level SDK demos in different programming languages for debugging. To view the sample code, visit OpenAPI Explorer.