1. Liferay Help Center
  2. Liferay Portal 6.2 Developer Tutorials
  3. Service Builder and Services

Documentation

JSON Web Services Invocation Examples

This tutorial provides examples of invoking Liferay’s JSON web services via JavaScript, URL, and cURL. The same two examples (getting a user and adding a user) are used for each method of invocation so that you can understand the differences between them. This tutorial also includes an example of using JavaScript to invoke Liferay’s JSON web services from a portlet.

Loading AlloyUI

Liferay web pages use the AlloyUI JavaScript framework. Among the JavaScript objects created for each Liferay page is a Liferay object. This object includes a Service function that can be used to invoke Liferay’s API. To invoke Liferay web services via Liferay.Service(...), your JavaScript context must include the AlloyUI JavaScript framework. Liferay 6.2 uses AlloyUI 2.0.x. If you’re working in a JSP, you can load the AlloyUI taglib and wrap your JavaScript code in an <aui:script> tag. Here’s the required import:

<%@ taglib uri="http://alloy.liferay.com/tld/aui" prefix="aui" %>

To load specific AUI modules, specify them via the use attribute. (By default, the <aui:script> tag includes the base AUI module.) For example, to use the AUI node and event modules, wrap your code like this:

<aui:script use="node, event">
    // Liferay service invocation here
</aui:script>

If you’re not working in a JSP, you won’t have access to taglibs. In this case, you can create an AUI context manually. For example, use the following HTML fragment to load the AUI seed and CSS files:

<script src="http://cdn.alloyui.com/2.0.0/aui/aui-min.js"></script>
<link href="http://cdn.alloyui.com/2.0.0/aui-css/css/bootstrap.min.css" rel="stylesheet"></link>

Then you can create an AUI context like this:

AUI().use('aui-base', function(A){
    // Liferay service invocation here
});

Now you’re ready to invoke Liferay’s JSON web services.

Get User JSON Web Service Invocation via JavaScript

Let’s examine a simple JSON web service invocation in JavaScript:

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

If you run this code, the test@liferay.com user (JSON object) is logged to the JavaScript console.

The Liferay.Service(...) function takes three arguments:

  1. A string representing the service being invoked
  2. A parameters object
  3. A callback function

The callback function takes the result of the service invocation as an argument.

Add User JSON Web Service Invocation via JavaScript

Here’s an example JSON web service invocation in JavaScript that adds a new user. It requires a lot more parameters than the one for retrieving a user!

Liferay.Service(
    '/user/add-user',
    {
        companyId: Liferay.ThemeDisplay.getCompanyId(),
        autoPassword: false,
        password1: 'test',
        password2: 'test',
        autoScreenName: false,
        screenName: 'joe.bloggs',
        emailAddress: 'joe.bloggs@liferay.com',
        facebookId: 0,
        openId: '',
        locale: 'en_US',
        firstName: 'Joe',
        middleName: 'T',
        lastName: 'Bloggs',
        prefixId: 0,
        suffixId: 0,
        male: true,
        birthdayMonth: 1,
        birthdayDay: 1,
        birthdayYear: 1970,
        jobTitle: 'Tester',
        groupIds: null,
        organizationIds: null,
        roleIds: null,
        userGroupIds: null,
        sendEmail: false,
        serviceContext: {assetTagNames: ['test']}
    },
    function(obj) {
        console.log(obj);
    }
);

Including the specified serviceContext object assigns the test tag to the newly created user. Note that you can use JSON syntax to supply values for objects and arrays. For example, to supply a value for the serviceContext object, you use curly brackets: { and }. And to supply a value for the assetTagNames array, you use square brackets: [ and ]. Thus, the line serviceContext: {assetTagNames: ['test']} indicates that serviceContext is an object containing an array named assetTagNames which contains the string test.

Invoking JSON Web Services via JavaScript in a Portlet

You can adapt the example from the previous section for use in a custom portlet. For example, the JSP page below provides a form that allows a first name, middle name, last name, screen name, and email address to be specified. When the user clicks the Add User button, these values are used to create a new user.

<%@ taglib uri="http://alloy.liferay.com/tld/aui" prefix="aui" %>
<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet" %>

<portlet:defineObjects />

<portlet:renderURL var="successURL">
    <portlet:param name="mvcPath" value="/success.jsp"/>
</portlet:renderURL>

<portlet:renderURL var="failureURL">
    <portlet:param name="mvcPath" value="/failure.jsp"/>
</portlet:renderURL>

<aui:form method="GET" name="<portlet:namespace />fm">
    <aui:fieldset>
        <aui:input label="First Name" name="first-name"></aui:input>
        <aui:input label="Middle Name" name="middle-name"></aui:input>
        <aui:input label="Last Name" name="last-name"></aui:input>
        <aui:input label="Screen Name" name="screen-name"></aui:input>
        <aui:input label="Email Address" name="email-address"></aui:input>
    </aui:fieldset>

        <p>Click the button below to add a new user by invoking Liferay's JSON web services.</p>
        
        <aui:button-row>
            <aui:button id="add-user" value="Add User">
            </aui:button>
        </aui:button-row>
</aui:form>

<aui:script use="node, event">
var addUserButton = A.one('#add-user');

var firstNameNode = A.one('#<portlet:namespace />first-name');
var middleNameNode = A.one('#<portlet:namespace />middle-name');
var lastNameNode = A.one('#<portlet:namespace />last-name');
var screenNameNode = A.one('#<portlet:namespace />screen-name');
var emailAddressNode = A.one('#<portlet:namespace />email-address');

addUserButton.on('click', function(event) {
        var firstName = firstNameNode.get('value');
        var middleName = middleNameNode.get('value');
        var lastName = lastNameNode.get('value');
        var screenName = screenNameNode.get('value');
        var emailAddress = emailAddressNode.get('value');

    var user = Liferay.Service(
        '/user/add-user',
        {
            companyId: Liferay.ThemeDisplay.getCompanyId(),
            autoPassword: false,
            password1: 'test',
            password2: 'test',
            autoScreenName: false,
            screenName: screenName,
            emailAddress: emailAddress,
            facebookId: 0,
            openId: '',
            locale: 'en_US',
            firstName: firstName,
            middleName: middleName,
            lastName: lastName,
            prefixId: 0,
            suffixId: 0,
            male: true,
            birthdayMonth: 1,
            birthdayDay: 1,
            birthdayYear: 1970,
            jobTitle: 'Tester',
            groupIds: null,
            organizationIds: null,
            roleIds: null,
            userGroupIds: null,
            sendEmail: false,
            serviceContext: {assetTagNames: ['test']}
        },
        function(obj) {
            console.log(obj);
            
            if (obj.hasOwnProperty('createDate')) {             
                window.open('<%= successURL %>', '_self');
            }
            else {
                window.open('<%= failureURL %>', '_self');
            }
        }
    );
});
</aui:script>

In this example, it’s assumed that the JSP page is part of a portlet plugin that uses or extends Liferay’s MVCPortlet class. This is required since the mvcPath URL parameter is used in the snippet above. It’s also assumed that the JSP code is in a file named view.jsp and that there are also success.jsp and failure.jsp files in the same directory. To view a sample portlet that uses the code above, please refer to the Sample JSON Web Services portlet. If you want to deploy the portlet, make sure to first read the deployment instructions in the README.markdown file.

Get User JSON Web Service Invocation via URL

Here’s a simple JSON web service invocation via URL that returns the user with the specified email address:

http://localhost:8080/api/jsonws/user/get-user-by-email-address/company-id/20154/email-address/test%40liferay.com?p_auth=[value]

This web service invocation returns the test@liferay.com user. The URL that’s provided by Liferay’s JSONWS API page when you click on URL Example after invoking a service omits the p_auth URL query parameter. It’s assumed that you’ll add it yourself. Remember that you must be logged in as a user with the required permission in order to be able to invoke a web service. Also, you must supply the p_auth token as a URL parameter. Please see the Invoking JSON Web Services tutorial for information on finding the p_auth token value that corresponds to your session.

If you read the Invoking JSON Web Services tutorial, you learned that you can supply parameters as either URL path parameters or as URL query parameters. In the example above, the company ID and email address are supplied as URL path parameters. Here’s an equivalent example using URL query parameters:

http://localhost:8080/api/jsonws/user/get-user-by-email-address?companyId=20154&emailAddress=test@liferay.com&p_auth=[value]

Next, you’ll consider an example that requires a lot more parameters!

Add User JSON Web Service Invocation via URL

Here’s an example JSON web service invocation via URL that adds a new user with the specified attributes:

http://localhost:8080/api/jsonws/user/add-user/company-id/20154/auto-password/false/password1/test/password2/test/auto-screen-name/false/screen-name/joe.bloggs/email-address/joe.bloggs%40liferay.com/facebook-id/0/-open-id/locale/en_US/first-name/Joe/middle-name/T/last-name/Bloggs/prefix-id/0/suffix-id/0/male/true/birthday-month/1/birthday-day/1/birthday-year/1970/job-title/Tester/-group-ids/-organization-ids/-role-ids/-user-group-ids/send-email/false?p_auth=[value]

And here’s the same example using URL query parameters instead of URL path parameters:

http://localhost:8080/api/jsonws/user/add-user?companyId=20154&autoPassword=false&password1=test&password2=test&autoScreenName=false&screenName=joe.bloggs&emailAddress=joe.bloggs@liferay.com&facebookId=0&-openId&locale=en_US&firstName=Joe&middleName=T&lastName=Bloggs&prefixId=0&suffixId=0&male=true&birthdayMonth=1&birthdayDay=1&birthdayYear=1970&jobTitle=Tester&-groupIds&-organizationIds&-roleIds&-userGroupIds&sendEmail=false&p_auth=[value]

Get User JSON Web Service Invocation via cURL

Here’s an example JSON web service invocation via the cURL tool that returns the user with the specified email address:

curl http://localhost:8080/api/jsonws/user/get-user-by-email-address \
  -u test@liferay.com:test \
  -d companyId=20154 \
  -d emailAddress='test@liferay.com'

cURL is a command line tool. You can execute the command above from a terminal or command prompt.

Add User JSON Web Service Invocation via cURL

Here’s an example JSON web service invocation via the cURL tool that adds the user with the specified attributes:

curl http://localhost:8080/api/jsonws/user/add-user \
  -u test@liferay.com:test \
  -d companyId=20154 \
  -d autoPassword=false \
  -d password1='test' \
  -d password2='test' \
  -d autoScreenName=false \
  -d screenName='joe.bloggs' \
  -d emailAddress='joe.bloggs@liferay.com' \
  -d facebookId=0 \
  -d openId='0' \
  -d locale=en_US \
  -d firstName='Joe' \
  -d middleName='T' \
  -d lastName='Bloggs' \
  -d prefixId=0 \
  -d suffixId=0 \
  -d male=true \
  -d birthdayMonth=1 \
  -d birthdayDay=1 \
  -d birthdayYear=1970 \
  -d jobTitle='Tester' \
  -d groupIds= \
  -d organizationIds= \
  -d roleIds= \
  -d userGroupIds= \
  -d sendEmail=false

Great! Now you’ve seen how to invoke Liferay’s JSON web services from JavaScript, URL, and cURL.

Invoking JSON Web Services

« JSON Web Services InvokerPortal Configuration of JSON Web Services »
Was this article helpful?
0 out of 1 found this helpful