vsts-extension-multivalue-control/xmldetails.md

In TFS, the layout for a work item type is defined via XML. Therefore, you will have to add the Multivalue control to your layout. Here's the series of steps that tell you how to do it.

Learn more about WebLayout XML here.

How to get started

1. Open the Developer Command Prompt. Export the XML file to your desktop with the following command.

   witadmin exportwitd /collection:CollectionURL /p:Project /n:TypeName /f:FileName
   

2. This will create a file in the directory that you specified. Open this file and search for "Work Item Extensions".

        <!--**********************Work Item Extensions**********************

Extension:
	Name: vsts-extensions-multivalue-control
	Id: ms-devlabs.vsts-extensions-multivalue-control

	Control contribution:
		Id: ms-devlabs.vsts-extensions-multivalue-control.multivalue-form-control
		Description: A work item form control which allows selection of multiple values.
		Inputs:
			Id: FieldName
			Description: 
			Type: WorkItemField
			Field Type: String; PlainText; HTML
			Data Type: String
			IsRequired: true

			Id: Values
			Description: Values can be user provided or from suggested values of the backing field
			Data Type: String
			IsRequired: false


Note: For more information on work item extensions use the following topic:
http://go.microsoft.com/fwlink/?LinkId=816513
-->

3. Add an Extension tag to make the control available to the work item form.

        <!--**********************************Work Item Extensions***************************
        ...

        Note: For more information on work item extensions use the following topic:
        http://go.microsoft.com/fwlink/?LinkId=816513
        -->

        <Extensions>
            <Extension Id="ms-devlabs.vsts-extensions-multivalue-control" />
        </Extensions>
     ```

    You can find your extension ID within the commented blob for "Work Item Extensions": 

    ```XML
        <!--**********************************Work Item Extensions***************************

    Extension:
        Name: vsts-extensions-multivalue-control
        Id: ms-devlabs.vsts-extensions-multivalue-control
        ...

4. Add the ControlContribution tag for your Multivalue control. This example adds it to the "Planning" group.

    <Page Id="Details">
    ...
        <Section>
        ...
            <Group Id="Planning">
            ...
                <ControlContribution Label="Label" Id="ms-devlabs.vsts-extensions-multivalue-control.multivalue-form-control">
                    <Inputs>
                        <Input Id="FieldName" Value="RefNameOfTheField" />
                    </Inputs>
                </ControlContribution>

                <Control Label="Risk" Type="FieldControl" FieldName="Microsoft.VSTS.Common.Risk" />

You can find the contribution ID and input information within the commented blob for "Work Item Extensions":

        <!--**********************************Work Item Extensions***************************
     ...

	Control contribution:
		Id: ms-devlabs.vsts-extensions-multivalue-control.multivalue-form-control
		Description: A work item form control which allows selection of multiple values.
		Inputs:
			Id: FieldName
			Description: 
			Type: WorkItemField
			Field Type: String; PlainText; HTML
			Data Type: String
			IsRequired: true

			Id: Values
			Description: Values can be user provided or from suggested values of the backing field
			Data Type: String
			IsRequired: false

For the input tag, the content of the Id attribute can be either FieldName or Values.

If the Id is FieldName, the content of the Value attribute should be the name of the field that you want to fill. Suppose you have a field called MyNamespace.MyField, the input tag becomes:

<Input Id="FieldName" Value="MyNamespace.MyField" />

To provide a list of value from a global list, you should add SUGGESTEDVALUES tag in the field definition.

<WORKITEMTYPE name="MyWIT">
    ...
    <FIELDS>
        ...
        <FIELD name="MyField" refname="MyNamespace.MyField" type="String">
            <SUGGESTEDVALUES expanditems="true">
                <GLOBALLIST name="MyGlobalList" />
            </SUGGESTEDVALUES>
        </FIELD>

NOTE: This only works if your field type is String. However, if you want to be able to store more than 255 character you should use the PlainText field type. In this case you have two options. First, is to specify the list items individually:

<WORKITEMTYPE name="MyWIT">
    ...
    <FIELDS>
        ...
        <FIELD name="MyField" refname="MyNamespace.MyField" type="String">
            <SUGGESTEDVALUES expanditems="true">
                <LISTITEM value="ValueOne" />
                <LISTITEM value="ValueTwo" />
            </SUGGESTEDVALUES>
        </FIELD>

Second, is to specify the value inline using the Values input:

<ControlContribution Label="Label" Id="ms-devlabs.vsts-extensions-multivalue-control.multivalue-form-control">
                    <Inputs>
                        <Input Id="FieldName" Value="RefNameOfTheField" />
                        <Input Id="Values" Value="ValueOne;ValueTwo;ValueThree;ValueFour" />
                    </Inputs>
                </ControlContribution>

5. Re-import the .xml file, using witadmin.

    witadmin importwitd /collection:CollectionURL /p:Project /f:FileName