AJAX API for TelHosting Software

Login

be_login (inputLogin, processResult, processError)

/**
 * this method is used to login a user;
 * depending on the type of user logging in, a URL is returned, which can
 * be used by the dashboard to forward the user;
 * the flag usedTempPassword tells, whether the user is logging in with
 * a temporary password; in this case, the user should prompted to change
 * his password immediately, since he won't be able to log in using this
 * password another time
 */

inputPreferences = {
	username: "johnsmith",
	password: "secret"
};

successResult = {
	success: true,
	usedTempPassword: false,
	urlForward: "http://localhost:8080/ps-server/g2/dashboard.action",
	actionMessages: ["user logged in successfully",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["invalid user name or password",
               	       "more errors here..."]
}; 

validation: be_login (inputLogin, processResult, processError)

value	name	description	validation
username	login allowed	check login permission based on "Allow web login" permission	AJAX API
username	login	check of combination username and password	backend
password	login	check of combination username and password	backend

For security reasons, any errors in the combination of username and password or a non existing username will lead to the same error.

be_logout (null, processResult, processError)

/**
 * this method is used to logout a user
 */

/** no input needed */

successResult = {
	success: true,
	actionMessages: ["user logged out successfully",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["an unexecpted problem occurred",
               	       "more errors here..."]
}; 

validation: be_logout (null, processResult, processError)

no validation required as the method does not have any input values

be_passwordRetrieval (inputLogin, processResult, processError)

/**
 * this method allows the user to reset his password; a valid
 * e-mail address has to be supplied and an an e-mail is sent to this
 * containing new temporary passwords for every user having this
 * address
 */

inputLogin = {
	email: "johnsmith@smith.th"
};

successResult = {
	actionMessages: ["e-mail sent",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["e-mail address does not exist",
               	       "more errors here..."]
}; 

validation: be_passwordRetrieval (inputLogin, processResult, processError)

the input is not validated

Wizard

be_setDashboardPreferences (inputPreferences, processResult, processError)

/**
 * this method sets the four flags for the dashboard preferences; these
 * preferences can be different for each second-level domain
 */

inputPreferences = {
	domainName: "cartman.tel",
	enablePrivacy: true,
	enableProfiles: false,
	enableFolders: true,
	displayFriending: true
};

successResult = {
	success: true,
	actionMessages: ["preferences successfully set",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot set preferences",
               	       "more errors here..."]
}; 

be_getDashboardPreferences (null, processResult, processError)

/**
 * this method returns the four flags for the dashboard preferences
 * of the given (second-level) domain; if a subdomain is submitted, the
 * preferences of its second-level domain are returned
 */

inputPreferences = {
	domainName: "cartman.tel"
};


successResult = {
	success: true,
	enablePrivacy: true,
	enableProfiles: false,
	enableFolders: true,
	displayFriending: true
	actionMessages: ["request successful",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get preferences",
               	       "more errors here..."]
}; 

Settings

be_changePassword (inputPassword, processResult, processError)

/**
 * method to change the user's password
 */

inputPassword = {
	newPassword: "secret"
};

successResult = {
	success: true,
	actionMessages: ["password changed successfully",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot change password",
               	       "more errors here..."],
	fieldErrors: ["newPassword", "invalid password"]
};

validation: be_changePassword (inputPassword, processResult, processError)

value	name	description	implemented
newPassword	presence	checks if input value is not empty or _null_	AJAX API

be_changeEmail (inputEmail, processResult, processError)

/**
 * method to change the user's e-mail address
 */

inputEmail = {
	newEmail: "tel@telinc.nic"
};

successResult = {
	success: true,
	actionMessages: ["email changed successfully",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot change email",
               	       "more errors here..."],
	fieldErrors: ["email", "invalid password"]
};

validation: be_changeEmail (inputEmail, processResult, processError)

value	name	description	implemented
newEmail	presence	checks if input value is not empty or _null_	AJAX API
newEmail	email	checks if input is a valid email	AJAX API

be_clearRecentLocations (null, processResult, processError)

/**
 * method to reset the recent location strings
 */

/** no input needed */

successResult = {
	success: true,
	actionMessages: ["recent location list cleared",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot clear recent location list",
               	       "more errors here..."]
};

validation: be_clearRecentLocations (null, processResult, processError)

no validation required as method has no input values

Folder management

be_getSubFolderList (inputFolder, processResult, processError)

/** 
 * retrieve the list of subfolders for the given folder (i.e. domain) name;
 * if the domainName is "tel", a list of all folders of the current user is
 * returned;
 * the input domain name is never returned, so the resulting list may be empty
 * the boolean parameter recursive determines whether all subdomains are
 * returned (true) or only the direct subdomains (false)
 */

input = {
	domainName: "tel",  /** gets a list of all folders */
	recursive: true
};

successResult = {
	success: true,
	folderList: [{id: 12, name: "cartman.tel", soConnection: "Active"},
		     {id: 23, name: "stan.cartman.tel", soConnection: "Uninitialised"},
		     {id: 14, name: "henry.tel", soConnection: "Incomplete"}],
	actionMessages: ["request successful",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get folder list",
               	       "more errors here..."]
}; 

validation: be_storeFolder (inputFolder, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
recursive	type cast check	checks if value is a boolean value	JSON framework

be_storeFolder (inputFolder, processResult, processError)

/** 
 * add a new folder;
 * the complete domain name of the new folder has to be provided;
 * the id of the new folder will be supplied in case of success 
 */

inputFolder = {
	domainName: "stan.cartman.tel"
};

successResult = {
	success: true,
	domainId: 25,
	actionMessages: ["folder added",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot add folder",
               	       "more errors here..."],
	fieldErrors: ["domainName", "invalid domain name"]
}; 

validation: be_storeFolder (inputFolder, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain has not been created before	backend
domainName	domain create permission	check for permission to create domain based on secondary user rights	backend
domainName	domain quota	check for permission to create domain based on "Max. number of domains" permission for sec. users	backend
domainName	domain quota	check for permission to create domain based on "Max. number of domains" permission for primary users	backend
domainName	label quota	check for permission to create domain based on "Max. number of etRecords" permission	backend
domainName	zone existance	check if zone must exist based on user permissions	backend
domainName	zone quota	check for permission to create domain based on "Max. number of labels" zone permission	backend
domainName	domain quota	check for permission to create domain based on "Max. number of domains" zone permission	backend

be_deleteFolder (inputFolder, processResult, processError)

/** 
 * delete a folder;
 * the complete domain name of the folder has to be provided
 */

inputFolder = {
	domainName: "cartman.tel"
};

successResult = {
	success: true,
	actionMessages: ["folder deleted"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot delete folder",
               	       "more errors here..."]
}; 

validation: be_deleteFolder (inputFolder, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

Profile management

be_getProfileList (inputProfile, processResult, processError)

/** 
 * retrieve the list of profiles for the specified domain;
 * the successResult contains the profileList, consisting of id and name
 * of the profile as well as flags whether it is the default and/or
 * active profile and a list of ids of the records belonging to this
 * profile
 */

inputProfile = {
	domainName: "cartman.tel"
};

successResult = {
	success: true,
	profileList: [{id: 12, name: "Paris", isDefault: false,
		       isActive: true, recordIds: [12,34,1,4]},
		      {id: 23, name: "London", isDefault: true,
		       isActive: false, recordIds: [12,1,2]}],
	actionMessages: ["request successful",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get profile list",
               	       "more errors here..."]
}; 

validation: be_getProfileList (inputProfile, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_activateProfile (inputProfile, processResult, processError)

/** 
 * activate a profile (defined by its id) for a given domain
 */

inputProfile = {
	domainName: "cartman.tel",
	profileId: 23
};

successResult = {
	success: true,
	actionMessages: ["profile activated",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot activate profile",
               	       "more errors here..."]
}; 

validation: be_activateProfile (inputProfile, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend
profileId	presence	checks if input value is present and not _null_	AJAX API & backend

be_deleteProfile (inputProfile, processResult, processError)

/** 
 * delete a profile (defined by its id) for a given domain
 */

inputProfile = {
	domainName: "cartman.tel",
	profileId: 23
};

successResult = {
	success: true,
	actionMessages: ["profile deleted"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot delete profile",
               	       "more errors here..."]
};

validation: be_deleteProfile (inputProfile, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend
profileId	presence	checks if input value is present and not _null_	AJAX API & backend
profileId	deleteable	check if profile is not the default profile (which is not allowed to delete)	backend

be_storeProfile (inputProfile, processResult, processError)

/** 
 * stores a profile of the given name in the given domain;
 * in case the profile id is set to 0, a new profile will be created (and
 * its id will be returned on success); for non-zero profile ids an
 * existing profile will be renamed (in this case the returned
 * id is the same as the one input)
 */

inputProfile = {
	domainName: "cartman.tel",
	profileId: 13,
	newProfileName: "holiday"
};

successResult = {
	success: true,
	profileId: 13,
	actionMessages: ["profile stored"
			 "2nd message here",
			 "3rd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["cannot store profile",
               	       "more errors here..."],
	fieldErrors: ["profileName", "invalid profile name"]
};

value	name	description	implemented
profileId	presence	checks if input value is present and not _null_	AJAX API & backend
profileId	profile quota	in case of a new profile (id=0) check if the profile can be created based on "Max. number of profiles" domain permission	backend
domainName	existance	check if the domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
newProfileName	uniqueness	check if profile name is only used once	backend

Text header management

be_getTextHeader (inputTextHeader, processResult, processError)

/** 
 * retrieve the text header of a profile (defined by its id) for the given
 * domain; if there is more than one text header in the profile, the text
 * header with the lowest api id is returned
 */

inputTextHeader = {
	domainName: "cartman.tel",
	profileId: 23
};

successResult = {
	success: true,
	textHeader: "This is my text header",
        apiId: 12,
	actionMessages: "request successful",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get text header",
               	       "more errors here..."]
}; 

validation: be_getTextHeader (inputTextHeader, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	check if the domain is existing	backend
profileId	existance	checks if porfile is existing	backend

be_storeTextHeader (inputTextHeader, processResult, processError)

/** 
 * create or edit the text header of a profile (defined by its id) for the
 * given domain if the apiId is 0, a new text header will be created for the
 * given profileId, if it is non-zero, the text record of the given apiId
 * will be changed and the profileId will simply be ignored;
 * note: due to the uniqueness constraint of the text header for each
 * profile it may  be the case that even though a specific record (defined
 * by its api id) is given to store, it may obtain a new api id; hence the
 * returned api id must always be checked and updated if necessary;
 *
 * as background information: the text header record has to be unique for
 * its profile; therefore, saving a text record can lead to several (maybe
 * unexpected) side effects, which are listed here for clarification:
 * in order to have just one text record in the profile, all other text
 * records will be removed from the profile by calling this method; if
 * removing a text record from the profile will make it abandoned
 * (i.e., not belonging to any profile any more), it will be deleted; this
 * is to make sure this method does not produce data garbage;
 * a second use case to consider is that this message edits a text record,
 * which belongs not only to this profile, but also to other profiles; just
 * editing it, would display the edited version also for the other profiles,
 * which is not something the user would expect; therefore the text record
 * itself will be removed from this profile, but otherwise left untouched;
 * a new text record will then be created for this profile and stored;
 * again, all other records in this profile will be removed and if
 * abandoned deleted
 */

inputTextHeader = {
	domainName: "cartman.tel",
	apiId: 23, /** may be 0 if text header is not yet set */
	profileId: 2, /** only needed if apiId is 0, else ignored */
	text: "lorem ipsum dolor sit amet consectateur..."
};

successResult = {
	success: true,
	actionMessages: ["text header changed"
			 "2nd message here",
                     	 "3rd message here"],
	apiId: 23, /** warning: can be different from the supplied one===  */
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot change text header",
               	       "more errors here..."]
};

validation: be_storeTextHeader (inputTextHeader, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	check if the domain is existing	backend
text	presence	checks if input is not _null_	AJAX API
profileId	existance	checks if porfile is existing	backend
apiId	existance	checks if apiId is existing, if id == 0	backend

be_deleteTextHeader (inputTextHeader, processResult, processError)

/** 
 * deletes the text record with the given apiId
 */

inputTextHeader = {
	domainName: "cartman.tel",
	apiId: 23
};

successResult = {
	success: true,
	actionMessages: ["text header deleted"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot delete text header",
               	       "more errors here..."]
};

validation: be_deleteTextHeader (inputTextHeader, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
apiId	existance	checks if apiId is existing	backend

Location management

be_getLocRecord (inputLocRecord, processResult, processError)

/** 
 * retrieve the (only) location record for the given domain;
 * only the apiId, latitude and longitude associated with the
 * location record are returned
 */

inputTextHeader = {
	domainName: "cartman.tel"
};

successResult = {
	success: true,
	apiId: 23,
	latitude: 1.0001,
	longitude: 0.1110,
	actionMessages: "request successful",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get location record",
               	       "more errors here..."]
};

validation: be_getLocRecord (inputLocRecord, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_storeLocation (inputLocation, processResult, processError)

/**
 * create or edit the location record of a domain;
 * if the apiId is 0 (and no other location record exists), a new
 * location record will be created, if it is non-zero,
 * the location record of the given id will be changed;
 * note that only the latitude and longitude of the location are changed,
 * since these are the only values GoogleMap can handle; all other
 * values (i.e., altitude, size, horizontal precision, and vertical
 * precision) which are visible in the DNS are set to a default value
 * (when creating a new location record) or left unchanged (when editing a
 * location record); in case of success, the (new) api id of the location
 * record will be returned; if the record was only edited, the api id will
 * stay the same
 */


inputLocation = {
	domainName: "cartman.tel",
	apiId: 23, /** may be 0 if location is not yet set */
	latitude: 1.0001,
	longitude: 0.1110
};

successResult = {
	success: true,
	apiId: 23,
	actionMessages: ["location changed"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot change location",
               	       "more errors here..."],
	fieldErrors: ["latitude", "latitude invalid",
		      "longitude", "longitude invalid"]
};

validation: be_storeLocation (inputLocation, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend
apiId	existance	checks if id / record is existing, if id == 0	backend
latitude	presence	checks if input value is present and not _null_	AJAX API
longitude	presence	checks if input value is present and not _null_	AJAX API

be_deleteLocation (inputLocation, processResult, processError)

/**
 * deletes a location record defined by its api id
 */

inputLocation = {
	domainName: "cartman.tel",
	apiId: 23
};

successResult = {
	success: true,
	actionMessages: ["location deleted"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot delete location",
               	       "The record is not a location record.",
               	       "more errors here..."]
};

validation: be_deleteLocation (inputLocation, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend
apiId	existance	checks if id / record is existing	backend
apiId	type check	checks if record for given id is a LOC Record	AJAX API

be_saveLocationSearchString (inputSearchString, processResult, processError)

/** 
 * save a location search string (as entered in the text field) for
 * display in the "recent locations" select box;
 * search strings are user-specific, so no domain name needs to be specified;
 * in case of success, the current list of recent location search strings
 * will be returned; this list always contains the last ten entered search
 * strings
 */

inputSearchString = {
	searchString: "21 Oxford Street, London"
};

successResult = {
	success: true,
	list: ["21 Oxford Street, London", 
               "another location", 
               "yet another one"],
	actionMessages: ["search string saved"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot save search string",
               	       "more errors here..."],
	fieldErrors: ["searchString", "search string invalid"]
};

validation: be_saveLocationSearchString (inputSearchString, processResult, processError)

no validation is required as the input can be arbitrary strings

be_getLocationSearchString (inputSearchString, processResult, processError)

/** 
 * returns the current list of recent location search strings;


 * search strings are user-specific, so no domain name needs to be specified;
 * the list always contains the last ten entered search strings;
 * no input is needed for the method
 */


successResult = {
	success: true,
	list: ["21 Oxford Street, London", 
               "another location", 
               "yet another one"],
	actionMessages: ["search string saved"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot save search string",
               	       "more errors here..."],
	fieldErrors: ["searchString", "search string invalid"]
};

validation: be_saveLocationSearchString (inputSearchString, processResult, processError)

no validation is required as the method has not input values

Record management

be_getRecordList (inputRecord, processResult, processError)

/**
 * gets the list of contact (NAPTR) records for the given domain and
 * profile; in order to get a complete list of records for a given domain,
 * the profile id can be set to -1; the returned list contains map
 * for each record, consisting of its api id, the list of service keys,
 * its value, its label, the list of group ids the record belongs to, the
 * list of profile ids the record belongs to, the global flag to tell
 * whether the record is global for this domain, i.e., belonging to all
 * profiles, and the list of locations;
 * additionally for each record a flag is returned to determine whether
 * the record is editable or not
 */

inputRecord = {
	domainName: "stan.cartman.tel",
	profileId: 12 /** use -1 to get all Records of the domain */
};

successResult = {
	success: true,
	domainId: 12,
	recordList: [{apiId: 23, serviceKeys: ["voice", "fax"],
		      value: "+34.34343443", label: "my home number",
		      groups: [1, 3], profiles: [12, 23], global: false,
		      locations: ["x-home", "x-mobile"], editable: true},
		     {apiId: 12, serviceKeys: ["web"],
		      value: "www.telnic.org", label: "my homepage",
		      groups: [3], profiles: [], global: true,
		      locations: ["x-home"], editable: true}],
	actionMessages: ["request successful",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["profile id does not exist",
		       "cannot get record list",
               	       "more errors here..."]
}; 

validation: be_getRecordList (inputRecord, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
domainName	existance	checks if domain is existing	backend
profileId	existance	if profileId == -1, check if profile is existing	combination of AJAX API & backend

be_storeRecord (inputRecord, processResult, processError)

/**
 * stores a single record for the given domain name; in case the api id is
 * set to 0, a new record will be created (and its new api id will be
 * returned on success); for non-zero api ids an existing record will be
 * changed
 * apart from the necessary service keys and the value, there are also the
 * optional parameters label, groups, profiles, and locations; these
 * may be set to the empty string or empty list respectively;
 * in case of success, the (new) api id of the record will be returned; if
 * the record was only edited, the api id will stay the same
 */

inputRecord = {
	domainName: "cartman.tel",
	apiId: 0,
	serviceKeys: ["voice", "fax"],
	value: "+34.34343443",
	label: "my home number",
	groups: [1, 2, 3],
	profiles: [12, 23, 47],
	locations: ["x-home", "x-mobile"]
};

successResult = {
	success: "true",
	actionMessages: ["record stored successfully",
			 "2nd message here",
			 "3dmessage here"],
	apiId: 17
};

errorResult = {
	success: "false",
	actionErrors: ["cannot store record",
		       "record data invalid",
		       "more errors here..."],
	fieldErrors: ["value", "value invalid=== "]
}; 

validation: be_storeRecord (inputRecord, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend
apiId	existance	if apiId == 0, check if a domain with the given apiId is existing	backend
serviceKeys	privileges	checks, if the user is allowed to use the given services based on "Allowed record types" permission	backend
serviceKeys	allow generic	checks, if user is allowed to use generic record types based on permission "Allowed generic record types"	backend
groups	existance	checks, if groups with given ids are existing (for logged in user)	backend
profiles	existance	checks, if profiles with given ids are existing (for logged in user)	backend
serviceKeys, value, label	NAPTR limit	checks if record does not exceed encrytable NAPTR limits	backend

be_getServiceKeys (null, processResult, processError)

/**
 * this method does not need any input; it returns the list of possible
 * service keys (and their internationalized display version) for resource
 * records, e.g., fax, sip, google-im; the result is a list of strings,
 * such that the key is followed by the internationalized version
 */

/** no input needed */

successResult = {
	success: true,
	serviceKeys: ["voice", "Voice Call", "fax", "Fax", "web", "Web Page"],
	actionMessages: "request successful",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get service keys",
               	       "more errors here..."]
}; 

validation:be_getServiceKeys (null, processResult, processError)

no validation is required as the method has not input values

be_getLocations (null, processResult, processError)

/**
 * this method does not need any input; it returns the list of possible
 * location keys (and their internationalized display version) for
 * resource records, e.g., x-home, x-work, x-main; the result is a list of
 * strings, such that the key is followed by the
 * internationalized version
 */

/** no input needed */

successResult = {
	success: true,
	locations: ["x-home", "Home", "x-work", "Work", "x-main",
		      "Main Contact"],
	actionMessages: "request successful",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get locations",
               	       "more errors here..."]
}; 

validation:be_getLocations (null, processResult, processError)

no validation is required as the method has not input values

be_orderRecords (inputRecords, processResult, processError)

/**
 * this method defines a new order on the record list for a given domain;
 * the new order is submitted as a list of api ids; in case of success the
 * records are altered at the backend such that they reflect the new order;
 * in case of failure the current order of the records from the backend is
 * returned such that the frontend can update its list accordingly;
 * this request will fail if the list of api ids is incomplete or if there
 * is an api id, which does not exist at the backend
 */

inputRecords = {
	domainName: "cartman.tel",
	apiIds: [23, 31, 1, 45, 2, 22]
};

successResult = {
	success: true,
	actionMessages: ["records reordered"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	oldApiIds: [1, 2, 22, 23, 31, 45],
	actionErrors: ["cannot reorder records",
               	       "more errors here..."]
};

be_orderRecords (inputRecords, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
apiIds	missing	checks, if all records in list are belonging to given domain	AJAX
apiIds	completeness	checks, if given list has not more or less elements as currently stored for given domain	AJAX

be_enableRecords (inputRecords, processResult, processError)

/**
 * this method enables the given list of records for the given profile;
 * the method will be lenient in such a way that it will not produce an
 * error if one ore more of the input records are already enabled in the
 * given profile;
 *
 * as background information: enabling a record for a profile means that
 * this record will be added to the profile
 */

inputRecords = {
	domainName: "cartman.tel",
	profileId: 23,
	apiIds: [23, 2, 22]
};

successResult = {
	success: true,
	actionMessages: ["records enabled"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot enable records",
               	       "more errors here..."]
};

validation: be_enableRecords (inputRecords, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
profileId	existance	checks, profile with given id is existing	backend
apiIds	completeness	checks, if given list of ids does only contain records belonging to domainName	AJAX

be_disableRecords (inputRecords, processResult, processError)

/**
 * this method disables the given list of records for the given profile;
 * the method will be lenient in such a way that it will not produce an
 * error if one ore more of the input records are already disabled in the
 * given profile;
 *
 * as background information: disabling a record for a profile means that
 * this record will be removed from the profile
 */

inputRecords = {
	domainName: "cartman.tel",
	profileId: 23,
	apiIds: [23, 2, 22]
};

successResult = {
	success: true,
	actionMessages: ["records disabled"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot disable records",
               	       "more errors here..."]
};

validation: be_disableRecords (inputRecords, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
profileId	existance	checks, profile with given id is existing	backend
apiIds	completeness	checks, if given list of ids does only contain records belonging to domainName	AJAX

be_deleteRecords (inputRecords, processResult, processError)

/**
 * this method deletes the given list of records;
 *
 * as background information: deleting a record has an effect on all 
 * profiles of the given domain;
 */

inputRecords = {
	domainName: "cartman.tel",
	apiIds: [23, 2, 22]
};

successResult = {
	success: true,
	actionMessages: ["records deleted"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot delete records",
               	       "more errors here..."]
};

validation: be_deleteRecords (inputRecords, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
apiIds	existance	checks if records with given ids are existing	backend

be_copyRecords (inputRecords, processResult, processError)

/**
 * this method creates copies of the records whose api ids are given;
 * each copy will be added as a new record to the given destination domain
 * name; the ids of the newly created records will be returned as a list;
 * the new records will retain their service keys, values, labels, and 
 * locations, but their groups and profiles will be reset to empty lists,
 * since the destination domain will not have the same groups and profiles;
 * however, records will be assigned to the destination
 * domain's default profile if they belonged to the source domain's
 * default profile
 */

inputRecords = {
	domainName: "cartman.tel",
	apiIds: [23, 2, 22],
	destinationDomainName: "stan.tel"
};

successResult = {
	success: true,
	newApiIds: [27, 28, 29],
	actionMessages: ["records copied"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot copy records",
               	       "more errors here..."],
	fieldErrors: ["destinationDomainName", "domain does not exist"]
};

validation: be_copyRecords (inputRecords, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
apiIds	existance	checks if ids are existing and accessible for logged in user	backend
destinationDomainName	existance	checks, destination with given id is existing and accessible for user	backend

be_moveRecords (inputRecords, processResult, processError)

/**
 * this method works similarly to be_copyRecords; it 'moves' the records
 * whose api ids are given to the destination domain; the records will NOT
 * be able to retain their api ids and will be assigned new ones; they will
 * retain the service keys, values, labels, and locations,
 * but their groups and profiles will be reset to empty lists,
 * since the destination domain will not have the same groups and profiles;
 * however, records will be assigned to the destination
 * domain's default profile if they belonged to the source domain's
 * default profile
 * the ids of the moved records will be returned as a list
 */

inputRecords = {
	domainName: "cartman.tel",
	apiIds: [23, 2, 22],
	destinationDomainName: "stan.tel"
};

successResult = {
	success: true,
	newApiIds: [27, 28, 29],
	actionMessages: ["records moved"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot move records",
               	       "more errors here..."],
	fieldErrors: ["destinationDomainName", "domain does not exist"]
};

validation: be_moveRecords (inputRecords, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
apiIds	existance	checks if ids are existing and accessible for logged in user	backend
destinationDomainName	existance	checks, destination with given id is existing and accessible for user	backend

be_getNTNAPTRRecordList (inputRecord, processResult, processError)

/**
 * gets the list of link (non-terminal NAPTR) records for the given
 * domain and profile; in order to get a complete list of link records
 * for a given domain, the profile id can be set to -1; the returned
 * list contains map for each record, consisting of its api id, the
 * value (i.e., the link itself), the list of group ids the record
 * belongs to, the list of profile ids the record belongs to, and
 * the global flag to tell whether the record is global for this domain,
 * i.e., belonging to all profiles;
 */

inputRecord = {
	domainName: "cartman.tel",
	profileId: 12   /** use -1 to get all links of the domain */
};

successResult = {
	success: true,
	domainId: 12,
	recordList: [{apiId: 23, value: "test.cartman.tel.",
		      groups: [1, 3], profiles: [12, 23],
		      global: false},
		     {apiId: 12, value: "stan.cartman.tel.",
		      groups: [3], profiles: [], global: true}],
	actionMessages: ["request successful",
			 "2nd message here",
                     	 "3rd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["profile id does not exist",
		       "cannot get record list",
               	       "more errors here..."]
};

validation: be_getNTNAPTRRecord (inputRecord, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
profileId	existance	if profileId == -1, check if a profile with the given id is existing	backend

be_storeNTNAPTRRecord (inputRecord, processResult, processError)

/**
 * stores a single non-terminal NAPTR record for the given domain name;
 * in case the api id is set to 0, a new record will be created (and its
 * new api id will be returned on success); for non-zero api ids an
 * existing record will be changed;
 * apart from domain name and apiId the value has to be provided; this
 * is the link the record points to; if the value is not ended with a
 * dot, the value is taken as relative to the given domain name, e.g.,
 * domainName="cartman.tel" and value="test.tel" will result in a link
 * to "test.tel.cartman.tel.", whereas "value.tel." will result in a
 * link to "value.tel.";
 * in case of success, the (new) api id of the record will be returned;
 * if the record was only edited, the api id will stay the same
 */

inputRecord = {
	domainName: "cartman.tel",
	apiId: 0,
	value: "test",
	groups: [],
	profiles: [],
	globalProfile: true
};

successResult = {
	success: true,
	actionMessages: ["record stored successfully",
			 "2nd message here",
			 "3dmessage here"],
	apiId: 17
};

errorResult = {
	success: false,
	actionErrors: ["cannot store record",
		       "record data invalid",
		       "more errors here..."]
};

validation: be_storeRecord (inputRecord, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
apiId	existance	if apiId == 0, check if a non-terminal NAPTR with the given apiId is existing	backend

be_deleteNTNAPTRRecords (inputRecord, processResult, processError)

/**
 * deletes all non-terminal NAPTR records having the same value as the
 * given value, i.e., all records that link to the given value; if the
 * value is not an absolute domain name, it is taken relative to the
 * given domainName, e.g., domainName = "cartman.tel" and value = "test"
 * will delete all non-terminal NAPTR records having "test.cartman.tel" 
 * as their link target;
 * the message will return no error if there is no matching non-terminal
 * NAPTR record;
 *
 * note, that it is also possible to use the be_deleteRecors method to
 * delete non-terminal NAPTR records by their api id
 */

inputRecord = {
	domainName: "cartman.tel",
	value: "test.cartman.tel."
};

successResult = {
	success: true,
	actionMessages: ["record(s) deleted successfully",
			 "2nd message here",
			 "3dmessage here"]
};

errorResult = {
	success: false,
	actionErrors: ["cannot delete record",
		       "more errors here..."]
};

validation: be_deleteNTNAPTRRecords (inputRecord, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
value	existance	checks that the field is not empty	backend

Group management

be_getGroupList (inputGroup, processResult, processError)

/**
 * this methods gets the list of groups for the given domain; if successful,
 * it returns the group's id, its name, and the flag whether the group is
 * the special undeletable all-friends group
 */

inputGroup = {
	domainName: "cartman.tel"
};

successResult = {
	success: true,
	groupList: [{id: 12, name: "friends", allFriends: true},
		    {id: 23, name: "family", allFriends: false}],
	actionMessages: "request successful",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get group list",
               	       "more errors here..."]
}; 

validation: be_getGroupList (inputGroup, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend

be_getGroupRecords (inputGroup, processResult, processError)

/**
 * this method gets the list of records for a given group; it
 * returns the full set of information for each record, i.e.,
 * its id, the service key(s), the value, the label, the list
 * of groups it belongs to, the list of profiles it belongs to,
 * the global flag to tell whether the record is global for this
 * domain, i.e., belonging to all profiles, and its location
 * identifiers; additionally for each record a flag will be
 * returned to determine whether the record is 
 * editable or not; also the domain id will be returned
 */


inputGroup = {
	domainName: "cartman.tel",
	groupId: 23
};

successResult = {
	success: true,
	domainId: 12,
	recordList: [{apiId: 23, serviceKeys: ["voice", "fax"],
		      value: "+34.34343443", label: "my home number",
		      groups: [1, 23], profiles: [12, 23],
		      global: false, locations: ["x-home", "x-mobile"],
		      editable: true},
		     {apiId: 12, serviceKeys: ["web"],
		      value: "www.telnic.org", label: "my homepage",
		      groups: [23], profiles: [], global: true,
		      locations: ["x-home"], editable: true}],
	actionMessages: "request successful",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get record list",
               	       "more errors here..."]
}; 

validation: be_getGroupList (inputGroup, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
groupId	existance	checks if group is existing	backend

be_getGroupFriends (inputGroup, processResult, processError)

/**
 * this method gets the list of friends for a given group; it
 * returns the ids and names of the friends/readers
 */

inputGroup = {
	domainName: "cartman.tel",
	groupId: 23
};

successResult = {
	success: true,
	friendList: [{id: 12, name: "Michael Palin"},
		     {id: 23, name: "Eric Idle"}],
	actionMessages: "request successful",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get list of friends",
               	       "more errors here..."]
}; 

validation: be_getGroupFriends (inputGroup, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
groupId	existance	checks if group is existing	backend

be_addRecordsToGroup (inputGroup, processResult, processError)

/**
 * this method adds a list of records (by their apiIds) to a given
 * group; the method is lenient in such a way that no exception is
 * thrown if a record already belonging to the group is added
 */

inputGroup = {
	domainName: "cartman.tel",
	groupId: 23,
	apiIds: [12, 1, 2]
};

successResult = {
	success: true,
	actionMessages: "records added",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot add records to group",
               	       "more errors here..."]
}; 

validation: be_addRecordsToGroup (inputGroup, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
groupId	existance	checks if group is existing	backend
apiIds	existance	checks if records are existing and accessible for logged in user	backend
apiIds	NAPTR limit	checks if record does not exceed encrytable NAPTR limits	backend

be_removeRecordsFromGroup (inputGroup, processResult, processError)

/**
 * this method removes a list of records (by their apiIds) from a given
 * group; the method is lenient in such a way that no exception is
 * thrown if a record not belonging to the group is removed
 */

inputGroup = {
	domainName: "cartman.tel",
	groupId: 23,
	apiIds: [12, 1, 2]
};


successResult = {
	success: true,
	actionMessages: "records removed",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot remove records to group",
               	       "more errors here..."]
}; 

validation: be_removeRecordsFromGroup (inputGroup, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
groupId	existance	checks if group is existing	backend
apiIds	existance	checks if records are existing and accessible for logged in user	backend

be_addFriendsToGroup (inputGroup, processResult, processError)

/**
 * this method adds a list of readers (by their ids) to a given
 * group; the method is lenient in such a way that no exception is
 * thrown if a reader already belonging to the group is added
 */

inputGroup = {
	domainName: "cartman.tel",
	groupId: 23,
	readerIds: [12, 1, 2]
};

successResult = {
	success: true,
	actionMessages: "friends added",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot add friends to group",
               	       "more errors here..."]
}; 

validation: be_addFriendsToGroup (inputGroup, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
groupId	existance	checks if group is existing	backend
readerIds	existance	checks if records are existing and accessible for logged in user	backend

be_removeFriendsFromGroup (inputGroup, processResult, processError)

/**
 * this method removes a list of readers (by their ids) from a given


 * group; the method is lenient in such a way that no exception is
 * thrown if a reader not belonging to the group is removed
 */

inputGroup = {
	domainName: "cartman.tel",

	groupId: 23,
	readerIds: [12, 1, 2]
};

successResult = {
	success: true,
	actionMessages: "friends removed",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot remove friends from group",
               	       "more errors here..."]
}; 

validation: be_removeFriendsFromGroup (inputGroup, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
groupId	existance	checks if group is existing	backend
readerIds	existance	checks if records are existing and accessible for logged in user	backend

be_storeGroup (inputGroup, processResult, processError)

/**
 * this method creates a new group or edits an existing group;
 * if groupId is set to 0, a new group will be created and its
 * new id will be returned; for a groupId greater than 0 the

 * given group will be edited, this can also be used to change a
 * group's name
 */

inputGroup = {
	domainName: "cartman.tel",
	groupId: 0,
	groupName: "friends",
	readerIds: [12, 1, 2]
};

successResult = {
	success: true,
	groupId: 24,
	actionMessages: "group stored",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot store group",
               	       "more errors here..."]
}; 

validation: be_storeGroup (inputGroup, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
groupId	group limit	if groupId == null, check if use is allowed to create a new group based on "Max. # of groups" permission	backend
readerIds	existance	checks if records are existing and accessible for logged in user	backend
groupName	uniqueness	checks if given group name is unique (for logged in user)	backend

be_deleteGroup (inputGroup, processResult, processError)

/**
 * this method deletes an existing group;
 */

inputGroup = {
	domainName: "cartman.tel",
	groupId: 45
};

successResult = {
	success: true,
	actionMessages: "group deleted",
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot delete group",
               	       "more errors here..."]
}; 

validation: be_addRecordsToGroup (inputGroup, processResult, processError)

value	name	description	implemented
domainName	existance	checks if domain is existing	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	privileges	checks if the logged in user has the rights to access the domain based on usertype and domain delegation	backend
groupId	existance	checks if group is existing and accessible for logged in user	backend
groupId	removeable	checks if group is not the non removeable "all friends" group	backend

== Friending

be_getSOUserName (domain, processResult, processError)

/**
 * this method should only be called for a domain which soConnection is 
 * 'Active', 'Incomplete', or 'Broken'; if the value is 'Unitialised'
 * the method will return an error saying so; 
 * in case of success the method will return the SO user name to whose SO
 * account the domain belongs;
 * this method should be used to ease a user's cold boot process by
 * telling him already with which user name he has to log in
 */

domain = {
	domainName: "cartman.tel"
};

successResult = {
	success: true,

	soUserName: "cartman",

	actionMessages: ["user name retrieved",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["domain unititialised",
		       "more errors here..."]
};

validation: be_getSOUserName (domain, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_getChallenge (credentials, processResult, processError)

/**
 * for the user to be able to use the friending functionality, he needs to
 * initialise his embedded friending client; the initialisation process has 
 * two steps; in this first step the user enters his SO user name and SO web
 * password to get his challenge question; if the authentication was
 * successful the challenge question is returned and can be displayed to the
 * user, which leads to step two;
 */

credentials = {
	soWebUsername: "cartman",
	soWebPassword: "secret"
};

successResult = {
	success: true,
	actionMessages: ["challenge retrieved",
			 "2nd message here"],
	challengeQuestion: "You talkin' to me?"
};

errorResult = {
	success: false,
	actionErrors: ["username or password incorrect",
		       "more errors here..."]
};

validation: be_getChallenge (credentials, processResult, processError)

value	name	description	implemented
soWebUsername	login	check of combination username and password	SOAP API (backend)
soWebPassword	login	check of combination username and password	SOAP API (backend)

be_sendChallengeAnswer (challengeAnswer, processResult, processError)

/**
 * this function is for the second step of the initialisation process
 * (compare be_getChallenge); the user has to supply the answer to the
 * previously received challenge question; since the backend does not save
 * the SO web user name and password, these two strings have to be provided
 * again; if the authentication was successful, the user is connected with
 * the SO and can from then on use the friending functionality
 *
 * as background information: the SO credentials needed for further
 * communication with the SO are stored at the backend, the frontend does
 * not need to care about this
 */

challengeAnswer = {
	soWebUsername: "cartman",
	soWebPassword: "secret",
	answer: "Hugo"
};

successResult = {
	success: true,
	actionMessages: ["answer accepted",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["wrong answer",
		       "more errors here..."]
};

validation: be_sendChallengeAnswer (challengeAnswer, processResult, processError)

value	name	description	implemented
soWebUsername	login	check of combination username, password and answer	SOAP API (backend)
soWebPassword	login	check of combination username, password and answer	SOAP API (backend)
answer	login	check of combination username, password and answer	SOAP API (backend)

be_getMessageList (null, processResult, processError)

/**
 * only possible after initialisation of the friending functionality;
 * this method needs the current domain name to determine which member
 * info should be used; it returns the current list of
 * message (i.e., friending requests, (solicited) friending responses,
 * and unsolicited friending responses) ids; the frontend can compare
 * this list with its current list of ids; for all new ids the messages
 * can be obtained from the backend via the be_getMessages method
 *
 * as background information: it might be useful to call this message
 * regularly, since new messages may arrive at any point of time; also
 * a button to 'check for new message' might be useful
 */

challengeAnswer = {
	domainName: "cartman.tel"
};

successResult = {
	success: true,
	actionMessages: ["messages retrieved",
			 "2nd message here"],
	idList: [13, 14, 16, 19, 20, 21]  /** messages at the NSP */
};

errorResult = {
	success: false,
	actionErrors: ["user does not exist",
		       "more errors here..."]
};

validation: be_getMessageList (null, processResult, processError)

value	name	description	implemented
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_getMessages (messageIdList, processResult, processError)

/**
 * only possible after initialisation of the friending functionality;
 * this method needs the current domain name to determine which member
 * info should be used; it also takes a list of message ids as input
 * and returns the
 * complete messages for these ids; all messages contain the sender,
 * the receiver, the sent date, and an optional cover note; furthermore
 * the messages have to flags to determine the message type:
 * - friending request (isRequest = true, isRejectable = true), friending
 *     requests are messages sent from an SO user to a specific .tel
 *     domain, asking to be put onto the list of friends for this domain;
 *     this message should have the buttons 'reject' and 'accept';
 * - (solicited) friending repsonse (isRequest = false, isRejectable =
 *     false), these messages are purely for informational purposes; the
 *     receiver is informed that an former friending request has been
 *     accepted and he is now on the list of friends of that .tel domain;
 *     this message should only have the button 'delete';
 * - unsolicited friending response (isRequest = false, isRejectable =
 *     true), these messages are also called 'friending invitation',
 *     because they  are sent by a .tel domain owner, who wants to put an
 *     SO user onto his list of friends; to avoid misuse of this feature,
 *     the receiver of an unsolicited friending response can either accept or
 *     reject it this message should have the buttons 'reject' and
 *     'accept'
 */

messageIdList = {
	domainName: "cartman.tel",
	idList: [20, 21]  /** ids of messages to be retrieved */
};

successResult = {
	success: true,
	actionMessages: ["messages retrieved",
			 "2nd message here"],
	messageList: [ {id: 20, isRequest: true, isRejectable: true,
			from: "henri", to: "cartman.tel",
			received: "2008-06-13 23:59",
			coverNote: "blabla"},

		       {id: 21, isRequest: false,
			isRejectable: true, from: "henri.tel", to: "cartman",
			received: "2008-06-15 04:20",
			coverNote: "Duh=== "} ]
};

errorResult = {
	success: false,
	actionErrors: ["message does not exist",
		       "more errors here..."]
};

validation: be_getMessageList (null, processResult, processError)

value	name	description	implemented
idList	existance	checks if the ids in list are existing	SOAP API (backend)
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_acceptRequestMessage (message, processResult, processError)

/**
 * only possible after initialisation of the friending functionality;
 * this method is used to accept a received friending request; thus
 * the supplied message id must be of a friending request message;
 * this method also needs the current domain name to determine which
 * member info should be used; 
 * accepting a friending request means that a friend (sometimes also
 * called reader) will be added to the .tel domain; the name of the new
 * friend may be chosen by the user and is supplied as the readerName to
 * this method;
 * if the call was successful a new reader has been created and its id is
 * returned; the id of the original message is also returned;
 *
 * as background information: accepting a friending request will initiate a
 * (solicited) friending response to be sent to the sender of the friending
 * request
 */

message = {
	domainName: "cartman.tel",
	id: 42
	readerName: "Dummi"  /** the name of new reader as shown to this user */
};

successResult = {
	success: true,
	actionMessages: ["message accepted",
			 "2nd message here"],
	id: 14,        /** the id of the created reader */
	readerName: "Dummi",
	messageId: 42  /** the id of the accepted message */
};



errorResult = {
	success: false,
	actionErrors: ["no message with given id found",
		       "more errors here..."],
	fieldErrors: ["readerName": "illegal reader name"]
};

validation: be_acceptRequestMessage (message, processResult, processError)

value	name	description	implemented
id	existance	checks if the ids in list are existing	SOAP API (backend)
id	double entries	checks if reader sending the request is unique	SOAP API (backend)
readerName	double entries	checks if readerName is unique	backend
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_acceptRequestMessages (message, processResult, processError)

/**
 * only possible after initialisation of the friending functionality;
 * this method is used to accept several received friending request at
 * the same time; thus the supplied message ids must be of friending
 * request messages; this method also needs the current domain name to
 * determine which member info should be used; 
 * accepting a friending request means that a friend
 * (sometimes also called reader) will be added to the .tel domain; the
 * name of the new friends are automatically determined by their sender
 * names, but can always be changed later through the be_renameFriend
 * method; if the call was successful a new reader has been created for
 * each of the selected friending requests; the returned response in the
 * success case will contain a list of pairs of id and name for each reader;
 * the ids of the original messages are also returned;
 *
 * as background information: accepting a friending request will initiate a
 * (solicited) friending response to be sent to the sender of the friending
 * request
 */

message = {
	domainName: "cartman.tel",
	idList: [1, 4, 42]
};

successResult = {
	success: true,
	actionMessages: ["message accepted",
			 "2nd message here"],
	readerList: [{id: 14, readerName: "stan"},
		     {id: 11, readername: "sam"},
		     {id: 23, readername: "john"}],
	messageIdList: [1, 4, 42]  /** the ids of the accepted messages */
 };

errorResult = {
	success: false,
	actionErrors: ["no message with given id found",
		       "reader with name xyz already exists"]
};

validation: be_acceptRequestMessages (message, processResult, processError)

value	name	description	implemented
id	existance	checks if the ids in list are existing	SOAP API (backend)
id	double entries	checks if reader sending the request is unique	SOAP API (backend)
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_acceptInvitationMessages (message, processResult, processError)

/**
 * only possible after initialisation of the friending functionality;
 * this method is used to accept one or several received unsolicited
 * friending requests (also called friending invitations); thus the
 * supplied message ids must be of unsolicited friending response messages;
 * this method also needs the current domain name to determine which member
 * info should be used; 
 * accepting an unsolicited friending response means that the user agrees
 * to be put onto the sender's list of friends; the ids of the original
 * messages are also returned;
 *
 * as background information: the sender of an unsolicited friending
 * response has put the receiver onto his list of friends; accepting or
 * rejecting this message does not make any difference; however,
 * accepting this message means that a publisher will be added for the
 * receiver at the SO; only if such a publisher exists, the user can
 * actually read any private data (otherwise he would not know where to
 * look for this private data)
 */

message = {
	domainName: "cartman.tel",
	idList: [42,13,1]
};

successResult = {


	success: true,
	actionMessages: ["messages accepted, you are now able to read private" +
                         " data provided for you at the domain",
			 "2nd message here"],
	messageIdList: [42, 13, 1]  /** the ids of the accepted messages */
};

errorResult = {
	success: false,
	actionErrors: ["no message with given id found",
		       "more errors here..."]

validation: be_acceptRequestMessages (message, processResult, processError)

value	name	description	implemented
id	existance	checks if the ids in list are existing	SOAP API (backend)
id	double entries	checks if reader sending the request is unique	SOAP API (backend)
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_rejectMessages (message, processResult, processError)

/**
 * only possible after initialisation of the friending functionality;
 * this method needs the current domain name to determine which member
 * info should be used; 
 * this method is the same for all kinds of friending messages,
 * because rejecting a message just means deleting it; no further action
 * will be taken;
 * the message ids will be returned in case of a successful deletion
 */

message = {
	domainName: "cartman.tel",
	idList: [42, 12, 1]
};

successResult = {
	success: true,
	idList: [42, 12, 1],
	actionMessages: ["messages rejected",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["no message with given id found",
		       "more errors here..."]
};

validation: be_rejectMessages (message, processResult, processError)

value	name	description	implemented
idList	existance	checks if field is not empty or null	AJAX API
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_sendFriendingRequest (newReqMessage, processResult, processError)

/**
 * only possible after initialisation of the friending functionality;
 * if a user would like to read private data of a specific .tel domain,
 * he needs to send a friending request to this domain; optionally a
 * cover note may be added; this method needs the current domain name
 * to determine which member info should be used; 
 *
 * as background information: once the friending request has been

 * accepted by the receiver, a corresponding (solicited) friending
 * response will be sent back to the sender of the friending request;
 * if such a response is received, the process has been completed and
 * the sender of the request is able to read private data at the domain
 */

newReqMessage = {
	domainName: "cartman.tel",
	to: "henri.tel",
	coverNote: "barbarbar"
};
  
successResult = {
	success: true,
	actionMessages: ["message sent",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["sending of message failed",
		       "more errors here..."],
	fieldErrors: ["to": "target domain does not exist",
		      "coverNote": "cover note too long"]
};

validation: be_sendFriendingRequest (newReqMessage, processResult, processError)

value	name	description	implemented
to	existance	checks if field is not empty or null	AJAX API
to	sending possible	checks ifSO can deliver message to domain and/or domain is existing	SOAP API (backend)
domainName	presence	checks if input value is present and not _null_	AJAX API
domainName	existance	checks if domain is existing	backend

be_sendFriendingInvitation (newInvMessage, processResult, processResult)

/**
 * only possible after initialisation of the friending functionality;
 * this method directly adds a new person to the list of friends; the
 * name of the friend can be chosen by setting the readerName parameter; the
 * from parameter determines to which domain the friend should be added;
 * to contains the SO user name of the person to invite as a friend and
 * the cover note may be an arbitary message for the receiver;
 * the successful result contains the id of the newly created reader (friend)
 * 
 * as background information: this method initiates an unsolicted
 * friending response to be sent to the SO user; only if that user accepts
 * the message, he is actually able to view the private data provided at
 * this domain; the sender of the friending invitation will not be notified
 * whether his invitation was accepted or rejected
 */

newInvMessage = {
	from: "cartman.tel",  /* specific subdomain the invited user shall be
                                 able to read */
	to: "henri",          /* SO username of the person to invite */
	readerName: "Henri VIII",  /* name of new reader as shown to this 
                                      user */
	coverNote: "barbarbar",
};

successResult = {
	success: true,
	actionMessages: ["message sent",
			 "2nd message here"],
	id: 6    /** the id of the user added as a new reader */
};

errorResult = {
	success: false,
	actionErrors: ["sending of message failed",
		       "more errors here..."],
	fieldErrors: ["from": "domain does not belong to you",
		      "to": "target user does not exist",
		      "readerName": "illegal reader name",
		      "coverNote": "cover note too long"]
};

validation: be_sendFriendingInvitation (newInvMessage, processResult, processResult)

value	name	description	implemented
from	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend
to	existance	checks SO can deliver message to domain and/or domain is existing	SOAP API (backend)
readerName	uniqueness	checks if readerName is unique	backend
readerName	reader limit	checks if user can create more readers based on permission "Max. # of readers"	backend

be_getFriendList (friendInput, processResult, processError)

/**
 * gets the list of all friends/readers for the given domain; 
 * note, that friends are only available for second level, but not third or
 * deeper level domains;
 * the friend's id and name will be returned
 */

friendInput = {
	domainName: "cartman.tel"
};

successResult = {
	success: true,
	friendList: [{id: 12, name: "Michael Palin"},
		     {id: 23, name: "Eric Idle"}],
	actionMessages: ["request successful",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["list of friends could not be retrieved",
		       "domain name must be a second level domain",
		       "more errors here..."]
};

validation: be_getFriendList (friendInput, processResult, processError)

value	name	description	implemented
domainName	presence	checks if domain is not empty or _null_	AJAX API
domainName	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend

be_deleteFriends (friendInput, processResult, processError)

/**
 * deletes a list of friends determined by their ids
 */

friendInput = {
	domainName: "cartman.tel",
	idList: [1,34]
}

successResult = {
	success: true,
	actionMessages: ["friends deleted",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["friends could not be deleted",
		       "more errors here..."]
};

validation: be_deleteFriends (friendInput, processResult, processError)

value	name	description	implemented
domainName	presence	checks if domain is not empty or _null_	AJAX API
domainName	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend
idList	existance	checks if isd in list are existing and accessible for logged in user	backend

be_renameFriend (friendInput, processResult, processError)

/**
 * renames a friend/reader determined by the id; the new name of the
 * friend is supplied in the readerName parameter
 */

friendInput = {
	domainName: "cartman.tel",
	id: 1,
	readerName: "My best friend"
}

successResult = {
	success: true,
	actionMessages: ["friend renamed",
			 "2nd message here"]
};



errorResult = {
	success: false,
	actionErrors: ["friend could not be renamed",
		       "more errors here..."],
	fieldErrors: ["readerName", "friend xyz already exist"]
};

validation: be_renameFriend (friendInput, processResult, processError)

value	name	description	implemented
domainName	presence	checks if domain is not empty or _null_	AJAX API
domainName	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend
id	existance	checks if isd in list are existing and accessible for logged in user	backend
readerName	uniqueness	checks if readerName is unique	backend

Keyword management

Currently available keyword types (short forms): s, fn, ln, nn, dob, g, ms, pa, a1, a2, a3, tc, sp, pc, c, ll, o, d, jt, hi, ft, bpa, bn, bar, bsa, sa, aux

be_getValidKeywords (null, processResult, processError)

/**
 * retrieve the list of valid keyword types;
 * the returned list contains the short form of the keyword type, a
 * human-readable description, and two boolean flags:
 * - canHaveSecondaries is true if the keyword type can have secondary
 *   keywords associated with it,
 * - canBeSecondary is true if the keyword type can appear as a secondary
 *   keyword
 */

/** no input needed */

successResult = {
	success: true,
	actionMessages: ["valid keywords retrieved",
			 "2nd message here"],
	validKeywordList = [ {shortForm: "pa", displayText: "Postal address",
			      canHaveSecondaries: true, canBeSecondary: false},
			     {shortForm: "a1", displayText: "Address line 1",
			      canHaveSecondaries: false, canBeSecondary: true}
			   ]
};

errorResult = {
	success: false,
	actionErrors: ["retrieval of valid keywords failed",
		       "more errors here..."]
};

validation: be_getValidKeywords (null, processResult, processError)

no validation required as the method does not have any input values

be_getKeywords (domain, processResult, processError)

/**
 * retrieve the list of current keywords for the given domain;
 * the returned list contains the following information for each keyword:
 * - id;
 * - field: the short form of the keyword type;
 * - value: the user-defined value;
 * - secondaryKewords: the list of secondary keywords (may be empty) of this
 *     keyword, has the same structure as the result of this request,
 *     except for the secondaryKeywords part
 */

domain = {
	domain: "cartman.tel"
};

successResult = {
	success: true,
	actionMessages: ["keywords retrieved",
			 "2nd message here"],

	keywordList = [ {id: 12, field: "pa", value: "my postal address",
			 secondaryKewords: [ {id: 15, field: "a1", 
                                              value: "my street"} ]},
			{id: 13, field: "fn", value: "cart", 
                         secondaryKewords: []} ]
};

errorResult = {
	success: false,
	actionErrors: ["retrieval of keywords failed",
		       "more errors here..."]
};

validation: be_getKeywords (domain, processResult, processError)

value	name	description	implemented
domainName	presence	checks if domain is not empty or null	AJAX API
domainName	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend

be_getSuggestions (inputKeyword, processResult, processError)

/**
 * retrieves a list of suggestions for the given keyword type and value;
 * the returned list contains keyword values starting with the given
 * value; note that the value has to contain at least two characters for
 * the suggestion to work;
 * the suggestions are generated via a request to the Tel-Pages index
 */

inputKeyword = {
	type: "tc",
	value: "Do"
};

successResult = {
	success: true,
	type: "tc",
	prefix: "Do",
	suggestions: ["Donaueschingen", "Dorsten", "Dortmund", "Dover"],
	actionMessages: ["suggestions retrieved",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["suggestions could not be retrieved",
		       "more errors here..."]
};

validation: be_getSuggestions (inputKeyword, processResult, processError)

value	name	description	implemented
type	presence	checks if the type is not empty or null	SOAP API
type	valid	checks if input value is valid (in list of defined keyword types)	backend
prefix	empty	checks if the prefix is not empty or null	SOAP API

be_addKeyword (newKeyword, processResult, processError)

/**
 * add a new (primary) keyword for the given domain;
 * the type is provided as the short form, the value specifies the
 * user's input;
 * upon success, the id of the created keyword is returned
 */

newKeyword = {
	domain: "cartman.tel",
	type: "tc",
	value: "Dormtund"
};

successResult = {
	success: true,
	actionMessages: ["keyword added",
			 "2nd message here"],
	id: 27    /** the id assigned to the newly created keyword */
};


errorResult = {
	success: false,
	actionErrors: ["addition of keyword failed",
		       "more errors here..."],
	fieldErrors: ["type": "unknown keyword type",
		      "value": "keyword value too long"]
};

validation: be_addKeyword (newKeyword, processResult, processError)

value	name	description	implemented
domainName	presence	checks if domain is not empty or _null_	SOAP API
domainName	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend
type	presence	checks if the type is not empty or null	SOAP API
type	valid	checks if input value is valid (in list of defined keyword types)	backend
type	limit	checks if the use is allowed to create a new search data entry based on "Max. # of keywords" permission	backend
type	allowed	checks if use is allowed to use the given type based "Allowed keywords" permission	backend

be_addSecondaryKeywords (newKeywords, processResult, processError)

/**
 * add new secondary keywords for the given domain;
 * the primary keyword to associated these new keywords with is specified
 * by its id, the list of secondary keywords contain the types given as
 * the short form and the values representing the user's input;
 * upon success, the ids of the created keywords are returned in given order
 */

newKeywords = {
	domain: "cartman.tel",
	primaryKeywordId: 47,
	keywords: [{key: "sp", value: "NRW"}, {key: "sp", value: "D"}]
};


successResult = {
	success: true,
	actionMessages: ["message sent",
			 "2nd message here"],

	ids: [28, 29]  /** the ids assigned to the newly created keywords */
};

errorResult = {
	success: false,
	actionErrors: ["addition of keyword failed",
		       "more errors here..."],
	fieldErrors: ["primaryKeywordId": 
                        "primary keyword of given id does not exist",
		      "type": "unknown keyword type",
		      "value": "keyword value too long"]
};

validation: be_addSecondaryKeywords (newKeywords, processResult, processError)

value	name	description	implemented
domainName	presence	checks if domain is not empty or null	SOAP API
domainName	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend
primaryKeywordId	existance	checks if keyword is existing and accessible for logged in user	backend
primaryKeywordId	secondary keywords allowed	checks if primary keyword is capabile for secondary keywords	backend
keywords.sp	valid	checks if input value is valid (in list of defined keyword types)	backend
keywords.sp	limit	checks if the use is allowed to create a new search data entry based on "Max. # of keywords" permission	backend
keywords.sp	allowed	checks if use is allowed to use the given type based "Allowed keywords" permission	backend

be_updateKeyword (keywordData, processResult, processError)

/**
 * updates a primary keyword of the given domain, specified by its id;
 * note that the primary keyword and all existing secondaries will be
 * deleted, new keywords will be created according to the data provided
 * in the "keywords" list, where the first element contains the new data

 * of the primary keyword, all following elements will be added as
 * secondary keywords;
 * upon success, the list of ids of the newly created keywords is
 * returned, with the first id being the one of the updated primary,
 * followed by the ids of its secondary keywords
 */

keywordData = {
	domain: "cartman.tel",
	primaryKeywordId: 42,
	keywords: [{key: "aux", value: "Miscellaneous info"},
		   {key: "hi", value: "playing the mouse organ"},
		   {key: "sp", value: "NRW"}]
};

successResult = {
	success: true,
	actionMessages: ["Keyword updated successfully.",
			 "2nd message here"],
	newIdList: [66, 67, 68]  /* the ids of the new keywords */
};

errorResult = {
	success: false,
	actionErrors: ["A keyword with ID \"42\" does not exist.",
		       "more errors here..."]
};

be_deleteKeywords (keywords, processResult, processError)

/**
 * deletes a number of keywords, provided as a list of ids; secondary keywords are 
 * deleted automatically with there primary keyword.
 */

keywords = {
	domain: "cartman.tel",
	idList: [13, 15],
};

successResult = {
	success: true,
	actionMessages: ["keywords deleted",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["deletion of keywords failed",
		       "more errors here..."]
};

validation: be_deleteKeywords (keywords, processResult, processError)

value	name	description	implemented
domainName	presence	checks if domain is not empty or _null_	backend
domainName	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend
idList	existance	checks if keywords in id list are existing and accessible for logged in user	backend

be_copyKeywords (keywords, processResult, processError)

/**
 * copies the given keywords (provided as a list of ids) from the given domain to
 * another domain/folder; dest specifies the destination domain where the
 * new keywords should be created;
 * to copy a primary keyword including the secondary keywords, all keywords should
 * be provided in the (linearized) list of ids in such an order that each list of 
 * secondary keywords is preceeded by its primary keyword. 
 * If the secondary keywords should be copied, too, please add "includeSecondary: true"
 * to the request.
 * Upon success, the list of ids of the newly created keywords is returned
 */

keywords = {
	domain: "henri.tel",
	idList: [13, 15, 16],
	dest: "social.henri.tel",  /** the destination folder/domain */
        includeSecondary: true   /** to copy secondary keywords for primary keywords */ 
};

successResult = {
	success: true,
	actionMessages: ["keywords copied",

			 "2nd message here"],
	newIdList: [21, 22, 23]  /* the ids of the new keywords in the
                                    destination folder */
};

errorResult = {
	success: false,
	actionErrors: ["copying of keywords failed",
		       "more errors here..."],
	fieldErrors: ["dest": "destination folder not found"]
};

validation: be_copyKeywords (keywords, processResult, processError)

value	name	description	implemented
domainName	presence	checks if domain is not empty or _null_	SOAP API
domainName	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend
idList	existance	checks if keywords in id list are existing and accessible for logged in user	backend
idList	secondaryKeyword	if includeSecondary is set to true, no secondary keywords are allowed in idList	backend
dest	empty	checks if domain is not empty or null	SOAP API
dest	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend

be_moveKeywords (keywords, processResult, processError)

/**
 * moves keywords (provided as a list of ids) from the given domain to
 * another domain; dest specifies the destination domain where the
 * keywords should be moved to; since the ids of the moved keywords do not
 * change, no corresponding list is returned.
 * To move a primary keyword including the secondary keywords, all keywords should
 * be provided in the (linearized) list of ids in such an order that each list of 
 * secondary keywords is preceeded by its primary keyword or use the parameter
 * "includeSecondary:true" for automatic move of secondary keywords
 */

keywords = {
	domain: "henri.tel",
	idList: [13, 15, 16]
	dest: "social.henri.tel",  /** the destination folder/subdomain */
        includeSecondary: true   /** to copy secondary keywords for primary keywords */ 
};

successResult = {
	success: true,
	actionMessages: ["keywords moved",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["moving of keywords failed",

		       "more errors here..."],
	fieldErrors: ["dest": "destination folder not found"]
};

validation: be_moveKeywords (keywords, processResult, processError)

value	name	description	implemented
domainName	presence	checks if domain is not empty or _null_	SOAP API
domainName	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend
idList	existance	checks if keywords in id list are existing and accessible for logged in user	backend
idList	secondaryKeyword	if includeSecondary is set to true, no secondary keywords are allowed in idList	backend
dest	empty	checks if domain is not empty or null	SOAP API
dest	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend

be_reorderSubkeywords (subkeywordOrder, processResult, processError)

/**
 * reorder the secondary keywords of a primary keyword (defined by its
 * id) for a given domain/folder;
 * the idList is the (newly ordered) list of ids;
 * if an error occurs, the unaltered ordering is returned to enable
 * consistency and simplify the presentation of the current ordering to the
 * user
 */

subkeywordOrder = {
	domain: "cartman.tel",
	primaryKeywordId: 36,
	idList: [2, 13, 7, 1, 10]
};

successResult = {
	success: true,
	actionMessages: ["subkeywords reordered",
			 "2nd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["reordering of subkeywords failed",
		       "more errors here..."],
	oldIdList: [1, 2, 7, 10, 13]
};

validation: be_reorderSubkeywords (subkeywordOrder, processResult, processError)

value	name	description	implemented
domain	presence	checks if domain is not empty or _null_	SOAP API
domain	existance	checks if domain is existing (domain is not existing, if not belonging to user)	backend
primaryKeywordId	existance	checks if keywords in id list are existing and accessible for logged in user	backend
idList	equality	checks if the entries are matching to the stored onces (same number of records and ids)	backend