Creating a defect

How to create a defect

Defects let you record the reported condition of your assets. Condition information may be received from members of the public, sensor data, or arise from other activities (defects/inspections/jobs) involving the same asset.

Using the Alloy API, you can create a defect against any asset that implements designInterfaces_defectsAssignable.

For more information, see:

• Defects in the Alloy Web guide

• the Defects interface blueprint

• the Item endpoints on Swagger and ReDoc

Special logic

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

• A defect can only have one parent asset.

• Typically, attributes_itemsGeometry is optional for a defect. 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 defect'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_defectsReportedDate during creation, it will automatically be set to the current date and time.

Example JavaScript

This example demonstrates how to create a defect 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 defect 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 defect item from
    // the design must implement designInterfaces_defects
    designCode: 'designs_exampleDefects',
    // the collection that the new defect will belong to
    collection: 'Live',
    // specify attributes for the new defect item
    attributes: [
      // dangerous is a required attribute that's only present on
      // the Example Defects design used in this example
      {
        attributeCode: 'attributes_exampleDefectsDangerous',
        value: false,
      },
      // defect 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],
        },
      },
      // reported date is an optional string attribute, so the value can be null
      // the value must be written in ISO 8601 format
      {
        attributeCode: 'attributes_defects_ReportedDate',
        value: '2020-11-18T00:00:00.000Z',
      },
      // remedied date is an optional string attribute, so the value can be null
      // the value must be written in ISO 8601 format
      {
        attributeCode: 'attributes_defects_RemediedDate',
        value: '2020-11-18T00:00:00.000Z',
      },
      // status is a required attribute
      // IDs for Defect Statuses items can be looked up in designs_defectStatuses
      {
        attributeCode: 'attributes_defectStatus',
        value: ['5bc5bdd281d088d177342c72'],
      },
      // description is an optional string attribute, so the value can be null
      // if required, provide a description of the defect
      {
        attributeCode: 'attributes_defectsDescription',
        value: null,
      },
      // related defects is an optional attribute, so the value can be an empty array
      // if required, link to related defects by providing an array of item ids
      {
        attributeCode: 'attributes_defectsRelatedDefects',
        value: [],
      },
      // attachments is an optional attribute, so the value can be an empty array
      // if required, link to any File items by providing an array of item ids
      {
        attributeCode: 'attributes_filesAttachableAttachments',
        value: [],
      },
      // raised jobs is an optional attribute, so the value can be an empty array
      // if required, link to related jobs by providing an array of item ids
      {
        attributeCode: 'attributes_defectsRaisingJobsRaisedJobs',
        value: [],
      },
      // defect inspections is an optional attribute, so the value can be an empty array
      // if required, link to related defects by providing an array of item ids
      {
        attributeCode: 'attributes_defectsWithInspectionsDefectInspection',
        value: [],
      },
      // reporters is an optional attribute, so the value can be an empty array
      // if required, link to people who reported the defect
      // IDs for Contact items can be looked up in designs_contacts
      {
        attributeCode: 'attributes_defectsReporters',
        value: ['5fb7d306253fd00065b399f9'],
      },
    ],
    parents: {
      // set the parent asset that you're creating the defect for
      attributes_defectsAssignableDefects: [parentID],
    },
    // optional property, so the value can be null
    // set to true to prevent the new defect from being editable
    locked: null,
  },
})
  .then((response) => {
    // output the id of the new defect item to the console
    console.log(response.data.item.itemId);
  })
  .catch((error) => {
    // output any error data to the console
    console.log(error.response.data);
  });