public class TC
extends java.lang.Object
This class provides a convenient way to interact with a Allegra server from a Groovy
console. You need to install the TC.jar
file and the documentation
in the .groovy/lib
directory in your home directory. Then you can call all methods from
the Groovy console application with TC.<methodName()>.
To get help type TC.help()
.
Make sure that on your Allegra server the web service is enabled on the server configuration page, tab "Other items". Then in the Groovy console type
import com.trackplus.TC;
TC.login("admin","tissi","http://localhost:8080/track");
TC.help();
replacing "localhost:8080/track"
with your servers URL and the user name and password
with your user name and password.
If you want to get a JSON string with all users and print it to the console (assuming you have administrator rights) type
String users = TC.getAllUsers();
System.out.println(users);
Modifier and Type | Method and Description |
---|---|
static java.lang.String |
addGroup(java.lang.String groupName)
Creates a new group with the given name
|
static java.lang.String |
addGroup(java.lang.String groupName,
boolean inheritAuthor,
boolean inheritManager,
boolean inheritResponsible)
Creates a new group with the given name
|
static void |
addPersonsToGroup(java.lang.String groupID,
java.lang.String[] personIDs)
Adds a number of persons identified by their object ids to the group with the given id.
|
static java.lang.String |
addProject(java.lang.String projectName)
Creates a new project or workspace and saves it to the database.
|
static void |
addRoleAssignment(WSRoleAssignmentEditBean roleAssignmentEditBean)
Adds a role assignment (a users role in a workspace).
|
static WSItemBean |
createItem(java.lang.String projectID,
java.lang.String itemTypeID,
WSEditItemContextBean editItemContext,
java.lang.String title,
java.lang.String description)
Create an item, setting some parameters.
|
static void |
deleteGroup(java.lang.String groupID)
Deletes the group with the given object identifier.
|
static void |
deleteGroupWithReplacement(java.lang.String groupID,
java.lang.String replacementID)
Replaces all references to the group with object identifier groupID
with the replacement and then deletes the group with groupID.
|
static void |
deletePerson(java.lang.String personID)
Delete a user from the database based on its object id.
|
static void |
deletePersonWithReplacement(java.lang.String personID,
java.lang.String replacementID)
Delete a user from the database based on its object id.
|
static void |
deleteProject(java.lang.Integer projectID)
Deletes a project or workspace based on its object identifier.
|
static void |
deleteProject(java.lang.String projectID)
Deletes a project or workspace based on its object identifier.
|
static java.lang.String |
executeQuery(java.lang.String queryID)
Get a JSON string containing the result of the given query.
|
static void |
exit()
Logs you off Allegra web service.
|
static java.lang.String |
getAllGroups()
Gets a JSON string with all user groups.
|
static WSGroupBean[] |
getAllGroupsBeans()
Gets an array of all user group beans.
|
static WSLabelValueBean[] |
getAllRoles()
Gets all user roles with their names and object identifiers.
|
static java.lang.String |
getAllUsers()
Gets a JSON string with all users registered in the systems database.
This is for looking at the users only, the data is not complete enough for editing a user entry. |
static WSPersonBean[] |
getAllUsersBeans()
Gets an array with all users registered in the systems database.
This is for looking at the users only, the data is not complete enough for editing a user entry. |
static java.lang.String |
getAssignmentRolesByProject(java.lang.String projectID)
Gets a JSON string list with roles assignments (which user has which roles) for a project or workspace.
|
static WSRoleAssignmentBean[] |
getAssignmentRolesByProjectBeans(java.lang.String projectID)
Gets a list with roles assignments (which user has which roles) for a project or workspace.
|
static java.lang.String |
getGroupEdit(java.lang.String groupID)
Gets a group bean you can modify and save back.
|
static WSGroupEditBean |
getGroupEditBean(java.lang.String groupID)
Gets a group bean you can modify and save back.
|
static WSItemBean |
getItem(java.lang.String itemID)
Retrieve an item by its identifier.
|
static java.lang.String |
getPersonEdit(java.lang.Integer personID)
Gets a JSON string of a user based on his integer object id.
|
static java.lang.String |
getPersonEdit(java.lang.String personID)
Gets a JSON string of a user based on his object id.
|
static WSPersonEditBean |
getPersonEditBean(java.lang.String personID)
Gets a bean of a user based on his object id.
|
static WSPersonEditBean |
getPersonEditBeanByLoginName(java.lang.String loginName)
Gets a bean of a user based on his login name.
|
static java.lang.String |
getPersonEditByLoginName(java.lang.String loginName)
Gets a JSON string of a user based on his login name.
|
static java.lang.String |
getPersonsForGroup(java.lang.String groupID)
Returns a JSON string of person beans that are members of the given group.
|
static WSPersonBean[] |
getPersonsForGroupBeans(java.lang.String groupID)
Returns a list of person beans that are members of the given group.
|
static java.lang.String |
getProjectEdit(java.lang.Integer projectID)
Gets a project bean in a JSON string that can be edited and saved back to the database.
|
static java.lang.String |
getProjectEdit(java.lang.String projectID)
Gets a project bean in a JSON string that can be edited and saved back to the database.
|
static WSProjectEditBean |
getProjectEditBean(java.lang.Integer projectID)
Gets a project bean that can be edited and saved back to the database.
|
static WSProjectEditBean |
getProjectEditBean(java.lang.String projectID)
Gets a project bean that can be edited and saved back to the database.
|
static WSProjectEditBean |
getProjectEditBeanByName(java.lang.String projectName)
Gets a project bean that can be edited and saved back to the database.
|
static java.lang.String |
getProjectEditByName(java.lang.String projectName)
Gets a project bean in a JSON string that can be edited and saved back to the database.
|
static WSTreeNode[] |
getProjectsAsTree()
Gets a tree structure of project label/value beans (see
WSLabelValueBean ). |
static java.lang.String |
getQueries()
Get all queries or filters as a flat structure not considering folders
as a JSON string.
|
static java.lang.String |
getQueriesTree()
Get the complete query tree with folders and filters as a JSON string.
|
static java.lang.String |
getQueryEdit()
Gets a query bean in a JSON string that can be edited and saved back to the database.
|
protected static void |
handleTCLFacadeException(TCLFacadeException e)
Simple Handler for TCLFacadeException
|
static void |
help()
Opens a browser with the help for this class.
|
static java.lang.String |
login()
This method is just for error handling.
|
static java.lang.String |
login(java.lang.String dummy)
This method is just for error handling.
|
static java.lang.String |
login(java.lang.String dummy,
java.lang.String dummy2)
This method is just for error handling.
|
static TCLFacade |
login(java.lang.String user,
java.lang.String passwd,
java.lang.String url)
Logs you in to the Allegra web service.
|
static void |
logoff()
Logs you off Allegra web service.
|
static void |
logout()
Logs you off Allegra web service.
|
static void |
main(java.lang.String[] args)
The main function just prints some help on how to use this class.
|
static void |
printAllProjects()
Prints all projects to the console.
|
static void |
printAllRoles()
Prints a list with all roles defined in the system to the console.
|
protected static void |
printEditGroup(WSGroupEditBean groupEditBean) |
static void |
printEditProject(WSProjectEditBean projectEditBean) |
protected static void |
printGroups(WSGroupBean[] allGroups) |
static void |
printItemTypes()
Print the list of item types available for this project.
|
static void |
printItemTypes(java.lang.String projectID)
Print the list of item types available for this project.
|
static void |
printProjectsItemTypes()
For each project, print item types available.
|
static void |
printRoleAssignments(WSRoleAssignmentBean[] roleAssignmentBeans,
WSLabelValueBean[] allRoles,
WSPersonBean[] allPersons,
WSGroupBean[] allGroups) |
protected static void |
printRoles(WSLabelValueBean[] allRoles) |
static void |
printStates()
Print the list of available states.
|
static void |
quit()
Logs you off Allegra web service.
|
static void |
removePersonsFromGroup(java.lang.String groupID,
java.lang.String[] personIDs)
Removes a number of persons identified by their object ids from the group with the given id.
|
static void |
removeRoleAssignment(WSRoleAssignmentEditBean roleAssignmentEditBean)
Removes a specific role assignment.
|
static java.lang.String |
saveItem(WSItemBean item)
Save an item to the database.
|
static java.lang.String |
savePersonEdit(java.lang.String personJSON)
Save a user to the database.
|
static WSPersonEditBean |
savePersonEdit(WSPersonEditBean person)
Save a user to the database.
|
public static void main(java.lang.String[] args)
args
- public static TCLFacade login(java.lang.String user, java.lang.String passwd, java.lang.String url)
Logs you in to the Allegra web service. Example:
import com.trackplus.TC;
TC.login("admin","tissi","http://localhost:8080/track");
user
- the Allegra user namepasswd
- the Allegra user passwordurl
- the Allegra server urlpublic static java.lang.String login()
public static java.lang.String login(java.lang.String dummy)
public static java.lang.String login(java.lang.String dummy, java.lang.String dummy2)
public static void logout()
Logs you off Allegra web service.
public static void logoff()
Logs you off Allegra web service.
public static void exit()
Logs you off Allegra web service.
public static void quit()
Logs you off Allegra web service.
public static WSPersonBean[] getAllUsersBeans()
Gets an array with all users registered in the systems database.
This is for looking at the users only, the data is not complete enough for editing a user entry.
You need to have logged in first (see login(java.lang.String, java.lang.String, java.lang.String)
).
if you want to interact with the result, you may be better off with the JSON version of this
command (see getAllUsers()
).
Example:
import com.trackplus.TC;
import com.trackplus.track.ws.beans.WSPersonBean;
WSPersonBean[] users = TC.getAllUsersBeans();
public static java.lang.String getAllUsers()
Gets a JSON string with all users registered in the systems database.
This is for looking at the users only, the data is not complete enough for editing a user entry.
You need to have logged in first (see login(java.lang.String, java.lang.String, java.lang.String)
).
Example:
import com.trackplus.TC;
import com.trackplus.track.ws.beans.WSPersonBean;
// ... login here, then:
String users = TC.getAllUsers();
public static WSPersonEditBean getPersonEditBean(java.lang.String personID)
Gets a bean of a user based on his object id. The result is suitable for
changing the users properties and saving it back into the database.
If you want to manually change this user you may be better off using the
JSON equivalent of this method (see getPersonEdit(Integer)
).
You need to have logged in first (see login(java.lang.String, java.lang.String, java.lang.String)
).
Example:
import com.trackplus.TC;
import com.trackplus.track.ws.beans.WSPersonEditBean;
import com.trackplus.track.ws.beans.WSPersonBean;
// ... login here, then:
WSPersonBean[] users = TC.getAllUsersBeans();
WSPersonEditBean user = TC.getPersonEditBean(users[0].getPersonID());
personID
- the object id of the user, a number like 101 or 133public static WSPersonEditBean getPersonEditBeanByLoginName(java.lang.String loginName)
Gets a bean of a user based on his login name. The result is suitable for
changing the users properties and saving it back into the database.
If you want to manually change this user you may be better off using the
JSON equivalent of this method (see getPersonEdit(Integer)
).
You need to have logged in first (see login(java.lang.String, java.lang.String, java.lang.String)
).
Example:
import com.trackplus.TC;
import com.trackplus.track.ws.beans.WSPersonEditBean;
import com.trackplus.track.ws.beans.WSPersonBean;
// ... login here, then:
WSPersonBean[] users = TC.getAllUsersBeans();
WSPersonEditBean user = TC.getPersonEditBean(users[0].getPersonID());
loginName
- the login name of the userpublic static java.lang.String getPersonEdit(java.lang.String personID)
Gets a JSON string of a user based on his object id. The result is suitable for changing the users properties and saving it back into the database.
You need to have logged in first (see login(java.lang.String, java.lang.String, java.lang.String)
).
personID
- the object id of the user, a number like 101 or 133public static java.lang.String getPersonEdit(java.lang.Integer personID)
Gets a JSON string of a user based on his integer object id. The result is suitable for changing the users properties and saving it back into the database.
You need to have logged in first (see login(java.lang.String, java.lang.String, java.lang.String)
).
personID
- the object id of the user, a number like 101 or 133public static java.lang.String getPersonEditByLoginName(java.lang.String loginName)
Gets a JSON string of a user based on his login name. The result is suitable for changing the users properties and saving it back into the database.
You need to have logged in first (see login(java.lang.String, java.lang.String, java.lang.String)
).
Example:
import com.trackplus.TC;
import com.trackplus.track.ws.beans.WSPersonEditBean;
// ... login here, then:
WSPersonBean[] users = TC.getAllUsersBeans();
String user = TC.getPersonEditBean(users[0].getPersonID());
loginName
- the login name of the userpublic static java.lang.String savePersonEdit(java.lang.String personJSON)
Save a user to the database. If it already exists, just modify. Otherwise create a new user.
To identify the user you need to supply at least the login name, the e-mail, and the last name.
To obtain a list with possible parameters use getPersonEdit(Integer)
.
personJSON
- the JSON object for the user to be savedpublic static WSPersonEditBean savePersonEdit(WSPersonEditBean person)
Save a user to the database. If it already exists, just modify. Otherwise create a new user.
To identify the user you need to supply at least the login name, the e-mail, and the last name.
To obtain a list with possible parameters use getPersonEditBean(String)
.
person
- the WSPersonEditBean for the user to be savedpublic static void deletePerson(java.lang.String personID)
Delete a user from the database based on its object id. If the person has any data associated with
it like items or workspaces, an error is returned. To delete such a person you need to provide
a replacement person with the delete operation (see deletePersonWithReplacement(String, String)
).
personID
- the object id of the user to be deleted.public static void deletePersonWithReplacement(java.lang.String personID, java.lang.String replacementID)
Delete a user from the database based on its object id. If the person has any data associated with it like items or workspaces, it is replaced with the replacement persons id.
personID
- the object id of the user to be deleted.replacementID
- the object id of the user which replaces the user to be deletedpublic static WSGroupBean[] getAllGroupsBeans()
Gets an array of all user group beans.
public static java.lang.String getAllGroups()
Gets a JSON string with all user groups.
public static WSGroupEditBean getGroupEditBean(java.lang.String groupID)
Gets a group bean you can modify and save back.
public static java.lang.String getGroupEdit(java.lang.String groupID)
Gets a group bean you can modify and save back.
public static void deleteGroup(java.lang.String groupID)
Deletes the group with the given object identifier. If the group is being referenced anywhere
an error is returned. To delete such a group use deleteGroupWithReplacement(String, String)
.
groupID
- the groups object idpublic static void deleteGroupWithReplacement(java.lang.String groupID, java.lang.String replacementID)
Replaces all references to the group with object identifier groupID with the replacement and then deletes the group with groupID.
groupID
- the groups object idreplacementID
- the replacement groups object idpublic static java.lang.String addGroup(java.lang.String groupName)
groupName
- the new groups namepublic static java.lang.String addGroup(java.lang.String groupName, boolean inheritAuthor, boolean inheritManager, boolean inheritResponsible)
groupName
- the new groups nameprotected static void printGroups(WSGroupBean[] allGroups)
public static void addPersonsToGroup(java.lang.String groupID, java.lang.String[] personIDs)
groupID
- the group id for the group to which the persons will be added.personIDs
- the array of persons identified by their object ids.public static void removePersonsFromGroup(java.lang.String groupID, java.lang.String[] personIDs)
groupID
- the group id for the group from which the persons will be removed.personIDs
- the array of persons identified by their object ids.public static WSPersonBean[] getPersonsForGroupBeans(java.lang.String groupID)
groupID
- the group object id for which to retrieve the group members.public static java.lang.String getPersonsForGroup(java.lang.String groupID)
groupID
- the group object id for which to retrieve the group members.protected static void printEditGroup(WSGroupEditBean groupEditBean)
public static WSTreeNode[] getProjectsAsTree()
Gets a tree structure of project label/value beans (see WSLabelValueBean
). . The label is the project name,
the value he object identifier.
This is useful if you need to work with workspace hierarchies.
WSLabelValueBean
objectspublic static java.lang.String addProject(java.lang.String projectName)
Creates a new project or workspace and saves it to the database.
projectName
- the name of the projectpublic static WSProjectEditBean getProjectEditBean(java.lang.String projectID)
Gets a project bean that can be edited and saved back to the database.
projectID
- the project or workspaces object identifierpublic static WSProjectEditBean getProjectEditBeanByName(java.lang.String projectName)
Gets a project bean that can be edited and saved back to the database.
projectName
- the project or workspaces namepublic static java.lang.String getProjectEdit(java.lang.String projectID)
Gets a project bean in a JSON string that can be edited and saved back to the database.
projectID
- the project or workspaces object identifierpublic static WSProjectEditBean getProjectEditBean(java.lang.Integer projectID)
Gets a project bean that can be edited and saved back to the database.
projectID
- the project or workspaces object identifierpublic static java.lang.String getProjectEdit(java.lang.Integer projectID)
Gets a project bean in a JSON string that can be edited and saved back to the database.
projectID
- the project or workspaces object identifierpublic static java.lang.String getProjectEditByName(java.lang.String projectName)
Gets a project bean in a JSON string that can be edited and saved back to the database.
projectName
- the project or workspaces namepublic static void deleteProject(java.lang.String projectID)
Deletes a project or workspace based on its object identifier.
projectID
- the project or workspace object identifier (an integer)public static void deleteProject(java.lang.Integer projectID)
Deletes a project or workspace based on its object identifier.
projectID
- the project or workspace object identifierpublic static void printAllProjects()
Prints all projects to the console.
public static void printEditProject(WSProjectEditBean projectEditBean)
public static WSLabelValueBean[] getAllRoles()
Gets all user roles with their names and object identifiers.
public static void printAllRoles()
Prints a list with all roles defined in the system to the console.
protected static void printRoles(WSLabelValueBean[] allRoles)
public static WSRoleAssignmentBean[] getAssignmentRolesByProjectBeans(java.lang.String projectID)
Gets a list with roles assignments (which user has which roles) for a project or workspace.
projectID
- the project or workspace object identifierpublic static java.lang.String getAssignmentRolesByProject(java.lang.String projectID)
Gets a JSON string list with roles assignments (which user has which roles) for a project or workspace.
projectID
- the project or workspace object identifierpublic static void addRoleAssignment(WSRoleAssignmentEditBean roleAssignmentEditBean)
Adds a role assignment (a users role in a workspace).
roleAssignmentEditBean
- the role assignment with all required attributespublic static void removeRoleAssignment(WSRoleAssignmentEditBean roleAssignmentEditBean)
Removes a specific role assignment.
roleAssignmentEditBean
- the role assignment to be removedpublic static void printRoleAssignments(WSRoleAssignmentBean[] roleAssignmentBeans, WSLabelValueBean[] allRoles, WSPersonBean[] allPersons, WSGroupBean[] allGroups)
public static java.lang.String getQueriesTree()
public static java.lang.String getQueries()
Get all queries or filters as a flat structure not considering folders as a JSON string. The important parts are the id and label attributes.
public static java.lang.String executeQuery(java.lang.String queryID)
Get a JSON string containing the result of the given query.
queryID
- the id of the query to be executedpublic static java.lang.String getQueryEdit()
Gets a query bean in a JSON string that can be edited and saved back to the database.
public static WSItemBean getItem(java.lang.String itemID)
Retrieve an item by its identifier. This retrieves the item, but all references to other objects are just available as foreign keys. For example, the priority is not returned as "high" but rather as "1". The manager is not returned as "John Manager" but as "238".
Example code:
import com.trackplus.*; import com.trackplus.track.ws.beans.*; TC.login("admin","tissi","http://localhost:8080/track"); WSItemBean item = TC.getItem("7"); println item.getSynopsis() + ": " + item.getProjectID(); item.setStateID("13"); // 9=assessing, 10=unverified, 11=verified, maybe different on your system. item.setNewComment("This test failed with error code 7856"); TC.saveItem(item);
itemID
- the object identifier of the item to retrieve.public static WSItemBean createItem(java.lang.String projectID, java.lang.String itemTypeID, WSEditItemContextBean editItemContext, java.lang.String title, java.lang.String description)
Create an item, setting some parameters. The item is not saved! To create the item context proceed like this:
try { editItemCtx=connector.getNewItemContext(projectID, itemTypeID); } catch (RemoteException e) { LOGGER.warn(e.getStackTrace(),e); } catch (TCLFacadeException e) { System.err.println("Error obtaining the newItemContext"); handleTCLFacadeException(e); }
To set additional attributes follow the example below. First you must have created the item. The WSFieldsConfigBean contains settings (label, tool tip, readOnly) and options only for fields present on the form configured for NEW item or EDIT in a given project and for a given item type. If you change a field that is not present on the form it will have no effect.
WSFieldsConfigBean cfg=editItemCtx.getFieldsConfig(); // set the priority (assuming the priority is present on the form) // the priorities length must be larger than 1 because include the default value WSSortedOptionBean[] priorities=cfg.getPriorityOptions(); String priorityID=priorities[priorities.length-1].getObjectID(); item.setPriorityID(priorityID); //set the comment item.setNewComment("Comment from web service."); WSCustomFieldValue[] customFieldValues=item.getCustomFieldValues(); if(customFieldValues==null){ System.out.println("null customFieldValues"); }else{ System.out.println("customFieldValues size="+customFieldValues.length); }
projectID
- the object id of the workspace in which to create the itemitemTypeID
- the object id of the item type for the new itemeditItemContext
- the context for this item (option values, fields, etc.)title
- the title for the itemdescription
- the description for the itempublic static java.lang.String saveItem(WSItemBean item)
Example code:
import com.trackplus.*; import com.trackplus.track.ws.beans.*; TC.login("admin","tissi","http://localhost:8080/track"); WSItemBean item = TC.getItem("7"); println item.getSynopsis() + ": " + item.getProjectID(); item.setStateID("13"); // 9=assessing, 10=unverified, 11=verified, maybe different on your system. item.setNewComment("This test failed with error code 7856"); TC.saveItem(item);
item
- the item to be made persistentprotected static void handleTCLFacadeException(TCLFacadeException e)
e
- public static void printProjectsItemTypes()
public static void printItemTypes(java.lang.String projectID)
projectID
- the object id of the project for which to print available item types.public static void printItemTypes()
public static void printStates()
public static void help()