|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.telelogic.cs.api.ChangeTriggerApi
public class ChangeTriggerApi
The API for BSF triggers to programmatically interact with the IBM Rational Change.
Constructor Summary | |
---|---|
ChangeTriggerApi(com.telelogic.cs.internal.api.CommonApi commonApi,
com.telelogic.cs.lifecycle.ProcessService processService,
com.telelogic.cs.TransitionService transitionService)
Warning, this constructor is used by internally IBM Rational Change; do not call from trigger scripts. |
Method Summary | |
---|---|
void |
adminDelete(java.lang.String token,
java.lang.String crid)
Permanently deletes a CR from the database. |
java.lang.String |
buildCrQuery(java.lang.String token,
java.lang.String crid)
Constructs a query string for a specific CR. |
java.lang.String |
buildTaskQuery(java.lang.String token,
java.lang.String taskId)
Constructs a query string for a specific task. |
java.util.Map<java.lang.String,Attribute> |
collectAttributes(java.lang.String token,
CollectibleEvent event,
java.lang.String[] additionalAttributes)
Collects and unifies attributes from certain event objects and the live attributes of the CR for that event. |
java.lang.String |
createAssociatedTask(java.lang.String token,
java.lang.String onCrid,
Attribute[] taskAttributes)
Creates a new task and associates it to a change request. |
void |
deleteAttributes(java.lang.String token,
java.lang.String crid,
java.lang.String[] attributeNames)
Deletes attributes from a change request. |
TaskDetails |
getAssociatedTaskDetails(java.lang.String token,
java.lang.String fromCrid,
java.lang.String[] attributeNames)
Gets the tasks associated with a change request and, in central server mode, details about offline databases and tasks. |
Task[] |
getAssociatedTasks(java.lang.String token,
java.lang.String fromCrid,
java.lang.String[] attributeNames)
Gets the tasks associated with a change request, if any. |
AttributeDefinition[] |
getAttributeDefs(java.lang.String token)
Gets all the attributes defined for the current CR process, including details like the label and type of each attribute. |
java.util.Map<java.lang.String,Attribute> |
getAttributes(java.lang.String token,
java.lang.String crid,
java.lang.String[] attributeNames)
Gets attribute values for a change request. |
java.lang.String |
getDbid(java.lang.String token)
Gets the database ID (DBID) for the database indicated by the token. |
java.lang.String |
getDcmDelimiter(java.lang.String token)
Gets the DCM delimiter for the database indicated by the token. |
java.lang.String |
getMessage(java.lang.String key,
java.lang.String... substitutions)
Gets a localized message from the default resource bundle. |
java.lang.String |
getMessageFrom(java.lang.String bundleName,
java.lang.String key,
java.lang.String... substitutions)
Gets a localized message from a custom resource bundle. |
ChangeRequest[] |
getRelatedFrom(java.lang.String token,
java.lang.String crid,
java.lang.String relationship,
java.lang.String[] attributeNames)
Gets related change requests where the relationship travels from the given change request to zero or more other change requests. |
ChangeRequest[] |
getRelatedTo(java.lang.String token,
java.lang.String crid,
java.lang.String relationship,
java.lang.String[] attributeNames)
Gets related change requests where the relationship travels to the given change request from zero or more other change requests. |
java.lang.String[] |
getRequiredAttributesForSubmit(java.lang.String token,
java.lang.String toState)
Gets the attributes that are required to submit a new CR into a given state. |
java.lang.String[] |
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 |
getServerCharset(java.lang.String token)
Gets the name of the character set the server will send textual information in, e.g., "UTF-8". |
java.lang.String |
getServerHostName(java.lang.String token)
Gets the host name of the server. |
int |
getServerPort(java.lang.String token)
Gets the port the web server is running on. |
java.lang.String |
getServerProtocol(java.lang.String token)
Gets the protocol the web server is using. |
java.lang.String |
getSystemValue(java.lang.String token,
java.lang.String name,
java.lang.String defaultValue)
Gets a system value as defined in pt.cfg. |
java.util.Map<java.lang.String,Attribute> |
getTaskAttributes(java.lang.String token,
java.lang.String taskId,
java.lang.String[] attributeNames)
Gets attribute values for a task. |
java.lang.String |
getUserPreference(java.lang.String token,
java.lang.String forUser,
java.lang.String preferenceName,
java.lang.String defaultValue)
Gets a user preference, i.e., a user setable profile value. |
boolean |
isCentralServer(java.lang.String token)
Checks if Change is in central server mode. |
boolean |
isDcmEnabled(java.lang.String token)
Checks if DCM is enabled for the database indicated by the token. |
ChangeRequest[] |
query(java.lang.String token,
java.lang.String queryString,
java.lang.String[] attributeNames)
Queries for change requests with an ad-hoc query string. |
void |
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. |
void |
relateNoSecurity(java.lang.String token,
java.lang.String fromCrid,
java.lang.String toCrid,
java.lang.String relationship)
Like relate but disables
both ACL and lifecycle security during the transition. |
void |
setAttributes(java.lang.String token,
java.lang.String crid,
Attribute[] newAttributes)
Modifies a change request by updating its attributes with the given values. |
void |
setTaskAttributes(java.lang.String token,
java.lang.String taskId,
Attribute[] newAttributes)
Modifies a task by updating its attributes with the given values. |
java.lang.String |
submit(java.lang.String token,
java.lang.String toState,
Attribute[] initialAttributes)
Submits and creates a new change request. |
void |
transition(java.lang.String token,
java.lang.String crid,
java.lang.String toState,
Attribute[] modifiedAttributes)
Transitions a change request to one of its next states. |
void |
transitionTask(java.lang.String token,
java.lang.String taskId,
java.lang.String toState,
Attribute[] attributes)
Transitions a task to a new state. |
void |
unrelate(java.lang.String token,
java.lang.String fromCrid,
java.lang.String toCrid,
java.lang.String relationship)
Breaks a relationship between two change requests. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public ChangeTriggerApi(com.telelogic.cs.internal.api.CommonApi commonApi, com.telelogic.cs.lifecycle.ProcessService processService, com.telelogic.cs.TransitionService transitionService)
bsf.lookupBean('api')
.
Constructs a high-level API which is
designed to be called from in-process (BSF) trigger scripts.
Scripts should never create this
object directly; BSF scripts can look up a pre-instantiated
bean for this object with bsf.lookupBean('changeTriggerApi')
.
commonApi
- injected, lower-level API.processService
- injected, process service.transitionService
- injected, transition service.Method Detail |
---|
public AttributeDefinition[] getAttributeDefs(java.lang.String token)
token
- a token.
public java.lang.String[] getRequiredAttributesForSubmit(java.lang.String token, java.lang.String toState)
token
- a token.toState
- the state to submit to.
public java.lang.String[] getRequiredAttributesForTransition(java.lang.String token, java.lang.String fromState, java.lang.String toState)
token
- a token.fromState
- the state to transition from.toState
- the sate to transition to.
public boolean isDcmEnabled(java.lang.String token)
token
- a token which determines the database to check.
true
if DCM is enabled in the database
for token
.public boolean isCentralServer(java.lang.String token)
token
- a token.
true
if this is a central server,
false
if it is a stand-alone server.public java.lang.String getDbid(java.lang.String token)
token
- a token which determines the database to check.
token
.
com.telelogic.cs.ChangeRuntimeException
- if DCM is not enabled for the database.public java.lang.String getDcmDelimiter(java.lang.String token)
This is sometimes used to "split" IDs and reassemble them into
query strings. In those cases, it may be better to use the
buildCrQuery
or buildTaskQuery
methods which work reliably whether or not DCM is enabled.
token
- a token which determines the database to check.
token
.
com.telelogic.cs.ChangeRuntimeException
- if DCM is not enabled for the database.public java.lang.String buildCrQuery(java.lang.String token, java.lang.String crid)
token
- a token.crid
- the CR to construct the query string for. Note that
the the CR need not actually exist.
and
or or
statement.public java.lang.String buildTaskQuery(java.lang.String token, java.lang.String taskId)
token
- a token.taskId
- the task to construct the query string for. Note that
the the task need not actually exist.
and
or or
statement.public void adminDelete(java.lang.String token, java.lang.String crid) throws ModifyException
token
- a token of a user that has the process admin role.
Non-admin users cannot delete CRs.crid
- the CR to delete.
ModifyException
- if the CR could not be deleted.public java.lang.String submit(java.lang.String token, java.lang.String toState, Attribute[] initialAttributes) throws CreateException
token
- a token.toState
- the state to submit to. A submit transition must exist from
START_HERE
to toState
.initialAttributes
- the attributes to set on the new change request.
Required attributes are particular to the transition.
CreateException
public java.lang.String createAssociatedTask(java.lang.String token, java.lang.String onCrid, Attribute[] taskAttributes) throws CreateException
token
- a token.onCrid
- the change request to associate the new task to.taskAttributes
- the initial attribute for the new task. At least one attribute
must be provided; a task_syopsis may be required.
CreateException
- if the task cannot be created.public void setTaskAttributes(java.lang.String token, java.lang.String taskId, Attribute[] newAttributes) throws ModifyException
In central server mode, the task is modified in the user's context database (identified by the token). This can be overridden by passing in the 'from_db_path' attribute with the path to the database to modify the task in.
token
- a token.taskId
- the task to modify.newAttributes
- the new or modified attributes to set on taskId
.
ModifyException
- if the task could not be modified.public ChangeRequest[] getRelatedFrom(java.lang.String token, java.lang.String crid, java.lang.String relationship, java.lang.String[] attributeNames)
token
- login token.crid
- get related change requests from this CR.relationship
- name of relationship between the CRs.attributeNames
- the attributes to return with each CR.
public ChangeRequest[] getRelatedTo(java.lang.String token, java.lang.String crid, java.lang.String relationship, java.lang.String[] attributeNames)
token
- login token.crid
- get change requests related to this CR.relationship
- name of relationship between the CRs.attributeNames
- the attributes to return with each CR.
public Task[] getAssociatedTasks(java.lang.String token, java.lang.String fromCrid, java.lang.String[] attributeNames)
In central server mode, tasks are returned from all the user's online task databases. The 'from_db_path' pseudo-attribute can be used to find which database a task is from.
token
- login token.fromCrid
- the CR to get tasks from.attributeNames
- the attributes to return with each task.
public TaskDetails getAssociatedTaskDetails(java.lang.String token, java.lang.String fromCrid, java.lang.String[] attributeNames)
In central server mode, tasks are returned from all the user's online task databases. The 'from_db_path' pseudo-attribute can be used to find which database a task is from.
token
- login token.fromCrid
- the CR to get tasks from.attributeNames
- the attributes to return with each task.
public void transitionTask(java.lang.String token, java.lang.String taskId, java.lang.String toState, Attribute[] attributes) throws ModifyException
In central server mode, the task is modified in the user's context database (identified by the token). This can be overridden by passing in the 'from_db_path' attribute with the path to the database to modify the task in.
token
- the user to modify the task as.taskId
- the task to transition.toState
- the state to transition to. A transition must exist from the current state to the new state.attributes
- new attributes to set on the task as part of the transition.
ModifyException
- if the task cannot be transitioned.public java.lang.String getServerCharset(java.lang.String token)
token
- a token.
public int getServerPort(java.lang.String token)
token
- a token.
public java.lang.String getServerProtocol(java.lang.String token)
token
- a token.
public java.lang.String getServerHostName(java.lang.String token)
token
- a token.
public java.lang.String getUserPreference(java.lang.String token, java.lang.String forUser, java.lang.String preferenceName, java.lang.String defaultValue)
token
- a token.forUser
- the user name to get the preference for. Can be the same as the user identified
by the token or another user, but you must specify the user.preferenceName
- the name of the preference to look up.defaultValue
- the default value to return to return if the preference cannot be found.
defaultValue
.
The default is used when the preference is not yet set, the preference name is wrong,
or the user is not found--essentially whenever the requested value is not found.
TokenException
- if token
is invalid or has timed out.public java.lang.String getSystemValue(java.lang.String token, java.lang.String name, java.lang.String defaultValue)
token
- a token.name
- the name of the system value to get.defaultValue
- the default value to return to return if the value cannot be found.
defaultValue
.
The default is used when system value is not set.
TokenException
- if token
is invalid or has timed out.public void transition(java.lang.String token, java.lang.String crid, java.lang.String toState, Attribute[] modifiedAttributes) throws ModifyException
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 role can transition between any two existing states. The transition doesn't need to exist in the CR process. This is called an admin transition.
Fires triggers if appropriate. Updates the transition log to note the change if successful.
token
- a token.crid
- the CR to transition.toState
- the state to transition crid
to.modifiedAttributes
- the attribute values to update or set on the change request
during the transition.
ModifyException
- 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.public java.util.Map<java.lang.String,Attribute> getAttributes(java.lang.String token, java.lang.String crid, java.lang.String[] attributeNames)
token
- a token.crid
- the CR to inspect.attributeNames
- the names of the attributes to get values for.
Attribute
.
There will be one attribute returned for each attribute that had a value
on the change request. 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.public java.util.Map<java.lang.String,Attribute> getTaskAttributes(java.lang.String token, java.lang.String taskId, java.lang.String[] attributeNames)
token
- a token.taskId
- the task to inspect.attributeNames
- the names of the attributes to get values for.
Attribute
.
There will be one attribute returned for each attribute that had a value
on the task. Attributes that had no value on the given task will not
be returned, thus the number of returned attributes may be less
than the requested number.public java.util.Map<java.lang.String,Attribute> collectAttributes(java.lang.String token, CollectibleEvent event, java.lang.String[] additionalAttributes)
Unlike getAttributes
, the return value will
contain an attribute object for every requested (additional) attribute--even those with no value on
the target CR. Attributes that have no value come back as empty attributes
.
Empty attributes like this can be passed to setAttributes
to delete them on other CRs. This
makes it easy to collect attributes (including those without a value) from a CR, then set those
attributes verbatim on another CR.
This method provides a fast yet robust way to look up attributes. Those sent with the event can be looked up without going to the database, but the database attributes are still used as a fall back for non-event attributes.
Works with all events that implement the CollectibleEvent
interface,
including transition and attribute events.
token
- a token.event
- the event to collect attributes from. Must implement the CollectibleEvent
interface.additionalAttributes
- the additional attributes to get beyond those on the event.
public void relate(java.lang.String token, java.lang.String fromCrid, java.lang.String toCrid, java.lang.String relationship) throws ModifyException
token
- a token.fromCrid
- the CR to create the relationship from.toCrid
- the CR to create the relationship to.relationship
- the name of the relationship to create.
ModifyException
- if the relationship could not be created, likely because the user
does not have write privileges to one or more of the change requests.
IdException
- if either change request is not found.
TokenException
- if token
is invalid or has timed out.public void relateNoSecurity(java.lang.String token, java.lang.String fromCrid, java.lang.String toCrid, java.lang.String relationship) throws ModifyException
relate
but disables
both ACL and lifecycle security during the transition. This mirrors
the behavior of TRELATIONs in older releases, which also disabled security.
This may be useful in triggers that should never fail once they
are called, but should be used with caution.
token
- a token.fromCrid
- the CR to create the relationship from.toCrid
- the CR to create the relationship to.relationship
- the name of the relationship to create.
ModifyException
- if the relationship could not be created, likely because the user
does not have write privileges to one or more of the change requests.
IdException
- if either change request is not found.
TokenException
- if token
is invalid or has timed out.public void unrelate(java.lang.String token, java.lang.String fromCrid, java.lang.String toCrid, java.lang.String relationship) throws ModifyException
token
- a token.fromCrid
- CR the relationships originates from.toCrid
- CR the relationship goes to.relationship
- name of the relationship to break.
ModifyException
- if the relationship cannot be broken, likely because the user
does not have write privileges to one or more of the change requests.
IdException
- if either change request is not found.public void setAttributes(java.lang.String token, java.lang.String crid, Attribute[] newAttributes) throws ModifyException
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.
token
- a token.crid
- the CR to modify.newAttributes
- the new or modified attributes to set on crid
.
ModifyException
- if the CR could not be modified.
PartialModifyException
- if some, but not all, of the attributes could be updated.
The detail section
will contain a list of all the attributes that could
not be updated.
IdException
- if the change request does not exist.
TokenException
- if token
is invalid or has timed out.public void deleteAttributes(java.lang.String token, java.lang.String crid, java.lang.String[] attributeNames) throws ModifyException
token
- a token.crid
- the CR to modify.attributeNames
- the names of the attributes to delete.
ModifyException
- if the attributes cannot be deleted.
PartialModifyException
- if some, but not all, of the attributes could be deleted.
The detail section
will contain a list of all the attributes that could
not be updated.
IdException
- if the change request does not exist.
TokenException
- if token
is invalid or has timed out.public ChangeRequest[] query(java.lang.String token, java.lang.String queryString, java.lang.String[] attributeNames) throws SyntaxException
token
- a token.queryString
- a query string. Do not include 'cvtype'.attributeNames
- the attributes to return with each found CR.
ChangeRequest
object for each 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 map of attributes for that CR.
The attributes are returned with the same semantics as
for the getAttributes
function: empty attributes are skipped.
SyntaxException
- If the query string syntax is incorrect. Queries should be
written in the IBM Rational Synergy query format.
TokenException
- if token
is invalid or has timed out.public java.lang.String getMessage(java.lang.String key, java.lang.String... substitutions)
key
- the key of the resource string to return.substitutions
- values to substitute into the message if needed.
See MessageFormat
for details.
public java.lang.String getMessageFrom(java.lang.String bundleName, java.lang.String key, java.lang.String... substitutions)
bundleName
- name of the custom message bundle to search for the key in.
Custom message bundles should be put in wsconfig/messages.key
- the key of the resource string to return.substitutions
- values to substitute into the message if needed.
See MessageFormat
for details.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |