setproperty

set property on stream or principal

Usage

accurev setproperty [ -s <stream> | -u <principal> ] [ -r ]
[ <property-name> <value> | -l <file-name> <property-name> ]

accurev setproperty -s <stream> -r [ streamStyle | streamCustomIcon |
stagingStreamResult ] "<xml>"

accurev setproperty -c -r userSchema -l customUserProps.xml

Description

The setproperty command assigns a property name/value pair to either a stream or a principal (user or group). If the property does not exist, AccuRev creates it; that is, a new property does not require a separate create command. Properties are not TimeSafe; if you respecify or remove a property, you cannot roll back to the prior property name/value pair.

Use setproperty command to create custom user properties using the customUserProps.xml file. The custom properties display in the user dialogs. Note that the customUserProps.xml file can have any name or path you give it.

If you want to restrict the ability to set properties on a stream or principal, you need to modify the server_admin_trig server-side trigger. See Format of the “server_admin_trig” Trigger Parameters File in the AccuRev Admin Guide.

Options

-s <stream>

Specifies the name of the stream on which to set the property.

-u <principal>

Specifies the name of the user or group on which to set the property.

<property-name>

Specifies the name of the property. Maximum of 255 characters. Property names are case-insensitive regardless of depot settings or platform. The names title and Title are equivalent, for example.

Tip: You can set the background color of streams and workspaces using the streamStyle reserved property. See Setting Stream Color for more information.

<value>

Specifies the property value. AccuRev places no limit on value length, but length limits may be established by the operating system shell for values input on the command line.

-l <file-name>

To specify a file as a value (an image, for example), use -l with the <file-name> option. You can use either a relative or absolute path to specify the file location. If you do not specify a path, AccuRev assumes the file is in the current directory. Note that when you use -l, you must reverse the order of the name/value pair to value/name.

The -l option transfers the file content to the AccuRev Server. Similarly, if a file name is specified when reading a stream or principal property (using getproperty, for example), AccuRev places the content in that file; otherwise, AccuRev returns the file name for that property. See getproperty for more information.

"<xml>"

XML input, enclosed with quotation marks, used to specify the value for the streamStyle (for color) and streamCustomIcon (for displaying icons and tooltips) reserved properties. See Setting Stream Color and Setting Stream Icons for more information. You can use both reserved properties for a stream, but each must be specified separately.

-r

Option required to designate a property as reserved. Required for streamStyle, streamCustomIcon, stagingStreamResult, and custom user properties. Reserved properties are not displayed in the StreamBrowser’s Property dialog box.

-c

Designates configuration.

Setting Stream Color

You can use the reserved property streamStyle to set the background color of a stream or workspace. The streamStyle property takes XML in the following format as its argument:

"<style>
   <color>
      <background-color>hex_value</background-color>
   </color>
</style>"

The preceding example is formatted to make it easy to read, but you should enter it as a single string when you specify the value for the streamStyle property. For example:

"<style><color><background-color>#00CC33</background-color></color></style>"

Note that the XML must be enclosed in quotes, and that the color (the <background-color> tag) is expressed as a hex value (#FF0000, for example). AccuRev supports web-safe colors.

Setting Stream Icons

You can use the reserved property streamCustomIcon to display an icon on a stream. AccuRev allows you to set:

Icons that indicate running, success, warning, and failed statuses

Tooltips that appear when the pointer is placed over the icon

A URL that opens the default browser at the specified address when clicked

The streamCustomIcon property takes XML in the following format as its argument:

"<streamicon>
   <image>running | success | warning | failed</image>
   <clickurl>desired URL, http://example.com/build, for example</clickurl>
   <tooltip>desired tooltip, Build 1245 passed, for example</tooltip>
</streamicon>"

The preceding example is formatted to make it easy to read, but you should enter it as a single string when you specify the value for the streamCustomIcon property. For example:

"<streamicon><image>success</image><clickurl>http://example.com/build</clickurl><tooltip>Build 1245 passed</tooltip></streamicon>"

If you refer to an image that is unknown to AccuRev, AccuRev displays the "warning" icon and a tooltip like the following: Unknown icon name "sucess" in reserved stream property streamCustomIcon.

Considerations for Using XML

Note that the XML used to specify the <streamicon> argument must be enclosed in quotes, and it must be well-formed. Reserved characters like the ampersand (&) must be properly escaped (as &amp; or &#38;, for example). If there are errors in the XML, AccuRev displays an error like the following when you click the status icon to open the URL:

Invalid XML in reserved stream property streamCustomIcon.
You might see this error if you do not properly escape an ampersand (&) in a URL parameter. In this case, AccuRev displays the warning icon and the error message shown here instead of those specified in the <image> and <tooltip> tags, respectively.

Illegal character in query at index 29:http://example.com/build?foo= bar
You might see this error if you do not properly escape a space in the URL specified in the <clickurl> tag. Note that in this case, AccuRev displays the icon and tooltip you defined (assuming they have been correctly specified).

Setting Custom User Properties

AccuRev supports the use of an XML file to define custom user properties that display in the user dialogs. The file name for custom properties is customUserProps.xml or any name that you give it. Format the file as demonstrated in the following example in order to define custom fields.

<fields>
<field name="Display Name"/>
<field name="Phone Number"/>
<field name="Email"/>
</fields>

Formatting the Tooltip

AccuRev supports the use of HTML tags to format tooltips displayed using the <tooltip> tag. For example, you can:

  • Format tooltip text as bold or italic (using <strong> or <i> tags)
  • Create new lines (using <br> or <p> tags)
  • Create lists (using <ul> and <li> tags)

If you want to use HTML to format streamCustomIcon tooltips, you need to:

  • Specify all formatting between <html> and </html> tags
  • Specify less-than and greater-than brackets using &lt; and &gt;, respectively, for both the <html> tags and any formatting tags they contain

For example, if you wanted to display this tooltip:

Build 1798 complete
12 warnings
3 errors

you would specify the <tooltip> content as follows:

"<streamicon>
...
<tooltip>&lt;html&gt;Build 1798 complete&lt;br&gt;12 warnings&lt;br&gt;3 errors
&lt;/html&gt;</tooltip>
</streamicon>"

Setting Staging Stream Status

If you are using gated streams in your stream hierarchy, there might be occasions when you want to manually override the Running status on a staging stream. For example, if your software development process requires a code review before changes can be promoted, your reviewer needs a way to set the staging stream status when the review is complete.

You can manually set the staging stream status using the stagingStreamResult reserved stream property:

accurev setproperty -s <stream name> -r stagingStreamResult "status"

If the stream name contains spaces, you must enclose it in quotation marks. Valid values for status are "running", "success", "failed", and "warning".

Examples

On stream "prod_2010", set a property named "model" with a value of "obsolete":

> accurev setproperty -s prod_2010 model obsolete

On stream "nightly", set the "streamStyle" property to red:

> accurev setproperty -s nightly -r streamStyle "<style><color><background-color>#FF0000</background-color></color></style>"

On user "jsmith", set a property named "contractor" with a value of "AcmeTemps":

> accurev setproperty -u jsmith contractor AcmeTemps

The order of the name/value pair changes to value/name when using the -l option to specify a file as a property value, as shown in the following two examples:

On user "jsmith", set a property named "profile" with a value of "jsmith.png":

> accurev setproperty -u jsmith -l jsmith.jpg profile

On user "jsmith", change the "profile" property to "jsmith_smiling.png":

> accurev setproperty -u jsmith -l jsmith_smiling.jpg profile

Set the status of staging stream acme dev to success:

> accurev setproperty -r -s "acme dev" stagingStreamResult "success"

See Also

getproperty, rmproperty, show