Urgent Computing: SPRUCE

Service Name:
SpruceUserServices
Endpoint Reference (EPR):
http://spruce.uchicago.edu:8080/axis2/services/SpruceUserServices
SPRUCE Namespace:
http://spruce.uchicago.edu/ws/xsd/
Target Namespace:
http://spruce.uchicago.edu/ws/xsd/

[TOC]

Services

The user services package includes six functions. This section will describe each in detail, along with the required input, given output and possible errors.

The six functions are:

getTokenInfo()
addUserToToken()
removeUserFromToken()
activateToken()
checkTokenTime()
getUserInfo()

Please note that the term "identity" used all through the document indicates the user's Distinguished Name (DN) on the TG resources.

[TOC]

Function Parameters

Nearly all the functions require at least a token input parameter. An example of an input parameter in xml is included below for a token:

<spruce:token xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/">
1111-2222-3333-4444</spruce:token>

To invoke a web service, the input parameters are attached to the method call, creating an xml element as follows:

<spruce:getTokenInfo xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/">
<spruce:token>1111-2222-3333-4444</spruce:token>
</spruce:getTokenInfo>

Input parameter checking is slightly rigid. For each web service call, input arguments can be passed in any order. But, the name of each parameter must be matched explicitly (case-sensitive). Current convention is that all input parameters are lowercase. Parameter checking is handled as follows:

At the start of the web service method, each required input parameter is extracted from the passed input arguments one at a time. If any extraction fails, an error (50: Invalid request format) is returned. There is no check to ensure that no "extra" parameters are included. At this point in time, anything extra is ignored.

[TOC]

Error Codes

Function invocations may result in a Spruce Fault being returned. A Spruce Fault is an xml element with three children (an error code, an error message, and an error description). An example of a Spruce Fault is given below:

 
<spruce:SpruceFault xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/" 
xmlns:tns="http://SpruceUserServices.spruce.org">
	<spruce:code>1</spruce:code>
	<spruce:message>Token Not Found</spruce:message>
	<spruce:description>getTokenInfo::Token not found in database
	</spruce:description>
</spruce:SpruceFault>

The following error codes may be returned:

 
CODE        	 MESSAGE						DESCRIPTION

0 	Invalid token		Invalid token format given. Tokens 
				are 19 charcters grouped into 
				4 blocks of 4 characters separated 
				by a hyphen '-'. The alphabet cont
				-ains the digits 2-9 and all capital 
				letters excluding 'O' and 'I'. (eg, 
				'xxxx-xxxx-xxxx-xxxx' where each x is
				a valid character from the alpahbet)

1 	Token not found		The given token does not exist in the 
				database

2 	Token expired		It is past the token's expiration date

3 	Token deactivated	It is past the token's deactivation date 
				(this implies the token was activated)

4 	Token not activated	Token has never been activated. It's 
				activation date in the database is 
				still '0000-00-00 00:00:00'.

5 	Token already		Token is already activated
	 activated		You cannot activate a token more than once.

10 	Invalid user		The given user exists in database, 
				but is not valid for one reason or another
				(eg trying to remove a user from a token 
				where the user is not associated with 
				that token).

11 	User not found		User not found in database

50 	Invalid request		Most commonly when a required  
	format			input parameter is not included
				with the method invocation
	
60 	Service currently	An error that is causing the service 
	unavailable	        to not respond. Right now, we return this 
				if the JDBC driver does not load properly. 
				We can return these in catastrophic errors.

[TOC]

getTokenInfo()

getTokenInfo() may be invoked to get all of the interesting information about a token from the database. In order to remove users from the token, you would need their identities. These could be grabbed from this method. Also, you could first check to see if the user you want to add is already added. Once a token is frozen (deactivated or expired) a spruce fault is returned. Because you can no longer use this token, we will no longer supply this info. If a PI needs to access this, they can request it from the admin who issued them the token. Normal users should have no regular need to see the details fo frozen tokens.

Input

The input to getTokenInfo() is a token number -

  
<spruce:getTokenInfo xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/">
	<spruce:token>1111-2222-3333-4444</spruce:token>
</spruce:getTokenInfo>

Return

After a successful invocation, the return is a large xml element that contains all the interesting data. A sample return is given below:

  
 <spruce:SpruceResponse xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/" 
xmlns:tns="http://SpruceUserServices.spruce.org">
	<spruce:token>1111-2222-3333-4444</spruce:token>
	<spruce:status>Activated</spruce:status>
	<spruce:lifetime>24:00:00</spruce:lifetime>
	<spruce:creation_date>2006-06-21 09:30:35.0</spruce:creation_date>
	<spruce:expiration_date>2006-07-23 14:56:04.0</spruce:expiration_date>
	<spruce:activation_date>2006-07-10 15:30:02.0</spruce:activation_date>
	<spruce:activation_ip>127.0.0.1</spruce:activation_ip>
	<spruce:deactivation_date>2006-07-25 13:20:44.0
	</spruce:deactivation_date>
	<spruce:issued_to>Team1</spruce:issued_to>
	<spruce:max_urgency>red</spruce:max_urgency>
	<spruce:notify_addr>foo@bar1</spruce:notify_addr>
	<spruce:issued_by spruce:id="1">
		<spruce:real_name>User 1</spruce:real_name>
	</spruce:issued_by>
	<spruce:VO spruce:id="1">
		<spruce:abbrv>TG</spruce:abbrv>
		<spruce:site spruce:id="1">
			<spruce:abbrv>ANL</spruce:abbrv>
			<spruce:resource spruce:id="1">
				<spruce:abbrv>ia64-compute</spruce:abbrv>
			</spruce:resource>
			<spruce:resource spruce:id="2">
				<spruce:abbrv>ia32-compute</spruce:abbrv>
			</spruce:resource>
		</spruce:site>
		<spruce:site spruce:id="2">
			<spruce:abbrv>Purdue</spruce:abbrv>
			<spruce:resource spruce:id="3">
				<spruce:abbrv>Lear</spruce:abbrv>
			</spruce:resource>
		</spruce:site>
	</spruce:VO>
	<spruce:UserList>
		<spruce:UserInfo spruce:id="1">
			<spruce:real_name>User 2</spruce:real_name>
			<spruce:email>user2@domain</spruce:email>
			<spruce:identity>User2-DN</spruce:identity>
		</spruce:UserInfo>
		<spruce:UserInfo spruce:id="3">
			<spruce:real_name>User 3</spruce:real_name>
			<spruce:email>user3@domain</spruce:email>
			<spruce:identity>User3-DN</spruce:identity>
		</spruce:UserInfo>
		<spruce:UserInfo spruce:id="4">
			<spruce:real_name>User 4</spruce:real_name>
			<spruce:email>user4@domain</spruce:email>
			<spruce:identity>User4-DN</spruce:identity>
		</spruce:UserInfo>
	</spruce:UserList>
</spruce:SpruceResponse>

Possible Faults

  
CODE                 MESSAGE                                                DESCRIPTION                                                       

0 	Invalid token			Invalid token format given. Tokens 
					are 19 charcters grouped into 4 blo
					-cks of 4 characters separated by a 
					hyphen '-'. The alphabet contains 
					the digits 2-9 and all capital letters
					excluding 'O' and 'I'. (eg, 'xxxx-xxxx
					-xxxx-xxxx' where each x is a valid 
					character from the alpahbet)

1 	Token not found			Supplied token not found in database

2 	Token expired			The given token has expired. No 
					longer able to view token information.

3 	Token deactivated		The given token is now deactivated. 
					No longer able to view token 
					information.

50 	Invalid request format		No input parameter 'token' found.

60 	Service currently unavailable	At this point, only for JDBC error.

[TOC]

addUsersToToken()

addUserToToken() enables a single user to be added to a token. A user is unique by his identity and email address. If the given user is not found in the users database, then a new record is created. Also, a check is performed to make sure we do not add a user to the same token twice. A user can have multiple email addresses (and thus potentially multiple user records). This enables a user to have differnet email addresses associated with different tokens. For instance, if Bob works on two different projects within a VO, he could have separate user records associated with tokens issued to those groups. If the wrong user (wrong email) is added to a token, you must remove it first before adding the correct one. Once a token is frozen (deactivated or expired) you can no longer add/remove users. Since the token can no longer be used, this functionality is no longer necessary.

Input

The input is a token and user info:

  
<spruce:addUserToToken xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/">
	<spruce:token>1111-2222-3333-4444</spruce:token>
	<spruce:real_name>Foo Bar</spruce:real_name>
	<spruce:email>foo@bar</spruce:email>
	<spruce:identity>Foo Bar</spruce:identity>
</spruce:addUserToToken>

Return

After a successful invocation, the return is an xml element containing the user info of the added user. A sample return is given below:

  
<spruce:SpruceResponse xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/" 
xmlns:tns="http://SpruceUserServices.spruce.org">
	<spruce:UserInfo spruce:id="10">
		<spruce:real_name>Foo Bar</spruce:real_name>
		<spruce:email>foo@bar</spruce:email>
		<spruce:identity>Foo Bar</spruce:identity>
	</spruce:UserInfo>
</spruce:SpruceResponse>

Possible Faults

CODE                 MESSAGE                                                DESCRIPTION                                                       
0       Invalid token           Invalid token format given. Tokens 
                                are 19 charcters grouped into 
                                4 blocks of 4 characters separated 
                                by a hyphen '-'. The alphabet cont
                                -ains the digits 2-9 and all capital 
                                letters excluding 'O' and 'I'. (eg, 
                                'xxxx-xxxx-xxxx-xxxx' where each x is
                                a valid character from the alpahbet)

1       Token not found         Supplied token does not exist in the 
                                database

2       Token expired           The given token has expired.
				No longer able to add users.

3       Token deactivated	The given token is now deactivated.
				No longer able to add users.

10	Invalid user		User already associated with the 
				given token.

50 	Invalid request format	No required input parameter found.

60 	Service currently	 At this point, only for JDBC error. 
	unavailable

[TOC]

removeUserFromToken()

removeUserFromToken() enables a single user to be removed from a token. We can assume that identites associated with a token are unique, since tokens are applicable within a single VO, and identities are unique within a VO. To remove a user, we see if the given identity is associated with the token. If so, delete it. Once a token is frozen (deactivated or expired) you can no longer add/remove users. Since the token can no longer be used, this functionality is no longer necessary.

Input

The input is a token and user 'identity':

 
<spruce:removeUserFromToken xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/">
	<spruce:token>1111-2222-3333-4444</spruce:token>
	<spruce:identity>Foo Bar</spruce:identity>
</spruce:removeUserFromToken>

Return

After a successful invocation, the return is an xml element containing a success message. A sample return is given below:

 
<spruce:SpruceResponse xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/" 
xmlns:tns="http://SpruceUserServices.spruce.org">
	<spruce:return>User removed from token</spruce:return>
</spruce:SpruceResponse>

Possible Faults

 
CODE                 MESSAGE                                                DESCRIPTION                                                       
0       Invalid token           Invalid token format given. Tokens 
                                are 19 charcters grouped into 
                                4 blocks of 4 characters separated 
                                by a hyphen '-'. The alphabet cont
                                -ains the digits 2-9 and all capital 
                                letters excluding 'O' and 'I'. (eg, 
                                'xxxx-xxxx-xxxx-xxxx' where each x is
                                a valid character from the alpahbet)   

1 	Token not found		Supplied token not found in database

2 	Token expired		The given token has expired. 
				No longer able to add users.

3 	Token deactivated	The given token is now deactivated. 
				No longer able to add users.

10	Invalid user		User not associated with the given token.

50 	Invalid request format	No required input parameter found.

60 	Service currently 	At this point, only for JDBC error.		
	unavailable

[TOC]

activateToken()

activateToken() takes a token and comment as input and activates it. This involves setting the activation_ip, the activation_date and a comment.

Input

The input is a token and 'comment':

    

<spruce:activateToken xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/">
	<spruce:token>1111-2222-3333-4444</spruce:token>
	<spruce:comment>test activation</spruce:comment>
</spruce:activateToken>

Return

After a successful invocation, the return is an xml element containing a success message. A sample return is given below:

    

<spruce:SpruceResponse xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/" 
xmlns:tns="http://SpruceUserServices.spruce.org">
	<spruce:return>Token activated</spruce:return>
</spruce:SpruceResponse>

Possible Faults

    
CODE                 MESSAGE                                                DESCRIPTION                                                       

0       Invalid token           Invalid token format given. Tokens 
                                are 19 charcters grouped into 
                                4 blocks of 4 characters separated 
                                by a hyphen '-'. The alphabet cont
                                -ains the digits 2-9 and all capital 
                                letters excluding 'O' and 'I'. (eg, 
                                'xxxx-xxxx-xxxx-xxxx' where each x is
                                a valid character from the alpahbet)

1 	Token not found		Supplied token not found in database

2 	Token expired		The given token has expired. 
				No longer able to add users.

5	Token already activated	The given token has already been 
				activated. Can only activate once.

10	Invalid user		User not associated with the given token.

50 	Invalid request format	No input parameter 'token' found.

60 	Service currently 	At this point, only for JDBC error.
	unavailable

[TOC]

checkTokenTime()

checkTokenTime() takes a token as input. It returns the amount of time remaining on that token.

Input

The input is a token:

<spruce:checkTokenTime xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/">
	<spruce:token>1111-2222-3333-4444</spruce:token>
</spruce:checkTokenTime>

Return

After a successful invocation, the return is an xml element containing the time remaining. A sample return is given below:

<spruce:SpruceResponse xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/" 
xmlns:tns="http://SpruceUserServices.spruce.org">
	<spruce:time_remaining>23:23:56</spruce:time_remaining>
</spruce:SpruceResponse>

Possible Faults

CODE        	 MESSAGE						DESCRIPTION

0       Invalid token           Invalid token format given. Tokens 
                                are 19 charcters grouped into 
                                4 blocks of 4 characters separated 
                                by a hyphen '-'. The alphabet cont
                                -ains the digits 2-9 and all capital 
                                letters excluding 'O' and 'I'. (eg, 
                                'xxxx-xxxx-xxxx-xxxx' where each x is
                                a valid character from the alpahbet) 

1 	Token not found		Supplied token not found in database

2 	Token expired		The given token has expired. 
				No longer able to add users.

4	Token not activated	The given token has not been activated

50 	Invalid request format	No input parameter 'token' found.

60 	Service currently	At this point, only for JDBC error. 
	unavailable

[TOC]

getUserInfo()

Return all the permissions and time remaining on all non-frozen tokens that a given user is associated with. Non-frozen tokens include tokens that are currently activated (prior to deactivation date), tokens that have not yet been activated and have not expired. These tokens represent tokens that are useable now or in the future. Token info for tokens that have been deactivated or expired or not returned, since they are not useable in the future. Note that time remaining is only returned for tokens that are activated.

Input

The input is an email and an identity:

<spruce:getUserInfo xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/">
	<spruce:email>foo@bar</spruce:email>
	<spruce:identity>Foo Bar</spruce:identity>
</spruce:getUserInfo>

Return

After a successful invocation, the return is an xml element containing a list of tokens. There are two types of tokens. First, all tokens with status "Activated" are listed, which include time remaining. Then, any tokens with status "Unactivated" are included, these only have permissions associated with them. A sample return is given below:

<spruce:SpruceResponse xmlns:spruce="http://spruce.uchicago.edu/ws/xsd/" 
xmlns:tns="http://ws.apache.org/axis2">
    <spruce:token_list>
	<spruce:TokenInfo>
 	  <spruce:status>Activated</spruce:status>
          <spruce:max_urgency>red</spruce:max_urgency>
	  <spruce:time_remaining>23:21:46</spruce:time_remaining>
     	  <spruce:VO spruce:id="1">
		<spruce:abbrv>TG</spruce:abbrv>
		<spruce:site spruce:id="1">
			<spruce:abbrv>ANL</spruce:abbrv>
			<spruce:resource spruce:id="2"><spruce:abbrv>
			ia32-compute</spruce:abbrv></spruce:resource>
	        </spruce:site>
	  </spruce:VO>
	</spruce:TokenInfo>
	<spruce:TokenInfo>
	  <spruce:status>Activated</spruce:status>
          <spruce:max_urgency>red</spruce:max_urgency>
	  <spruce:time_remaining>23:21:38</spruce:time_remaining>
	  <spruce:VO spruce:id="1">
		<spruce:abbrv>TG</spruce:abbrv>
		<spruce:site spruce:id="1">
			<spruce:abbrv>ANL</spruce:abbrv>
			<spruce:resource spruce:id="1"><spruce:abbrv>
			ia64-compute</spruce:abbrv></spruce:resource>
		</spruce:site>
		<spruce:site spruce:id="2">
			<spruce:abbrv>Purdue</spruce:abbrv>
			<spruce:resource spruce:id="3"><spruce:abbrv>
			cerias-compute</spruce:abbrv></spruce:resource>
		</spruce:site>
	  </spruce:VO>
	</spruce:TokenInfo>
	<spruce:TokenInfo>
	  <spruce:status>Unactivated</spruce:status>
          <spruce:max_urgency>red</spruce:max_urgency>
	  <spruce:VO spruce:id="1">
		<spruce:abbrv>TG</spruce:abbrv>
		<spruce:site spruce:id="1">
		  	<spruce:abbrv>ANL</spruce:abbrv>
			<spruce:resource spruce:id="1"><spruce:abbrv>
			ia64-compute</spruce:abbrv></spruce:resource>
		</spruce:site>
		<spruce:site spruce:id="2">
			<spruce:abbrv>Purdue</spruce:abbrv>
			<spruce:resource spruce:id="3"><spruce:abbrv>
			cerias-compute</spruce:abbrv></spruce:resource>
		</spruce:site>
	  </spruce:VO>
	</spruce:TokenInfo>
   </spruce:token_list>
</spruce:SpruceResponse>

Possible Faults


CODE        	 MESSAGE						DESCRIPTION

10	Invalid User			User not associated with any
					actiavted or unactivated tokens

11	User Not Found			The given user not found in database

50 	Invalid request format		No required input parameter found.

60 	Service currently unavailable	At this point, only for JDBC error.

[TOC]

Example Scenarios

The purpose of this web service suite is to allow the activation and association of users with tokens to be incorporated into pre-existing scientific portals and workflows. Originally, this functionality was available solely from the Spruce web portal. It is important to note that the creation of tokens is not included in this functionality. That is currently handled by administrators. This set of functionality is for existing tokens.

The following example scenarios talk about when and how the above functions may need to be used.

Scenario 1(Using tokens to submit jobs)

The PI for research group A has a token that they can use for emergency computation. This token can have various attributes such as an urgency level, resource set allowed on, lifetime, pre-loaded user identities and expiration date. All this information can be obtained using the getTokenInfo() call. The PI can pre-load the token with the users in his research group who would most likely be submitting the emergency computation jobs using addUserToToken(). Users can be associated after activation, but it may be convenient to do (if possible) prior to the actual emergency event. When some event occurs that signals the PI that the emergency computation window needs to begin, they activate the token using activateToken(). If needed the users added to the token can be removed anytime using removeUserFromToken(). Please note that any jobs submitted by an user before removal still continue to run. Once an user's identity (DN in case of TG) is added onto an active token with necessary permissions, they can start submitting urgent jobs.

Scenario 2(Check time remaining on a token)

Midway through the token's activation lifetime, if the PI wants to check the time remaining on the token, he can do so by using the checkTokenTime() call.

Scenario 3(Check remaining time a user has)

One of the researchers involved in group A under the PI is unsure if they are associated with the token. They can invoke the getUserInfo() web service, which returns a list of all permissions for all tokens the user is associated with. In addition, for all active tokens the user is associated with, the time remaining is also returned.

An example Client for Java Axis2 can be found here.

[TOC]

Contact Information

Please contact Spruce Team for any questions or problems using Spruce software.

[TOC]

SPRUCE User Web Services Guide

Table of Contents