Skip to main content

Invoking Operations

An execute command is a command object with a from clause and an execute clause. Assets it acts on are reported in assetsOperatedOn.

The Bare Form​

When an operation takes no parameters, execute is just the operation name.

Single asset
{ "from": "Task:1592", "execute": "Delete" }

filter (the full expression language) and with variables are accepted on an execute command exactly as on an update — where below is just the shortest form.

Every asset matching a query
{
  "from": "Workitem",
  "where": { "Parent": "Story:1591" },
  "execute": "Delete"
}
Response
{
  "assetsOperatedOn": { "oidTokens": ["Task:1592", "Test:1593"], "count": 2 }
}

Regardless of which form you use, the projection phase normalises execute into an operation name plus an argument bag:

{ "oid": "Scope:0", "execute": { "op": "NonexistentOperation", "args": {} } }

The args Form — One Invocation with Parameters​

Use an object with op and args when the operation takes parameters.

from: Member:1040
execute:
 op: AssignToScopeWithRole
 args:
  Scope: Scope:1503
  Role: Role:3
  IsOwner: true
{
  "from": "Member:1040",
  "execute": {
    "op": "AssignToScopeWithRole",
    "args": { "Scope": "Scope:1503", "Role": "Role:3", "IsOwner": true }
  }
}

The response reports one entry in assetsOperatedOn.

The list Form — Repeated Invocation​

list replaces args with an array of argument bags. The operation is invoked once per entry, against the same from target.

from: Member:1040
execute:
 op: AssignToScopeWithRole
 list:
 - Scope: Scope:1503
   Role: Role:3
   IsOwner: true
 - Scope: Scope:1504
   Role: Role:7
   IsOwner: false
{
  "from": "Scope:1503",
  "execute": {
    "op": "AssignMemberWithRole",
    "list": [
      { "Member": "Member:1040", "Role": "Role:3", "IsOwner": true },
      { "Member": "Member:1041", "Role": "Role:7", "IsOwner": false }
    ]
  }
}

The same OID token appears once per invocation in assetsOperatedOn.oidTokens — a two-entry list against one asset yields count: 2 with the token repeated.

Subquery Arguments​

Any value inside args may itself be a query. This lets a script address assets by a stable business value instead of an instance-specific OID token.

from: Member:1040
execute:
 op: AssignToScopeWithRole
 args:
  Scope:
    from: Scope
    where:
     Name: Subquery project for Member.AssignToScopeWithRole
  Role:
    from: Role
    where:
     Name: Role.Name'Project Lead
  IsOwner: true
{
  "from": "Scope:1503",
  "execute": {
    "op": "AssignMemberWithRole",
    "args": {
      "Member": { "from": "Member", "where": { "Username": "scopeMember2" } },
      "Role": { "from": "Role", "where": { "Name": "Role.Name'Project Lead" } },
      "IsOwner": true
    }
  }
}
Only the first match is used

When a subquery supplies an operation argument, only the very first result becomes the value. If the subquery could match more than one asset, add a sort clause to make the choice deterministic.

This differs from a subquery used in a relation update, where every match is used.

Undelete​

Deleted assets are excluded from queries by default, so Undelete must explicitly opt in with IsDeleted: true.

from: Story:1591
where:
 IsDeleted: true
execute: Undelete

Deferring an Operation Until Processing​

An execute command that targets an asset created earlier in the same request must be wrapped in a user alias, so its projection is deferred until the processing phase — by which point the alias resolves to a real OID token.

[
  {
    "@story": {
      "AssetType": "Story", "Scope": "Scope:0", "Name": "Story Test",
      "Children": [
        { "@test1": { "AssetType": "Test", "Name": "My Test 1" } },
        { "AssetType": "Test", "Name": "My Test 2" }
      ]
    }
  },
  { "@inactivate": { "from": "@test1", "execute": "Inactivate" } },
  {
    "from": "Test",
    "where": { "Parent": "@story" },
    "select": ["Name", "AssetState"]
  }
]

See Deferring commands for the full explanation.

Unknown Operations​

Naming an operation the asset type does not support produces a command failure with HTTP 200:

{
  "commands": [
    {
      "@op": { "oid": "Scope:0", "execute": { "op": "NonexistentOperation", "args": {} } },
      "error": {
        "message": "Unknown Operation 'Scope.NonexistentOperation'",
        "sourceCommandIndex": 0
      }
    }
  ],
  "count": 1
}