Skip to main content

Creating a job work item

How to create a job work item​

A Job Work Item defines a unit of work, e.g. a component change, amount of material required, time required.

Using the Alloy API, you can create a Job Work Item against any item that implements designInterfaces_jobs.

For more information, see:

Special logic​

When a Job Work Item is created using the Item endpoint, special logic is applied:

  • A Job Work Item can only have one parent job.

  • If you don't specify a value for attributes_jobWorkItemsBudget during creation, it will automatically be copied from the linked Work Item's attributes_jobWorkItemsBudget if set.

  • If you don't specify a value for attributes_jobWorkItemsEstimatedValue during creation, it will automatically be copied from the linked Work Item's attributes_jobWorkItemsEstimatedValue if set.

Example JavaScript​

This example demonstrates how to create a Job Work Item that is linked to a job.

// load a http request library
const axios = require('axios');

// enter your api key here!
const apiKey = 'e0e3a4ef-5ec8-4e05-ac25-a34adadf4a80';

// the id of the job you wish to create the Job Work Item against
const parentJobID = '5dda8584ca315005f4dd5765';

// request to create an item
axios({
  method: 'POST',
  url: `https://api.uk.alloyapp.io/api/item`,
  headers: { Authorization: `Bearer ${apiKey}` },
  data: {
    // the design that you wish to create a Job Work Item from
    // design must implement designInterfaces_jobWorkItems
    designCode: 'designs_measurementJobWorkItems',
    // the collection that the new Job Work Item will belong to
    collection: 'Live',
    // specify attributes for the new Job Work Item
    attributes: [
      {
        // work item is a required attribute
        // specify the Work Item that the Job Work Item will be created from
        attributeCode: 'attributes_jobWorkItemsWorkItem',
        value: ['5fb3b1bb8cb57700659745dd'],
      },
      // invoicing status is a required attribute
      // supply an ID for a Job Work Unit Invoice status item (e.g. "Ready")
      // IDs can be looked up in designs_jobWorkUnitInvoiceStatuses
      {
        attributeCode: 'attributes_jobWorkUnitInvoicingInvoicing',
        value: ['5f3256d31b5ad5367054c496'],
      },
      // estimated value is an optional attribute, so the value can be null
      // represents estimated quantity of work, e.g. 2.5 hrs, 10 x light bulbs
      // if null, the default value for the selected Work item will be used
      // value should be a number (integer or decimal)
      {
        attributeCode: 'attributes_jobWorkItemsEstimatedValue',
        value: 1,
      },
      // actual value is an optional attribute, so the value can be null
      // represents actual quantity of work, e.g. 2.5 hrs, 10 x light bulbs
      // if null, the default value for the selected Work item will be used
      // value should be a number (integer or decimal)
      {
        attributeCode: 'attributes_jobWorkItemsActualValue',
        value: null,
      },
      // estimated cost is an optional attribute, so the value can be null
      // if null, it will be calculated (estimated value x default rate)
      // value should be a number (integer or decimal)
      {
        attributeCode: 'attributes_jobWorkItemsEstimatedCost',
        value: null,
      },
      // actual cost is an optional attribute, so the value can be null
      // if null, it will be calculated (actual value x default rate)
      // value should be a number (integer or decimal)
      {
        attributeCode: 'attributes_jobWorkItemsActualCost',
        value: null,
      },
      // budget is an optional attribute, so the value can be an empty array
      // if applicable, provide a single item ID from designs_budgets
      // after job is completed, the Job Work Item will be assigned to the Budget item
      {
        attributeCode: 'attributes_jobWorkItemsBudget',
        value: [],
      },
      // price multiplier is an optional attribute, so the value can be null
      // e.g. if actual cost is £100, a multiplier of 15 gives final cost of £115
      // value represents a percentage so must be in range of 0 to 100
      {
        attributeCode: 'attributes_upliftPriceMultiplier',
        value: null,
      },
      // price adjustment is an optional attribute, so the value can be null
      // e.g. to apply a discount to the final cost
      // value should be a number (integer or decimal)
      {
        attributeCode: 'attributes_upliftPriceAdjustment',
        value: null,
      },
      // tax amount is a required attribute
      // value should be a number (integer or decimal)
      {
        attributeCode: 'attributes_jobWorkUnitInvoicingTaxAmount',
        value: 0,
      },
      // total is an optional attribute, so the value can be null
      // value should be a number
      {
        attributeCode: 'attributes_jobWorkUnitInvoicingTotal',
        value: 0,
      },
      // invoice line is an optional attribute, so the value can be an empty array
      // if applicable, provide a single item ID from designs_accountInvoiceLines
      {
        attributeCode: 'attributes_jobWorkUnitInvoicingInvoiceLine',
        value: [],
      },
    ],
    parents: {
      // link the new Job Work Item to the parent job
      attributes_jobsJobWorkItems: [parentJobID],
    },
  },
})
  .then((response) => {
    // output the id of the new Job Work Item to the console
    console.log(response.data.item.itemId);
  })
  .catch((error) => {
    // output any error data to the console
    console.log(error.response.data);
  });