Skip to main content

Creating a job

How to create a job​

Jobs help you to schedule and record work to be performed on assets, e.g. repairs, replacements, removals or cleanings.

Using the Alloy API, you can create a job against any asset that implements designInterfaces_tasksAssignable. Once the job is created, you can create one or more Job Work Units that link to it.

For more information, see:

Special logic​

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

  • A job can only have one parent asset.

  • Typically, attributes_itemsGeometry is optional for a job. If you don't specify a value during creation, it will automatically be copied from the parent asset's attributes_itemsGeometry.

  • However, if attributes_itemsGeometry is required by the job's design, it must be specified during creation. It will not be copied from the parent asset.

  • If you don't specify a value for attributes_tasksRaisedTime during creation, it will automatically be set to the current date and time.

  • If you don't specify a value for attributes_tasksTeam, it will automatically be set to the same value as the parent asset's attributes_tasksTeam.

Example JavaScript​

This example demonstrates how to create a job against an asset.

// 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 asset you wish to create the job against
const parentID = '5dda8584ca315005f4be5061';

// 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 item from
    // the design must implement designInterfaces_jobs
    designCode: 'designs_exampleJobs',
    // the collection that the new job will belong to
    collection: 'Live',
    // specify attributes for the new job item
    attributes: [
      // status is a required attribute
      // IDs for Task Status items can be looked up in designs_taskStatuses
      {
        attributeCode: 'attributes_tasksStatus',
        value: ['5bc5bdd281d088d177342c72'],
      },
      // job geometry is usually an optional attribute
      // if not set then the parent asset's geometry will be used
      // geometry must be provided in GeoJSON format
      {
        attributeCode: 'attributes_itemsGeometry',
        value: {
          type: 'Point',
          coordinates: [-0.450338, 51.391263],
        },
      },
      // related jobs is an optional attribute, so the value can be an empty array
      // if applicable, link to related jobs by providing an array of item ids
      {
        attributeCode: 'attributes_jobsRelatedJobs',
        value: [],
      },
      // attachments is an optional attribute, so the value can be an empty array
      // if applicable, link to any File items by providing an array of item ids
      {
        attributeCode: 'attributes_filesAttachableAttachments',
        value: [],
      },
      // description is an optional string attribute, so the value can be null
      // if applicable, provide a description of the job
      {
        attributeCode: 'attributes_tasksDescription',
        value: null,
      },
      // priority is an optional attribute, so the value can be an empty array
      // IDs for task priority can be looked up in designs_taskPriorities
      {
        attributeCode: 'attributes_tasksPriority',
        value: [],
      },
      // raised time is an optional string attribute, so the value can be null
      // the value must be written in ISO 8601 format
      {
        attributeCode: 'attributes_tasksRaisedTime',
        value: '2020-11-18T00:00:00.000Z',
      },
      // estimated start time is an optional string attribute, so the value can be null
      // the value must be written in ISO 8601 format
      {
        attributeCode: 'attributes_tasksEstimatedStartTime',
        value: null,
      },
      // estimated end time is an optional string attribute, so the value can be null
      // the value must be written in ISO 8601 format
      {
        attributeCode: 'attributes_tasksEstimatedEndTime',
        value: null,
      },
      // start time is an optional string attribute, so the value can be null
      // the value must be written in ISO 8601 format
      {
        attributeCode: 'attributes_tasksStartTime',
        value: null,
      },
      // completion time is an optional string attribute, so the value can be null
      // the value must be written in ISO 8601 format
      {
        attributeCode: 'attributes_tasksCompletionTime',
        value: null,
      },
      // target time is an optional string attribute, so the value can be null
      // the value must be written in ISO 8601 format
      {
        attributeCode: 'attributes_tasksTargetTime',
        value: null,
      },
      // cancelled time is an optional string attribute, so the value can be null
      // the value must be written in ISO 8601 format
      {
        attributeCode: 'attributes_tasksCancelledTime',
        value: null,
      },
      // price multiplier is an optional attribute, so the value can be null
      // 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
      // value must be a number
      {
        attributeCode: 'attributes_upliftPriceAdjustment',
        value: null,
      },
      // reports is an optional attribute, so the value can be an empty array
      // if applicable, link to any Item Level Report items by providing an array of item ids
      {
        attributeCode: 'attributes_itemsWithReportsItemLevelReport',
        value: [],
      },
      // job bill items is an optional attribute and value can be an empty array
      // if applicable, link to any Job Bill items by providing an array of item ids
      {
        attributeCode: 'attributes_jobsWithBillItemsBillItems',
        value: [],
      },
      // job inspections is an optional attribute, so the value can be an empty array
      // if applicable, link to related inspections by providing an array of item ids
      {
        attributeCode: 'attributes_jobsWithInspectionsJobInspections',
        value: [],
      },
      // fixed defects is an optional attribute, so the value can be an empty array
      // if applicable, link to related defects by providing an array of item ids
      {
        attributeCode: 'attributes_jobsRaisingDefectsRaisedDefects',
        value: [],
      },
      // team is an optional attribute, so the value can be an empty array
      // if applicable, provide the ID of a Teams item to assign the job to them.
      // can't have multiple values
      {
        attributeCode: 'attributes_tasksTeam',
        value: ['5df77624ca3150031446ba23'],
      },
      // team member is an optional attribute, so the value can be an empty array
      // if applicable, provide the ID of a Team Members item to assign the job to them.
      // can't have multiple values. can't be set if the team attribute is not set
      {
        attributeCode: 'attributes_tasksTeamMember',
        value: ['5df7763dca3150031446ba29'],
      },
    ],
    parents: {
      // set the parent asset that you're creating the job for
      attributes_tasksAssignableTasks: [parentID],
      // optionally add the job to a project by providing the project ID
      attributes_projectsTasks: ['5fb7cac9253fd00065b3937a'],
    },
    // optional property, so the value can be null
    // set to true to prevent the new job from being editable
    locked: null,
  },
})
  .then((response) => {
    // output the id of the new job item to the console
    console.log(response.data.item.itemId);
  })
  .catch((error) => {
    // output any error data to the console
    console.log(error.response.data);
  });