The "insert" command. Transacted content import capability from tabular text files


New to the StarTeam Command Line is the "insert" command. 

It's grammar mimics the standard SQL insert, and the full supported syntax is

insert into typeName ( propertyName, propertyName,... )

[ values | revisions ]

[ ( value1, value2,... ) | from "filePath" { separator "fieldSeparator"}  ]

{-pattern = "dateTimePattern"}

{output  into "outputFilePath" }

{ [-epwdfile "pathToEncryptedPasswordFile"]

-p "userName:password@hostName:endpoint/projectName/[viewName/][folderHierarchy/]"] }

The command can be executed directly from the  SDK's CommandProcessor class, using stcmd and the stateful connect/set/disconnect sequence, or through stcmdEx using -p.

As always, note that -p and connect/set/disconnect are mutually exclusive. Additionally, if -p and -epwdfile are both used, then their relative position w.r.t. the rest of the command is critical. -epwdfile must be the second last parameter, and -p must be the last parameter in the command

Note: All elements in the grammar are required as is, including commas and/or double-quotes where specified. The only caveat to this is the | and { } notations, which are used to indicate optional components of the syntax. 

typeName must be one of the supported item types on the server, typically ChangeRequest, Task, or Requirement, or any StarTeam Type (excluding the File type) including Custom Components.

(propertyName, ...) must be valid internal (sql) names of the property types, as reported by the describe type command. The sequence must begin with ( and end with ). The order of the sequence must match the order of the item property values from the input file. Only user modifiable properties may be specified.

values specifies the matching set of property values to be inserted into the type. They can be described inline as a parenthesis enclosed, comma separated list, or as an import feed from a tabular text file. If imported from a text file, the entire import is transacted, i.e. either all the items are successfully inserted, or all are rejected pending an error in the data feed.

revisions is mutually exclusive to values. If specified, then the contents of the file are treated as a set of revisions of the same item. Accordingly, the first (oldest) revision is added to and all subsequent revisions are updated in sequence.
Consequently, the content is expected to be presented such that the oldest revision is the first row of the file and the newest revision is the final row of the file. The revisions syntax provides a mechanism to make one-off copies of items (with history) from non-StarTeam to StarTeam repositories or to make copies of StarTeam assets across projects/repositories. Additionally, if the properties modifiedUserID and/or modifiedTime are part of the data feed, then, for each revision, the command impersonates the user (mapping modifiedUserID) and rolls back to the time (mapping modifiedTime) when saving the revision. As with values, this sequence is transacted as well.

from ‘filePath’ describes the path to the input file whose content needs to be imported.

Each row in the file is separated by a new line. Each column is separated by the default or specified separator.

separator ‘fieldSeparator' defines the column separator. The default is expected to be |, but can be replaced by ,, &, or any consistent pattern of characters e.g. separator *&* implies that every column value is separated by the sequence *&*

pattern = "dateTimePattern" Describes the format of embedded date/time strings in the input feed.

If specified, then date/time values are parsed using java.text.SimpleDateFormat, localized pattern set to "dateTimePattern". refer

If pattern is not specified, the software attempts to match date/time values using java.text.DateFormat
{SHORT, MEDIUM, LONG, FULL} in that order. If none succeed, the algorithm will attempt ISO8601 parsing e.g.: yyyy-mm-ddThh:mm:ssZ (ignoring any fractional content after seconds).

The Property Values supported by the command are

Text A literal string.

Integer A string in the form of an integer such as "1234".

Double A string in the form of a double such as "1234.5678".

Long A string in the form of a long such as "1234567890".

Boolean The case insensitive string "true" or "false".

Date A string formatted as "yyyy-mm-dd", 4 digit year, 1 <= mm <= 12, 1 <= dd <= 31.

DateTime A string supported by a matching formatting pattern. 

TimeSpan A string formatted as [ws][-][d. |d]hh:mm:ss[.ff][ws], items in brackets optional.

See com.starteam.util.TimeSpan. ws whitespace, d days, ff fractional second,  hh hours, mm minutes 0 <= mm <= 59, ss seconds 0 <= ss <= 59

A preferable alternative is to describe a timespan using a double representing its number of hours.

Enumeration. Enumerated values may be specified by internal name, display name, or integer enumeration code. If the Enumerated property is multiselectable, two or more enums may be specified as values. In this case, they must be separated by a period. e.g.: 101.102.103.

A simple example: insert into story (name, tag) values ("This is a story name", 101.103)


User  A StarTeam user may be specified by full name, the integer user id or the user logon name.  If specifying the logon name, the command must be run in administrative context, with the right to access user accounts..

Group A StarTeam group may be specified by group name or  the integer group id.

Label  A label may be specified by label name or integer label id. The "magic" label ID -2 implies a build label.

output Turns on logging of the command to a log file specified by INTO.

Output property values are specified by

            * meaning, all properties of the type, or

            filter = myFilter which specifies a filter by name (whose properties will be used to create the report), or

            propertyName1, propertyName2, ... which identifies the properties to report back.

The following is an example of insert from file:
insert into story (name, tag) values from "c:\temp\story.csv" separator ,
The contents of story.csv would look like this
"This is a story name",101.103
"This is a second story",105


How To-Best Practice
Comment List