createWorkItem

This mutation creates a new work item.

Query

createWorkItem (WorkItem!)
Creates a single work item.

Argument Type Description
app String! The api name of the app to create the work item instance in.
type String! The api name of the template to instantiate.
parent WorkItemReference The optional parent to create the instance under. If this isn’t specified, the template must support being instantiated at the top level.
attributes [AttributeValueUpdate!] Attribute values to set when the work item is created.
metrics [MetricValueUpdate!] Metric values to set when the work item is created.
participants [ParticipantUpdate!] Participants to assign when the work item is created.

Examples

Creating work item instances

The following is an example that creates a new Initiative based on the template Initiative__t setting the name to “Automate Data Entry” and the custom attribute Anticipated_Value__c to “2000”. The new Initiative will be added under an existing Program work item with the Shibumi ID of “123”.

mutation {
  createWorkItem(
    app: "App_1__app"
    type: "Initiative__t"
    parent: {type: "Workstream__t", id: "123"}
    attributes: [
      {attribute: "name" value: "Automate Data Entry"}
      {attribute: "Anticipated_Value__c" value: "2000"}
    ]) {
    url
    id
  }
}
{
  "data": {
    "createWorkItem": {
      "url": "https://app.shibumi.com/shibumi/12345678-1234-1234-1234-123456789012/workItem-summary?id=12345678-1234-1234-1234-123456789012",
      "id": "678"
    }
  }
}

Creating top-level work items

Top-level work items in Shibumi do not have a parent work item. There are some considerations when creating a top-level work item.

  • The underlying template in Shibumi must be configured to allow top-level work item instances
  • The parent argument should not be supplied as part of the mutation call

The following is an example that creates a new Program top-level object based on the template Program__t setting the name to “RPA Program” and the custom attribute Team__c to “Program Management Office”.

mutation {
  createWorkItem(
    app: "App_1__app"
    type: "Program__t"
    attributes: [
      {attribute: "name" value: "RPA Program"}
      {attribute: "Team__c" value: "Program Management Office"}
    ]) {
    url
    id
  }
}
{
  "data": {
    "createWorkItem": {
      "url": "https://app.shibumi.com/shibumi/12345678-1234-1234-1234-123456789012/workItem-summary?id=12345678-1234-1234-1234-123456789012",
      "id": "678"
    }
  }
}

Creating work items with metric, association, and participant values

Beyond attributes, many other aspects of a new work item can be set at creation time. In this example, both a metric and an association are updated, and a user is assigned to a role.

mutation {
  createWorkItem(
    app: "App_1__app"
    type: "Program__t"
    attributes: [
      {attribute: "name" value: "RPA Program"}
      {attribute: "associated_item__q" value: "321"}
    ]
    metrics: [
      {metric: "Savings__m" dataset: "target__d" value: "1000000"}
    ]
    participants: [
      {username: "[email protected]" role: "Budget_Administrator__r"}
    ]) {
    url
    id
  }
}
{
  "data": {
    "createWorkItem": {
      "url": "https://app.shibumi.com/shibumi/12345678-1234-1234-1234-123456789012/workItem-summary?id=12345678-1234-1234-1234-123456789012",
      "id": "678"
    }
  }
}

Populating attachment attributes

Uploading an attachment when creating or updating a work item is a 3-step process. First, you need to make a document upload request to Shibumi. To do this, issue a post request to the following endpoint:

/api/1.0/enterprise/{tenant-id}/documents?name={name}&mimeType={type}

The documents request will return a json object with the following structure:

{
  "documentId": "uuid",
  "uploadUrl": "url"
}

The second step is to upload the document to the uploadUrl returned by the document endpoint using a PUT request. Do not set the authorization header when making this request. You must set the content-type header, and it must match the mimeType from the first request.

Finally, when you create or update the work item, use the documentId from step 1 as the value of the attachment attribute you wish to update.

Updated on September 9, 2025

Related Articles