Skip to main content

Works Orders

This document provides an overview of the operations available for the Works Orders business entity. Please note that the queries shown below only present a subset of the fields.

For a full list of fields, please refer to our schema documentation provided within our API. See Explore the API.

Mutations​

Create Works Orders​

To create new Works Orders within an Orchestrate database, the Works Order create endpoint can be used.

Request​

Here's an example of how you can use the create mutation:

mutation (
$worksOrder: WorksOrderInput!
) {
 worksOrder {
   worksordersRecords {
     create (worksOrder: $worksOrder)
     {
       ...Success
       ...Validation
       ...Errors
     }
   }
 }
}

fragment Success on IntEntityIdResultGraphType {
 ... on IntEntityId {
   id
 }
}

fragment Validation on IntEntityIdsResultGraphType {
 ... on FailedValidation {
   errors {
     message
     details {
       primaryKey
       field
       value
     }
   }
 }
}

fragment Errors on IntEntityIdsResultGraphType {
 ... on UnexpectedError {
   errorMessage
 }
}

When you execute the create mutation, it performs several steps to create a new works order:

  1. Calculating missing information: If any required information is missing from the input object, the mutation will calculate the missing values based on default settings or any other logic defined in the system. This ensures that the works order has all the necessary data before it is created.

  2. Running business validations: The API performs a number of business validations on the input data to ensure that it meets the required criteria. These validations can include checks for things like valid Item information, correct quantity, and any other business rules specific to your application. If any validation errors occur, the mutation will return a response with the details of the errors.

  3. Saving the works order: If all the necessary information is present and the business validations pass successfully, the mutation will save the works order in the system and make it available for further processing or retrieval.

Parameters​

WorksOrder [Required]​

This mutation requires an input object of type WorksOrderInput, which should contain all the necessary information to create the works order.

Response​

After executing the create mutation, you will receive a response containing the Id of the updated works order if the creation was successful. If any validation errors or unexpected errors occur during the operation, the response will include the details of those errors.

An example of the three response types provided by this request can be found below:

{
  "data": {
    "worksOrder": {
      "worksordersRecords": {
        "create": {
          "id": 123
        }
      }
    }
  }
}

Update Works Orders​

To update a works order, you can use the update mutation. Like the works order creation request, this mutation requires an input object of type WorksOrderInput, which should contain the information you wish to update on the existing works order.

Request​

Here's an example of how you can use the update mutation to update a works order:

  mutation (
    $worksOrder: WorksOrderInput!
  ) {
    worksOrder {
      worksordersRecords {
        update (worksOrder: $worksOrder)
        {
          ...Success
          ...Validation
          ...Errors
        }
      }
    }
  }

  fragment Success on IntEntityIdResultGraphType {
    ... on IntEntityId {
      id
    }
  }

  fragment Validation on IntEntityIdsResultGraphType {
    ... on FailedValidation {
      errors {
        message
        details {
          primaryKey
          field
          value
        }
      }
    }
  }

  fragment Errors on IntEntityIdsResultGraphType {
    ... on UnexpectedError {
      errorMessage
    }
  }

When you execute the update mutation, it performs the following steps to update the works order:

  1. Finding the works order: The mutation first finds the works order in the system.
  2. Updating the information: The mutation then updates the works order with the new information provided in the WorksOrderInput object. You can modify any relevant fields such as Item information, Works Order Type, or any other details specific to your application.
  3. Recalculating missing information: If any required information is missing from the input object, the mutation will calculate the missing values based on default settings or any other logic defined in the system. This ensures that the works order has all the necessary data before it is updated.
  4. Running business validations: Similar to the create mutation, the update mutation also performs business validations on the updated data to ensure it meets the required criteria. If any validation errors occur, the mutation will return a response with the details of the errors.
  5. Saving the updated works order: If all the necessary information is present and the business validations pass successfully, the mutation will save the updated works order in the system. This means that the changes will be persisted and available for further processing or retrieval.

Parameters​

WorksOrder [Required]​

This mutation requires an input object of type WorksOrderInput, which should contain all the necessary information to update the works order.

Response​

After executing the update mutation, you will receive a response containing the updated works order's Id if the update was successful. If any validation errors or unexpected errors occur during the operation, the response will include the details of those errors.

An example of the three response types provided by this request can be found below:

{
  "data": {
    "worksOrder": {
      "worksordersRecords": {
        "update": {
          "id": 123
        }
      }
    }
  }
}

Delete Works Orders​

To delete works Orders, you can use the delete mutation. This operation contains a mandatory primaryKeys parameter which should be populated with the primary key of each works order you want to delete.

Here's an example of how you can use the delete mutation to delete works orders:

mutation (
    $primaryKeys: [Int!]!
  ) {
    worksOrder {
      worksordersRecords {
        delete (ids: $primaryKeys)
        {
          ...Success
          ...Validation
          ...Errors
        }
      }
    }
  }

  fragment Success on IntEntityIdResultGraphType {
    ... on IntEntityId {
      id
    }
  }

  fragment Validation on IntEntityIdsResultGraphType {
    ... on FailedValidation {
      errors {
        message
        details {
          primaryKey
          field
          value
        }
      }
    }
  }

  fragment Errors on IntEntityIdsResultGraphType {
    ... on UnexpectedError {
      errorMessage
    }
  }

In the above example, you need to provide the primaryKeys array containing the primary keys of the works orders you want to delete. The mutation will then attempt to delete the specified works orders.

If the deletion is successful, the response will include a succeeded field with a value of true.

note

This operation won't validate the existance of the the provided Ids. If they don't exist, they will simply be ignored and won't notify the calling system.

An example of the success response type provided by this request can be found below:

{
  "data": {
    "worksOrder": {
      "worksordersRecords": {
        "delete": {
          "succeeded": true
        }
      }
    }
  }
}