Invoking Liferay Services

Liferay DXP provides many web services out-of-the-box. To see a comprehensive list of the available web services, navigate to http://localhost:8080/api/jsonws (assuming your localhost is running on port 8080). If you’ve deployed your own Service Builder-generated JSON web services, follow these guidelines for invoking them. These services are useful for creating single page applications and can even be used to create custom front-ends in Liferay DXP.

This tutorial explains how to invoke these web services using JavaScript.

Invoking Web Services via JavaScript

Liferay DXP 7.1 contains a global JavaScript object called Liferay that has many useful utilities. One method is Liferay.Service, which invokes JSON web services.

The Liferay.Service method takes four possible arguments:

service {string|object}: Specify the service name or an object with the keys as the service to call, and the value as the service configuration object. (Required)

data {object|node|string}: Specify the data to send to the service. If the object passed is the ID of a form or a form element, the form fields will be serialized and used as the data.

successCallback : A function to execute when the server returns a response. It receives a JSON object as its first parameter.

exceptionCallback : A function to execute when the response from the server contains a service exception. It receives an exception message as its first parameter.

One of the benefits of using the Liferay.Service method versus using a standard AJAX request is that it handles the authentication for you.

Below is an example configuration of the Liferay.Service method:

Liferay.Service(
        '/user/get-user-by-email-address',
        {
                companyId: Liferay.ThemeDisplay.getCompanyId(),
                emailAddress: 'test@liferay.com'
        },
        function(obj) {
                console.log(obj);
        }
);

The example above retrieves information about a user by passing its companyId and emailAddress. The response data resembles the following JSON object:

{
        "agreedToTermsOfUse": true,
        "comments": "",
        "companyId": "20116",
        "contactId": "20157",
        "createDate": 1471990639779,
        "defaultUser": false,
        "emailAddress": "test@liferay.com",
        "emailAddressVerified": true,
        "facebookId": "0",
        "failedLoginAttempts": 0,
        "firstName": "Test",
        "googleUserId": "",
        "graceLoginCount": 0,
        "greeting": "Welcome Test Test!",
        "jobTitle": "",
        "languageId": "en_US",
        "lastFailedLoginDate": null,
        "lastLoginDate": 1471996720765,
        "lastLoginIP": "127.0.0.1",
        "lastName": "Test",
        "ldapServerId": "-1",
        "lockout": false,
        "lockoutDate": null,
        "loginDate": 1472077523149,
        "loginIP": "127.0.0.1",
        "middleName": "",
        "modifiedDate": 1472077523149,
        "mvccVersion": "7",
        "openId": "",
        "portraitId": "0",
        "reminderQueryAnswer": "test",
        "reminderQueryQuestion": "what-is-your-father's-middle-name",
        "screenName": "test",
        "status": 0,
        "timeZoneId": "UTC",
        "userId": "20156",
        "uuid": "c641a7c9-5acb-aa68-b3ea-5575e1845d2f"
}

Now that you know how to send an individual request, you’re ready to run batch requests.

Batching Requests

Another way to invoke the Liferay.Service method is by passing an object with the keys of the service to call and the value of the service configuration object.

Below is an example configuration for a batch request:

Liferay.Service(
        {
                '/user/get-user-by-email-address': {
                        companyId: Liferay.ThemeDisplay.getCompanyId(),
                        emailAddress: 'test@liferay.com'
                }
        },
        function(obj) {
                console.log(obj);
        }
);

You can invoke multiple services with the same request by passing in an array of service objects. Here’s an example:

Liferay.Service(
        [
                {
                        '/user/get-user-by-email-address': {
                                companyId: Liferay.ThemeDisplay.getCompanyId(),
                                emailAddress: 'test@liferay.com'
                        }
                },
                {
                        '/role/get-user-roles': {
                                userId: Liferay.ThemeDisplay.getUserId()
                        }
                }
        ],
        function(obj) {
                // obj is now an array of response objects
                // obj[0] == /user/get-user-by-email-address data
                // obj[1] == /role/get-user-roles data

                console.log(obj);
        }
);

Next you can learn how to nest your requests.

Nesting Requests

Nested service calls bind information from related objects together in a JSON object. You can call other services in the same HTTP request and conveniently nest returned objects.

You can use variables to reference objects returned from service calls. Variable names must start with a dollar sign ($).

The example in this section retrieves user data with /user/get-user-by-id and uses the contactId returned from that service to then invoke /contact/get-contact in the same request.

Below is an example configuration that demonstrates these concepts:

Liferay.Service(
        {
                "$user = /user/get-user-by-id": {
                        "userId": Liferay.ThemeDisplay.getUserId(),
                        "$contact = /contact/get-contact": {
                                "@contactId": "$user.contactId"
                        }
                }
        },
        function(obj) {
                console.log(obj);
        }
);

Here is what the response data would look like for the request above:

{
        "agreedToTermsOfUse": true,
        "comments": "",
        "companyId": "20116",
        "contactId": "20157",
        "createDate": 1471990639779,
        "defaultUser": false,
        "emailAddress": "test@liferay.com",
        "emailAddressVerified": true,
        "facebookId": "0",
        "failedLoginAttempts": 0,
        "firstName": "Test",
        "googleUserId": "",
        "graceLoginCount": 0,
        "greeting": "Welcome Test Test!",
        "jobTitle": "",
        "languageId": "en_US",
        "lastFailedLoginDate": null,
        "lastLoginDate": 1472231639378,
        "lastLoginIP": "127.0.0.1",
        [...]
        "screenName": "test",
        "status": 0,
        "timeZoneId": "UTC",
        "userId": "20156",
        "uuid": "c641a7c9-5acb-aa68-b3ea-5575e1845d2f",
        "contact": {
                "accountId": "20118",
                "birthday": 0,
                [...]
                "createDate": 1471990639779,
                "emailAddress": "test@liferay.com",
                "employeeNumber": "",
                "employeeStatusId": "",
                "facebookSn": "",
                "firstName": "Test",
                "lastName": "Test",
                "male": true,
                "middleName": "",
                "modifiedDate": 1471990639779,
                [...]
                "userName": ""
        }
}

Now that you know how to process requests, you can learn how to filter the results.

Filtering Results

If you don’t want all the properties returned by a service, you can define a whitelist of properties. This returns only the specific properties you request in the object.

Below is an example of whitelisting properties:

Liferay.Service(
        {
                '$user[emailAddress,firstName] = /user/get-user-by-id': {
                        userId: Liferay.ThemeDisplay.getUserId()
                }
        },
        function(obj) {
                console.log(obj);
        }
);

To specify whitelist properties, place the properties in square brackets (e.g., [whiteList]) immediately following the name of your variable. The example above requests only the emailAddress and firstName of the user.

Below is the filtered response:

{
        "firstName": "Test",
        "emailAddress": "test@liferay.com"
}

Next you can learn how to populate the inner parameters of the request.

Inner Parameters

When you pass in an object parameter, you’ll often need to populate its inner parameters (i.e., fields).

Consider a default parameter serviceContext of type ServiceContext. To make an appropriate call to JSON web services you might need to set serviceContext fields such as scopeGroupId, as shown below:

Liferay.Service(
        '/example/some-web-service',
        {
                serviceContext: {
                        scopeGroupId: 123
                }
        },
        function(obj) {
                console.log(obj);
        }
);

Now you know how to invoke Liferay services!

Liferay DXP JavaScript Utilities

Accessing ThemeDisplay Information

« Liferay DXP JavaScript UtilitiesIntroduction to JavaScript Module Loaders »
Was this article helpful?
0 out of 0 found this helpful