Main Page

From lr-service-api (inactive) Wiki
Jump to: navigation, search

Contents

Introduction

Liferay 5.2 provides over the "tunnel-web" service an interface for (but not limited to) content and user administration. This interface is offered through Apache axis, meaning all comunication is done via SOAP, and all services are described through WSDL files.

Unfortunatelly, the methods provided by liferay are often difficult to understand and consume, therefore the need to create a new layer on top of them in order to increase usability of liferay's remote administration capabilities.

Download the lr-service-api at: http://maven-repo.evolvis.org/releases/org/evolvis/lr/service/lrServiceAPI/lr-service-api-ear/

Disclaimer

Although we aimed for full compatibility with out-of-the box Liferay v5.2.2, it was not possible to achieve some of the desired functionality without making adjustments to liferay itself. These changes only affect the [CompanyService] implementation, and are described in the affected methods.

Configuration

Liferay

First of all the access to tunnel-web must be activated. In order to achieve this stop JBoss and edit liferay-portal.war/WEB-INF/classes/portal-ext.properties to include following section:

  # enable tunnel 
  tunnel.servlet.hosts.allowed=server-ip
  tunnel.servlet.https.required=false
  axis.servlet.hosts.allowed=server-ip
  axis.servlet.https.required=false

Some notes on server-ip:

  • server-ip should be replaced by liferay with the real IP of the server, but this did not seem to work on our tests servers
  • 127.0.0.1 does not work
  • Hostnames do not work either.

Deployment

Once this changes are done, copy lr-service-api-ear.ear in jboss/server/all/deploy/ and start JBoss. Once up, JBoss will generate the WSDLs for the services implemented in lr-service-api and these are ready to use. The default path to access the services is defined by the maven variable ${project.artifactId}.

.properties file

In order for lr-service-api to work it needs to know the address to access liferay's tunnel-web, as well as user credentials to use the service. These variables are defined in example.properties under test/resources:

#
# * lr-service-api
# * Abstraction layer over lr's tunnel-web (Axis) interface.
# * Copyright (c) 2011 tarent solutions GmbH
# *
# * This program is free software: you can redistribute it and/or modify
# * it under the terms of the GNU Affero General Public License, version 3
# * as published by the Free Software Foundation.
# *
# * This program is distributed in the hope that it will be useful,
# * but WITHOUT ANY WARRANTY; without even the implied warranty of
# * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# * GNU Affero General Public License for more details.
# *
# * You should have received a copy of the GNU Affero General Public License
# * along with this program.  If not, see <http://www.gnu.org/licenses/
#
# properties needed by the api to connect to lr-tunnel (Configuration-Object)
org.evolvis.lr.service.lrServiceApi.test.lrServicePath = host:8080/tunnel-web/secure/axis/
org.evolvis.lr.service.lrServiceApi.test.userID=lr-id(suffix) eg (12345-sso)
org.evolvis.lr.service.lrServiceApi.test.password=pass
# properties needed by the ws client to connect to the api
org.evolvis.lr.service.lrServiceApi.test.ws.protocol=http
org.evolvis.lr.service.lrServiceApi.test.ws.lrServiceAPIHost=yourDomain.org
# properties needed to test the ScopeService
org.evolvis.lr.service.lrServiceApi.test.scopeService.scope.className=com.liferay.portal.model.Group
org.evolvis.lr.service.lrServiceApi.test.scopeService.scope.classPK=yourGroupsDatabasePK
# properties needed to test the AnnouncementService
org.evolvis.lr.service.lrServiceApi.test.announcementsService.scope.groupName=yourGroupsName

Please note that the last two sets of key-value pairs are only meant for test purposes and wont be needed for production environments.

The Configuration class

A configuration object is needed throughout lr-services-api in order to provide the api with the needed information to consume the services. Here is the soap definition of a configuration object:

<xs:complexType name="configuration">
   <xs:sequence>
      <xs:element minOccurs="0" name="lrServicePath" type="xs:string"/>
      <xs:element minOccurs="0" name="password" type="xs:string"/>
      <xs:element minOccurs="0" name="serviceHost" type="xs:string"/>
      <xs:element minOccurs="0" name="userID" type="xs:string"/>
   </xs:sequence>
</xs:complexType>

Available Services

All these services will need *at least* the following two parameters:

  • A serializable object meaningful for the context (i.e. Announcement, Company, user, etc.)
  • A configuration object.

First we will enumerate the main services alphabetically, and we will end with the less user-friendly, "support" services (they enable other services to achieve their goal).

AnnouncementService

The announcement service provides various operations for the management of [Announcements] in liferay.

The complexType "announcement"

   <xs:complexType name="announcement">
      <xs:sequence>
      <xs:element minOccurs="0" name="announcementID" type="xs:long"/>
      <xs:element minOccurs="0" name="content" type="xs:string"/>
      <xs:element minOccurs="0" name="displayDate" type="xs:dateTime"/>
      <xs:element minOccurs="0" name="title" type="xs:string"/>
      <xs:element minOccurs="0" name="type" type="xs:string"/>
   </xs:sequence>
</xs:complexType>

addAnnouncementForScope

(Announcement,Scope,Configuration)

addAnnouncement

(Announcement, String ClassName, long ClassPK, Configuration)

addAnnouncementForGroup

(Announcement,(String)GroupName, Configuration)

removeAnnouncement

(long announcementID , Configuration)

CompanyService

The company service provides various operations for the management of companies in liferay.

Please note: Although the service allows to create companies, it does not support removing them, as this would have needed serious changes to the liferay codebase.

The complexType "company"

<xs:complexType name="company">
   <xs:sequence>
      <xs:element name="accountId" type="xs:long"/>
      <xs:element maxOccurs="unbounded" minOccurs="0" name="addresses" nillable="true" type="tns:addressSoap"/>
      <xs:element name="companyId" type="xs:long"/>
      <xs:element maxOccurs="unbounded" minOccurs="0" name="emailAddresses" nillable="true" type="tns:emailAddressSoap"/>
      <xs:element minOccurs="0" name="homeURL" type="xs:string"/>
      <xs:element minOccurs="0" name="industry" type="xs:string"/>
      <xs:element minOccurs="0" name="key" type="xs:string"/>
      <xs:element minOccurs="0" name="languageId" type="xs:string"/>
      <xs:element minOccurs="0" name="legalId" type="xs:string"/>
      <xs:element minOccurs="0" name="legalName" type="xs:string"/>
      <xs:element minOccurs="0" name="legalType" type="xs:string"/>
      <xs:element name="logoId" type="xs:long"/>
      <xs:element minOccurs="0" name="mx" type="xs:string"/>
      <xs:element minOccurs="0" name="name" type="xs:string"/>
      <xs:element maxOccurs="unbounded" minOccurs="0" name="phones" nillable="true" type="tns:phoneSoap"/>
      <xs:element name="primaryKey" type="xs:long"/>
      <xs:element minOccurs="0" name="sicCode" type="xs:string"/>
      <xs:element minOccurs="0" name="size" type="xs:string"/>
      <xs:element minOccurs="0" name="tickerSymbol" type="xs:string"/>
      <xs:element minOccurs="0" name="timeZoneId" type="xs:string"/>
      <xs:element minOccurs="0" name="type" type="xs:string"/>
      <xs:element minOccurs="0" name="virtualHost" type="xs:string"/>
      <xs:element minOccurs="0" name="webId" type="xs:string"/>
      <xs:element maxOccurs="unbounded" minOccurs="0" name="websites" nillable="true" type="tns:websiteSoap"/>
   </xs:sequence>
</xs:complexType>

addCompany

(String webId, String virtualHost, String mx, Configuration)

getCompanyByCompanyID

(long companyId, Configuration)

getCompanyByWebId

(String webId, Configuration)

updateCompany

(Company, Configuration)

Please note: the update-call will not work on some liferay-portals (i.e. 5.2.2) without modifications:

  1. The given user has to be admin in the given company as liferay doesnt check if the user is Omni-Admin. You can fix that by changing updateCompany() in CompanyServiceImpl.java. Simply change if (!roleLocalService.hasUserRole(getUserId(), companyId, RoleConstants.ADMINISTRATOR, true)) {... to something like: if (!isOmniAdmin && !roleLocalService.hasUserRole(getUserId(), ... where boolean isOmniAdmin = PermissionCheckerFactoryUtil.create(userLocalService.getUser(getUserId()), true).isOmniadmin();
  2. tunnel web does not know and tell about a field "name" for company. this causes an AccountNameException since the field is null. You can fix this in CompanyLocalServiceImpl.java by replacing validate(name) with try {validate(name); } catch (AccountNameException e) {name = company.getWebId();} as liferay does set the name from the webID during internal use, too.

updateTimeZone

(String webId, String timeZone, Configuration)

Please note: the update-call will not work on some liferay-portals (i.e. 5.2.2) without modifications:

  1. The given user has to be admin in the given company as liferay doesnt check if the user is Omni-Admin. You can fix that by changing updateCompany() in CompanyServiceImpl.java. Simply change if (!roleLocalService.hasUserRole(getUserId(), companyId, RoleConstants.ADMINISTRATOR, true)) {... to something like: if (!isOmniAdmin && !roleLocalService.hasUserRole(getUserId(), ... where boolean isOmniAdmin = PermissionCheckerFactoryUtil.create(userLocalService.getUser(getUserId()), true).isOmniadmin();
  2. tunnel web does not know and tell about a field "name" for company. this causes an AccountNameException since the field is null. You can fix this in CompanyLocalServiceImpl.java by replacing validate(name) with try {validate(name); } catch (AccountNameException e) {name = company.getWebId();} as liferay does set the name from the webID during internal use, too.

GroupService

The group service provides various operations for the management of user groups in liferay.

Please note: Although the service allows to create groups, it does not support removing them, as this would have needed serious changes to the liferay codebase.

getGroupByName

(String, long comapanyID, Configuration)

getGroupById

(long groupID, Configuration)

addGroup

(String groupName, String groupDescription, Configuration)

RoleService

The role service provides various operations for the management of user roles in liferay.

The complexType "role"

<xs:complexType name="role">
   <xs:sequence>
      <xs:element name="classNameId" type="xs:long"/>
      <xs:element name="classPK" type="xs:long"/>
      <xs:element name="companyId" type="xs:long"/>
      <xs:element minOccurs="0" name="description" type="xs:string"/>
      <xs:element minOccurs="0" name="name" type="xs:string"/>
      <xs:element name="primaryKey" type="xs:long"/>
      <xs:element name="roleId" type="xs:long"/>
      <xs:element minOccurs="0" name="subtype" type="xs:string"/>
      <xs:element minOccurs="0" name="title" type="xs:string"/>
      <xs:element minOccurs="0" name="type" type="xs:string"/>
   </xs:sequence>
</xs:complexType>

getRoleByID

(long roleId, Configuration)

getRoleByName

(String Name, Configuration)

addRole

(Role, Configuration)

removeRole

(long roleId, Configuration)

UserService

The user service provides various operations for the management of users in liferay.

The complexType "user"

<xs:complexType name="user">
   <xs:sequence>
      <xs:element name="active" type="xs:boolean"/>
      <xs:element name="agreedToTermsOfUse" type="xs:boolean"/>
      <xs:element minOccurs="0" name="comments" type="xs:string"/>
      <xs:element name="companyId" type="xs:long"/>
      <xs:element name="contactId" type="xs:long"/>
      <xs:element minOccurs="0" name="createDate" type="xs:dateTime"/>
      <xs:element name="defaultUser" type="xs:boolean"/>
      <xs:element minOccurs="0" name="emailAddress" type="xs:string"/>
      <xs:element name="failedLoginAttempts" type="xs:int"/>
      <xs:element name="graceLoginCount" type="xs:int"/>
      <xs:element minOccurs="0" name="greeting" type="xs:string"/>
      <xs:element minOccurs="0" name="languageId" type="xs:string"/>
      <xs:element minOccurs="0" name="lastFailedLoginDate" type="xs:dateTime"/>
      <xs:element minOccurs="0" name="lastLoginDate" type="xs:dateTime"/>
      <xs:element minOccurs="0" name="lastLoginIP" type="xs:string"/>
      <xs:element name="lockout" type="xs:boolean"/>
      <xs:element minOccurs="0" name="lockoutDate" type="xs:dateTime"/>
      <xs:element minOccurs="0" name="loginDate" type="xs:dateTime"/>
      <xs:element minOccurs="0" name="loginIP" type="xs:string"/>
      <xs:element minOccurs="0" name="modifiedDate" type="xs:dateTime"/>
      <xs:element minOccurs="0" name="openId" type="xs:string"/>
      <xs:element minOccurs="0" name="password" type="xs:string"/>
      <xs:element name="passwordEncrypted" type="xs:boolean"/>
      <xs:element minOccurs="0" name="passwordModifiedDate" type="xs:dateTime"/>
      <xs:element name="passwordReset" type="xs:boolean"/>
      <xs:element name="portraitId" type="xs:long"/>
      <xs:element name="primaryKey" type="xs:long"/>
      <xs:element minOccurs="0" name="reminderQueryAnswer" type="xs:string"/>
      <xs:element minOccurs="0" name="reminderQueryQuestion" type="xs:string"/>
      <xs:element minOccurs="0" name="screenName" type="xs:string"/>
      <xs:element minOccurs="0" name="timeZoneId" type="xs:string"/>
      <xs:element name="userId" type="xs:long"/>
      <xs:element minOccurs="0" name="uuid" type="xs:string"/>
   </xs:sequence>
</xs:complexType>

getUserFromRequest

(Configuration)

getUserById

(long userId, Configuration)

ClassNameService

The class name service is a support service that provides a connection between classnames and their IDs. This classname should only be used in combination with (or by) other services.

ScopeService