Workflow Definition Link API Basics

Liferay DXP 2025.Q1+/Portal GA132+

You can manage workflow definition links from the Liferay UI or using Liferay’s REST APIs. In Liferay, the Control Panel → Process Builder → Configuration application configures a workflow definition link to a specific asset type across the instance, while the Site Administration → Configuration → Workflow application configures the link at the site scope. You can use the batch APIs to export these configurations from one environment and import into another, preserving your workflow-to-asset links in the new environment.

You can link a workflow definition to an asset at the site or instance scope.

Call these services to create and manage workflow definition links.

Adding a Workflow Definition Link

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.120-ga120

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps:

Download and unzip Workflow Definition Link API Basics.

	curl https://resources.learn.liferay.com/examples/liferay-z8b3.zip -O

	unzip liferay-z8b3.zip

To post a workflow definition link, you need the workflow definition’s external reference code (ERC). Retrieve the workflow definitions in the system:
```
curl -X 'GET' \
    'http://localhost:8080/o/headless-admin-workflow/v1.0/workflow-definitions' \
    --user 'test@liferay.com:learn'
```
Copy the single approver definition’s ERC from the response.
To link the JournalArticle model (i.e., web content articles) with the single approver workflow, invoke the cURL script to post a new WorkflowDefinitionLink, passing the single approver’s ERC as a parameter:
```
	./WorkflowDefinitionLink_POST_ToInstance.sh [workflow-definiton-erc]
```

curl \
    "http://localhost:8080/o/headless-admin-workflow/v1.0/workflow-definitions/by-external-reference-code/4d5690f0-9176-98be-2957-62df1f8e2b71/workflow-definition-links" \
    --data-raw '
        {
          "className": "com.liferay.journal.model.JournalArticle",
          "groupId": 0
        }' \
    --header "Content-Type: application/json" \
    --request "POST" \
    --user "test@liferay.com:learn"

{
  "className": "com.liferay.journal.model.JournalArticle",
  "externalReferenceCode": "eaf0fc24-4922-71e2-d555-24806bf338bb",
  "groupExternalReferenceCode": "L_GUEST",
  "groupId": 20117,
  "workflowDefinitionName": "Single Approver",
  "workflowDefinitionVersion": 1
}

The JSON response shows a new workflow definition link has been added:

{
  "actions" : { },
  "facets" : [ ],
  "items" : [ {
    "className" : "com.liferay.journal.model.JournalArticle",
    "externalReferenceCode" : "e6a75adc-4d47-2d72-797e-94931d754ed7",
    "groupExternalReferenceCode" : "",
    "groupId" : 0,
    "id" : 34149,
    "workflowDefinitionName" : "Single Approver",
    "workflowDefinitionVersion" : 1
  } ],
  "lastPage" : 1,
  "page" : 1,
  "pageSize" : 20,
  "totalCount" : 2
}
	```

1. Open the *Global Menu* and navigate to *Applications* &rarr; *Process Builder*. Go to the second page and see that the web content article asset is linked to the single approver workflow definition.

![Web content articles are linked with the single approver workflow definition.](./workflow-definition-link-api-basics/images/02.png)

1. The REST service can also be called using the Java client. Navigate out of the `curl` folder and into the `java` folder. Compile the source files:

	```bash
	javac -classpath .:* *.java
	```

1. Run the `WorkflowDefinitionLink_POST_ToInstance.java` class:

!!! important
    If you're using an older version of Liferay on Java 8, remove `--add-opens java.base/java.net=ALL-UNNAMED` in the subsequent sections.

## Examine the cURL Command

The `WorkflowDefinitionLink_POST_ToInstance.sh` script calls the REST service with a cURL command.

```bash
curl \
	"http://localhost:8080/o/headless-admin-workflow/v1.0/workflow-definitions/by-external-reference-code/${1}/workflow-definition-links" \
	--data-raw '
		{
			"className": "com.liferay.journal.model.JournalArticle",
			"groupId": 0
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

Here are the command’s arguments:

Arguments	Description
`--header "Content-Type: application/json"`	Indicates that the request body format is JSON.
`--request "POST"`	The HTTP method to invoke at the specified endpoint
`http://localhost:8080/o/headless_admin_change_this/v1.0/workflow-definitions`	The REST service endpoint
`--data-raw '{ add_data_here }`	The data you are requesting to post
`--user "test@liferay.com:learn"`	Basic authentication credentials

Note

Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application that uses OAuth2.

The other cURL commands use similar JSON arguments.

Examine the Java Class

The WorkflowDefinitionLink_POST_ToInstance.java class adds a workflow definition link by calling the WorkflowDefinitionLinkResource service.

	WorkflowDefinitionLink workflowDefinitionLink =
		workflowDefinitionLinkResource.
			postWorkflowDefinitionByExternalReferenceCodeWorkflowDefinitionLink(

This class invokes the REST service using only three lines of code:

Line (abbreviated)	Description
`WorkflowDefinitionLinkResource.Builder builder = ...`	Gets a `Builder` for generating a `WorkflowDefinitionLinkResource` service instance.
`WorkflowDefinitionLinkResource workflowdefinitionlinkResource = builder.authentication(...).build();`	Specifies basic authentication and generates a `WorkflowDefinitionLinkResource` service instance.
`WorkflowDefinitionLink workflowDefinitionLink = workflowDefinitionLinkResource.postWorkflowDefinitionByExternalReferenceCodeWorkflowDefinitionLink(...);`	Calls the `workflowDefinitionLinkResource.postWorkflowDefinitionByExternalReferenceCodeWorkflowDefinitionLink` method and passes the data to post.

Note that the project includes the com.liferay.headless.admin.workflow.client.jar file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api.

Note

The main method’s comment demonstrates running the class.

The other example Java classes are similar to this one, but call different WorkflowDefinitionLinkResource methods.

Important

See WorkflowDefinitionLink for service details.

Below are examples of calling other WorkflowDefinitionLink REST services using cURL and Java.

Get Workflow Definition Links from a Workflow Definition

You can list the workflow definition links for a workflow definition. Pass the workflow definition’s ERC as a parameter to the following cURL or Java command.

WorkflowDefinitionLinks_GET_FromWorkflowDefinition.sh

Command:

./WorkflowDefinitionLinks_GET_FromWorkflowDefinition.sh [workflow-definition-erc]

Code:

curl \
	"http://localhost:8080/o/headless-admin-workflow/v1.0/workflow-definitions/by-external-reference-code/${1}/workflow-definition-links" \
	--header "Accept: application/json" \
	--user "test@liferay.com:learn"

WorkflowDefinitionLinks_GET_FromWorkflowDefinition.java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DworkflowDefinitionExternalReferenceCode=[workflow-definition-erc] WorkflowDefinitionLinks_GET_FromWorkflowDefinition

Code:

public static void main(String[] args) throws Exception {
	WorkflowDefinitionLinkResource.Builder builder =
		WorkflowDefinitionLinkResource.builder();

	WorkflowDefinitionLinkResource workflowDefinitionLinkResource =
		builder.authentication(
			"test@liferay.com", "learn"
		).build();

	Page<WorkflowDefinitionLink> workflowDefinitionLink =
		workflowDefinitionLinkResource.
			getWorkflowDefinitionByExternalReferenceCodeWorkflowDefinitionLinksPage(
				System.getProperty(
					"workflowDefinitionExternalReferenceCode"),
				Pagination.of(1, 2));

	System.out.println(workflowDefinitionLink);
}

}

The instance’s WorkflowDefinitionLink objects appear in JSON.

Put a Workflow Definition Link

Completely overwrite an existing workflow definition link with the following cURL and Java commands. Note, replace [external-reference-code] with your workflow definition link’s ERC.

WorkflowDefinitionLink_PUT_ByExternalReferenceCode.sh

Command:

./WorkflowDefinitionLink_PUT_ByExternalReferenceCode.sh [external-reference-code]

Code:

curl \
	"http://localhost:8080/o/headless-admin-workflow/v1.0/workflow-definition-links/by-external-reference-code/${1}" \
	--data-raw '
		{
			"className": "com.liferay.blogs.model.BlogsEntry",
			"groupId": 0,
			"workflowDefinitionName": "Single Approver",
			"workflowDefinitionVersion": 1
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

WorkflowDefinitionLink_PUT_ByExternalReferenceCode.java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DworkflowDefinitionLinkId=[external-reference-code] WorkflowDefinitionLink_PUT_ByExternalReferenceCode

Code:

public static void main(String[] args) throws Exception {
	WorkflowDefinitionLinkResource.Builder builder =
		WorkflowDefinitionLinkResource.builder();

	WorkflowDefinitionLinkResource workflowDefinitionLinkResource =
		builder.authentication(
			"test@liferay.com", "learn"
		).build();

	WorkflowDefinitionLink workflowDefinitionLink =
		workflowDefinitionLinkResource.
			putWorkflowDefinitionLinkByExternalReferenceCode(
				System.getProperty(
					"workflowDefinitionLinkExternalReferenceCode"),
				new WorkflowDefinitionLink() {
					{
						className = "com.liferay.blogs.model.BlogsEntry";
						groupId = 0L;
						workflowDefinitionName = "Single Approver";
						workflowDefinitionVersion = 1;
					}
				});

	System.out.println(workflowDefinitionLink);
}

}

The API Explorer shows all of the WorkflowDefinitionLink services and schemas and has an interface to try out each service.

Capability: