NameValue

Description

The NameValue type holds a field name with either a single value or a list of values and determines how the field value is set. The NameValue parameters are listed below.

Parameters

Name	Type	Description
id	FieldIdentifier	The field identifier.
setValueBy	Set-Value-By	Determines how to set the value (which value takes precedence).
setValueMethod	Set-Value-Method	Use setValueMethod to append, remove, or replace a value.
value	FieldValue	Holds information about a field value.

Usage

When specifying a value or values, you can use the display, internal, or UUID value. In addition, you can use the setValueBy element to specify which type of value it is, though it is not required. The setValueBy element is mainly used if you are passing in an empty value. Otherwise, SBM will determine which type of value is set by checking for a non-empty value.

To set an empty value, you must use the SET-VALUE-BY parameter that corresponds to the empty <value> parameter. For example, to set an empty value for a field using the internalValue parameter, you could specify:

<urn:setValueBy>INTERNAL-VALUE</urn:setValueBy>
<urn:setValueMethod>REPLACE-VALUES</urn:setValueMethod>
<urn:value>
    <urn:internalValue></urn:internalValue>

Alternatively, to set an empty value for a field using the displayValue parameter, you could specify:

<urn:setValueBy>DISPLAY-VALUE</urn:setValueBy>
<urn:setValueMethod>REPLACE-VALUES</urn:setValueMethod>
<urn:value>
    <urn:displayValue></urn:displayValue>

To set an empty value for a single or Multi-Relational field, you must use INTERNAL-VALUE in SetValueBy and empty tags in the internalValue parameter.
To set an empty value for a Text field, use INTERNAL-VALUE in SetValueBy and REMOVE-VALUES in the SetValueMethod parameter.

XML

The following XML shows the NameValue type as seen in a typical call.

<urn:extendedField>
    <urn:id>
        <urn:displayName>Severity</urn:displayName>
        <urn:id></urn:id>
        <urn:uuid></urn:uuid>
        <urn:dbName>SEVERITY</urn:dbName>
    </urn:id>
    <urn:setValueBy>DISPLAY-VALUE</urn:setValueBy>
    <urn:setValueMethod>REPLACE-VALUES</urn:setValueMethod>
    <urn:value>
        <urn:displayValue>Critical</urn:displayValue>
        <urn:internalValue></urn:internalValue>
        <urn:uuid></urn:uuid>
    </urn:value>
</urn:extendedField>

The following XML shows the NameValue type with multiple values as seen in a typical call.

<urn:extendedField>
    <urn:id>
        <urn:displayName>MULTI USER</urn:displayName>
        <urn:id>178</urn:id>
        <urn:uuid>f62c6b63-2531-441a-9fff-9cd471bc61ca</urn:uuid>
        <urn:dbName>MULT_USER</urn:dbName>
    </urn:id>
    <urn:setValueBy>PRECEDENCE-VALUE</urn:setValueBy>
    <urn:setValueMethod>APPEND-VALUES</urn:setValueMethod>
        <urn:value>
            <urn:displayValue>admin</urn:displayValue>
            <urn:internalValue>1</urn:internalValue>
            <urn:uuid>d2d60592-656e-4103-a20d-f12da9305fe4</urn:uuid>
        </urn:value>
        <urn:value>
            <urn:displayValue>bill</urn:displayValue>
            <urn:internalValue>10</urn:internalValue>
            <urn:uuid>7130c9c3-abb6-41f5-bd7a-30c40f47b824</urn:uuid>
        </urn:value>
        <urn:value>
            <urn:displayValue>carmen</urn:displayValue>
            <urn:internalValue>11</urn:internalValue>
            <urn:uuid>9d71b19e-9b72-4731-bec3-3eba938da0de</urn:uuid>
        </urn:value>
</urn:extendedField>

Using the example above, if this payload was sent with TransitionItems, the call would append admin, bill, and carmen to the current selections that exist in the "MULTI USER" field.

The following XML shows how to clear a Text field value.

<urn:extendedField>
    <urn:id>
        <urn:displayName>text</urn:displayName>
        <urn:id></urn:id>
        <urn:uuid></urn:uuid>
        <urn:dbName></urn:dbName>
    </urn:id>
    <urn:setValueBy>INTERNAL-VALUE</urn:setValueBy>
    <urn:setValueMethod>REMOVE-VALUES</urn:setValueMethod>
    <urn:value>
        <urn:displayValue></urn:displayValue>
        <urn:internalName></urn:internalName>
        <urn:internalValue></urn:internalValue>
        <urn:uuid></urn:uuid>
    </urn:value>
</urn:extendedField>