com.telelogic.cs.webservices
Class ChangeService

java.lang.Object
  extended by com.telelogic.cs.webservices.ChangeService
All Implemented Interfaces:
com.telelogic.cs.webservices.ChangeServiceSkeletonInterface

public class ChangeService
extends java.lang.Object
implements com.telelogic.cs.webservices.ChangeServiceSkeletonInterface

The IBM Rational Change Web Service

The IBM® Rational® Change web service (or simply ChangeService) provides programmatic access to common Rational Change operations. It enables the development of tools and integrations to combine existing Rational Change functionality in new ways. This document describes how to get started with ChangeService and details on the functionality that it provides.

ChangeService is a web service that communicates with wrapped, document/literal style SOAP messages, and as such can used by any language or tool that understands this communication style. For simplicity this document documents the operations as Java code, but the details of how the operations work are the same no matter what tool or client language is used. Each method described here corresponds to an operation of the same name in the ChangeService WSDL document; each type corresponds to to an XML element in the types section of that document. Combining this document with ChangeService WSDL should give a complete view of how to interact with ChangeService.

ChangeService is automatically deployed as part of a standard Rational Change installation; no additional configuration is required. As such, it will be available through the same host and port as the Rational Change web interface. Once Rational Change is running the WSDL for it can be found at http://yourserver:8600/your_context/webservices/ChangeService?wsdl (substitute the server name, port and context root of your installation).

ChangeService operates with the same security model as the Rational Change web interface: a user is required to log on to receive a token; the token must be passed with each request. Operations given an invalid token will fail. Some operations may fail with a valid token if the user associated with that token is restricted by further security restrictions like lifecycle or group security. Requests and responses, including the login operation, are sent as clear-text XML documents. Security conscious sites are recommended to configure Rational Change to operate over secure HTTP (HTTPS) to encrypt all communications.

Where to Start

Most interactions with ChangeService are likely to begin with a call to getLoginInfo. This does not require a token and returns information about the available Rational Change databases and roles. After deciding on a database and role, a call can be made to login to authenticate the user and receive a token specific that database. Clients must keep track of this token for the duration of their interaction. All other operations will require a valid token. Note that a different token is required for each database and role the user wishes to log on with. Tokens can become invalid after going unused for a certain amount of time or if the Rational Change server is restarted.

Many operations also require a CR ID (change request ID) to know which change request to operate on. In non-DCM-enabled databases this is simply the problem number, which is just a unique integer associated with each change request, for example, 101. In DCM-enabled databases this will be the DCM database identifier, the DCM delimiter, and the problem number, for example, m#101. While the Rational Change web interface will allow users to omit the DCM identifier in some cases and still shows the right change request, ChangeService does not promise this convenience; you should always specify the full CR ID in DCM-enabled databases. In practice, this is usually not a worry since operations that return change requests will already include the correct CR ID.

Working With Attributes

Several operations require or return Attribute value objects. Attributes can be defined to have one of several possible types in the database: string, date, and boolean. Consequently, the Attribute type has optional value fields for each possible type. When working with an attribute you should set and read the appropriate value based on the known type of the attribute. For example, for a string attribute like 'problem_synopsis' you should set or read the stringValue field, for a date you should set and read the dateTimeValue field, etc. Other values should be left unset, but will be ignored if present. The type of an attribute found in its attribute definition.

Always take note of the type to the attribute you are dealing with--their types may not always be what you expect. For example, some of the default attributes that are shown as checkboxes in the web interface (that is, some CCM_TOGGLE attributes) have historically used 'string' as their database type; other checkbox attributes use 'boolean' for the database type. While these types are not important to a user of the web interface, web service clients must get them right to avoid errors and confusing results.

While there is no explicit function for deleting attributes, they can be deleted by setting them to a null value. In most web service client frameworks this is accomplished by setting the attribute's appropriate type value to null, nil, or a similar "unset" value. The actual XML request would omit the element for the "null" value entirely, or create it as an empty element with no children. Rational Change allows you to treat certain things as "attributes" in its lifecycle editor even though they are not actually attributes in the database. Relationships are treated like attributes with regards to adding them to a form, but they cannot be looked up with attribute related functions. Pseudo-attributes, which begin with an underscore, cannot be read; they are used to trigger action when modifying a change request. For example, _COMMENTS can be set as if it were an attribute, but it actually causes a note to be appended to the transition log.

Attachment Support

ChangeService handles the transfer of change request attachments with MTOM (Message Transmission Optimization Mechanism), a W3C Recommendation for handling the transfer of large amounts of binary--or textual--data. This means your web service client must support MTOM to transfer attachments to and from ChangeService. MTOM is becoming increasingly more common, but often requires that you explicitly enable it. Consult your web service client's documentation for details on how to do so. Without MTOM enabled you will not be able to upload and download change request attachments--the functions will likely appear to work, but your attachments will be empty. Functions unrelated to attachments will work with or without MTOM support.

Optionally, you may also want to check if your web service client supports HTTP chunking. Though not required, this can significantly decrease the amount of memory required to send large attachments.

Since:
4.6

Constructor Summary
ChangeService()
           
 
Method Summary
 com.telelogic.cs.webservices.types.AddAdminNotesResponse addAdminNotes(java.lang.String token, java.lang.String crid, com.telelogic.cs.webservices.types.ArrayOfAdminNote adminNotes)
          Allows admins to append notes to the transition log.
 com.telelogic.cs.webservices.types.AssociateTaskResponse associateTask(java.lang.String token, java.lang.String crid, java.lang.String taskId)
          Associates an existing task to a change request.
 java.lang.String createAssociatedTask(java.lang.String token, java.lang.String crid, com.telelogic.cs.webservices.types.ArrayOfAttribute attributes)
          Creates a new CM task associated with the given change request.
 com.telelogic.cs.webservices.types.DeleteAttachmentResponse deleteAttachment(java.lang.String token, java.lang.String attachmentId)
          Removes an attachment from its associated change request and deletes it.
 com.telelogic.cs.webservices.types.DeleteQueryResponse deleteQuery(java.lang.String token, com.telelogic.cs.webservices.types.QueryType type, java.lang.String name)
          Deletes a saved CR query by name.
 com.telelogic.cs.webservices.types.DisassociateTaskResponse disassociateTask(java.lang.String token, java.lang.String crid, java.lang.String taskId)
          Disassociates a task from a change request.
 javax.activation.DataHandler downloadAttachment(java.lang.String token, java.lang.String attachmentId)
          Downloads a single attachment from a CR.
 com.telelogic.cs.webservices.types.ArrayOfStateDefinition getAllStateDefs(java.lang.String token)
          Gets all state definitions for the current process, that is, the state definitions from each lifecycle.
 com.telelogic.cs.webservices.types.ArrayOfSubmitStates getAllSubmitDetails(java.lang.String token)
          Gets all states that CRs can be submitted to, plus the label of the corresponding submit transition.
 com.telelogic.cs.webservices.types.ArrayOfString getAllSubmitStates(java.lang.String token)
          Gets all states that CRs can be submitted to.
 com.telelogic.cs.webservices.types.ArrayOfTask getAssociatedTasks(java.lang.String token, java.lang.String crid, com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
          Gets the tasks associated with a given change request.
 com.telelogic.cs.webservices.types.ArrayOfAttributeDefinition getAttributeDefs(java.lang.String token)
          Gets all the attribute definitions for the current process.
 com.telelogic.cs.webservices.types.ArrayOfAttribute getAttributes(java.lang.String token, java.lang.String crid, com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
          Gets attributes values for a change request.
 java.lang.String getDcmDelimiter(java.lang.String token)
          Get the DCM delimiter for the current database.
 java.lang.String getDcmId(java.lang.String token)
          Get the DCM identifier for the current database.
 com.telelogic.cs.webservices.types.ArrayOfString getLifecycles(java.lang.String token)
          Gets the names of all lifecycles in the CR process.
 java.lang.String getListboxDefaultValue(java.lang.String token)
          Used to get the default display value for listboxes, which is normally "Any".
 com.telelogic.cs.webservices.types.ArrayOfListboxEntry getListboxEntries(java.lang.String token, java.lang.String listboxName)
          Gets the possible values for a given listbox.
 com.telelogic.cs.webservices.types.LoginInfo getLoginInfo()
          Returns the databases and roles a user can use to log on to Rational Change.
 com.telelogic.cs.webservices.types.ArrayOfString getNextStates(java.lang.String token, java.lang.String crid)
          Determines the next possible states that a CR can be transitioned to by the current user.
 java.lang.String getQueryBuilderUrl(java.lang.String token)
          Gets a URL to the new query dialog.
 com.telelogic.cs.webservices.types.ArrayOfQueryDefinition getQueryDefs(java.lang.String token)
          Gets the saved CR queries available to this user.
 com.telelogic.cs.webservices.types.ArrayOfChangeRequest getRelatedFrom(java.lang.String token, java.lang.String crid, java.lang.String relationship, com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
          Gets related change requests where the relationship travels from the given change request to zero or more other change requests.
 com.telelogic.cs.webservices.types.ArrayOfChangeRequest getRelatedTo(java.lang.String token, java.lang.String crid, java.lang.String relationship, com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
          Gets related change requests where the relationship travels to the given change request from zero or more other change requests.
 com.telelogic.cs.webservices.types.ArrayOfReportDefinition getReportDefs(java.lang.String token)
          Gets the saved CR reports available to this user.
 java.lang.String getReportUrl(java.lang.String token, com.telelogic.cs.webservices.types.QueryType type, java.lang.String name, java.lang.String optionalTitle)
          Gets the URL to run a saved CR report.
 com.telelogic.cs.webservices.types.ArrayOfString getRequiredAttributesForSubmit(java.lang.String token, java.lang.String toState)
          Gets the attributes that are required to submit a new CR into a given state.
 com.telelogic.cs.webservices.types.ArrayOfString getRequiredAttributesForTransition(java.lang.String token, java.lang.String fromState, java.lang.String toState)
          Gets the attributes that are required to transitions a CR from one state to another.
 java.lang.String getShowUrl(java.lang.String crUrn, java.lang.String token)
          Returns the URL for showing the CR.
 com.telelogic.cs.webservices.types.ArrayOfStateDefinition getStateDefsForLifecycle(java.lang.String token, java.lang.String lifecycle)
          Gets the state definitions for a specific lifecycle.
 com.telelogic.cs.webservices.types.ArrayOfString getSubmitStatesForLifecycle(java.lang.String token, java.lang.String lifecycle)
          Gets the states that CRs can be submitted to for a particular lifecycle.
 java.lang.String getSubmitUrl(java.lang.String submitState, java.lang.String token)
          Returns the URL for submitting a CR.
 java.lang.String getTokenlessShowFormUrl(java.lang.String token, java.lang.String crid)
          Gets a URL to a show for for the given change request.
 com.telelogic.cs.webservices.types.ArrayOfTransitionLogEntry getTransitionLog(java.lang.String token, java.lang.String crid)
          Returns a structured version of the transition log.
 java.lang.String getTransitionUrl(java.lang.String token, java.lang.String crUrn, java.lang.String toState, java.lang.String optionalLabel)
          Gets a URL to the transition form to the requested state for a CR.
 com.telelogic.cs.webservices.types.ArrayOfListboxEntry getValueListboxEntries(java.lang.String token, java.lang.String valueListboxName)
          Gets the possible values for a given value-listbox.
 boolean isDcmEnabled(java.lang.String token)
          Determine if the current database is DCM-enabled.
 com.telelogic.cs.webservices.types.ArrayOfAttachmentDetail listAttachments(java.lang.String token, java.lang.String crid)
          Gets information about each of the attachments associated with a CR.
 java.lang.String login(java.lang.String username, java.lang.String password, java.lang.String database, java.lang.String role)
          Logs on a user and returns a unique token to identify them in future requests.
 com.telelogic.cs.webservices.types.LogoutResponse logout(java.lang.String token)
          Logs out a user by releasing their checked out license immediately (without any license linger time).
 com.telelogic.cs.webservices.types.ArrayOfChangeRequest query(java.lang.String token, java.lang.String queryString, com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
          Queries for change requests with an ad-hoc query string.
 com.telelogic.cs.webservices.types.RelateResponse relate(java.lang.String token, java.lang.String fromCrid, java.lang.String toCrid, java.lang.String relationship)
          Relates one change request to another through a given relationship name.
 com.telelogic.cs.webservices.types.ArrayOfChangeRequest runQuery(java.lang.String token, com.telelogic.cs.webservices.types.QueryType type, java.lang.String name, com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
          Runs a saved CR query by name.
 com.telelogic.cs.webservices.types.SetAttributesResponse setAttributes(java.lang.String token, java.lang.String crid, com.telelogic.cs.webservices.types.ArrayOfAttribute attributes)
          Modifies a change request by updating its attributes with the given values.
 com.telelogic.cs.webservices.types.SetTaskAttributesResponse setTaskAttributes(java.lang.String token, java.lang.String taskId, com.telelogic.cs.webservices.types.ArrayOfAttribute attributes)
          Modifies a task by updating its attributes with the given values.
 java.lang.String ssoLogin(java.lang.String ssoToken, java.lang.String database, java.lang.String role)
          Logs on a user using a single sign on (SSO) token instead of a name and password.
 java.lang.String submit(java.lang.String token, java.lang.String toState, com.telelogic.cs.webservices.types.ArrayOfAttribute initialAttributes)
          Submits and creates a new change request.
 com.telelogic.cs.webservices.types.SyncDatabaseResponse syncDatabase(java.lang.String token, java.lang.String database)
          In central server mode, waits for the central server to finish syncing all its CRs into a particular database.
 com.telelogic.cs.webservices.types.TransitionResponse transition(java.lang.String token, java.lang.String crid, java.lang.String toState, com.telelogic.cs.webservices.types.ArrayOfAttribute attributes)
          Transitions a change request to one of its next states.
 com.telelogic.cs.webservices.types.UnrelateResponse unrelate(java.lang.String token, java.lang.String fromCrid, java.lang.String toCrid, java.lang.String relationship)
          Breaks the relationship between two change requests.
 com.telelogic.cs.webservices.types.UploadAttachmentResponse uploadAttachment(java.lang.String token, java.lang.String toCrid, javax.activation.DataHandler attachment, java.lang.String attachmentName, java.lang.String description)
          Uploads a file and attaches it to a change request.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ChangeService

public ChangeService()
Method Detail

getLoginInfo

public com.telelogic.cs.webservices.types.LoginInfo getLoginInfo()
Returns the databases and roles a user can use to log on to Rational Change. Does not require a token and can be used to determine which Rational Change database and role to log on to.

Specified by:
getLoginInfo in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Returns:
Both an array of log on roles, and an array of DatabaseInfoss. Each DatabaseInfo contains the name of the database that must be used with the login operation, an alias for the database that can be used as its displayable name, an optional description of the database, and whether or not the database is enabled. Note that users logging on with the Admin role can still log on to disabled databases; other roles cannot.

login

public java.lang.String login(java.lang.String username,
                              java.lang.String password,
                              java.lang.String database,
                              java.lang.String role)
                       throws com.telelogic.cs.webservices.LoginFault
Logs on a user and returns a unique token to identify them in future requests. If already logged on, the existing token is returned. Tokens may expire if they are not used for long enough, or if the Rational Change server is restarted.

Specified by:
login in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
username - name of user to log in as.
password - password.
database - the database to log in to, as returned by getLoginInfo.
role - the user role, typically "User". "Admin" is required for some operations.
Returns:
The unique token for this user in this database and role.
Throws:
com.telelogic.cs.webservices.types.LoginFault - If any login details are wrong or missing.
com.telelogic.cs.webservices.LoginFault

getAllSubmitDetails

public com.telelogic.cs.webservices.types.ArrayOfSubmitStates getAllSubmitDetails(java.lang.String token)
Gets all states that CRs can be submitted to, plus the label of the corresponding submit transition. These are all the submit states for all lifecycles in the CR process.

Specified by:
getAllSubmitDetails in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
Returns:
The names of all possible states the CR can be submitted to, along with the corresponding transition name.
Throws:
java.lang.RuntimeException - If no process is installed.

transition

public com.telelogic.cs.webservices.types.TransitionResponse transition(java.lang.String token,
                                                                        java.lang.String crid,
                                                                        java.lang.String toState,
                                                                        com.telelogic.cs.webservices.types.ArrayOfAttribute attributes)
                                                                 throws com.telelogic.cs.webservices.ModifyFault
Transitions a change request to one of its next states. A transition is also a way to modify--or set attributes on--a change request, but a transition also moves the change request along in the lifecycle. Depending on the lifecycle, there may be no way to revert the change request to the previous state.

Transitions may have required attributes. Values must be supplied for all required attributes that are currently unset on the change request, otherwise the transition will fail.

Users with the process admin privilege can transition between any two existing states. The transition doesn't need to exist in the CR process. This is called an admin transition. Admins are also allowed to omit required attributes.

Fires triggers if appropriate. Updates the transition log to note the change if successful.

Specified by:
transition in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token -
crid - the CR to transition.
toState - the name of the state to transition to.
attributes - the attribute values to update or set on the change request during the transition.
Returns:
An empty response.
Throws:
com.telelogic.cs.webservices.types.ModifyFault - If the transition could not occur. Possibly because the transition is invalid or illegal for the current user. Or if there were missing required attributes.
com.telelogic.cs.webservices.ModifyFault

getAttributes

public com.telelogic.cs.webservices.types.ArrayOfAttribute getAttributes(java.lang.String token,
                                                                         java.lang.String crid,
                                                                         com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
Gets attributes values for a change request. Values can only be requested for attributes defined in the CR process, otherwise returns an error.

Specified by:
getAttributes in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token -
crid - the change request to inspect.
attributeNames - the names of the attributes to get the values of.
Returns:
The values of the requested attributes. There will be one name/value pair for each attribute that had value on the change requests. Attributes that are defined in the CR process, but had no value on the given change request will not be returned, thus the number of returned attributes may be less than the requested number. Found values will be returned in the same order that they were requested.

unrelate

public com.telelogic.cs.webservices.types.UnrelateResponse unrelate(java.lang.String token,
                                                                    java.lang.String fromCrid,
                                                                    java.lang.String toCrid,
                                                                    java.lang.String relationship)
                                                             throws com.telelogic.cs.webservices.ModifyFault
Breaks the relationship between two change requests. Does not delete either change request.

Specified by:
unrelate in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token -
fromCrid - the CR ID the relationship comes from.
toCrid - the CR ID the relationship goes to.
relationship - the name of the relationship to break. Note the direction of the relationship dictates which CR IDs are used as the "from" and "to" IDs as described for relate.
Returns:
An empty response.
Throws:
com.telelogic.cs.webservices.types.ModifyFault - If the relationship cannot be broken, likely because the user does not have write privileges to one or more of the change requests.
com.telelogic.cs.webservices.ModifyFault

relate

public com.telelogic.cs.webservices.types.RelateResponse relate(java.lang.String token,
                                                                java.lang.String fromCrid,
                                                                java.lang.String toCrid,
                                                                java.lang.String relationship)
                                                         throws com.telelogic.cs.webservices.ModifyFault
Relates one change request to another through a given relationship name. Though relationships can be traversed in both directions, they retain a notion of direction, that is, which change request the relationship flows from, and which it flows to. This influences both how relationships are latter looked up, and the logical meaning of a relationship. For example, the 'duplicate' relationship flows to the duplicate change request; only one of the associated change requests is a "duplicate" of the other.

Specified by:
relate in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
fromCrid - The CR ID to create the relationship from.
toCrid - The CR ID to relate to.
relationship - The name of the relationship to create.
Returns:
An empty response.
Throws:
com.telelogic.cs.webservices.types.ModifyFault - If the relationship could not be created, likely because the user does not have write privileges to one or more of the change requests.
com.telelogic.cs.webservices.ModifyFault

getAssociatedTasks

public com.telelogic.cs.webservices.types.ArrayOfTask getAssociatedTasks(java.lang.String token,
                                                                         java.lang.String crid,
                                                                         com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
Gets the tasks associated with a given change request.

Specified by:
getAssociatedTasks in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - The CR ID to get the tasks from.
attributeNames - A list of attribute names to look up on the associated tasks.
Returns:
The associated tasks with their requested attributes. An empty array if there are none.

setAttributes

public com.telelogic.cs.webservices.types.SetAttributesResponse setAttributes(java.lang.String token,
                                                                              java.lang.String crid,
                                                                              com.telelogic.cs.webservices.types.ArrayOfAttribute attributes)
                                                                       throws com.telelogic.cs.webservices.PartialModifyFault,
                                                                              com.telelogic.cs.webservices.ModifyFault
Modifies a change request by updating its attributes with the given values. If attributes do not already exist, they are first created. Can only set attributes defined in the lifecycle. Updates as many attributes as possible; attributes that cannot be updated are skipped.

Fires triggers if appropriate. Updates the transition log to indicate the changes.

Note that some attributes should be considered private and not altered directly. For example, the transition_log attribute is kept up to date when a change request is modified. Making this modifiable then setting it directly could corrupt the attribute if it is not formatted in a specific manner. In this case, it is preferable to add a note to the transition log by setting the _COMMENT pseudo-attribute, which has effect of appending a new note to the transition log. Other special attributes which should considered private include e-signature and subscription attributes.

Specified by:
setAttributes in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - The CR to modify.
attributes - The attribute values to set. Attributes not defined in the CR process are discarded.
Returns:
An empty response.
Throws:
com.telelogic.cs.webservices.types.ModifyFault
com.telelogic.cs.webservices.types.PartialModifyFault - If some, but not all, of the attributes could be updated. The PartialModificationFault detail section will contain a list of all the attributes that could not be updated.
com.telelogic.cs.webservices.PartialModifyFault
com.telelogic.cs.webservices.ModifyFault

getListboxEntries

public com.telelogic.cs.webservices.types.ArrayOfListboxEntry getListboxEntries(java.lang.String token,
                                                                                java.lang.String listboxName)
                                                                         throws com.telelogic.cs.webservices.NoMatchFault
Gets the possible values for a given listbox. Values are returned as entries that pair a label, used for visually displaying a value, with the value, that is actually used for setting and reading attributes. Listbox entries will normally use the same text for their label and value. The exception is default or "Any" value which represents "no value" or "delete the current value" depending on the context.

If the value-listbox is defined in multiple scopes, precedence is given to personal over shared over system.

Specified by:
getListboxEntries in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
listboxName - and the name of the listbox to retrieve.
Returns:
All possible values for the given listbox returned as pairs of displayable labels and data values.
Throws:
com.telelogic.cs.webservices.types.NoMatchFault - If no listbox has the given name.
com.telelogic.cs.webservices.NoMatchFault

getSubmitStatesForLifecycle

public com.telelogic.cs.webservices.types.ArrayOfString getSubmitStatesForLifecycle(java.lang.String token,
                                                                                    java.lang.String lifecycle)
                                                                             throws com.telelogic.cs.webservices.NoMatchFault
Gets the states that CRs can be submitted to for a particular lifecycle. Any CR submitted to one of the returned states will be part of the given lifecycle.

Specified by:
getSubmitStatesForLifecycle in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
lifecycle - The name of a lifecycle.
Returns:
The names of the states a CR can be submitted to to enter the given lifecycle.
Throws:
com.telelogic.cs.webservices.types.NoMatchFault - If the lifecycle does not exist.
com.telelogic.cs.webservices.NoMatchFault

createAssociatedTask

public java.lang.String createAssociatedTask(java.lang.String token,
                                             java.lang.String crid,
                                             com.telelogic.cs.webservices.types.ArrayOfAttribute attributes)
                                      throws com.telelogic.cs.webservices.CreateFault
Creates a new CM task associated with the given change request.

Specified by:
createAssociatedTask in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - The CRID to associate the task to.
attributes - A list of attribute values to set on the new task. All attributes must be known task attributes (have an entry in task_framework.cfg). Unknown attributes are discarded and not set on the new task.
Returns:
The task ID of the newly created task.
Throws:
com.telelogic.cs.webservices.types.CreateFault - If a new task could not be created and associated to the change request.
com.telelogic.cs.webservices.CreateFault

getRelatedFrom

public com.telelogic.cs.webservices.types.ArrayOfChangeRequest getRelatedFrom(java.lang.String token,
                                                                              java.lang.String crid,
                                                                              java.lang.String relationship,
                                                                              com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
Gets related change requests where the relationship travels from the given change request to zero or more other change requests. In parent-child relationships this function traverses from the parent to the children. For example, duplicate CRs are often handled with the 'duplicate' relationship. Calling this function on a CR with duplicates will find all of the duplicates of the CR since the relationship travels from the CR to its duplicates.

Specified by:
getRelatedFrom in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - The parent CRID.
relationship - A relationship name to follow.
attributeNames - Attributes to return with the related change requests.
Returns:
The related change requests or an empty array if none were found.

getStateDefsForLifecycle

public com.telelogic.cs.webservices.types.ArrayOfStateDefinition getStateDefsForLifecycle(java.lang.String token,
                                                                                          java.lang.String lifecycle)
                                                                                   throws com.telelogic.cs.webservices.NoMatchFault
Gets the state definitions for a specific lifecycle.

Specified by:
getStateDefsForLifecycle in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
lifecycle - The name of a lifecycle.
Returns:
The state definitions for the given lifecycle.
Throws:
com.telelogic.cs.webservices.types.NoMatchFault - If the lifecycle doesn't exist.
com.telelogic.cs.webservices.NoMatchFault

submit

public java.lang.String submit(java.lang.String token,
                               java.lang.String toState,
                               com.telelogic.cs.webservices.types.ArrayOfAttribute initialAttributes)
                        throws com.telelogic.cs.webservices.CreateFault
Submits and creates a new change request. Fires appropriate triggers.

Specified by:
submit in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
toState - The state to submit to, which must be a valid submit state.
initialAttributes - The list of attribute values that should be set on the new CR. All attributes required by the CR process must be submitted or the operation will fail. Attributes not defined in the CR process are discarded.
Returns:
the CR ID of the new change request.
Throws:
com.telelogic.cs.webservices.types.CreateFault - If the change request could not be created. The submit state may not exist, or the user may not have the right privileges.
com.telelogic.cs.webservices.CreateFault

ssoLogin

public java.lang.String ssoLogin(java.lang.String ssoToken,
                                 java.lang.String database,
                                 java.lang.String role)
                          throws com.telelogic.cs.webservices.SsoTokenFault,
                                 com.telelogic.cs.webservices.LoginFault
Logs on a user using a single sign on (SSO) token instead of a name and password. Validates the SSO token against RDS and, if it is valid, returns a database-specific Rational Change token to identify future requests.

Specified by:
ssoLogin in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
ssoToken - A RDS SSO token
database - The database to log into
role - The role of the user.
Returns:
LoginResponse. A Rational Change login token.
Throws:
com.telelogic.cs.webservices.types.LoginFault - If RDS down or invalid database/role.
com.telelogic.cs.webservices.types.SsoTokenFault - If the SSO token is not authenticated.
com.telelogic.cs.webservices.SsoTokenFault
com.telelogic.cs.webservices.LoginFault

setTaskAttributes

public com.telelogic.cs.webservices.types.SetTaskAttributesResponse setTaskAttributes(java.lang.String token,
                                                                                      java.lang.String taskId,
                                                                                      com.telelogic.cs.webservices.types.ArrayOfAttribute attributes)
                                                                               throws com.telelogic.cs.webservices.ModifyFault
Modifies a task by updating its attributes with the given values. If attributes do not already exist, they are first created.

Specified by:
setTaskAttributes in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
taskId - The task ID to modify.
attributes - A list of attributes to set.
Returns:
an empty response.
Throws:
com.telelogic.cs.webservices.types.ModifyFault - if the task could not be modified.
com.telelogic.cs.webservices.ModifyFault
Since:
5.0

getQueryDefs

public com.telelogic.cs.webservices.types.ArrayOfQueryDefinition getQueryDefs(java.lang.String token)
Gets the saved CR queries available to this user. This includes personal, shared, and system queries. Prompting queries and others that special Change templates are not returned.

Specified by:
getQueryDefs in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
Since:
5.2

getReportDefs

public com.telelogic.cs.webservices.types.ArrayOfReportDefinition getReportDefs(java.lang.String token)
Gets the saved CR reports available to this user. This includes personal, shared, and system reports. Reports that require special templates to run, e.g., prompting reports, are not returned.

Specified by:
getReportDefs in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
Since:
5.2

runQuery

public com.telelogic.cs.webservices.types.ArrayOfChangeRequest runQuery(java.lang.String token,
                                                                        com.telelogic.cs.webservices.types.QueryType type,
                                                                        java.lang.String name,
                                                                        com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
                                                                 throws com.telelogic.cs.webservices.SyntaxFault
Runs a saved CR query by name.

Specified by:
runQuery in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
type - The type of query: personal, shared or system. The same query name can be used for different query types.
name - The name of the query to run. The first query found with this name is run, no matter which subfolder it is in.
attributeNames - The attributes that should be returned with each returned change request.
Returns:
A ChangeRequest object for change request that matches the query. An empty list if no change requests were found. Each returned object will contain both the CR ID and a list of attribute values for that CR. The attributes are returned with the same semantics as for the getAttributes function: empty attributes are skipped, attributes are ordered.
Throws:
com.telelogic.cs.webservices.SyntaxFault
Since:
5.2

query

public com.telelogic.cs.webservices.types.ArrayOfChangeRequest query(java.lang.String token,
                                                                     java.lang.String queryString,
                                                                     com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
                                                              throws com.telelogic.cs.webservices.SyntaxFault
Queries for change requests with an ad-hoc query string. The supplied query is unrelated to saved queries; it can be any query string. Since this automatically--and only--queries for change requests you should not query against the "cvtype" attribute.

Specified by:
query in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
queryString - A query string.
attributeNames - The list of attributes to return with each change request. The query string should not include a clause against "cvtype".
Returns:
A ChangeRequest object for change request that matches the query. An empty list if no change requests were found. Each returned object will contain both the CR ID and a list of attribute values for that CR. The attributes are returned with the same semantics as for the getAttributes function: empty attributes are skipped, attributes are ordered.
Throws:
com.telelogic.cs.webservices.types.SyntaxFault - If the query string syntax is incorrect. Queries should be written in the IBM® Rational® Synergy query format.
com.telelogic.cs.webservices.SyntaxFault

downloadAttachment

public javax.activation.DataHandler downloadAttachment(java.lang.String token,
                                                       java.lang.String attachmentId)
Downloads a single attachment from a CR. The CR must exist and be readable by the calling user, other returns an error.

Clients must support MTOM to upload an attachment. Many web service clients support this, but may require it to be explicitly enabled--consult your documentation for details.

Specified by:
downloadAttachment in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token -
attachmentId - The ID of the attachment to get. The ID can be found with listAttachments.
Returns:
The contents of the attachment. Different web service clients may present the data as a byte array, stream, or file. Clients will likely need to move the data to a file of their choosing or rename the file to match the listed display name of the attachment.
Throws:
java.lang.RuntimeException - If the attachment ID doesn't exist or could not be read due to security restrictions.

deleteAttachment

public com.telelogic.cs.webservices.types.DeleteAttachmentResponse deleteAttachment(java.lang.String token,
                                                                                    java.lang.String attachmentId)
                                                                             throws com.telelogic.cs.webservices.ModifyFault
Removes an attachment from its associated change request and deletes it.

Specified by:
deleteAttachment in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
attachmentId - The ID of the attachment to get. The ID can be found with listAttachments.
Returns:
An empty response.
Throws:
com.telelogic.cs.webservices.types.ModifyFault - If the delete was unsuccessful, likely because the user didn't have write privileges for the change request associated to the attachment.
com.telelogic.cs.webservices.ModifyFault

disassociateTask

public com.telelogic.cs.webservices.types.DisassociateTaskResponse disassociateTask(java.lang.String token,
                                                                                    java.lang.String crid,
                                                                                    java.lang.String taskId)
                                                                             throws com.telelogic.cs.webservices.ModifyFault
Disassociates a task from a change request.

Specified by:
disassociateTask in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - The CR ID to remove from.
taskId - The task ID to remove.
Returns:
An empty response.
Throws:
com.telelogic.cs.webservices.types.ModifyFault - If the task could not be disassociated, likely because the change request is not modifiable by the user.
com.telelogic.cs.webservices.ModifyFault

listAttachments

public com.telelogic.cs.webservices.types.ArrayOfAttachmentDetail listAttachments(java.lang.String token,
                                                                                  java.lang.String crid)
Gets information about each of the attachments associated with a CR. This information can be used to list the attachments for a user, or the returned IDs can be used to download the attachments. The CR must exist and be readable by the calling user, otherwise returns an error.

Specified by:
listAttachments in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - A CR to list the attachments for.
Returns:
An array of AttachmentDetails. Each object contains the ID to download the attachment with, a display name, the time the attachment was created and associated with its CR, and the optional description.

getShowUrl

public java.lang.String getShowUrl(java.lang.String crUrn,
                                   java.lang.String token)
                            throws com.telelogic.cs.webservices.UrlFault
Returns the URL for showing the CR.

Specified by:
getShowUrl in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
crUrn - The URN for the CR.
token - The user's token.
Returns:
A URL to show the CR.
Throws:
com.telelogic.cs.webservices.types.UrlFault
com.telelogic.cs.webservices.UrlFault
Since:
5.0

getNextStates

public com.telelogic.cs.webservices.types.ArrayOfString getNextStates(java.lang.String token,
                                                                      java.lang.String crid)
Determines the next possible states that a CR can be transitioned to by the current user. Evaluates all security rules to give the next states for the given user; other users may see different results. Only states with visible transition forms are returned.

Specified by:
getNextStates in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - The ID of the CR to get the next states for.
Returns:
the names of the next states the CR can be transitioned to by the current user.

syncDatabase

public com.telelogic.cs.webservices.types.SyncDatabaseResponse syncDatabase(java.lang.String token,
                                                                            java.lang.String database)
In central server mode, waits for the central server to finish syncing all its CRs into a particular database. This call is never required, since central CRs are automatically synced to all other databases, but this allows you to wait for all pending updates to complete.

For example, if a caller quickly modifies a large number of CRs, it may take a while for these changes to be synced. If subsequent actions of the caller depend on a particular database being in sync with the the central database. The caller can call this function to wait for all those changes to sync. Once up-to-date, this function will return and the caller can proceed. Changes made after this function call--even while this is waiting--are ignored.

Times out if the database is online, but hasn't synced any CRs in a while.

Specified by:
syncDatabase in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - The user's token for any database.
database - The database to sync, unrelated to the token's database.
Returns:
Nothing. Returns silently once the sync has completed. If no updates are pending, returns immediately.
Since:
5.0

getRequiredAttributesForTransition

public com.telelogic.cs.webservices.types.ArrayOfString getRequiredAttributesForTransition(java.lang.String token,
                                                                                           java.lang.String fromState,
                                                                                           java.lang.String toState)
                                                                                    throws com.telelogic.cs.webservices.NoMatchFault
Gets the attributes that are required to transitions a CR from one state to another.

Specified by:
getRequiredAttributesForTransition in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
fromState - The name of the state to transition from
toState - The name of the state to transition to.
Returns:
The names of the attributes that are required to transition between to the two given states.
Throws:
com.telelogic.cs.webservices.types.NoMatchFault - If the transition does not exist.
com.telelogic.cs.webservices.NoMatchFault

logout

public com.telelogic.cs.webservices.types.LogoutResponse logout(java.lang.String token)
Logs out a user by releasing their checked out license immediately (without any license linger time).

Specified by:
logout in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - The user token.
Returns:
An empty response.
Since:
5.0

associateTask

public com.telelogic.cs.webservices.types.AssociateTaskResponse associateTask(java.lang.String token,
                                                                              java.lang.String crid,
                                                                              java.lang.String taskId)
                                                                       throws com.telelogic.cs.webservices.ModifyFault
Associates an existing task to a change request.

Specified by:
associateTask in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - The CR ID to add the task to.
taskId - The task ID to add.
Returns:
An empty response.
Throws:
com.telelogic.cs.webservices.types.ModifyFault - If the task could not be associated, likely because the change request is not modifiable by the user.
com.telelogic.cs.webservices.ModifyFault

getLifecycles

public com.telelogic.cs.webservices.types.ArrayOfString getLifecycles(java.lang.String token)
Gets the names of all lifecycles in the CR process.

Specified by:
getLifecycles in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
Returns:
The names of all lifecycle in the current CR process.

getRelatedTo

public com.telelogic.cs.webservices.types.ArrayOfChangeRequest getRelatedTo(java.lang.String token,
                                                                            java.lang.String crid,
                                                                            java.lang.String relationship,
                                                                            com.telelogic.cs.webservices.types.ArrayOfString attributeNames)
Gets related change requests where the relationship travels to the given change request from zero or more other change requests. In parent-child relationships this function traverses from a child to find its parent. (Note though that there is no restriction on the number of CRs that can relate to this CR, so it is possible to have multiple parents.) For example, duplicate CRs are often handled with the 'duplicate' relationship. Calling this function on a CR that is a duplicate will return the original CR that this one is a duplicate of.

Specified by:
getRelatedTo in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - A CR ID.
relationship - A relationship name to follow.
attributeNames - Attributes to return with the related change requests.
Returns:
The related change requests or an empty array if none were found.

uploadAttachment

public com.telelogic.cs.webservices.types.UploadAttachmentResponse uploadAttachment(java.lang.String token,
                                                                                    java.lang.String toCrid,
                                                                                    javax.activation.DataHandler attachment,
                                                                                    java.lang.String attachmentName,
                                                                                    java.lang.String description)
                                                                             throws com.telelogic.cs.webservices.CreateFault
Uploads a file and attaches it to a change request.

Clients must support MTOM to upload an attachment. Many web service clients support this, but may require it to be explicitly enabled--consult your documentation for details.

Specified by:
uploadAttachment in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
toCrid - The CR ID to attach to.
attachment - The attachment data.
attachmentName - The display name to be used for the attachment.
description - An optional description of the attachment.
Returns:
An empty response.
Throws:
com.telelogic.cs.webservices.types.CreateFault - If the attachment cannot be created or associated with the change request.
com.telelogic.cs.webservices.CreateFault

isDcmEnabled

public boolean isDcmEnabled(java.lang.String token)
Determine if the current database is DCM-enabled.

Specified by:
isDcmEnabled in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - The user's token.
Returns:
Whether or not the current database is DCM-enabled.
Since:
4.7

getSubmitUrl

public java.lang.String getSubmitUrl(java.lang.String submitState,
                                     java.lang.String token)
                              throws com.telelogic.cs.webservices.UrlFault
Returns the URL for submitting a CR.

Specified by:
getSubmitUrl in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
submitState - The submit state.
token - The user's token.
Returns:
A URL to submit a CR.
Throws:
com.telelogic.cs.webservices.types.UrlFault
com.telelogic.cs.webservices.UrlFault
Since:
5.0

getDcmDelimiter

public java.lang.String getDcmDelimiter(java.lang.String token)
                                 throws com.telelogic.cs.webservices.DcmNotEnabledFault
Get the DCM delimiter for the current database.

Specified by:
getDcmDelimiter in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - The user's token.
Returns:
The DCM delimiter for the current database.
Throws:
com.telelogic.cs.webservices.types.DcmNotEnabledFault - If DCM is not enabled.
com.telelogic.cs.webservices.DcmNotEnabledFault
Since:
4.7

getAllStateDefs

public com.telelogic.cs.webservices.types.ArrayOfStateDefinition getAllStateDefs(java.lang.String token)
Gets all state definitions for the current process, that is, the state definitions from each lifecycle.

Specified by:
getAllStateDefs in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
Returns:
All state definitions from all lifecycles.

addAdminNotes

public com.telelogic.cs.webservices.types.AddAdminNotesResponse addAdminNotes(java.lang.String token,
                                                                              java.lang.String crid,
                                                                              com.telelogic.cs.webservices.types.ArrayOfAdminNote adminNotes)
                                                                       throws com.telelogic.cs.webservices.ModifyFault
Allows admins to append notes to the transition log. Notes should almost always be set via the _COMMENTS pseudo-attribute, which handles recording the current time and user. This function lets users with the CR process admin privilege add notes with more control over the summary, effectively allowing notes to be copied to a new change request yet retaining the original author name and timestamp.

Specified by:
addAdminNotes in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - An admin token.
crid - The CRID to append to.
adminNotes - A list of notes to add. Each note takes a user display name and timestamp--to use in the note summary-- as well as the text of the note. The display name is used for display only and does not need to be in any specific format. It does not need to be an actual Change user (though that is normally recommended).
Returns:
An empty response.
Throws:
com.telelogic.cs.webservices.types.ModifyFault - If notes cannot be added to the CR. Most often if you do not have the process admin role.
com.telelogic.cs.webservices.ModifyFault
Since:
4.7

getAllSubmitStates

public com.telelogic.cs.webservices.types.ArrayOfString getAllSubmitStates(java.lang.String token)
Gets all states that CRs can be submitted to. These are all the submit states for all lifecycles in the CR process.

Specified by:
getAllSubmitStates in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
Returns:
The names of all possible states CR can be submitted to.

getTransitionLog

public com.telelogic.cs.webservices.types.ArrayOfTransitionLogEntry getTransitionLog(java.lang.String token,
                                                                                     java.lang.String crid)
Returns a structured version of the transition log. The "transition_log" attribute is a private attribute stored in an opaque format, not necessarily suitable for direct viewing. This method returns a parsed, structured version of the transition log that a client can inspect without know about the underlying format.

Specified by:
getTransitionLog in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - The CRID to get the log from.
Returns:
An ordered array of log entries. Each entry contains the type of the entry (note, transition, or modification), the time the entry was created, a display name for the user that added the entry, a summary line, and the--possibly empty--text of the entry. The summary, display name and text are suitable for displaying to a user as-is; the type and timestamp are for programmatic inspection. The user display name is a formatted name, not necessarily a login username. Both the timestamp and user display name can possibly come back as null. This is not typical, but clients should be prepared to handle this.
Since:
4.7

getDcmId

public java.lang.String getDcmId(java.lang.String token)
                          throws com.telelogic.cs.webservices.DcmNotEnabledFault
Get the DCM identifier for the current database.

Specified by:
getDcmId in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - The user's token.
Returns:
The DCM identifier for the current database.
Throws:
com.telelogic.cs.webservices.types.DcmNotEnabledFault - If DCM is not enabled.
com.telelogic.cs.webservices.DcmNotEnabledFault
Since:
4.7

getListboxDefaultValue

public java.lang.String getListboxDefaultValue(java.lang.String token)
Used to get the default display value for listboxes, which is normally "Any". This value represents the "unset" state of a listbox, but it only used for displaying to the user; it is not ever saved as the value of a listbox attribute. See setAttributes(java.lang.String, java.lang.String, com.telelogic.cs.webservices.types.ArrayOfAttribute) for details on deleting an attribute value.

Specified by:
getListboxDefaultValue in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - The user's token.
Returns:
the default listbox value. Normally 'Any'.
Since:
5.0

getAttributeDefs

public com.telelogic.cs.webservices.types.ArrayOfAttributeDefinition getAttributeDefs(java.lang.String token)
Gets all the attribute definitions for the current process. An attribute definition describes the properties of an attribute that has been defined for use in CR process. Properties include

Specified by:
getAttributeDefs in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
Returns:
The list of all attribute definitions.

getTokenlessShowFormUrl

public java.lang.String getTokenlessShowFormUrl(java.lang.String token,
                                                java.lang.String crid)
Gets a URL to a show for for the given change request. The URL will no have an embedded token in it, and thus can be shared safely among users. When viewed, the system will ensure that the user viewing the CR has logged on--this is tracked with a cookie. If the user has not, he or she will be prompted to do so before viewing the URL.

Fails if the CR does not exist.

Specified by:
getTokenlessShowFormUrl in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crid - The ID of the change request to show.
Returns:
A URL that points to the Rational Change show form for the requested change request.

getRequiredAttributesForSubmit

public com.telelogic.cs.webservices.types.ArrayOfString getRequiredAttributesForSubmit(java.lang.String token,
                                                                                       java.lang.String toState)
                                                                                throws com.telelogic.cs.webservices.NoMatchFault
Gets the attributes that are required to submit a new CR into a given state.

Specified by:
getRequiredAttributesForSubmit in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
toState - The state to submit to.
Returns:
The names of the attributes that are required to submit to the given state.
Throws:
com.telelogic.cs.webservices.types.NoMatchFault - If the submit state is not found.
com.telelogic.cs.webservices.NoMatchFault

getValueListboxEntries

public com.telelogic.cs.webservices.types.ArrayOfListboxEntry getValueListboxEntries(java.lang.String token,
                                                                                     java.lang.String valueListboxName)
                                                                              throws com.telelogic.cs.webservices.NoMatchFault
Gets the possible values for a given value-listbox. Values are returned as entries that pair a label, used for visually displaying a value, with the value, that is actually used for setting and reading attributes.

If the value-listbox is defined in multiple scopes, precedence is given to personal over shared over system.

Specified by:
getValueListboxEntries in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
valueListboxName - The name of the listbox to retrieve.
Returns:
All possible values for the given value-listbox returned as pairs of displayable labels and data values.
Throws:
com.telelogic.cs.webservices.types.NoMatchFault - If no value-listbox has the given name.
com.telelogic.cs.webservices.NoMatchFault

getReportUrl

public java.lang.String getReportUrl(java.lang.String token,
                                     com.telelogic.cs.webservices.types.QueryType type,
                                     java.lang.String name,
                                     java.lang.String optionalTitle)
Gets the URL to run a saved CR report. The report will start to run when the URL is subsequently loaded, not when this function is called.

Specified by:
getReportUrl in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
type - The type of query: personal, shared or system. The same query name can be used for different query types.
name - The name of the report the will be run. The first report with this name will be used, no matter which subfolder it is in.
optionalTitle - The display title for this report. Can be blank for a default title.
Since:
5.2

deleteQuery

public com.telelogic.cs.webservices.types.DeleteQueryResponse deleteQuery(java.lang.String token,
                                                                          com.telelogic.cs.webservices.types.QueryType type,
                                                                          java.lang.String name)
                                                                   throws com.telelogic.cs.webservices.ModifyFault
Deletes a saved CR query by name.

Specified by:
deleteQuery in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
type - The type of query: personal, shared or system. The same query name can be used for different query types.
name - The name of the query to delete. The first query with this name is deleted, no matter what subfolder it is in.
Throws:
com.telelogic.cs.webservices.ModifyFault
Since:
5.2

getQueryBuilderUrl

public java.lang.String getQueryBuilderUrl(java.lang.String token)
Gets a URL to the new query dialog. This can be used to define and save a new personal or shared query.

Specified by:
getQueryBuilderUrl in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
Returns:
A URL, that when loaded, will show the new query dialog
Since:
5.2

getTransitionUrl

public java.lang.String getTransitionUrl(java.lang.String token,
                                         java.lang.String crUrn,
                                         java.lang.String toState,
                                         java.lang.String optionalLabel)
Gets a URL to the transition form to the requested state for a CR.

Specified by:
getTransitionUrl in interface com.telelogic.cs.webservices.ChangeServiceSkeletonInterface
Parameters:
token - A token.
crUrn - URN to the CR to transition.
toState - The state to transition to. This state must represent a legal transition from the current state for the user. Can be null. If not passed, then the admin transition form is loaded, allowing the user to pick any state to transition to, if poasses the CR process admin privilege (normally pt_admin).
optionalLabel - Reserved for future use. Can be null.
Returns:
A URL, that when loaded, will load the transition form for the CR to the given state.
Since:
5.2


© Copyright IBM Corporation 2000, 2009
US Government Users Restricted Rights--Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Notices