Using the Shipping Engine Client Extension

Liferay DXP 2024.Q1+/Portal GA112+

You can use a client extension to add a new shipping engine to Liferay. This client extension from the sample workspace consists of a standalone Spring Boot application that communicates with Liferay using OAuth 2. See Configuring Shipping Methods to read more about the shipping methods available out-of-the-box with Liferay.

Prerequisites

1. Install a supported version of Java.

   Note

   See JVM Configuration for recommended JVM settings.

2. Download and unzip the sample workspace:

   curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip
   

   unzip -d liferay-sample-workspace com.liferay.sample.workspace-latest.zip
   

Now you have the tools to start and deploy the client extension(s) to Liferay.

Examine the Shipping Engine Client Extension

The client-extensions/liferay-sample-commerce-shipping-engine/client-extension.yaml file defines the shipping engine client extension in the sample workspace. There are three important blocks in the .yaml file that you must understand:

assemble:
    - fromTask: bootJar

The assemble block specifies that the standalone application/microservice is created with the bootJar command. This is available from the Spring Boot Gradle Plugin. The application JAR must be included in the LUFFA for deployment in Liferay SaaS.

liferay-sample-commerce-shipping-engine:
   key: liferay-sample-commerce-shipping-engine
   name: Liferay Sample Commerce Shipping Engine
   oAuth2ApplicationExternalReferenceCode: liferay-sample-commerce-shipping-engine-oauth-application-user-agent
   shippingEngineTypeSettings:
      key1: value1
      key2: value2
      key3: value3
      key4: value4
      key5: value5
   type: commerceShippingEngine

The liferay-sample-commerce-shipping-engine block contains the key configurations required for a shipping engine client extension. See Shipping Engine Client Extension YAML Reference for more information on each field.

liferay-sample-commerce-shipping-engine-oauth-application-user-agent:
   .serviceAddress: localhost:58081
   .serviceScheme: http
   name: Liferay Sample Commerce Shipping Engine OAuth Application User Agent
   scopes:
      - Liferay.Headless.Admin.Workflow.everything
   type: oAuthApplicationUserAgent

Another important part of the client-extension.yaml is in the liferay-sample-commerce-shipping-engine-oauth-application-user-agent definition. The serviceAddress parameter defines where the service runs locally and the serviceScheme parameter defines the protocol. The name field defines the name of the OAuth application user agent. The scopes field defines the access given to the headless API. This section sets up Liferay as the authorization server, so that the shipping engine you deploy next can invoke the resource server’s secure endpoints and send payloads. See OAuth User Agent YAML Configuration Reference for more information.

Deploy the Shipping Engine Client Extension

1. Go to the sample workspace.

2. Run

   ./gradlew initBundle
   

   This downloads a bundle inside the workspace’s /bundles folder.

3. Go to the /bundles/tomcat/bin folder. Run

   ./catalina run
   

4. Go back to the sample workspace’s /client-extensions/liferay-sample-commerce-shipping-engine folder.

5. Run

   ../../gradlew clean createClientExtensionConfig deploy
   

6. In Liferay’s log, confirm that the client extension deployed and started:

   2024-02-23 11:41:03.277 INFO  [com.liferay.portal.kernel.deploy.auto.AutoDeployScanner][AutoDeployDir:212] Processing liferay-sample-commerce-shipping-engine.zip
   2024-02-23 11:41:13.918 INFO  [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED liferaysamplecommerceshippingengine_7.4.13 [1504]
   

   In addition, messages about the OAuth user agent are logged.

   2024-02-23 11:41:14.066 INFO  [CM Event Dispatcher (Fire ConfigurationEvent: pid=com.liferay.oauth2.provider.configuration.OAuth2ProviderApplicationUserAgentConfiguration~liferay-sample-commerce-shipping-engine-oauth-application-user-agent)][InterpolationConfigurationPlugin:135] Replaced value of configuration property 'homePageURL' for PID com.liferay.oauth2.provider.configuration.OAuth2ProviderApplicationUserAgentConfiguration~liferay-sample-commerce-shipping-engine-oauth-application-user-agent
   2024-02-23 11:41:14.099 INFO  [CM Event Dispatcher (Fire ConfigurationEvent: pid=com.liferay.oauth2.provider.configuration.OAuth2ProviderApplicationUserAgentConfiguration~liferay-sample-commerce-shipping-engine-oauth-application-user-agent)][OAuth2ProviderApplicationUserAgentConfigurationFactory:170] OAuth 2 application with external reference code liferay-sample-commerce-shipping-engine-oauth-application-user-agent and company ID 44408322414245 has client ID id-536a55dd-89fb-f483-b719-328270d95199
   

7. Verify that the OAuth Application User Agent was added to Liferay. Go to Control Panel → OAuth2 Administration.

The Liferay Sample Commerce Shipping Engine OAuth Application User Agent provides the OAuth 2 authorization