{"id":10652,"date":"2015-12-10T10:40:00","date_gmt":"2015-12-10T10:40:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/visualstudioalm\/2015\/12\/10\/adding-a-custom-field-to-a-work-item\/"},"modified":"2022-08-02T06:35:17","modified_gmt":"2022-08-02T14:35:17","slug":"adding-a-custom-field-to-a-work-item","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/devops\/adding-a-custom-field-to-a-work-item\/","title":{"rendered":"Adding a custom field to a work item"},"content":{"rendered":"
\n Thank you everyone for your patience, but the wait is finally over.\u00a0 Today begins our journey delivering process customization to Visual Studio Team Services (VSTS)!\u00a0 We\u2019re releasing the first stage of the rollout plan I described back in July<\/a>, the ability to add custom fields & modify layout for existing work item types.\u00a0 Before jumping into the details I want to talk about the goals we have set for ourselves while delivering customization to VSTS. <\/p>\n
    \n
  1. \n Processes can be shared across multiple projectsWe\u2019ve seen customers with multiple team projects struggle to keep them all aligned when managing process updates.\u00a0 In VSTS, processes are stored at the collection level and when a process changes, all team projects referencing that process see the change.\u00a0 This is a change from our current model in TFS where the process is stored in each team project.\n <\/li>\n
  2. \n Updates to the product will work on any processMost customers want to use our \u201cout of the box\u201d processes (Agile, Scrum, CMMI) but want to make a few tweaks to make the process fit well with their organization.\u00a0 In VSTS, you can use our processes as a base and create an inherited process to store your own customizations.\u00a0 As we move our processes forward with updates and enhancements, you can expect to inherit all new changes while preserving your own customizations.\n <\/li>\n
  3. \n UX built into the productYou shouldn\u2019t need a PHD in TFS to make customizations!\u00a0 We have built experiences into our web portal to allow process administrators to make the changes they want through a simple and approachable UI without having to muck with XML files or additional tools.\n <\/li>\n<\/ol>\n<\/div>\n
    \n With that in mind, let\u2019s see how you can customize your team projects\u2026 <\/p>\n

    \n Shared and inherited process<\/a>\n <\/h2>\n

    As discussed above and in the last <\/p>\n

    2 posts on customization<\/a>, the first change from the existing TFS process customization is moving to a shared process model.\u00a0 Customizations will no longer be scoped to a team project.\u00a0 Rather, process will be its own entity and team projects will reference a process to get the definition of work item types, fields, links, etc.\u00a0 In addition, we will allow a one-level inheritance tree where an inherited process can augment and override the choices made by the process it’s inheriting from. \u00a0\n<\/div>\n\n\n\n\n
    \n \u00a0\"\"<\/a>\n <\/td>\n<\/tr>\n
    \n Figure 1. In TFS today, projects make a copy of process templates to define their initial process.\u00a0 The project is then the target of all customizations.\u00a0 In the new world, projects reference a process and the process is the target of all customizations.\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    On the admin site at the collection level, we have a new Process page (figure 3) that allows you to view and interact with all the processes in the collection.<\/p>\n\n\n\n\n
    \n \u00a0\"\"<\/a>\n <\/td>\n<\/tr>\n
    \n Figure 2. Process overview admin site.\u00a0 Custom Agile is the default process used when creating new projects.\u00a0 Agile and CMMI are disabled so new projects cannot be created using these processes.\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    You can easily create new team projects from the context menu.\u00a0 When creating a project, a user can only use processes which are enabled\u2026 so if you want to enforce that all new projects are \u201cCustom Agile\u201d, just disable the rest!\u00a0 You can also drill into a process to view and modify the types, fields, etc. that are defined inside the process.\u00a0 Over time we\u2019ll be adding more customizations but right now you can modify the fields on work item types.\u00a0 But before you can do that, you need to create an inherited process.<\/p>\n

    Creating an inherited process<\/a><\/h2>\n

    The first step to enable customization is creating an inherited process.\u00a0 Inherited processes can be created from any of the \u201cout of the box\u201d system processes. As shown in Figure 3 above, right clicking on a system process shows a context menu with \u201cCreate inherited process\u201d.\u00a0 This action opens a wizard (figure 3) where you create the inherited process which is the container for all customizations.\u00a0 Once you have created the inherited process, you can create new projects or start customizing it.<\/p>\n

    You may be wondering how you can customize existing projects since they were created using system processes.\u00a0 Project migration is your answer.\u00a0 As part of the create process wizard, you can optionally migrate a project to use the inherited processes (figure 4).\u00a0 Once a project is migrated all customizations in the inherited process will immediately be seen in that project.\u00a0 This process is 100% reversible, simply migrate the project back to the system process.\u00a0 You can migrate projects between system and its inherited processes at any time by right clicking on the current process the projects are using and choosing \u201cMigrate projects\u201d from the context menu.\u00a0 History for existing work item types is preserved so there is no data loss.<\/p>\n

    Currently there is no way to migrate team projects laterally, i.e. you can\u2019t convert an Agile project to Scrum, but that\u2019s on our long term backlog.<\/p>\n\n\n\n\n
    \n \u00a0\"\"<\/a>\n <\/td>\n\n \u00a0\"\"<\/a>\n <\/td>\n<\/tr>\n
    \n Figure 3. Creating an inherited process is as simple as choosing a name and optionally providing a description.\n <\/td>\n\n Figure 4. Once the new inherited process is created, you are offered the chance to migrate existing projects to the new process. In this example, we\u2019re taking an existing project \u201cChatter\u201d and enabling customization by migrating it to the newly created inherited process \u201cMy Scrum\u201d. This action is reversible and the project will lose the customizations.\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    Process security<\/a><\/h2>\n

    We\u2019ve made some improvements to the security model around process as well.\u00a0 Each process is a securable unit and has individual ACLs for creating inherited processes, editing the process and deleting the process.\u00a0 At the collection level, team project collection administrators can choose which processes can be inherited from and by whom.\u00a0 When a new inherited process is created, the creator of the process, as well as team project collection administrators, has full control of the process and can also set individual ACLs for which users and groups can edit and delete the process (figure 5).<\/p>\n\n\n\n\n
    \n \u00a0\"\"<\/a>\n <\/td>\n<\/tr>\n
    \n Figure 5. Justin Marks is the owner of \u201cMy Scrum\u201d process and has full control but he has also granted Derrick Fu the ability to edit the process.\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    Now the moment you\u2019ve all been waiting for, let\u2019s add a field\u2026<\/p>\n

    Add custom fields to existing work item types<\/a><\/h2>\n

    When we talk to customers about process customization, the most common ask we hear is something like, \u201cWhy can\u2019t I add a \u2018Date due\u2019 field to the Scrum bug?\u201d\u00a0 Now you can! Let’s go through that exact scenario and add a date field called “Date due” to the bug work item type (figure 6)…<\/p>\n\n\n\n\n
    \n \u00a0\"\"<\/a>\n <\/td>\n<\/tr>\n
    \n Figure 6. I want to add a \u201cdate due\u201d field to the bug work item type.\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    We have provided the beginnings of a full process editor as part of the admin site (figure 7).\u00a0 You can navigate to the admin site by clicking the customize button on the work item toolbar (figure 6) or by clicking on a process name from the process overview page (figure 2).<\/p>\n\n\n\n\n
    \n \u00a0\"\"<\/a>\n <\/td>\n<\/tr>\n
    \n Figure 7. The process admin site shows all fields included on each work item.\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    The process editor allows you to see all fields on each work item type and access the add a field experience by clicking the “New field” button in the toolbar.\u00a0This opens the \u201cAdd a field\u201d dialog (figure 8) where users can create a brand new field or use an existing field that\u2019s not already associated with the work item type.\u00a0 When you add a new field, you have to provide a name for the field, choose the type (e.g. integer, date\/time, string, etc.) and optionally provide a description for what the field is.\u00a0 Clicking the \u201cadd field\u201d button will add the field to the work item type and display the field on the form (figure 11).\u00a0 It\u2019s that easy!<\/p>\n

    In addition to defining the field itself, you can use the Layout and Options tabs to provide more options:<\/p>\n