statusLevelService

Manages status level feature. StatusLevel levels allow the system to rank users by points or associate users with a specific group.

Method	Description
addPoints	Rewards points to a user.
addPoints	Rewards points to a user.
createStatusLevel	Creates a new points based StatusLevel.
createStatusLevel	Creates a new group based StatusLevel Level
deleteStatusLevel	Deletes a statusLevel level from the system
getAllStatusLevelScenarios	Returns all of the WSStatusLevelScenario objects.
getGroupStatusLevel	If there is a status level associated with the group passed in then the status level will be returned, Otherwise null will be returned.
getGroupStatusLevels	Returns an array of all group based status levels in the system.
getLeaders	Returns an array of system wide leaders.
getLeaders	Returns an array of system wide leaders.
getLeaders	Returns an Iterable of leaders for a specific community
getLeaders	Returns an Iterable of leaders for a specific container
getLeaders	Returns an Iterable of leaders for a specific community
getLeaders	Returns an Iterable of leaders for a specific container
getPointLevel	Returns the point level for a user system wide.
getPointLevel	Returns the status level points for a user in regards to a specific community
getPointLevel	Returns the status level points for a user in regards to a specific container
getPointStatusLevels	Returns an array of point based status levels in the system sorted by point range.
getStatusLevel	Used to acquire a specific status level object from the system
getStatusLevelByPoints	Used to get a status level by a point value.
getStatusLevelScenarioByCode	Returns a WSStatusLevelScenario by its code.
getStatusLevelScenarioByCode	Returns a WSStatusLevelScenario by its code.
getUserStatusLevel	Returns the system wide status level for specific user, will return null if there is no status level for this user.
isStatusLevelsEnabled	Returns true if status levels are enabled in the system
setStatusLevelsEnabled	Sets whether status levels should be enabled in the system.
updateStatusLevelScenario	Update the points and whether or not this scenario is included in status level results.

addPoints

Rewards points to a user. By providing the object and a reason we can tell which object the user is be rewarded on and a code explaining why.

Note that it is valid to submit negative point values to remove points from a user.

POST http://domain:port/application_context/rpc/rest/statusLevelService/addPoints

Arguments

Name	Type	Description
userID	xs:long	The ID of the user who is receiving points.
communityID	xs:long	The ID of the community the points are added to.
objectID	xs:long	The ID of the object the user should receive points on.
objectType	xs:int	Amount of points to award the user.
points	xs:long	A code explaining why the user is receiving points.
code	xs:string	The objectType of the object to add points for.

Arguments Template

<addPoints> 
    <userID>xs:long</userID>
    <communityID>xs:long</communityID>
    <objectID>xs:long</objectID>
    <objectType>xs:int</objectType>
    <points>xs:long</points>
    <code>xs:string</code>
</addPoints>

Errors

Error	When Returned
NotFound	Thrown if one of the ids for the specified object does not exist.

addPoints

Rewards points to a user. By providing the object and a reason we can tell which object the user is be rewarded on and a code explaining why.

Note that it is valid to submit negative point values to remove points from a user.

POST http://domain:port/application_context/rpc/rest/statusLevelService/addPointsByContainer

Arguments

Name	Type	Description
userID	xs:long	The ID of the user who is receiving points.
containerObjectID	xs:long	The ID of the container the points are added to.
containerObjectType	xs:int	The type of the container the points are added to.
objectID	xs:long	The ID of the object the user should receive points on.
objectType	xs:int	Amount of points to award the user.
points	xs:long	A code explaining why the user is receiving points (UTF8 encoded).
code	xs:string	The objectType of the object to add points for.

Arguments Template

<addPoints> 
    <userID>xs:long</userID>
    <containerObjectID>xs:long</containerObjectID>
    <containerObjectType>xs:int</containerObjectType>
    <objectID>xs:long</objectID>
    <objectType>xs:int</objectType>
    <points>xs:long</points>
    <code>xs:string</code>
</addPoints>

Errors

Error	When Returned
NotFound	Thrown if one of the ids for the specified object does not exist.
Unauthorized	if not system admin.

createStatusLevel

Creates a new points based StatusLevel. The minPoints and maxPoints range must not intersect, and maxPoints cannot be zero. Specify -1 in either to denote a boundless range (ie minPoints=50, maxPoints=-1 would mean everything over 50 has this status level)

The minPoints and maxPoints values must not go into the range over another StatusLevel levels point range.

POST http://domain:port/application_context/rpc/rest/statusLevelService/pointStatusLevels

Arguments

Name	Type	Description
name	xs:string	name of the status level
imagePath	xs:string	The path the image used when displaying this status level.
minPoints	xs:int	minimum amount in the point range
maxPoints	xs:int	maximum amount in the point range

Arguments Template

<createStatusLevel> 
    <name>xs:string</name>
    <imagePath>xs:string</imagePath>
    <minPoints>xs:int</minPoints>
    <maxPoints>xs:int</maxPoints>
</createStatusLevel>

Response

Type	Description
StatusLevel	The newly created status level object

Response Template

<createStatusLevelResponse> 
    <return>
        <!-- Contents of StatusLevel -->
    <return>
</createStatusLevelResponse>

Errors

Error	When Returned
Unauthorized	if not system admin
com.jivesoftware.community.StatusLevelAlreadyExistsException	Thrown if there is a status level already matching these criteria.
com.jivesoftware.community.StatusLevelException	if an illegal range is specified.

createStatusLevel

Creates a new group based StatusLevel Level

POST http://domain:port/application_context/rpc/rest/statusLevelService/groupStatusLevels

Arguments

Name	Type	Description
name	xs:string	name of the status level
imagePath	xs:string	The path the image used when displaying this status level.
groupID	xs:long	ID of the group to associate this status level with

Arguments Template

<createStatusLevel> 
    <name>xs:string</name>
    <imagePath>xs:string</imagePath>
    <groupID>xs:long</groupID>
</createStatusLevel>

Response

Type	Description
StatusLevel	newly created status level object

Response Template

<createStatusLevelResponse> 
    <return>
        <!-- Contents of StatusLevel -->
    <return>
</createStatusLevelResponse>

Errors

Error	When Returned
Unauthorized	if not system admin
com.jivesoftware.community.StatusLevelAlreadyExistsException	Thrown if there is a status level already matching these criteria.
com.jivesoftware.community.StatusLevelException	If this status level cannot be created.
GroupNotFound	If the specified group is not found.

deleteStatusLevel

Deletes a statusLevel level from the system

DELETE http://domain:port/application_context/rpc/rest/statusLevelService/statusLevels/{statusLevelID}

Arguments

Name	Type	Description
statusLevelID	xs:long	ID of the statusLevel level to delete

Arguments Template

<deleteStatusLevel> 
    <statusLevelID>xs:long</statusLevelID>
</deleteStatusLevel>

Errors

Error	When Returned
com.jivesoftware.community.StatusLevelNotFoundException	If the id of the specified status level does not exist.
Unauthorized	if not system admin

getAllStatusLevelScenarios

Returns all of the StatusLevelScenario objects.

GET http://domain:port/application_context/rpc/rest/statusLevelService/scenarios

Response

Type	Description
List of StatusLevelScenario	all of the StatusLevelScenario objects.

Response Template

<getAllStatusLevelScenariosResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of StatusLevelScenario -->
    <return>
</getAllStatusLevelScenariosResponse>

getGroupStatusLevel

If there is a status level associated with the group passed in then the status level will be returned, Otherwise null will be returned.

GET http://domain:port/application_context/rpc/rest/statusLevelService/groupStatusLevels/{groupID}

Arguments

Name	Type	Description
groupID	xs:long	ID of the group to find a status level for

Arguments Template

<getGroupStatusLevel> 
    <groupID>xs:long</groupID>
</getGroupStatusLevel>

Response

Type	Description
StatusLevel	status level that is associated with group, else null

Response Template

<getGroupStatusLevelResponse> 
    <return>
        <!-- Contents of StatusLevel -->
    <return>
</getGroupStatusLevelResponse>

Errors

Error	When Returned
GroupNotFound	Thrown if the group with the specified id does not exist.

getGroupStatusLevels

Returns an array of all group based status levels in the system.

GET http://domain:port/application_context/rpc/rest/statusLevelService/groupStatusLevels

Response

Type	Description
List of StatusLevel	an array of all group based status levels in the system.

Response Template

<getGroupStatusLevelsResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of StatusLevel -->
    <return>
</getGroupStatusLevelsResponse>

getLeaders

Returns an array of system wide leaders.

GET http://domain:port/application_context/rpc/rest/statusLevelService/leaders

Response

Type	Description
List of User	Array of User objects for system wide leaders

Response Template

<getLeadersResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getLeadersResponse>

getLeaders

Returns an array of system wide leaders.

GET http://domain:port/application_context/rpc/rest/statusLevelService/leaders/{startIndex}/{numResults}

Arguments

Name	Type	Description
startIndex	xs:int	The starting point of the results.
numResults	xs:int	The number of results to return in the array.

Arguments Template

<getLeaders> 
    <startIndex>xs:int</startIndex>
    <numResults>xs:int</numResults>
</getLeaders>

Response

Type	Description
List of User	Array of User objects for system wide leaders

Response Template

<getLeadersResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getLeadersResponse>

getLeaders

Returns an Iterable of leaders for a specific community

GET http://domain:port/application_context/rpc/rest/statusLevelService/leadersByCommunity/{communityID}

Arguments

Name	Type	Description
communityID	xs:long	ID of the community to find leaders for.

Arguments Template

<getLeaders> 
    <communityID>xs:long</communityID>
</getLeaders>

Response

Type	Description
List of User	Array of User objects for a specific forum

Response Template

<getLeadersResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getLeadersResponse>

Errors

Error	When Returned
CommunityNotFound	Thrown if the community with the specified id does not exist.

getLeaders

Returns an Iterable of leaders for a specific container

GET http://domain:port/application_context/rpc/rest/statusLevelService/leadersByContainer/{containerObjectID}/{containerObjectType}

Arguments

Name	Type	Description
containerObjectID	xs:long	ID of the container to find leaders for.
containerObjectType	xs:int	Type of the container to find leaders for.

Arguments Template

<getLeaders> 
    <containerObjectID>xs:long</containerObjectID>
    <containerObjectType>xs:int</containerObjectType>
</getLeaders>

Response

Type	Description
List of User	Array of User objects for a specific forum

Response Template

<getLeadersResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getLeadersResponse>

Errors

Error	When Returned
NotFound	Thrown if the container with the specified id and type does not exist.

getLeaders

Returns an Iterable of leaders for a specific community

GET http://domain:port/application_context/rpc/rest/statusLevelService/leadersByCommunity/{communityID}/{startIndex}/{numResults}

Arguments

Name	Type	Description
communityID	xs:long	ID of the community to find leaders for
startIndex	xs:int	The starting point of the leader results.
numResults	xs:int	The number of results in the array.

Arguments Template

<getLeaders> 
    <communityID>xs:long</communityID>
    <startIndex>xs:int</startIndex>
    <numResults>xs:int</numResults>
</getLeaders>

Response

Type	Description
List of User	Iterable of User objects for a specific forum

Response Template

<getLeadersResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getLeadersResponse>

Errors

Error	When Returned
CommunityNotFound	Thrown if the community with the specified id does not exist.

getLeaders

Returns an Iterable of leaders for a specific container

GET http://domain:port/application_context/rpc/rest/statusLevelService/leadersByContainer/{containerObjectID}/{containerObjectType}/{startIndex}/{numResults}

Arguments

Name	Type	Description
containerObjectID	xs:long	ID of the container to find leaders for
containerObjectType	xs:int	Type of the container to find leaders for
startIndex	xs:int	The starting point of the leader results.
numResults	xs:int	The number of results in the array.

Arguments Template

<getLeaders> 
    <containerObjectID>xs:long</containerObjectID>
    <containerObjectType>xs:int</containerObjectType>
    <startIndex>xs:int</startIndex>
    <numResults>xs:int</numResults>
</getLeaders>

Response

Type	Description
List of User	Iterable of User objects for a specific forum

Response Template

<getLeadersResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getLeadersResponse>

Errors

Error	When Returned
NotFound	Thrown if the container with the specified id and type does not exist.

getPointLevel

Returns the point level for a user system wide.

GET http://domain:port/application_context/rpc/rest/statusLevelService/pointLevel/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user to get status level points for

Arguments Template

<getPointLevel> 
    <userID>xs:long</userID>
</getPointLevel>

Response

Type	Description
xs:long	how many status points the user has

Response Template

<getPointLevelResponse> 
    <return>xs:long</return>
</getPointLevelResponse>

Errors

Error	When Returned
UserNotFound	Thrown if the user with the specified id does not exist.

getPointLevel

Returns the status level points for a user in regards to a specific community

GET http://domain:port/application_context/rpc/rest/statusLevelService/pointLevel/{userID}/{communityID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user to get status level points for
communityID	xs:long	ID of the community to filter by

Arguments Template

<getPointLevel> 
    <userID>xs:long</userID>
    <communityID>xs:long</communityID>
</getPointLevel>

Response

Type	Description
xs:long	how many status level points a user has for the particular community

Response Template

<getPointLevelResponse> 
    <return>xs:long</return>
</getPointLevelResponse>

Errors

Error	When Returned
UserNotFound	Thrown if the user with the specified id does not exist.
CommunityNotFound	Thrown if the Community with the specified id does not exist.

getPointLevel

Returns the status level points for a user in regards to a specific container

GET http://domain:port/application_context/rpc/rest/statusLevelService/pointLevel/{userID}/{containerObjectID}/{containerObjectType}

Arguments

Name	Type	Description
userID	xs:long	ID of the user to get status level points for
containerObjectID	xs:long	ID of the container to filter by
containerObjectType	xs:int	Type of the container to filter by

Arguments Template

<getPointLevel> 
    <userID>xs:long</userID>
    <containerObjectID>xs:long</containerObjectID>
    <containerObjectType>xs:int</containerObjectType>
</getPointLevel>

Response

Type	Description
xs:long	how many status level points a user has for the particular container

Response Template

<getPointLevelResponse> 
    <return>xs:long</return>
</getPointLevelResponse>

Errors

Error	When Returned
NotFound	Thrown if the Container with the specified id and type does not exist. Or if the user with the specified id does not exist.

getPointStatusLevels

Returns an array of point based status levels in the system sorted by point range.

GET http://domain:port/application_context/rpc/rest/statusLevelService/pointStatusLevels

Response

Type	Description
List of StatusLevel	point range sorted array of StatusLevel objects

Response Template

<getPointStatusLevelsResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of StatusLevel -->
    <return>
</getPointStatusLevelsResponse>

getStatusLevel

Used to acquire a specific status level object from the system

GET http://domain:port/application_context/rpc/rest/statusLevelService/statusLevels/{statusLevelID}

Arguments

Name	Type	Description
statusLevelID	xs:long	the id of the object to acquire

Arguments Template

<getStatusLevel> 
    <statusLevelID>xs:long</statusLevelID>
</getStatusLevel>

Response

Type	Description
StatusLevel	the object found in the system

Response Template

<getStatusLevelResponse> 
    <return>
        <!-- Contents of StatusLevel -->
    <return>
</getStatusLevelResponse>

Errors

Error	When Returned
com.jivesoftware.community.StatusLevelNotFoundException	thrown if the object does not exist in the system

getStatusLevelByPoints

Used to get a status level by a point value. If the points exceeds that of the maximum status level, the maximum status level will be returned.

GET http://domain:port/application_context/rpc/rest/statusLevelService/statusLevelByPoints/{points}

Arguments

Name	Type	Description
points	xs:long	point value find a status level for

Arguments Template

<getStatusLevelByPoints> 
    <points>xs:long</points>
</getStatusLevelByPoints>

Response

Type	Description
StatusLevel	the StatusLevel matching a point level, or null if non is found

Response Template

<getStatusLevelByPointsResponse> 
    <return>
        <!-- Contents of StatusLevel -->
    <return>
</getStatusLevelByPointsResponse>

getStatusLevelScenarioByCode

Returns a StatusLevelScenario by its code.

Note: When using REST use to encode the string.

GET http://domain:port/application_context/rpc/rest/statusLevelService/scenarios/{code}

Arguments

Name	Type	Description
code	xs:string	The code of the StatusLevelScenario.

Arguments Template

<getStatusLevelScenarioByCode> 
    <code>xs:string</code>
</getStatusLevelScenarioByCode>

Response

Type	Description
StatusLevelScenario	The matching StatusLevelScenario.

Response Template

<getStatusLevelScenarioByCodeResponse> 
    <return>
        <!-- Contents of StatusLevelScenario -->
    <return>
</getStatusLevelScenarioByCodeResponse>

getStatusLevelScenarioByCode

Returns a StatusLevelScenario by its code. The code could be encoded using UTF-8 to avoid problems when using REST URLs.

GET http://domain:port/application_context/rpc/rest/statusLevelService/scenarios/{code}/{encoded}

Arguments

Name	Type	Description
code	xs:string	The code of the StatusLevelScenario.
encoded	xs:boolean	True if the code was UTF-8 encoded to avoid problems whenusing REST URLs.

Arguments Template

<getStatusLevelScenarioByCode> 
    <code>xs:string</code>
    <encoded>xs:boolean</encoded>
</getStatusLevelScenarioByCode>

Response

Type	Description
StatusLevelScenario	The matching StatusLevelScenario.

Response Template

<getStatusLevelScenarioByCodeResponse> 
    <return>
        <!-- Contents of StatusLevelScenario -->
    <return>
</getStatusLevelScenarioByCodeResponse>

getUserStatusLevel

Returns the system wide status level for specific user, will return null if there is no status level for this user.

If the user belongs to a group status level the group status level will always be returned.

GET http://domain:port/application_context/rpc/rest/statusLevelService/userStatusLevels/{userID}

Arguments

Name	Type	Description
userID	xs:long	IDof the user to find the status level for

Arguments Template

<getUserStatusLevel> 
    <userID>xs:long</userID>
</getUserStatusLevel>

Response

Type	Description
StatusLevel	system wide status level for the user or null if no status level

Response Template

<getUserStatusLevelResponse> 
    <return>
        <!-- Contents of StatusLevel -->
    <return>
</getUserStatusLevelResponse>

Errors

Error	When Returned
UserNotFound	Thrown if the user with the specified id does not exist.

isStatusLevelsEnabled

Returns true if status levels are enabled in the system

GET http://domain:port/application_context/rpc/rest/statusLevelService/statusLevelsEnabled

Response

Type	Description
xs:boolean	true if status levels are enabled

Response Template

<isStatusLevelsEnabledResponse> 
    <return>xs:boolean</return>
</isStatusLevelsEnabledResponse>

setStatusLevelsEnabled

Sets whether status levels should be enabled in the system.

POST http://domain:port/application_context/rpc/rest/statusLevelService/statusLevelsEnabled

Arguments

Name	Type	Description
statusLevelsEnabled	xs:boolean	true if status levels are statusLevelsEnabled, else false

Arguments Template

<setStatusLevelsEnabled> 
    <statusLevelsEnabled>xs:boolean</statusLevelsEnabled>
</setStatusLevelsEnabled>

Errors

Error	When Returned
Unauthorized	if not system admin

updateStatusLevelScenario

Update the points and whether or not this scenario is included in status level results.

PUT http://domain:port/application_context/rpc/rest/statusLevelService/scenarios

Arguments

Name	Type	Description
scenario	Contents of StatusLevelScenario	the points and whether or not this scenario is included in status level results.

Arguments Template

<updateStatusLevelScenario> 
    <scenario>
        <!-- Contents of StatusLevelScenario -->
    <scenario>
</updateStatusLevelScenario>

Errors

Error	When Returned
Unauthorized	if not system admin.