Version: 24.3

Advanced Bulk Topics

This endpoint was introduced in 18.0, Winter 2018. Please view the About Digital.aiAgilityinformation from the help icon in the menu bar to see if you are on this release or later.

Filters

Filters are not necessarily advanced but the idea that you can use some of the from the Rest-1 lexicon makes it familiar and powerful. If you have used the rest-1 endpoint, you will recognize the Asset[Filter value].@function form. This filter states to return Epics that have 1 or more of its Subs (Primary Workitems) that have not been deleted (aka AssetState!=255).

from: Epic
select:
- Name
- Subs[AssetState!="255"].@Count
- from: Subs
select:
- AssetType
- Name
- CreatedBy.Name
where:
CreatedBy.Name: ALM Connect
filter:
- Subs[AssetState!="255"].@Count>"0"
sort:
- +Subs[AssetState!="255"].@Count

Deferred Execution

In some cases users may need to get a list of assets that will effected by a bulk operation. The bulk API allows for you to write the query and instead of executing the bulk operation, it creates the a graph of the executions. The bulk engine reduces graph of the execution into single ordered list. This list contains all of the operations and assets that will be affected by bulk operation . Posting to

http://myV1Host/instance/api/Asset?previewOnly=true

will get you a the full execution path. For example, given this payload,

from: Story
filter:
Name='Happy'
execute: QuickClose

here is the output.

[
{
"@62d57651-a1d7-462a-bab4-69f292f5c791": {
"oid": "Story:5715",
"execute": "QuickClose"
}
},
{
"@debd1133-1c9b-4919-a260-a14f71028a66": {
"oid": "Story:5717",
"execute": "QuickClose"
}
},
{
"@088b99ef-ab5f-47a8-9dea-0b27c5c49965": {
"oid": "Story:5718",
"execute": "QuickClose"
}
}
]

This operation QuickCloses every story in the system with the name "Happy". Notice the guid associated with each one of the Stories. The are independent which implies that they can be created in any order since there are no references to other guids thus, out of order execution can be performed. This is similar to the concept of aliasing coming up in the next section. The beauty of this deferred execution is that you can take the output of previewOnly=true then resubmit this to the Bulk engine for continued execution of the original bulk operation.

Aliasing

Aliasing will allow you to assign the output of a bulk operation to a reference. One of the advantages of this feature is that it will allow users to make a reference to previously created assets in a later part of the payload. For example, I want to create a brand new scope and use this scope but reference it later on in the payload.

[
{
"@myNewScope": {
"AssetType": "Scope",
"Parent": "Scope:0",
"Name": "test_org",
"BeginDate": "1/1/2017"
}
},
{
"@DudeStory": {
"AssetType": "Story",
"Name": "test_org",
"Scope" : "@myNewScope"
}
}
]

Here is a more elaborate sample of how to use this aliasing:

[
{
"@scope": {
"AssetType": "Scope",
"Parent": "Scope:0",
"Name": "test_org",
"BeginDate": "1/1/2017"
}
},
{
"@team": {
"AssetType": "Team",
"Name": "test_org",
}
},
{
"@teamRoom": {
"AssetType": "TeamRoom",
"Name": "test_org",
"IsKanban": true,
"Team": "@team",
"Scope": "@scope"
}
},
{
"@owner": {
"AssetType": "Member",
"Name": "John Doe",
"Nickname": "John",
"IsCollaborator": false,
"NotifyViaEmail": false,
"Password": "john",
"Username": "john@example.com",
"Email": "john@example.com",
"DefaultRole": "Role:2",
"Scopes": [
"@scope"
]
}
},
{
"@notstarted": {
"AssetType": "StoryStatus",
"Name": "Not Started",
"RollupState": "0",
"Team": "@team"
}
},
{
"@inprogress": {
"AssetType": "StoryStatus",
"Name": "In Progress",
"RollupState": "64",
"Team": "@team"
}
},
{
"@done": {
"AssetType": "StoryStatus",
"Name": "Done",
"RollupState": "64",
"Team": "@team"
}
},
{
"@readytodeploy": {
"AssetType": "StoryStatus",
"Name": "Read To Deploy",
"RollupState": "128",
"Team": "@team"
}
}
]

Integration with programming environments

Here is a sample in Python that demonstrates some of the simple features in a programmatic format.

import requests

uri = 'https://MyVersionOne/api/asset'
accessToken = '1.jnzIS3VJv80DE/coUak6OdXBvGV='
parentScope = 'System (All Projects)'

session = requests.Session()
session.headers.update({'Authorization': 'Bearer {accessToken}'})

def create_single_Story():
story = {
'Scope': parentScope,
'AssetType': 'Story',
'Name': 'Python Story'
}

result = session.post(uri, json=story)

print(result.json()['assetsCreated'])

def create_multiple_Stories_with_child_Task_and_Tests():
storyCount = 3
taskAndTestCount = 2

stories = []

for storyNum in range(1, storyCount + 1):
story = {
'Scope': parentScope,
'AssetType': 'Story',
'Name': 'Story-{storyNum}',
'Children': []
}

for childNum in range(1, taskAndTestCount + 1):
story['Children'].append({
'AssetType': 'Test',
'Name': 'Test-{childNum}'
})
story['Children'].append({
'AssetType': 'Task',
'Name': 'Task-{childNum}'
})