Child pages
  • Flux REST API
Skip to end of metadata
Go to start of metadata

You can use the Flux REST API to interact with a Flux Cluster using an HTTP interface. Complete documentation for the REST API (including input and output payload details for each API) is available on the Flux Support Portal. For example, the following examples illustrate using CURL to interact with a Flux instance through this REST API. 

When using the scripts below, your server name, port, and username:password will need to be changed to match your environment.


 Any CURL script first needs to perform a signIn (see sample code below) to fetch a session cookie, and then save that cookie to a file. All subsequent CURL commands need to submit that cookie file in their request. Finally, a signOut should occur to invalidate the session. Note the syntax may vary depending upon your CURL implementation.

NOTE: For those operating systems that do not provide CURL as a utility program (e.g., Windows), download and install the appropriate version of CURL from here: 


SignIn and save session information (a cookie) to a cookies file

curl -c cookies.txt -u admin:admin http://FluxServer:7186/cluster/session/signIn.json

Query the repository of flowcharts

curl -b cookies.txt -u admin:admin http://FluxServer:7186/cluster/repositoryFlowCharts.json
{"count":"1","matched":"1","repositoryElement":{"creationTimestamp":"2013-11-06T21:31:26.179-06:00","creationTimestampFormatted":"06 Nov 2013 @ 21:31:26","id":"2","lastModifiedTimestamp":"2013-11-26T13:17:25.736-06:00","lastModifiedTimestampFormatted":"26 Nov 2013 @ 13:17:25","namespace":"/Workflow","owner":"admin"}}

Insert a workflow named /Workflow into the Flux repository from the current directory

curl -b cookies.txt -F "file=@Workflow.ffc" -u admin:admin http://FluxServer:7186/cluster/repositoryFlowCharts/upload


Returns the message <success/>

Fetch a workflow named /Workflow

curl -b cookies.txt -u admin:admin http://FluxServer:7186/cluster/repositoryFlowCharts/download?namespace=/Workflow
Returns the workflow XML

SignOut of a session

curl -b cookies.txt -d " " http://FluxServer:7186/cluster/session/signOut
Returns: {"message":"Success"}
curl -b cookies.txt -u admin:admin -d " " http://FluxServer:7186/cluster/session/signOut
Returns: {"message":"Success"}


Submit a workflow from the Flux Repository to the Engine and Populate it with variables (startTemplateWithVariables)

This example is a little more involved. This curl command was constructed using the POSTMAN tool - a Google Chrome Add-in. POSTMAN allows one to test and create REST calls. Using such tools is not required, but they do simplify building and testing REST calls.

Flux has a REST service that allows one to start a workflow and pass that workflow variables at startup. In this case we created a simple workflow that only contains a mail action and named it '/DEMO/MailAction'. We then saved it to the Flux Repository.

The workflow has 3 workflow variables defined in it - SENDTOADDRESS, SUBJECT, and BODY. In the Mail Action itself we use Flux's runtime substitution to map the mail action's toAddress to ${SENDTOADRESS}, subject to ${SUBJECT}, and body to ${BODY}. This REST API requires you specify a repository workflow name (i.e., 'template'), and the engine namespace  (i.e., 'namespace') you want to the template to run .

This curl command has embedded into the command the user name and password using Basic authorization. 

curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -F "template=/DEMO/MailAction" -F "namespace=/DEMO/MailAction" -F "" -F "subject=Test" -F "body=Test" "http://localhost:8080/cluster/flowCharts/startTemplateWithVariables"

To test this - load the attached workflow ffc file into your repository and modify it for your email server, username, password, and port. Then edit the above curl command and execute it - changing the Authentication string, sendToAddress, subject, and body to something of your choosing.

Returns: /DEMO/MailAction  (The name of the repository template submitted) or an error messages such as {"message":"No matching template found for namespace \/DEMO\/MailkAction"}.

Download the DEMO/MailAction workflow here: DEMO-MailAction.ffc


Call the Flux REST API Using Java

The following example demonstrates calling Flux's RESTful web services using Java. This code makes no assumptions about the returned data – it simply returns the json. But it does demonstrate the use of cookies to move from API call to API call. This jersey jar file must be in your classpath if, and only if, flux.jar is NOT on your classpath.  jersey-bundle-1.18.jar

If you are using the Flux REST API with flux.jar on the classpath, you must replace the 5 import statements referencing com.sun.jersey in the provided example with imports referencing Flux's embedded version of jersey. These Flux import statements are:

import jersey.client.api.client.Client;
import jersey.client.api.client.ClientResponse;
import jersey.client.api.client.WebResource;
import jersey.client.api.client.filter.HTTPBasicAuthFilter;
import jersey.core.core.util.MultivaluedMapImpl;

Sample Java Code to call Flux REST Services
import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.filter.HTTPBasicAuthFilter;
import com.sun.jersey.core.util.MultivaluedMapImpl;
import java.util.List;
public class RestJavaClient {
    public static void main(String[] args) {
        List<NewCookie> cookies;
        MultivaluedMap formData = new MultivaluedMapImpl();
        String signInResource = "";
        String signOutResource = "";
        String repoResource = "";
        try {
            Client client = Client.create();
            client.addFilter(new HTTPBasicAuthFilter("eval", "12345679"));
            WebResource signIn = client.resource(signInResource);
            WebResource signOut = client.resource(signOutResource);
            WebResource repo = client.resource(repoResource).queryParam("namespaceFilter", "/");
            // Signin
            WebResource.Builder builder = signIn.getRequestBuilder();
            ClientResponse response = builder.type("application/json").get(
            if (response.getStatus() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                        + response.getStatus());
            cookies = response.getCookies();
            for (NewCookie c : cookies) {
                System.out.println("Cookie from Server ... " + c.toString());
            System.out.print("Output from Server .... ");
            // Query for repository entries
            builder = repo.getRequestBuilder();
            response = builder.type("application/json").get(
            if (response.getStatus() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                        + response.getStatus());
            System.out.print("Output from Server .... ");
            // Signout
            builder = signOut.getRequestBuilder();
            response = builder.type("application/json").post(
            if (response.getStatus() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                        + response.getStatus());
            System.out.print("Output from Server .... ");
        } catch (Exception e) {


A successful run looks like:

Cookie from Server ... JSESSIONID=1v91o3o16klluh4lfkpop8akr;Version=1;Path=/
Output from Server .... {"message":"Success"}
Output from Server .... {"count":"2","matched":"2","repositoryElement":[{"creationTimestamp":"2013-10-25T17:01:48.278Z","creationTimestampFormatted":"25 Oct 2013 @ 17:01:48","id":"27","lastModifiedTimestamp":"2013-10-25T17:03:15.982Z","lastModifiedTimestampFormatted":"25 Oct 2013 @ 17:03:15","namespace":"/FLUX-SAMPLES/MFT-Example","owner":"admin"},{"creationTimestamp":"2013-12-12T16:02:15.031Z","creationTimestampFormatted":"12 Dec 2013 @ 16:02:15","id":"42","lastModifiedTimestamp":"2013-12-12T16:03:09.891Z","lastModifiedTimestampFormatted":"12 Dec 2013 @ 16:03:09","namespace":"/FLUX-SAMPLES/Ping","owner":"admin"}]}
Output from Server .... {"message":"Success"}

A failure to login looks like:

Cookie from Server ... JSESSIONID=1qiy9exofylmw8gj6apirvb9b;Version=1;Path=/
Output from Server .... {"error":"Login failed.","evaluationLicense":"false","ldapSecurity":"false","licenseExpirationFormatted":"","menuItems":null,"pageSize":"0","perpetualLicense":"false","privileges":null,"propertiesInWebapp":"false","redirect":"signIn","secured":"false","supportAndMaintenanceExpirationFormatted":"","timeZone":"Etc/UTC"}
java.lang.RuntimeException: Failed : HTTP error code : 400
at RestJavaClient.main(
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(
at sun.reflect.DelegatingMethodAccessorImpl.invoke(
at java.lang.reflect.Method.invoke(
at com.intellij.rt.execution.application.AppMain.main(




  • No labels