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.
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 newWorkflowDefinitionLink
, 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* → *Process Builder*. Go to the second page and see that the web content article asset is linked to the single approver workflow definition.

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 |
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
.
The main
method’s comment demonstrates running the class.
The other example Java classes are similar to this one, but call different WorkflowDefinitionLinkResource
methods.
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.