Notifications API Basics

Liferay’s headless delivery application provides REST and GraphQL services for subscribing to or unsubscribing from notifications for platform events across several default applications. Access these services using methods such as cURL commands and Java classes.

You can manage notifications for these applications under the headless-delivery namespace: blogs, document folders, knowledge base articles, message board messages, message board sections, message board threads, structured content folders, structured content, wiki nodes, and wiki pages.

Start by setting up the environment and gathering the necessary information.

Setting Up the Environment

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 [e-mail] and the password test. When prompted, change the password to learn.

When signed in, retrieve the site ID. Use this ID in several service calls. In this example, the ID is 20117.

Then, follow these steps:

1. Download and unzip the example project:

   curl https://resources.learn.liferay.com/dxp/latest/en/process-automation/notifications/liferay-v3g2.zip -O
   

   unzip liferay-v3g2.zip
   

2. Check which subscriptions are active under your user account by executing the Subscriptions_GET_FromMyUserAccount.sh script.

   ./Subscriptions_GET_FromMyUserAccount.sh
   

   The response should be empty since there are no active subscriptions:

   {
      "actions": {},
      "facets": [],
      "items": [],
      "lastPage": 1,
      "page": 1,
      "pageSize": 20,
      "totalCount": 0
   }
   

   Important

   Ensure the email and password specified in the --user option match those used in the scripts.

Subscribing to Notifications

Subscribe to notifications for various applications under the headless-delivery namespace.

To find which applications are available for subscription, use the Liferay API Explorer at [server]:[port]/o/api (e.g., http://localhost:8080/o/api).

In the API Explorer, click REST Applications and select the headless-delivery/v1.0 option.

Look for PUT methods that include subscribe or unsubscribe in their endpoint paths. For example, you can find endpoints like /v1.0/sites/{siteId}/blog-postings/subscribe for blog posting subscription actions.

Using REST Services

Use the REST API to subscribe to an application with the BlogPostings_PUT_Subscribe_ToSites.sh script. This script subscribes to notifications for blog postings on a site.

curl \
   "http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/blog-postings/subscribe" \
   --header "Content-type: application/json" \
   --request "PUT" \
   --user "[e-mail]:learn"

Tip

Modify the endpoint path to subscribe to other applications. For instance, to subscribe to notifications from a document folder, use http://localhost:8080/o/headless-delivery/v1.0/document-folders/{documentFolderId}/subscribe. The API Explorer provides additional details about available endpoints and their requirements.

1. On the command line, navigate to the curl folder. Execute the BlogPostings_PUT_Subscribe_ToSites.sh with your site ID as a parameter.

   BlogPostings_PUT_Subscribe_ToSites.sh [site-ID]
   

2. This call returns no output. Verify the subscription by executing Subscriptions_GET_FromMyUserAccount.sh. The result should include the contentType and the id for the subscription:

   {
      "actions" : { },
      "facets" : [ ],
      "items" : [ {
         "contentId" : 20117,
         "contentType" : "BlogPosting",
         "dateCreated" : "2024-09-09T21:56:12Z",
         "dateModified" : "2024-09-09T21:56:12Z",
         "frequency" : "instant",
         "id" : 32471,
         "siteId" : 20117
      } ],
      "lastPage" : 1,
      "page" : 1,
      "pageSize" : 20,
      "totalCount" : 1
   }
   

3. The REST service can also be called with a Java class. Navigate out of the curl folder and into the java folder. Compile the source files:

   javac -classpath .:* *.java
   

4. Run the BlogPostings_PUT_Subscribe_ToSites Java class. Replace the siteId value with your site ID:

java -classpath .:* -DsiteId=1234 BlogPostings_PUT_Subscribe_ToSites

Tip

For subscribing to other applications, identify the corresponding class for the target application. For example, use DocumentFolderResource for document folders. Update the method call to match the correct subscription method for the new resource.

1. Run the Subscriptions_GET_FromMyUserAccount class to verify the action was successful.

{"actions": {}, "items": [{"contentId": "20117", "contentType": "BlogPosting", "dateCreated": "2024-09-10T09:53:32-0300", "dateModified": "2024-09-10T09:53:32-0300", "frequency": "instant", "id": 32471, "siteId": 20117}], "page": 1, "pageSize": 10, "totalCount": 1}

Examine the cURL Command

The BlogPostings_PUT_Subscribe_ToSites.sh script subscribes to notifications for blog postings on a given site by calling a headless-delivery application REST service.

Here are the command’s arguments:

Arguments	Description
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/blog-postings/subscribe"	The REST service endpoint. Your site ID parameter replaces ${1}.
--header "Content-type: application/json" \	The media type (MIME type) of the resource sent to the server is JSON.
--request "PUT"	The HTTP method to invoke at the specified endpoint.
--user "[e-mail]:learn"	Basic authentication credentials.

Note

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

Examine the Java Class

The BlogPostings_PUT_Subscribe_ToSites.java class subscribes to notifications for blog postings on a given site.

Line (abbreviated)	Description
BlogPostingResource.Builder builder = ...	Gets a Builder for generating a BlogPostingResource service instance.
BlogPostingResource blogPostingResource = builder.authentication(...).build();	Specifies basic authentication and generates a BlogPostingResource service instance.
blogPostingResource.putSiteBlogPostingSubscribe(...);	Calls the blogPostingResource.putSiteBlogPostingSubscribe method, passing in a site ID.

Note that the project includes the com.liferay.headless.delivery.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.

Important

See BlogPostingResource for service details.

Using GraphQL Services

GraphQL services for notifications work similarly to their REST counterparts. Access the Liferay API Explorer to perform this action. Read Consuming GraphQL APIs to learn more about GraphQL queries and mutations.

1. Click GraphQL in the top right corner, add the following mutation query to the left column, and replace siteKey with your site ID:

   mutation {
      headlessDelivery_v1_0 {
         updateSiteBlogPostingSubscribe(siteKey: "20117")
      }
   }
   

2. Click Execute Query. The response should include a boolean value indicating whether the subscription was successful:

   {
      "data": {
         "headlessDelivery_v1_0": {
            "updateSiteBlogPostingSubscribe": true
         }
      }
   }
   

3. Verify the subscription with this query:

   {
      headlessAdminUser_v1_0 {
         myUserAccountSubscriptions {
            items {
            contentType
            dateCreated
            dateModified
            frequency
            id
            siteId
            }
         }
      }
   }
   

   The response should confirm the subscription to blog postings:

   {
      "data": {
         "headlessAdminUser_v1_0": {
            "myUserAccountSubscriptions": {
            "items": [
               {
                  "contentType": "BlogPosting",
                  "dateCreated": "2024-09-09T21:56:12Z",
                  "dateModified": "2024-09-09T21:56:12Z",
                  "frequency": "instant",
                  "id": 32471,
                  "siteId": 20117
               }
            ]
            }
         }
      }
   }
   

Unsubscribing From Notifications

Unsubscribe from notifications for applications under the headless-delivery namespace.

Using REST Services

To unsubscribe using the REST API, use the endpoint with the unsubscribe action. This is the counterpart to the subscribe endpoint used for notifications. In this example, the ./BlogPostings_PUT_Unsubscribe_ToSites.sh script unsubscribes from notifications for blog postings on a site.

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/blog-postings/unsubscribe" \
	--header "Content-type: application/json" \
	--request "PUT" \
	--user "[e-mail]:learn"

Replace [site-ID] with your site ID and run BlogPostings_PUT_Unsubscribe_ToSites.sh.

BlogPostings_PUT_Unsubscribe_ToSites.sh [site-ID]

This call returns no response. Verify the subscription is gone by executing Subscriptions_GET_FromMyUserAccount.sh. The result should be empty:

{
   "actions" : { },
   "facets" : [ ],
   "items" : [ ],
   "lastPage" : 1,
   "page" : 1,
   "pageSize" : 20,
   "totalCount" : 0
}

Alternatively, execute the corresponding Java class:

java -classpath .:* -DsiteId=1234 BlogPostings_PUT_Unsubscribe_ToSites

Run Subscriptions_GET_FromMyUserAccount.java to confirm the unsubscription was successful:

{"actions": {}, "items": [], "page": 1, "pageSize": 10, "totalCount": 0}

Using GraphQL Services

Unsubscribe from notifications using GraphQL services. Access the Liferay API Explorer for this task.

1. Click GraphQL in the top right corner. Add the following mutation query to the left column, replacing siteKey with your site ID:

   mutation {
      headlessDelivery_v1_0 {
         updateSiteBlogPostingUnsubscribe(siteKey: "20117")
      }
   }
   

2. Click Execute Query. The response indicates whether the user is unsubscribed:

   {
      "data": {
         "headlessDelivery_v1_0": {
            "updateSiteBlogPostingUnsubscribe": true
         }
      }
   }
   

Deleting a Subscription

Delete a subscription using the headless-admin-user namespace using an endpoint similar to the one used for Subscriptions_GET_FromMyUserAccount.sh. Execute the Subscriptions_DELETE_FromMyUserAccount.sh script, replacing [subscription-ID] with the specific subscription ID.

If the operation is successful, the server returns a 204 No Content response with no body.

Run the following command:

./Subscriptions_DELETE_FromMyUserAccount.sh [subscription-ID]

Verify the deletion by running Subscriptions_GET_FromMyUserAccount.sh.

Alternatively, delete a subscription by executing the Subscriptions_DELETE_FromMyUserAccount Java class, replacing -DsubscriptionId with the specific subscription ID:

java -classpath .:* -DsubscriptionId=1234 Subscriptions_DELETE_FromMyUserAccount

Verify the deletion by running Subscriptions_GET_FromMyUserAccount.java.

Using GraphQL Services

Delete a subscription using GraphQL services. Access the Liferay API Explorer for this task.

1. Click GraphQL in the top right corner. Add the following mutation query to the left column, replacing subscriptionId with your subscription ID:

   mutation {
      headlessAdminUser_v1_0 {
         deleteMyUserAccountSubscription(subscriptionId: 32672)
      }
   }
   

2. Click Execute Query. The response indicates whether the subscription is deleted:

   {
      "data": {
         "headlessAdminUser_v1_0": {
            "deleteMyUserAccountSubscription": true
         }
      }
   }
   

Related Topics

• Consuming REST Services
• API Headers Reference
• Consuming GraphQL APIs