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
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.
-
To post a workflow definition link, you need the workflow definition’s external reference code (ERC). Retrieve the workflow definitions in the system:
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:
The JSON response shows a new workflow definition link has been added:
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.
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:
Code:
WorkflowDefinitionLinks_GET_FromWorkflowDefinition.java
Command:
Code:
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:
Code:
WorkflowDefinitionLink_PUT_ByExternalReferenceCode.java
Command:
Code:
The API Explorer shows all of the WorkflowDefinitionLink
services and schemas and has an interface to try out each service.