Flower REST API

About

The Flower REST API is the API of Flower BPM for Jira. It lets you start and read the processes that Flower runs in Jira from your own tools, for example to start a process instance when an order arrives in your shop system. The reference at the end of this page documents the REST resources, the HTTP response codes, and example requests and responses.

Quick Start

All calls go to https://api.flower-bpm.com and use Basic auth with your Jira e-mail and an API token (see Authentication and Authorization). {jiraInstance} is the name of your Jira site: your-domain for your-domain.atlassian.net.

Start a process instance of the model BPMN-12:

# Replace the email, the API token, the Jira site, and the model key with your own values
curl --request POST \
  --user '[email protected]:freds_api_token' \
  --header 'Content-Type: application/json' \
  --data '{"model": "BPMN-12", "summary": "Order 4711"}' \
  'https://api.flower-bpm.com/flower/rest/api/1/your-domain/processInstance/'

The response is the new process instance as JSON. model is the key of the model and is required, summary is optional. With "nodes": "all" in the body, Flower creates the work items of all activities at once.

Endpoints at a Glance

For the format of a BPMN file, see Export and Import Your BPMN File.

Version and Status

Authentication and Authorization

The Flower REST API is protected in the same way as the Jira REST API. You use the same credentials as for a Jira Basic auth connection, and access follows the permissions of the Jira user. See Basic auth for REST APIs  for details.

Get an API Token (Jira Cloud)

Basic auth in Jira Cloud needs an API token instead of your password. This is more secure, because:

• You do not save your primary account password outside of where you sign in.
• You can revoke individual API tokens at any time.
• API tokens also work if your Atlassian organization has two-factor authentication or SAML enabled.

To create a token:

1. Open Atlassian account API tokens  and select Create API token.
2. Enter a name that describes what the token is for, and choose an expiration date between 1 and 365 days.
3. Copy the token and store it safely. You cannot display it again.

When a token expires, create a new one and update your integration. See Manage API tokens for your Atlassian account .

In Jira Data Center, use your username and password or a personal access token  as a bearer token.

Test Your Credentials

The following call checks your credentials with a simple Jira request. It returns your own Jira user. Use the same credentials for the Flower resources in the reference below.

# Replace the email, the API token, and the domain with your own values
curl --request GET \
  --user '[email protected]:freds_api_token' \
  --header 'Accept: application/json' \
  'https://your-domain.atlassian.net/rest/api/3/myself'

Read Flower Data with the Jira REST API

Models, process instances, and tasks are Jira work items. You can therefore also read them with Jira’s own search API and the Flower JQL fields, for example all open process instances:

# Searches all open process instances (Jira Cloud). Data Center uses /rest/api/2/search.
curl --request POST \
  --user '[email protected]:freds_api_token' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"jql": "flowerType = \"Process Instance\" AND resolution is EMPTY", "fields": ["summary", "status"], "maxResults": 50}' \
  'https://your-domain.atlassian.net/rest/api/3/search/jql'

See Search Flower Data with JQL for all Flower search fields.

Changes with the Move to Forge

Flower for Jira Cloud moves to Atlassian Forge (see Moving to Atlassian Forge and the Atlassian guide How to adopt Forge from Connect ). This changes the Flower REST API in two steps.

Step 1: The Call Runs with the Permissions of the Caller

Today, Flower does the work in Jira with its own app permissions, and the permissions of the API user do not matter. In a later release, the Flower REST API will pass your credentials on to Jira. Jira then decides with the permissions of the API user, exactly like for a call of the Jira REST API. Your credentials stay the same: Jira e-mail and API token. We will announce the date in the changelog before we switch.

You can prepare now. This is what the API user needs in Jira:

Once the switch is on, a missing permission makes the call fail with the status code Jira returns, usually 403, or 404 when the user cannot see the work item. Please check before we switch that your API user can create and edit process instances in the Jira UI. If this works there, it works through the API.

Step 2: Use Jira Directly (the Flower Endpoints Will Be Switched Off Later)

Everything the Flower endpoints do can also be done with the Jira REST API. This is the way we recommend for new integrations and for existing ones in the long run. The Flower endpoints stay for now. We will announce the date of their shut-off in the changelog well ahead of time.

Start a process instance: Work Type Mapping and Create Issue

Instead of createProcessInstance, you create a Jira work item. Flower starts the process on its own when the work item is created in a space and with a work type that you mapped to a model.

1. Open the Flower Settings, tab Jira Work Type Mapping, and map the Jira space and the work type to the published model. See Setup Flower.
2. Create a work item of this space and work type with the Jira REST API:

# Creates a work item. Flower starts the mapped process for it. Replace the values with your own.
curl --request POST \
  --user '[email protected]:freds_api_token' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"fields": {"project": {"key": "ORD"}, "issuetype": {"name": "Order"}, "summary": "Order 4711"}}' \
  'https://your-domain.atlassian.net/rest/api/3/issue'

The work item is the process instance. You find its tasks as linked work items and can read everything with the Jira search API (see Read Flower Data with the Jira REST API).

Read the BPMN of a model: the Attachment

Instead of getBpmnXml, you read the BPMN file of the model from Jira. When you publish a model, it gets the BPMN as an attachment named <MODEL-KEY>.bpmn, for example BPMN-12.bpmn, on the model work item.

# 1. Find the attachment of the model work item
curl --request GET \
  --user '[email protected]:freds_api_token' \
  --header 'Accept: application/json' \
  'https://your-domain.atlassian.net/rest/api/3/issue/BPMN-12?fields=attachment'
 
# 2. Download the file with the "content" url of the attachment named BPMN-12.bpmn
curl --location --user '[email protected]:freds_api_token' \
  'https://your-domain.atlassian.net/rest/api/3/attachment/content/10042' --output BPMN-12.bpmn

The API user needs Browse projects in the space of the models for both calls.

Reference

What’s Next?

• Search Flower Data with JQL: Find models, process instances, and tasks.
• Sync Magic: Call external services from a process with throw events.
• Setup Flower: Configure space and work types.