Reference

Endpoint Create Work Item

Name

add_workitem

Description

Creates a new work item in the default project within the organization. [API reference]

Related Tables

WorkItems

Parameters

Parameter Required Options
Name: Project

Label: Project Name

The Name of the project. 		YES
Name: WorkItemType

Label: WorkItemType

 YES
Name: BypassRules

Label: Bypass Rules (useful to set Readonly - e.g. ResolvedBy)

Allows setting read-only/system fields during creation (like CreatedBy, ResolvedBy).
Option Value
true true
false false
Name: SuppressNotifications

Label: Suppress email notifications

Suppresses email notifications triggered by the new work item creation
Option Value
true true
false false
Name: ValidateOnly

Label: Validate Only (Do not perform actual update/insert)

Validates the JSON patch without actually creating / updating the work item. Useful for testing templates.
Option Value
true true
false false

Output Columns

Label Data Type (SSIS) Data Type (SQL) Length Description
Id DT_I4 int
Title DT_WSTR nvarchar(1000) 1000
Description DT_NTEXT nvarchar(MAX)
WorkItemType DT_WSTR nvarchar(100) 100
State DT_WSTR nvarchar(100) 100
Url DT_WSTR nvarchar(2048) 2048
Tags DT_WSTR nvarchar(4000) 4000
Revision DT_I4 int
AreaPath DT_WSTR nvarchar(500) 500
TeamProject DT_WSTR nvarchar(500) 500
IterationPath DT_WSTR nvarchar(500) 500
Reason DT_WSTR nvarchar(500) 500
CreatedDate DT_DBTIMESTAMP datetime
ChangedDate DT_DBTIMESTAMP datetime
CommentCount DT_I4 int
ParentId DT_I4 int Only returned if Expand Parameter is set to Relations or All
AssignedToDisplayName DT_WSTR nvarchar(500) 500
AssignedToUrl DT_WSTR nvarchar(2048) 2048
AssignedToLinksAvatarHref DT_WSTR nvarchar(4000) 4000
AssignedToId DT_WSTR nvarchar(500) 500
AssignedToUniqueName DT_WSTR nvarchar(500) 500
AssignedToImageUrl DT_WSTR nvarchar(2048) 2048
AssignedToDescriptor DT_WSTR nvarchar(2000) 2000
CreatedByDisplayName DT_WSTR nvarchar(500) 500
CreatedByUrl DT_WSTR nvarchar(2048) 2048
CreatedByLinksAvatarHref DT_WSTR nvarchar(2048) 2048
CreatedById DT_WSTR nvarchar(500) 500
CreatedByUniqueName DT_WSTR nvarchar(500) 500
CreatedByImageUrl DT_WSTR nvarchar(2048) 2048
CreatedByDescriptor DT_WSTR nvarchar(2000) 2000
ChangedByDisplayName DT_WSTR nvarchar(500) 500
ChangedByUrl DT_WSTR nvarchar(2048) 2048
ChangedByLinksAvatarHref DT_WSTR nvarchar(2048) 2048
ChangedById DT_WSTR nvarchar(500) 500
ChangedByUniqueName DT_WSTR nvarchar(500) 500
ChangedByImageUrl DT_WSTR nvarchar(2048) 2048
ChangedByDescriptor DT_WSTR nvarchar(2000) 2000
Watermark DT_WSTR nvarchar(500) 500
StateChangeDate DT_DBTIMESTAMP datetime
Priority DT_I4 int
Triage DT_WSTR nvarchar(1000) 1000
StackRank DT_I4 int
Blocked DT_WSTR nvarchar(500) 500
TaskType DT_WSTR nvarchar(500) 500
RequiresReview DT_WSTR nvarchar(100) 100
RequiresTest DT_WSTR nvarchar(100) 100
ActivatedDate DT_DBTIMESTAMP datetime
ActivatedByDisplayName DT_WSTR nvarchar(500) 500
ActivatedByUrl DT_WSTR nvarchar(2048) 2048
ActivatedByLinksAvatarHref DT_WSTR nvarchar(2048) 2048
ActivatedById DT_WSTR nvarchar(500) 500
ActivatedByUniqueName DT_WSTR nvarchar(500) 500
ActivatedByImageUrl DT_WSTR nvarchar(2048) 2048
ActivatedByDescriptor DT_WSTR nvarchar(2000) 2000
ClosedDate DT_DBTIMESTAMP datetime
ClosedByDisplayName DT_WSTR nvarchar(500) 500
ClosedByUrl DT_WSTR nvarchar(2048) 2048
ClosedByLinksAvatarHref DT_WSTR nvarchar(2048) 2048
ClosedById DT_WSTR nvarchar(500) 500
ClosedByUniqueName DT_WSTR nvarchar(500) 500
ClosedByImageUrl DT_WSTR nvarchar(2048) 2048
ClosedByDescriptor DT_WSTR nvarchar(2000) 2000
ResolvedDate DT_DBTIMESTAMP datetime
ResolvedByDisplayName DT_WSTR nvarchar(500) 500
ResolvedByUrl DT_WSTR nvarchar(2048) 2048
ResolvedByLinksAvatarHref DT_WSTR nvarchar(2048) 2048
ResolvedById DT_WSTR nvarchar(500) 500
ResolvedByUniqueName DT_WSTR nvarchar(500) 500
ResolvedByImageUrl DT_WSTR nvarchar(2048) 2048
ResolvedByDescriptor DT_WSTR nvarchar(2000) 2000
ResolvedReason DT_WSTR nvarchar(4000) 4000
AreaId DT_WSTR nvarchar(500) 500
IterationId DT_WSTR nvarchar(500) 500
RevisedDate DT_DBTIMESTAMP datetime
RemoteLinkCount DT_I4 int
RelatedLinkCount DT_I4 int
HyperLinkCount DT_I4 int
ExternalLinkCount DT_I4 int
History DT_NTEXT nvarchar(MAX)
IntegrationBuild DT_WSTR nvarchar(500) 500
FoundIn DT_WSTR nvarchar(500) 500
OriginalEstimate DT_R4 real
RemainingWork DT_R4 real
CompletedWork DT_R4 real
Size DT_R4 real
Effort DT_R4 real
TargetDate DT_DBTIMESTAMP datetime
StoryPoints DT_R4 real
StartDate DT_DBTIMESTAMP datetime
FinishDate DT_DBTIMESTAMP datetime
DueDate DT_DBTIMESTAMP datetime
Discipline DT_WSTR nvarchar(500) 500
SystemInfo DT_NTEXT nvarchar(MAX)
Steps DT_NTEXT nvarchar(MAX)
ReproSteps DT_NTEXT nvarchar(MAX)
Severity DT_WSTR nvarchar(100) 100
ProposedFix DT_NTEXT nvarchar(MAX)
Symptom DT_NTEXT nvarchar(MAX)
RootCause DT_WSTR nvarchar(100) 100
HowFound DT_WSTR nvarchar(100) 100
FoundInEnvironment DT_WSTR nvarchar(100) 100
BusinessValue DT_I4 int
ValueArea DT_WSTR nvarchar(100) 100
TestedBy DT_WSTR nvarchar(500) 500
TestPriority DT_I4 int
Activity DT_WSTR nvarchar(100) 100
[$parent.referenceName$] DT_WSTR nvarchar(4000) 4000
If the column you are looking for is missing, consider customizing Azure DevOps Connector.

Input Columns

Label Data Type (SSIS) Data Type (SQL) Length Description
WorkItemType DT_WSTR nvarchar(4000) 4000
Title DT_WSTR nvarchar(1000) 1000
Description DT_NTEXT nvarchar(MAX)
State DT_WSTR nvarchar(100) 100
History DT_NTEXT nvarchar(MAX)
Tags DT_WSTR nvarchar(4000) 4000
Revision DT_I4 int
AreaPath DT_WSTR nvarchar(500) 500
TeamProject DT_WSTR nvarchar(500) 500
IterationPath DT_WSTR nvarchar(500) 500
Reason DT_WSTR nvarchar(500) 500
AssignedTo DT_WSTR nvarchar(500) 500
Priority DT_I4 int
Triage DT_WSTR nvarchar(1000) 1000
StackRank DT_I4 int
Blocked DT_WSTR nvarchar(500) 500
TaskType DT_WSTR nvarchar(500) 500
RequiresReview DT_WSTR nvarchar(100) 100
RequiresTest DT_WSTR nvarchar(100) 100
ActivatedDate DT_DBTIMESTAMP datetime
ActivatedBy DT_WSTR nvarchar(500) 500
ClosedDate DT_DBTIMESTAMP datetime
ClosedBy DT_WSTR nvarchar(500) 500
ResolvedDate DT_DBTIMESTAMP datetime
ResolvedReason DT_WSTR nvarchar(4000) 4000
ResolvedBy DT_WSTR nvarchar(500) 500
IntegrationBuild DT_WSTR nvarchar(500) 500
FoundIn DT_WSTR nvarchar(500) 500
OriginalEstimate DT_R4 real
RemainingWork DT_R4 real
CompletedWork DT_R4 real
Size DT_R4 real
Effort DT_R4 real
TargetDate DT_DBTIMESTAMP datetime
StartDate DT_DBTIMESTAMP datetime
FinishDate DT_DBTIMESTAMP datetime
DueDate DT_DBTIMESTAMP datetime
StoryPoints DT_R4 real
Discipline DT_WSTR nvarchar(100) 100
SystemInfo DT_NTEXT nvarchar(MAX)
Steps DT_NTEXT nvarchar(MAX)
ReproSteps DT_NTEXT nvarchar(MAX)
Severity DT_WSTR nvarchar(100) 100
ProposedFix DT_NTEXT nvarchar(MAX)
Symptom DT_NTEXT nvarchar(MAX)
RootCause DT_WSTR nvarchar(100) 100
HowFound DT_WSTR nvarchar(100) 100
FoundInEnvironment DT_WSTR nvarchar(100) 100
BusinessValue DT_I4 int
ValueArea DT_WSTR nvarchar(100) 100
TestedBy DT_WSTR nvarchar(500) 500
TestPriority DT_I4 int
Activity DT_WSTR nvarchar(100) 100
[$parent.referenceName$] DT_WSTR nvarchar(4000) 4000
Required columns that you need to supply are bolded.

Examples

SSIS

Use Azure DevOps Connector in API Source or in API Destination SSIS Data Flow components to read or write data.

API Destination

This Endpoint belongs to the WorkItems table, therefore it is better to use it, instead of accessing the endpoint directly. Use this table and table-operation pair to create work item:

API Destination - Azure DevOps
Read and write Azure DevOps (Cloud or On-Premises) data effortlessly. Integrate, manage, and automate work items, projects, and teams — almost no coding required.
Azure DevOps
WorkItems
Insert
Required Parameters
Project Name Fill-in the parameter...
WorkItemType Fill-in the parameter...
SSIS API Destination - Access table operation

ODBC application

Use these SQL queries in your ODBC application data source:

Create work item (default project)

<p>Creates a new work item in the default project. Specify at least work item type and title; you can add custom or system fields as columns and values. The example shows a task with a few custom fields. Use WITH to set project if the default is not the target project.</p> 

INSERT INTO WorkItems (WorkItemType, Title, [CustomFieldText], [CustomFieldDate], [CustomFieldNumber])
VALUES ('task', 'Fix Issues in System', 'My Custom Text', '2021-01-01T23:59:59.123', 1000)

Create work item in a project

<p>Creates a new work item in a specific project by passing the project name in the WITH clause. Use this when the connection default project is not the one you want. Same columns and values as creating in the default project; only the target project changes.</p> 

INSERT INTO WorkItems (WorkItemType, Title, [CustomFieldText], [CustomFieldDate], [CustomFieldNumber])
VALUES ('task', 'Fix Issues in System', 'My Custom Text', '2021-01-01T23:59:59.123', 1000)
WITH(Project='MyProject')

Create work item with many fields

<p>Creates a work item with a full set of common fields: type, title, description, tags, area and iteration path, assignee, priority, triage, task type, dates, estimates, story points, and more. Use this as a template when you need to set many fields at once. Omit or comment out columns you do not need; add custom fields with the Custom prefix as in the connector docs.</p> 

INSERT INTO WorkItems  (   
      [WorkItemType]   
    , [Title] 
	, [Description] 
	, [Tags]
	, [AreaPath]  
	, [IterationPath] 
	, [AssignedTo] 
	, [Priority]
    , [Triage] 	
  --, [StackRank]  
	, [Blocked]  
	, [TaskType] 
	, [RequiresReview]
	, [RequiresTest] 
	, [IntegrationBuild] 
	, [FoundIn] 
	, [OriginalEstimate] 
	, [RemainingWork] 
	, [CompletedWork] 
	, [Size] 
	, [Effort] 
	, [TargetDate] 
	, [StartDate] 
	, [FinishDate] 
	, [DueDate] 
	, [StoryPoints] 
  --, [Discipline] 
	, [SystemInfo] 
	, [Steps] 
	, [ReproSteps] 
	--, [CustomFieldText]  --custom field prefix with CustomYOUR_FIELD_NAME_WITHOUT_SPACE_OR_DASH_OR_DOT
	--, [CustomFieldDate] 
	--, [CustomFieldNumber] 
	--, [CustomFieldDecimal] 
	--, [CustomFieldPickListString] 
	--, [CustomFieldPickListNum] 
)
VALUES (
      'Bug' -- Task, User Story -- WorkItemType
    , 'My Task Title - Created on <<FUN_NOW>>'  --Title
    , 'Some Description - Created on <<FUN_NOW>>' --Description
    , 'odata; api' --Tags
    , 'ProductTesting\SSISPowerPack' --AreaPath
    , 'ProductTesting\2021.6' --IterationPath
    , 'build@mycompany.com' --AssignedTo
    , 1 --Priority
    , 'Pending' --Triage
  --, ??? --[StackRank]
	, 'No' --Blocked
	, 'Planned' --TaskType
	, 'No' --RequiresReview
	, 'No' --RequiresTest
	, '101.1.2.3' --IntegrationBuild
	, '100.1.2.3' --FoundIn
	, 9999.111 --OriginalEstimate
	, 9999.222 --RemainingWork
	, 9999.333 --CompletedWork
	, 9999.444 --Size
	, 9999.555 --Effort
	, '2021-01-31' --TargetDate
	, '2022-01-31' --StartDate
	, '2023-01-31' --FinishDate
	, '2024-01-31' --DueDate
	, 100.5 --StoryPoints
  --, 'Some Discipline' --Discipline
	, 'Windows 10' --SystemInfo
	, 'Here are steps' --Steps
	, 'Here are steps to reproduce' --ReproSteps
	--, 'abcd'  --CustomFieldText
	--, '2021-01-31' --CustomFieldDate
	--, 9999  --CustomFieldNumber 
	--, 9999.123 --CustomFieldDecimal
	--, 'BBB' --CustomFieldPickListString
	--, '2' --CustomFieldPickListNum
)
WITH(
	Project='ProductTesting'
-- ,BypassRules='true'  --Useful to set ReadOnly Fields like ResolvedBy, ClosedBy
-- ,SuppressNotifications='true'  --Avoids email notifications on change
-- ,ValidateOnly='true'  --Dont perform actual insert - just validate
)

add_workitem endpoint belongs to WorkItems table(s), and can therefore be used via those table(s).

SQL Server

Use these SQL queries in SQL Server after you create a data source in Data Gateway:

Create work item (default project)

<p>Creates a new work item in the default project. Specify at least work item type and title; you can add custom or system fields as columns and values. The example shows a task with a few custom fields. Use WITH to set project if the default is not the target project.</p> 

DECLARE @MyQuery NVARCHAR(MAX) = 'INSERT INTO WorkItems (WorkItemType, Title, [CustomFieldText], [CustomFieldDate], [CustomFieldNumber])
VALUES (''task'', ''Fix Issues in System'', ''My Custom Text'', ''2021-01-01T23:59:59.123'', 1000)';

EXEC (@MyQuery) AT [LS_TO_AZURE_DEVOPS_IN_GATEWAY];

Create work item in a project

<p>Creates a new work item in a specific project by passing the project name in the WITH clause. Use this when the connection default project is not the one you want. Same columns and values as creating in the default project; only the target project changes.</p> 

DECLARE @MyQuery NVARCHAR(MAX) = 'INSERT INTO WorkItems (WorkItemType, Title, [CustomFieldText], [CustomFieldDate], [CustomFieldNumber])
VALUES (''task'', ''Fix Issues in System'', ''My Custom Text'', ''2021-01-01T23:59:59.123'', 1000)
WITH(Project=''MyProject'')';

EXEC (@MyQuery) AT [LS_TO_AZURE_DEVOPS_IN_GATEWAY];

Create work item with many fields

<p>Creates a work item with a full set of common fields: type, title, description, tags, area and iteration path, assignee, priority, triage, task type, dates, estimates, story points, and more. Use this as a template when you need to set many fields at once. Omit or comment out columns you do not need; add custom fields with the Custom prefix as in the connector docs.</p> 

DECLARE @MyQuery NVARCHAR(MAX) = 'INSERT INTO WorkItems  (   
      [WorkItemType]   
    , [Title] 
	, [Description] 
	, [Tags]
	, [AreaPath]  
	, [IterationPath] 
	, [AssignedTo] 
	, [Priority]
    , [Triage] 	
  --, [StackRank]  
	, [Blocked]  
	, [TaskType] 
	, [RequiresReview]
	, [RequiresTest] 
	, [IntegrationBuild] 
	, [FoundIn] 
	, [OriginalEstimate] 
	, [RemainingWork] 
	, [CompletedWork] 
	, [Size] 
	, [Effort] 
	, [TargetDate] 
	, [StartDate] 
	, [FinishDate] 
	, [DueDate] 
	, [StoryPoints] 
  --, [Discipline] 
	, [SystemInfo] 
	, [Steps] 
	, [ReproSteps] 
	--, [CustomFieldText]  --custom field prefix with CustomYOUR_FIELD_NAME_WITHOUT_SPACE_OR_DASH_OR_DOT
	--, [CustomFieldDate] 
	--, [CustomFieldNumber] 
	--, [CustomFieldDecimal] 
	--, [CustomFieldPickListString] 
	--, [CustomFieldPickListNum] 
)
VALUES (
      ''Bug'' -- Task, User Story -- WorkItemType
    , ''My Task Title - Created on <<FUN_NOW>>''  --Title
    , ''Some Description - Created on <<FUN_NOW>>'' --Description
    , ''odata; api'' --Tags
    , ''ProductTesting\SSISPowerPack'' --AreaPath
    , ''ProductTesting\2021.6'' --IterationPath
    , ''build@mycompany.com'' --AssignedTo
    , 1 --Priority
    , ''Pending'' --Triage
  --, ??? --[StackRank]
	, ''No'' --Blocked
	, ''Planned'' --TaskType
	, ''No'' --RequiresReview
	, ''No'' --RequiresTest
	, ''101.1.2.3'' --IntegrationBuild
	, ''100.1.2.3'' --FoundIn
	, 9999.111 --OriginalEstimate
	, 9999.222 --RemainingWork
	, 9999.333 --CompletedWork
	, 9999.444 --Size
	, 9999.555 --Effort
	, ''2021-01-31'' --TargetDate
	, ''2022-01-31'' --StartDate
	, ''2023-01-31'' --FinishDate
	, ''2024-01-31'' --DueDate
	, 100.5 --StoryPoints
  --, ''Some Discipline'' --Discipline
	, ''Windows 10'' --SystemInfo
	, ''Here are steps'' --Steps
	, ''Here are steps to reproduce'' --ReproSteps
	--, ''abcd''  --CustomFieldText
	--, ''2021-01-31'' --CustomFieldDate
	--, 9999  --CustomFieldNumber 
	--, 9999.123 --CustomFieldDecimal
	--, ''BBB'' --CustomFieldPickListString
	--, ''2'' --CustomFieldPickListNum
)
WITH(
	Project=''ProductTesting''
-- ,BypassRules=''true''  --Useful to set ReadOnly Fields like ResolvedBy, ClosedBy
-- ,SuppressNotifications=''true''  --Avoids email notifications on change
-- ,ValidateOnly=''true''  --Dont perform actual insert - just validate
)';

EXEC (@MyQuery) AT [LS_TO_AZURE_DEVOPS_IN_GATEWAY];

add_workitem endpoint belongs to WorkItems table(s), and can therefore be used via those table(s).