Skip to main content
Skip table of contents

Item Resource

Item resource is used to create new items and update existing items.

Creating a New Item

The following request is used to create a new item (issue, folder or other type) and insert it into a forest.

PERL
POST $baseUrl/rest/structure/2.0/item/create

This request should upload a specification of the creation action and coordinates of where to put the result.

Example

CODE
{
  "item": {
    "type": "com.almworks.jira.structure:type-folder",
    "values": { "summary": "New folder name" }
  },
  "forest": {
    "spec": { "structureId": 128 },
    "version": {
      "signature": 0,
      "version": 0
    }
  },
  "items": {
    "version": {
      "signature": 0,
      "version": 0
    }
  },
  "rowId": -100,
  "under": 0,
  "after": 0,
  "before": 0,
  "parameters": {}
}

Parameters

Parameter (see example above)Meaning
itemDefines the item being created.
item.type

Item type (complete key of the module that provides this item's main functionality.)

Use com.almworks.jira.structure:type-folder for folders and com.almworks.jira.structure:type-issue for issues. See also: CoreItemTypes

item.valuesA set of values for the new item. The specific fields depend on the item. For a folder, it is "summary". For other items, see examples below.
forest.specForest specification of the forest that will receive the new item. See ForestSpec and RestForestSpec.
forest.versionLast known version of the forest. The reply to this call will contain the update to that version. Use zero version (as in example) to receive full forest.
items.versionLast known version of instance items set. The reply to this call will contain an update to the known items. Use zero version (as in example) to receive full update.
rowIdTemporary ID assigned to the created issue. Must be negative. You can use -100 in most cases.
under / after / beforeForest coordinates to insert the new item into. See Forest Resource.

Specific parameters for main item types

Folder

This is the example of item parameter for a new folder:

CODE
"item": {
  "type": "com.almworks.jira.structure:type-folder",
  "values": { "summary": "New folder name" }
}

The only parameter sent is the folder name.

Issue

This is the example of item parameter for a new issue:

CODE
"item": {
  "type": "com.almworks.jira.structure:type-issue",
  "values": {
    "issue": {
      "summary": "issue summary"
    },
    "pid": 10000,
    "issuetype": "3",
    "mode": "new",
  }
}

The above are the minimal fields needed to create a new issue. Note that pid is a number, but issuetype is a string.

Insert Generator

This is the example of item parameter for a new JQL insert generator. The generator adds issues from DEMO project.

CODE
"item": {
  "type": "com.almworks.jira.structure:type-generator",
  "values": {
    "moduleKey": "com.almworks.jira.structure:inserter-jql",
    "params": {
      "jql": "project = DEMO",
      "limit": 1000
    }
  }
}

Note that limit indicates the maximum number of issues added by this generator. Use null value or omit limit parameter to add issues without a limit.

Extend Generator

This is the example of item parameter for a new Sub-tasks extender.

CODE
"item": {
  "type": "com.almworks.jira.structure:type-generator",
  "values": {
    "moduleKey": "com.almworks.jira.structure:extender-subtasks",
    "params": {
      "typeIds": null,
      "from": null,
      "to": 10
    }
  }
}

Note that null value of typeIds parameter stands for "All available sub-task types". null value of from and 10 of to parameter stand for "All levels up to 10". See Sub-tasks Extender for details about parameter values.

Filter Generator

This is the example of item parameter for a new JQL filter generator. The generator keeps only issues in "To Do" status category.

CODE
"item": {
  "type": "com.almworks.jira.structure:type-generator",
  "values": {
    "moduleKey": "com.almworks.jira.structure:filter-jql",
    "params": {
      "showSubItems": false,
      "jql": "statusCategory = \"To Do\"",
      "level": null,
      "keepNonIssues": false
    }
  }
}

Note that null value for "level" stands for "All levels". See Filter Generators for details about parameter values.

Group Generator

This is the example of item parameter for a new field group generator. The generator groups issues by assignee field.

CODE
"item": {
  "type": "com.almworks.jira.structure:type-generator",
  "values": {
    "moduleKey": "com.almworks.jira.structure:grouper-field",
    "params": {
      "fieldId": "assignee"
    }
  }
}

Sort Generator

This is the example of item parameter for a new field sort generator. The generator sorts issues by priority field.

CODE
"item": {
  "type": "com.almworks.jira.structure:type-generator",
  "values": {
    "moduleKey": "com.almworks.jira.structure:sorter-attribute",
    "params": {
      "attribute": {
        "id": "priority",
        "format": "order"
      }
    }
  }
}

Reply Example

The following is an example of a reply.

CODE
{
  "successfulActions": 1,
  "itemId": "com.almworks.jira.structure:type-issue/10100",
  "oldRowIds": [-100],
  "newRowIds": [61],

  "forestUpdates": [...],
  "itemsUpdate": {...}
}

Most important fields are itemId and newRowIds. More on the return fields:

FieldExplanation
successfulActionsA number of actions successfully performed by the server. In this case, it's either 0 or 1.
itemIdThe ID of the newly created item. See ItemIdentity.
oldRowIds / newRowIdsProvides mapping from the temporary row IDs used for uploading the action and the real row IDs obtained after the item was inserted.
forestUpdatesChanges to the forest since the version passed in the request.
itemsUpdateChanges to the items set since the version passed in the request.

Updating an Existing Item

The following request is used to update an existing item (issue, folder or other type). 

PERL
POST $baseUrl/rest/structure/2.0/item/update

Example of the request:

CODE
{
  "item": {
    "itemId": "10000", 
    "values": {
      "summary": "New Summary"
    }
  },
  "items": {
    "version": { "signature": 0, "version": 0 }
  },
  "forest": {
    "spec": {
      "type": "clipboard"
    },
    "version": { "signature": 0, "version": 0 }
  }
}

Note that although the update does not depend on the forest, the low-level API in the current version requires the request to specify a forest spec and known version of items stream. If you don't need to maintain up-to-date items cache and not interested in updates to a forest where the item is located, just use empty version in items field and "clipboard" forest spec – like in this example.

Parameters

Parameter (see example above)Meaning
item.itemId

The ID of the item.

If it is just a number, like in the example, it is an issue ID. Note that it is still a String value that contains issue ID.

Instead of a number, it can be a canonical notation of an ItemIdentity. For example, to update a folder, use "com.almworks.jira.structure:type-folder/123" where 123 is the folder ID.

item.values

A map of values to be updated. The keys are the same as when the item is created.

For updating a folder, use "summary".

items.versionKnown version of the items stream. The response will contain an update based on that number. Use zeroes, as in example, when updated is not needed.
forest.spec and forest.versionMonitored forest spec and known version of that forest. The response will contain a forest update based on those values. When not needed, use a simple forest (like clipboard in this example) and zeroed version.

Reply

The reply is similar to the reply from calling /create method, defined above. A positive HTTP status tells that the item has been updated. There is no "itemId" in the response.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.