Allow to Update-VSTeamWorkItem to add relations with other work items

[mnieto]

Proposal

Add a similar parameter as existing AdditionalFields, for example -Relations. This parameter can be a hashtable like this:

$rel = @(
 [pscustomobject]@{
   Relation = "Parent"
   Id = 193812
   Operation = "Add"
 },
 [pscustomobject]@{
   Relation = "Related"
   Id = 123
   Operation = "Add"
 }
)
Update-VSTeamWorkItem -id 555 -Relations $rel

Solved Problem

This will allow to simplify the process to udpate work items with related ones

Additional info / code snippets?

There is a basic example of this in the Add-VSTeamWorkItem cmdlet using the -ParentId parameter. But this feature will allow to define additional relationships for a work item

[mnieto]

dup of (or related to) #228

[SebastianSchuetze]

@mnieto what do you think is
Making it better I'm regards to complexity, maintainibility and usability you solution to include it in an existing cmdlet or new ones?

[mnieto]

@SebastianSchuetze
On the one hand, implementing all together in the same cmdlet allows to do not perform additional calls to the REST API, for example when we want to update a field and also a relation for the same workitem. Also the command Get-VSTeamWorkItem -Id number -Expand All is returning the relations. For consistency, Update-VSTeamWorkItem should update both fields and relations.

On the other hand, implementing in separated cmdlets simplify the logic. In fact the az devops CLI implement the relations management in a separated command set.

In both cases, my idea is to implement an internal function to retrieve the different relationship types and then use it to both create a dynamic parameter (RelationType) and to expose a new cmdlet Get-VSTeamWorkItemRelationTypes

Then, I can implement a New-VSTeamWorkItemRelation cmdlet to generate a in-memory definition of the relation. In this way it's easier to validate the parameters and build the corresponding JsonPatchDocument. Also, with this only one cmdlet I expect to cover the use cases to add, remove or replace relations in the WorkItem. For eample:

$relations = @()
$relations += New-VSTeamWorkItemRelation -RelationType Parent -Id 1502 -RelatedWorkItemId 903 -Operation Add
Update-VSTeamWorkItem -Id 1502 -Relations $relations

But if you prefer implement the relationship management in a separate set of cmdlets (like in #228 proposal) it is fine also for me.

Please send me your advice on this

[SebastianSchuetze]

@mnieto Internal function is a clever idea, and I would go with the consistent approach done in Get-VSTeamWorkItem. Meaning We can update relations with Update-VSTeamWorkItem.

But still, I would say that we expose cmdlets for doing relations stuff also with the same internal function.

Would you give it a try? Did I express myself clear enough?

[mnieto]

It's clear.
This is my proposal of cmdlets to be added/updated
I have some doubts about replace operations. i.e. change a parent workitem. So expect minor changes during the implementation, but in general should be something like this:

• Update-VSTeamWorkItem: add a -Relations parameter
• Get-VSTeamWorkItemRelationTypes: list Relations types. Paramerters:
  • Usage: All|resourceLink|workItemLink. Default workItemLink
• New-VSTeamWorkItemRelation: Helper cmdlet that creates an in-memory object to facilitate building the -Relations parameter in Update-VSTeamWorkIte. Parameters:
  • Id Work item to be modified
  • RelationType: Values got from dynamic parameter
  • RelatedWorkItemId Related work item id
  • Operation Add|Remove|Replace
• Add-VSTeamWorkItemLink Parameters:
  • Id workitem to be modified
  • RelationType: Values get from dynamic parameter
  • RelatedWorkItemId Related work item id
• Get-VSTeamWorkItemLink Parameters
  • Id workitem to be modified
  • RelationType Optional. If not specified, return all relations in -Id
• Remove-VSTeamWorkItemLink Parameters
  • Id workitem to be modified
  • RelatedWorkItemId Related work item id

All the above cmdlets will work internally with a JsonPatchDocument or compatible object. Also, below cmdlets will return this object/collection of objects respectively. Using this aproach, the -Relations paramter in the Update-VSTeamWorkItem can be built with the help of New-VSTeamWorkItemRelation or directly as the example at the very beginning of this thread.

• New-VSTeamWorkItemRelation
• Get-VSTeamWorkItemLink

[SebastianSchuetze]

Yes start. Just not sure if I understood. The minor changes would they mean that older scripts would break?

[mnieto]

No, what I mean is that during implementation perhaps I need to change some parameter or function behaviour, but only for the planned cmdlets described above El mié, 24 may 2023, 21:10, Sebastian Schütze ***@***.***> escribió:

…

Yes start. Just not sure if I understood. The minor changes would they mean that older scripts would break? — Reply to this email directly, view it on GitHub <#518 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB4X4XR3DTVVFKPEHVOCBI3XHZML3ANCNFSM6AAAAAAXMSBSPI> . You are receiving this because you were mentioned.Message ID: ***@***.***>