Creates an item Object to add a new item to the workspace specified by 'WS_WORKSPACE_ID.' The parameter takes the value for Workspace ID as it appears on the Workspace Settings page. Values for Item Detail fields are passed through properties on the object using Field IDs.
getPrintView('PRINT_VIEW_NAME')
Merges data from the associated item with the advanced print view specified by 'PRINT_VIEW_NAME.' The function returns a text string containing the combined result. The print view must be one set up for the associated item's workspace. See Email() Object.
loadItem(dmsID)
Returns the workspace item specificed by dmsID. Deprecated.
print(), println()
Print information to a debug message when testing.
ImportantTo improve performance, comment out or delete any debugging code when you finish writing a script.
returnValue()
Returns the "return value" required at the end of Precondition and Validation scripts.
Security.inGroup(userID, 'GROUP_NAME')
Checks if the user specified by userID is in the user group specified by 'GROUP_NAME'
Security.inRole(userID, 'ROLE_NAME')
Checks if the user specified by userID is assigned to the user role specified by 'ROLE_NAME'
Security.listGroups(userID)
Returns a list of groups the user belongs to
Security.listRoles(userID)
Returns a list of roles assigned to the user
Security.listUsersInGroup('GROUP_NAME')
Loads an array of user records from the user group specified by 'GROUP_NAME'.
Security.listUsersInRole('ROLE_NAME')
Loads an array of user records from the user role specified by 'ROLE_NAME'.
Security.loadUser(userID)
Returns a user object
Security.loadGroup("GROUP_NAME")
Returns the user group specified by GROUP_NAME.
Preset Parameters
dmsID
ID of the workspace associated with the script
userID
Login ID of the user triggering the script
transID
ID of the workflow transition controlled by the script (see Transition Properties in the Workflow Editor)
newStep
ID of the item workflow state after the transition is performed (see Transition Properties in the Workflow Editor)
item Object
item is a pre-defined, top-level object. The workspace item associated with the script is automatically loaded into the item object. Item Detail fields are implemented as properties on the object through Field IDs. Field IDs are always uppercase.
Performs the workflow transition specified by transID (see Transition Properties in the Workflow Editor). The comments parameter is optional. If comments are specified, they are saved with the workflow step in the Workflow Actions tab.
Is version in the array the latest version? (1 = True; 0 = False)
descriptor.revisionList.working (Boolean)
Is version in the array the Working version? (1 = True; 0 = False)
descriptor.ownerID (string)
User ID of the item Owner
descriptor.createdDate (JavaScript date)
Date and time the item was created (Created on in Owner and Change Summary)
descriptor.createdBy (string)
ID of the user who created the item (Created by in Owner and Change Summary)
item.master Object
The item.master object provides read/write/update access to the associated item's ownership data. The object's arrays are readable and modifiable as any other standard array.
Properties on the item.master Object
master.owner
ID of the user who currently owns the associated item
master.additionalOwners (JavaScript array)
Array of IDs of the users who are currently Additional Owners of the associated item
master.groupAdditionalOwners (JavaScript array)
Array of user groups that are currently Additional Owners of the associated item
item Object Grid Array
The item Grid array (item.grid) is a standard JavaScript array of objects that represent individual rows in the item Grid. Access grid row properties through field IDs the same way you access Item Details fields (for example, item.grid[0].DESCRIPTION).
Adds a row to the item Grid and returns the new row. You can pass row field values as an associative array of name-value pairs or in a row object. If you do not use an argument, the new row is blank. You can assign values using properties on the item object. You can also assign values through variables declared in the script, including ones used to add other new rows. You can use this capability to add multiple rows in a single script through cloning. You do not need to assign values to all fields in a row, only to fields you want to populate.
item.grid[INDEX].remove()
Method to delete the row in the item Grid using the array position specified by INDEX. Use this method with care since you cannot undelete a row.
item Object Attachments Array
The item Attachments array (item.attachments) is a standard JavaScript array of objects that represent files attached to the associated item in the Attachments tab. Access to attachment data is read-only.
Properties on the Attachments Array
attachments.checkoutTimeStamp (JavaScript date)
Date and time of the last or current checkout of the attachment
attachments.checkOutUserID (string)
ID of the user who performed the last or current checkout
attachments.createdUserID (string)
ID of the user who created the attachment
attachments.fileDescription (string)
Description of the attachment
attachments.fileName (string)
Name of the attached file (physical name)
attachments.fileSize (int)
Size of the attached file in bytes
attachments.fileVersion (int)
Current version of the attachment
attachments.folderName
Name of the folder the attachment is "stored" in, if any
attachments.resourceName
Title of the attachment
attachments.timeStamp (JavaScript date)
Date and time on which the attached file was last modified
attachments.versionUserID (string)
ID of the user who checked in the current the version of the attachment
attachments.fileStatus (string)
Status of the attachment (Checked IN, Checked OUT, Locked, Deleted, Archived)
item Object Relationships Array
The item Relationships array (item.relationships) is a standard JavaScript array of objects that represent individual rows in the associated item's Relationships tab. You can access Relationship data through properties on array objects, including target item properties.
Method to add a row to the item's Relationships tab. You can pass row property values as an associative array of name-value pairs (RELATED: target, TYPE: typeStr, DIRECTION: dir, DESCRIPTION: desc) or in a related object. Assign values using properties on the array.
Method to set the type of the relationship at the array position specified by INDEX (Relationship Type) on the tab). The typeStr parameter takes one of these strings as its value: Cross-Reference, Substitution, Application, Manufactured, and Other (See Descriptor). Returns an error if typeStr is invalid.
item.relationships[INDEX].setDescription("desc")
Method to write the description of the relationship at the array position specified by INDEX (Description on the tab). The description is passed as a string assigned to the desc parameter.
item.relationships[INDEX].remove()
Method to delete a relationship row in the item's Relationships tab using the array position specified by INDEX. Use this method with care since you cannot undelete a row.
Properties on the Relationships Array
relationships.id (int)
dmsID of the relationship target item
relationships.descriptor (string)
Descriptor of the relationship target item
relationships.type (string)
Relationship type (typeStr): Cross-Reference, Substitution, Application, Manufactured, and Other (See Descriptor)
relationships.direction (string)
Direction of the relationship (dir): Unidirectional or Bidirectional
relationships.description (string)
Description of the relationship (desc)
relationships.item
Target item of the relationship (target)
relationships.item.FIELD_ID
Property on the relationship target item
item Object Workflow Items Array
The item Workflow Items array (item.workflowItems) is a standard JavaScript array of objects that represent the individual linked items listed on the associated item's Linked/Managed Items tab (target items). Access linked item properties through field IDs the same way you access Item Details fields (for example item.workflowItems[0].COMMENTS). Access target item data through properties on the array object.
NoteIn Revisioning Workspaces, the Linked Items tab becomes the Managed Items tab to enable product lifecycle management (see Linked Items).
Method to add a workflow item to the associated item's Linked/Managed Items tab. You can pass item property values as an associative array of name-value pairs or in a related item.
item.workflowItems[INDEX].item = targetItem2
Method to change the target of an item in the tab using the array position specified by INDEX.
item.workflowItems[INDEX].remove()
Method to delete a workflow item from the tab using the array position specified by INDEX. Use this method with care since you cannot undelete an item.
Properties on the Workflow Items Array
workflowItems.item
Target item. Access target item data through field IDs implemented as properties on workflowItems.item (for example, item.workflowItems[0].item.COMMENTS).
workflowItems.descriptor (string)
Target item Descriptor
workflowItems.id (int)
dmsID of the target item
item Object Workflow Actions Array
The item Workflow Actions array (item.workflowActions) is an array of workflow actions performed on the item. The last action is at the 0 INDEX position in the array.
Properties on the Worfklow Actions Array
workflowActions.step (int)
Step number of the workflow action
workflowActions.userID (string)
ID of the user who performed the workflow action
workflowActions.timeStamp (JavaScript date)
Date and time the workflow action was performed
workflowActions.comments (string)
Comments saved with the workflow action
workflowActions.transition
Transition associated with the workflow action
workflowActions.transition.transitionID (int)
ID of the associated workflow transition (see Transition Properties in the Workflow Editor)
workflowActions.transition.shortName (string)
Name of the associated transition (see Transition Properties in the Workflow Editor)
Description of the workflow state after the transition occurrred (see State Properties in the Workflow Editor)
item.project Object
The item.project object provides access to root project tasks in the associated item's Project Management tab as well as sub-tasks and children. Through properties on the object, you can traverse and read data from items the project tasks are linked to (target items), including workflow- and revision-controlled items, items with milestones, and other project items with their own tasks (children tasks/subtasks). Methods on the item allow scripts to add manual and linked item tasks to the item.
Method to add manual or linked tasks to the item's Project Management tab. You can pass task property values in a task object, as an array of values, or in a related item. Properties passed are TASK_NAME=title, TARGET_ITEM=target, START_DATE=start_date, END_DATE=end_date, PROGRESS_PCT=progress.
Properties on the item.project Object
id (int)
Task number (#on the Project Management tab)
title (string)
Task title or name (Title/Item on the Project Management tab)
type (string)
Task type
start_date (JavaScript date)
Task start date (Start on the Project Management tab)
end_date (JavaScript date)
Task end date (End on the Project Management tab)
duration (string)
Duration of the task in days (Duration on the Project Management tab)
progress (string)
Percentage of the task completed to date (% Complete on the Project Management tab)
owner (string)
Item that owns the task.
owner_id (int)
dmsID of task owner
owner_descriptor (string)
Descriptor of task owner
target
Item the task is linked to
target_id (int)
dmsID of the task's target item
target_descriptor (string)
Descriptor of the task's target item
predecessors (JavaScript array)
Array of task's predecessor tasks (tasks in Pre column on the Project Management tab)
children (JavaScript array)
Array of target item's children tasks (subtasks); only on tasks linked to other project items (project tasks); children tasks can be manual, workflow/revision-controlled, milestone, or project task
subTasks (JavaScript array)
Array of task's sub-tasks that returns values on target_id, title, start_date, end_date, duration, progress, predecessors, subTasks, children, status, owner, and target.
state (string)
Workflow state of the task's target item; only on tasks linked to workflow-controlled items (workflow-controlled tasks)
status (string)
Task status (Status on the Project Management tab)
priority (string)
Priority of the task's status
item Object Milestones Array
The item Milestones array (item.milestones) is a standard JavaScript array of objects that represent individual milestones in the item's Milestones tab.
Methods on the Milestones Array
milestones.setWorkflowState("SHORT_NAME")
Method to set the workflow state associated with the milestone (milestones.workflowState). The "SHORT_NAME" parameter takes the value for the milestones.workflowState.shortName property.
Properties on the Milestones Array
milestones.milestoneType (string)
Identifies whether the milestone represents a transition to or from the associated workflow state: ENTER or EXIT (Milestone Event in the Milestones tab)
milestones.milestoneDate (JavaScript date)
Target date of the milestone (Target Date in the Milestones tab)
milestones.warnThreshold (int)
Milestone warning threshold defined as number of days before milestoneDate (Warning Period in the Milestones tab)
milestones.progress (int)
Percentage of the item's workflow that is complete when the milestone is reached (Workflow Progress (%) in the Milestones tab)
milestones.workflowState
Workflow state associated with the milestone (Workflow State in the Milestones tab)
milestones.workflowState.stateID (int)
ID of the workflow state associated with the milestone (as shown in Workflow Editor State Properties).
milestones.workflowState.shortName (string)
Name of the workflow state associated with the milestone (as entered in Workflow Editor State Properties).
milestones.workflowState.longName (string)
Description of the workflow state associated with the milestone (as entered in Workflow Editor State Properties).
Email() Object
Email() is a pre-defined, top-level object. You create an Email() object to send an email message to one or more email addresses. Message attributes are implemented through properties on the object. For example code, see Action Scripts in Scripting Examples.
Methods on the Email() Object
Email.send()
Sends the email message created with the Email() object .
Properties on the Email() Object
Assign a value to a property as a string or as a property on the item Object. For example, if the item has an email address as one of its fields (EMAIL_ADDRESS) and you want to send a message to that address, assign the value item.EMAIL_ADDRESS to the to property.
to
Single email address or list of email addresses delimited by a semicolon (;)
bc
Same as to but sent in bc header of the message
bcc
Same as to but sent in bcc header of the message
subject
Subject of the email message; string or passed as a property on the item object
body
Body of the email message. HTML or plain text string (see Content-type) OR passed as a property on the item object OR data passed from the associated item via a given Advanced Print View (see getPrintView() under Top-Level Functions).
Content-type
Message header that identifies the format of the message body; supported formats are HTML (text/html( or plain text (text/plain). The default value is text/html.