Web Service Catalog

RSS Service

Description

The RSS service implemented in and available from the portal2012-services.war web application archive supports straight forward and conditional GET queries from RSS clients using the rss_2.0 protocol standard.

The Portal2012 Search Portlets provide the means for a user to save a reference to an executed document query in order to access it later in the portal using the ‘My Saved Queries' portlet and also to create an RSS feed link that  will also point to the saved document query's results. These RSS feed links are handled by the Portal2012 RSS service which returns a page with the newest results for the referenced saved query.

Service Architecture

The service was developed on top of the Spring Framework and ROME API in order to support request handling and RSS content construction.

Whenever an RSS request is received, its parameters are interpreted in order to get the corresponding SavedQuery details from the User Profiling database, execute that query to the IDOL service and return the newest relevant results as an rss_2.0 feed to the RSS client.

Also, the portal2012-services module depends on the portal2012-data-service module by referencing it in its project object model file.

Integration of RSS Service

The portal2012-services.war is packaged a Liferay Portlet war so it has to be deployed through Liferay's deployment process, but any servlets that are included in the application will receive requests starting from the ‘/portal2012-services' context path combined with the additional servlet mappings that are configured with the included servlets.

The servlet responsible for handling RSS requests is made available through the RSSController  which is a Spring Framework @Controller annotated class which contains a @RequestMapping annotated method with the context path mapping of ‘/savedQuery'. So, the RSS requests for a user's saved queries have to be issued to the address ‘http://liferay-host:port/portal2012-services/savedQuery'.

In order to obtain the RSS feed for a given saved query the following request parameters must be sent:

Parameter Name

Type

Description

queryid

LONG

The saved query identifier, issued at the corresponding SavedQuery entity creation through the ‘Save Query' functionality in the search results page of the portal.

userid

STRING

Optional.

The identifier of the user that saved the query. This value is the same as the username with which a user autheniticates in the Portal.

hash

STRING

A control value generated when the SavedQuery entity is created.

The link containing all the above mentioned parameters is generated and stored in the SavedQuery entity when a user specifies in the search results page or the ‘My Portal' page that the query he is saving should also be accessed through RSS.

Short URL service

The Short URL service is meant to be used by users to create shorter URL for document detail page. Thus, the URL won't be trimmed by other applications, preventing broken links.

The service is defined in portal2012-data module and it persists in the database URL's with an id. To make it easier for portlets to create short URL's, a helper class is available (named "ShortUrlHelper") in portal2012-portlet module. The method createShortUrl(String url) found in this class persists the url and returns a case sensitive string id, representing a long value encoded in base 62.

The redirection to the real URL is made in a filter implemented in portal2012-hook module. The filter is mapped on "/s/*" patterns, matching every URL that starts with "/s/". After this string, the short URL identifier is found.

In the processFilter method, the real URL is searched in the service, based on the decoded short URL id, then the user is redirected to the requested document detail page.

List of other web services

Services provided by PO-PROFILING-SERVICES can be executed by issuing HTTP commands on service URL. Http commands that can be issued are:

  • GET – to retrieve single result or a list of results
  • PUT – to save or update profiling information
  • DELETE – to remove a specific profiling information

Parameters of the services are divided in two categories:

  • Path parameters – are parameters for which the value is retrieved from the URL path
  • Query parameters – are parameters for which the value is retrieve from http request parameters.

The result of each PO-PROFILING-SERVICES services invocation represents a well formed XML of java object serialized with JAXB and it is composed from two parts:

  • A response header part which contains the outcome of the invocation (if it was successful or not) and about the list of error, warning and information messages generated by the invocation
  • A response body that contains the actual result.

The definition of PO-PROFILING-SERVICES is provided as a WADL (Web Application Description Language) file together with an XML schema that contains the definition of the messages.

OrganisationService

The service include the operations that enable management of organizations within OP authentication system

Method

Description

HTTP Method

Path

Query parameters

Result

saveOrganisation

Method used to create or update an existing organization

PUT

/organisation

OrganisationViewModel – object that encapsulates organization attributes

ResponseMessage- containing the status of the operation

getOrganisation

Method used to retrieve a specific organization details

GET

/organisation

Name – the code of the organization to be retrieved

OrganisationViewModelMessage – object that encapsulates  the organization detail message

removeOrganisation

Method used to remove a specific organization

DELETE

/organisation

Name – the name of the organizations to be retrieved

ResponseMessage- containing the status of the operation

getOrganisations

Method used to search for organizations

GET

/organization/search

Name – organization name pattern to search for

OrganizationViewModelListMessage – that encapsulates the list of organizations that matches the name pattern provided as parameter

 

SystemPrivilegeService

The service provides methods to manage privileges associated with systems.

Method

Description

HTTP Method

Path

Parameters

Result

saveSystemPrivilege

Method used to create a privilege associated with a system

PUT

/system/privilege

system – the system code

privilege – the privilege code

ResponseMessage containing the status of the operation

removeSystemPrivilege

Method used to remove a privilege from a system

DELETE

/system/privilege

system – the system code

privilege – the privilege code

ResponseMessage containing the status of the operation

searchSystemPrivileges

Method used to search

GET

/system/privilege/search

System – the system code

priviletePattern – privileges pattern to search for

SystemPrivilegeListMessage – object that encapsulates the list of privileges that match the search criteria

 

SystemRoleService

The service contains methods to manage roles associated to systems.

Method

Description

HTTP Method

Path

Parameters

Result

saveSystemRole

Method used to create or update a system associated role

PUT

/system/role

System – the system code

SystemRoleViewModel – the role to be saved. The role include also the list of system privileges associated to it

ResponseMessage containing the status of the operation

removeSystemRole

Method used to remove a role from a system

DELETE

/system/role

 

ResponseMessage containing the status of the operation

getSystemRoles

Method used to retrieve the list of roles associated with a given system. The roles can be filtered based on role name

GET

/system/role

System – the code of the system

RolePattern – the role pattern to search for

SystemRolesListMessage encapsulating the list  roles that match the provided pattern for the given system

addRolePrivilege Method used to add role privileges PUT /system/role/privilege

System – the code of the system

Role - the role

Privilege - the privilege of the role

ResponseMessage - success or error
removeRolePrivilege Method used to remove role privileges delete /system/role/privilege

System – the code of the system

Role - the role

Privilege - the privilege of the role

ResponseMessage - success or error

 

UserSystemService

The service contains methods to create user identities and user profile data associated with a specific System

Method

Description

HTTP Method

Path

Query parameters

Result

updateUser

Method used to create or update user identities and user profile preferences associated with the system received as parameter

PUT

/user/system/identity

SystemUserPutModel as XML post data. To minimize the calls between external systems and OP Profiling services the object encapsulates user organizations, address, roles associated  in the given system user attributes within the given system

ResponseMessage containing status of the operation: success or error

getSystemUser

Method used to retrieve user identity and user attributes for a specific system

GET

/user/system/identity

userId – the user id to be retrieved

system – the system to retrieve attributes for

SystemUserViewModelMessage – that encapsulates the user attributes and its system associated roles and attributes

getAllUserAttributes

Method used to retrieve all user attributes within a specific system

GET

/user/system/attribute

userId – the id of the user

System – the code of the system

UserAttributesListResponseMessage – response message that encapsulates user attributes associated with the system

addAttribute

Method used to create or update a user attribute within a given system

PUT

/user/system/attribute

userId – the user id

systemId – the system code

type – the type of the attribute

key – the attribute key(code)

value – the value of the attribute

ResponseMessage - containing status of the operation: success or error

deleteAttribute

Method used to remove an attribute associated to the user in the given system

DELETE

/user/system/attribute

userId – the id of the user

systemId – the system code

key – the attribute code

ResponseMessage - containing status of the operation: success or error

getUserAttributesByType

Method used to retrieve all user attributes within a specific system and for a specific user or specific type

GET

/user/system/attribute/type

System – the code of the system

User –optional user id

Type –the type of parameters

UserAttributesListResponseMessage - The list of user attributes that match the criteria

getUserAttributesByName

Method used to retrieve all user attributes within a specific system and for a specific user or with a specific key

GET

/user/system/attribute/name

System – the code of the system

User- optional the user id

Name- optional the attribute name

UserAttributesListResponseMessage - The list of user attributes that match the criteria

deleteAttributeValue

Method used to remove an attribute value without removing the attribute

DELETE

/user/system/attribute/value

System – the system code

User – the user id

Key – the attribute code

ResponseMessage - containing status of the operation: success or error

getUserRoles

Method used to retrieve the user roles within a given system

GET

/user/system/role

User – the user id

System – the system code

UserRolesListMessage – class that encapsulates the roles associated to the user in the given system.

addUserRole

Method used to associate a role to a user in a specific system

PUT

/user/system/role

Role – role code to be associated

User – the user id

System – the code of the system

ResponseMessage - containing status of the operation: success or error

removeUserRole

Method used to remove the association of a given role from a user

DELETE

/user/system/role

Role – role code to be associated

User – the user id

System – the code of the system

ResponseMessage - containing status of the operation: success or error

searchUserSystemProfile

The method is used to search for users which have preferences or associated roles in a given system

GET

/user/system/search

System – the system id

userIdpattern – the userid pattern to look for

firstNamePattern – the first name pattern to look for

lastNamePattern – the last name patter to look for

emailPattern – the email pattern to look for

SystemUserViewModelListMessage – object that encapsulates the list of users that are matching the search criteria.

getUserSystemPreferences

Method used to retrieve user preferences within a given system

GET

/user/system/preferences

userId – the id of the user

system – the system code

UserPreferenceViewModelListMessage – object that encapsulates the list of preferences objects

getUserSystemPreference

Method used to retrieve specific user preferences type from given system

GET

/user/system/preference

userId – the id of the user

system – the system code preferenceType – the type of preferences

UserPreferenceViewModelMessage = object that encapsulates all user preferences

getDefaultUserSystemPreference

Method used to retrieve default user preferences from given system

GET

/user/system//preference/def

userId – the id of the user

system – the system code

UserPreferenceViewModelMessage- object that encapsulates all user preferences

saveUserSystemPreference

Method used to add or update user preferences within a given system

PUT

/user/system/preference

UserPreferenceViewModel as XML post data

ResponseMessage- containing status of the operation: success or error

deleteUserSystemPreference

Method used to remove specific user preferences record

DELETE

/user/system/preference

userId – the id of the user

system – the system code preferenceType – the type of preferences to be removed

ResponseMessage- containing status of the operation: success or error

 

UserIdentityService

Method

Description

HTTP Method

Path

Query parameters

Result

getUser

Retrieves the identity of a user including its organizations, roles and attributes

GET

/user/profile

User- id of the user to be retrieved

SystemUserViewModelMessage

getUserOrganisations

Retrieves the list of a user organizations

GET

/user/organization

User- the name of the user to retrieve results for

UserOrganizationsResponseMessage – object that encapsulates the list of organizations associated to the user

addUserOrganisation

Method used to add an organization to a user

PUT

/user/organization

UserOrganisationViewModel – object containing details about organization to be added to the user

ResponseMessage - Status of the message – success or error

removeUserOrganisation

Method used to remove an organization from the user

DELETE

/user/organization

User – user to remove organization from

Organization – organization to be removed from the user

ResponseMessage - Status of the message – success or error

changePassword

Method used to change the password of an user

POST

/user/profile/changePassword

userId - the id of the user

oldPassword – old user password

newPassword– new user password

ResponseMessage- Status of the message – success or error

validatePassword

Method used to validate the password of an user

POST

/user/profile/verifyPassword

userId – id of the user to validate the password for

password – the password of the user

ResponseMessage- Status of the message – success or error

deleteUser

Method used to delete an user

DELETE

/user/profile

userId- id of the user to be deleted

ResponseMessage-- Status of the message – success or error

searchUsers

Method used to search for users

GET

/user/profile/search

userIdPattern – pattern of the username

firstNamePattern – pattern for the first name to search for

lastNamePattern – pattern for the last name to search for

emailPattern – pattern of the email to search for

SystemUserViewModelListMessage – object containing users that matches the search criteria.

getProfileAddress

Method used to retrieve the address of an user

GET

/profile/address

User – the id of the user to retrieve address for

AddressViewModelMessage – object containing the address of the user

saveProfileAddress

Method used to save or update the address of an user

PUT

/profile/address

User – the id of the user to save the address for

AddressViewModel – data transfer object containing the address details

ResponseMessage-- Status of the operation – success or error

deleteProfileAddress

Method used to delete a user address

DELETE

/profile/address

User – the id of the user to remove address from

ResponseMessage-- Status of the operation – success or error

getUserSummary
Method used to get the user summary object GET /user/userSummary

userId – the id of the user

systemId – the system code

UserSummaryViewModelMessage- object that encapsulates user summary data

UserGeneralPreferenceService

Method

Description

HTTP Method

Path

Query parameters

Result

getUserGeneralPreferences

Method used to retrieve the list of user preferences within a given system

GET

/user/preference/list

userId – the id of the user

System – the system code

UserPreferenceViewModelListMessage – object that encapsulates all preferences records within a system

getUserGeneralPreference

Method used to retrieve preferences of a specific type for a given system

GET

/user/preference

userId – the id of the user

System – the system code

preferenceType - type of preferences to be retrieved

UserPreferenceViewModelMessage- object that encapsulates user preferences data

getUserDefaultGeneralPreference

Method used to retrieve the default user preferences within a system

GET

/user/preference/ generalPreferences

userId – the id of the user

system – the code of the system

UserPreferenceViewModelMessage- object that encapsulates user preferences data

saveUserGeneralPreference

Method used to save user preferences within a system

PUT

/user/preference

userPreferenceViewModel as XML post DATA

ResponseMessage - Status of the operation – success or error

deleteUserGeneralPreference

Method used to delete a specific user preference object

DELETE

/user/preference

userId – the id of the user

systemId – the system code

preferenceType – the type of preferences to be deleted.

ResponseMessage- Status of the operation – success or error

 

DocumentRatingService

Method

Description

HTTP Method

Path

Query parameters

Result

getDocumentRating

Method used to retrieve the overall rating associated with a specific documented.

GET

/document/rating

System – optional system identifier to identify the system for which the document rating will  be retrieved

documentId – document cellar identifier.

DocumentRatingViewModelMessage – object that encapsulates the computed rating of the requested document and the status of the opperation

 

NotificationSubscriptionService

The service incorporates all the methods required for management of notification subscriptions.

Method

Description

HTTP Method

Path

Query parameters

Result

saveDocumentNotification

Method used to save a document notification

PUT

/user/notification/document

DocumentNotificationViewModel– object that encapsulates document notification attributes

ResponseMessage containing the status of the operation

getDocumentNotifications

Method used to retrieve the document notifications for a given system. The method can filter the system document notifications based on user id or document id

GET

/user/notification/document

System – the code of the system

userId –optional user id

documentId – optional document id

DocumentNotificationViewModelList – objects that contains the list of document notifications

deleteDocumentNotification

Method used to delete a specific document notification

DELETE

/user/notification/document

notificationId – the id of the notification to be deleted

ResponseMessage conaining the status of the message

saveQueryNotification

Method used to save a query notifications

PUT

/user/notification/query

QueryNotificationEventViewModel – object that encapsulates query notification attributes

ResponseMessage containing the status of the message

getQueryNotifications

Method used to retrieve the query notifications for a given system. Notifications can be filtered based on userId, notificationId, creation date and frequency

GET

/user/notification/query

System – mandatory system id

userId – optional user id to retrieve notifications for

queryNotificationId – the notification id

createdBefore – parameter to filter only notifications created before a specific date

frequency – parameter used to filter the notifications with a specific frequency

QueryNotificationViewModelList containing the list of notifications that are matching the query parameters.

deleteQueryNotification

Method used to delete a query notifications

DELETE

/user/notification/query

notificationId – id of the notification to be removed

ResponseMessage containing the status of the message

SavedDocumentsService

The service contains the methods used to manage the saved documents within OP profiling services.

Method

Description

HTTP Method

Path

Query parameters

Result

saveSavedDocument

Method used to save a document associated with a system and a user.

PUT

/user/saveddocument

SavedDocumentViewModel

ResponseMessage- containing the status of the operation

getSavedDocuments

Method used to retrieve the list of saved documents for a specific system and a specific user. The documents can be filtered based on cellarID.

GET

/user/saveddocument/savedDocument

System – the system id

userId – optional user id

id - predicate id

hash - predicate hash

cellarId – optional the document cellar id

SavedDocumentViewModelList – object that encapsulates all the saved documents that are matching the provided parameters

deleteSavedDocument

Method used to delete a saved document

DELETE

/user/saveddocument

savedDocumentId – the id of the document to be deleted

ResponseMessage- containing the status of the operation

 

SavedQueriesService

The service provides methods to manage the saved queries within the OP profiling services.

Method

Description

HTTP Method

Path

Query parameters

Result

getSavedQueries

Method used to retrieve the saved queries for a specific system. The queries may be filtered based on user id, saved query id, and rss flag

GET

/user/savedquery

System – system code

userId – optional user id

savedQueryId – optional saved query id

hash – optional hash value

rssOnly – optional flag to filter only queries with rss feeds.

SavedQueryViewModelListMessage – object that encapsulates all the queries that are matching the input parameters.

deleteSavedQuery

Method used to delete a saved query record

DELETE

/user/savedquery

savedQueryId – the id of the saved query to be removed.

ResponseMessage- containing the status of the operation

saveSavedQuery

Method used to create or update a saved query

PUT

/user/savedquery

SavedQueryViewModel

ResponseMessage- containing the status of the operation

getSavedQuery? Method used to retrieve the saved queries for a specific system. The queries may be filtered based on query id GET /user/query savedQueryId ResponseMessage - list of objects of SavedQueryViewModel - error with generic error response

 

UserRatingService

Service that provide required methods to manage ratings saved by users.

Method

Description

HTTP Method

Path

Query parameters

Result

saveUserRating

Method used to create or update a user rating record.

PUT

/user/rating

UserRatingViewModel as XML post data encapsulating the rating information

ResponseMessage- containing the status of the operation

deleteUserRating

Method used to delete a rating provided by a given user.

DELETE

/user/rating

Id – user rating id

ResponseMessage- containing the status of the operation

getUserRatings

Method used to retrieve user ratings. User ratings are retrieved per system. Optional the rating can be filtered based on document id in order to retrieve the user rating associated with a given document

GET

/user/rating

System – the system code

User –user id

document-id – optional the document id

UserRatingViewModelListMessage – object that encapsulates the list of user ratings.

 

UserAnnotationsService

The service contains the methods required to manage the annotations on documents

Method

Description

HTTP Method

Path

Parameters

Result

saveUserAnnotation

Method used to save a user annotation

PUT

/user/annotation

userAnnotationViewModel – as post XML data

ResponseMessage- containing the status of the operation

deleteUserAnnotation

Method used to delete a user annotation

DELETE

/user/annotation

userAnnotationId

document-id

ResponseMessage- containing the status of the operation

getUserAnnotations

Method used to retrieve a list of user annotations. The list of annotations can be filtered based on user, document identifier, annotation uuid.

GET

/user/annotation

System – the system code

User – the user id

document-id – the document id

uuid – the document uuid

annotationId – the annotation id

UserAnnotationViewModelListMessage – class that encapsulates all the annotation records that match the input parameters.

 

UserCommentsService

Service that provides services to manage user comments

Method

Description

HTTP Method

Path

Query parameters

Result

saveUserComment

Method used to create or update a user comment.

PUT

/user/comment

UserCommentViewModel – as post data

ResponseMessage

deleteUserComment

Method used to remove a user service.

DELETE

/user/comment/{id}

Id – Path parameter representing the identifier of the comment to be deleted

ResponseMessage

getUserCommentsForDocument

Method used to retrieve user comments for a specific system. The list of comments can be filtered based on user id or document id

GET

/user/comment

System – the system code

User – the user id

Document-id – the document id

UserCommentViewModelListMessage class that encapsulates the list of user comments that match the input parameters

 

UserWidgetService

Service that provides services access the widget component

Method

Description

HTTP Method

Path

Query parameters

Result

getUserWidgets

Method used to get user widgets on a specific user.

GET

/user/widgets

system - system id

user - user id

id - widget id

UserWidgetsViewModelListMessage - class that encapsulates all the widget records that match the input parameters. - error with gneric error message

saveUserWidget

Method used to user widget

PUT

/user/widgets

UserWidgetViewModel – class that encapsulates the user widget

ResponseMessage - status of the operation: success (the widget id) or error 

deleteUserWidget

Method used to delete a user widget

DELETE

/user/widgets

system - system id

user - user id

id - widget id

ResponseMessage - status of the operation: success or error