--- keyword: [Extend, Workday Graph API, Graph API, GraphQL, Validate Only] nav: wcp_docs parent_url: /wcp_docs/ title: Graph API Mutations layout: subsection --- To add, update, or delete data using Graph API, submit a `mutation` that performs the operation on the business object and related data in the schema. Specify the input data and response fields that are available in the schema. For a mutation on a specific object, include the ID argument of the object you want to update or delete. Ensure that you've configured the proper permissions for the mutation security domains listed in the schema. If the mutation submits a business process, ensure that you've configured the security policy for the initiating action for the business process. The Generate Query option on the Graph API Explorer can help you write a mutation. ## Mutation Structure A mutation begins with the `mutation` keyword, and follows this basic structure: ``` mutation operationName ( $mutation_input: InputType!, $variable: Type ) { rootMutationField ( input: $mutation_input, argument: $variable ) { responseField1 responseObjectField2 { responseField2 } } } ``` The rootMutationField is a top-level mutation field in the Graph API schema, and represents the object data or business process event you can create, update delete, or submit. ![](GUID-6f39ec41-4f4a-4110-98e6-1969ef7bb4e2-enHYPHENus.png) A rootMutationField defines the elements that you'll need in your mutation. It defines the arguments, which enable you to send input variables through the operation name. The mutation elements that start with `$` are [Input Variables](/wcp_docs/kbu1671067116723.html#section-input-variables), which you must define as [Query Variables](/wcp_docs/kbu1671067116723.html#section-query-variables). The return type of the rootMutationField defines the [Response Data Fields](/wcp_docs/kbu1671067116723.html#section-response-data-fields) that you can select in your mutation. Example: The `createProcurementRequisition` root mutation field in the Graph API schema: ![](GUID-ad123ccf-19cf-4d73-9bd5-5e554ee9df38-enHYPHENus.png) ## Input Variables Declare the input variables with the mutation operation name: operationName($mutation_input: InputType!, $variable: Type) Where: - operationName( ) A name you can assign to the mutation. The operation name requires parentheses `( )`, which contains input variable declarations. A mutation that has input variables requires the operation name. - $mutation_input: InputType! - `$mutation_input` An input variable containing the fields sent to the mutation. Always begin an input variable with `$`. Define the input variable in the Query Variables as a JSON map containing the required and optional input data. For input fields that require Workday IDs, check the `Mutation_Prompts` in the Graph API schema to determine whether input prompt values are available for a specific mutation. See [Input Prompt Values for Mutations](/wcp_docs/GUID-285d95ca-d2d1-4e0a-b7df-7e4d9c345240-enHYPHENus.html) - `InputType!` The type of the mutation input. In the schema, the `input` argument specifies the type. The input type contains the fields that you can send to the mutation. Always append the type of the input variable with `!`, indicating that it's non-nullable and required. - $variable: Type - `$variable` An input variable for any of the other mutation arguments. Example: The instance ID for the update or delete mutation. Always begin an input variable with `$`. Define the input variable in the Query Variables as a JSON key-value pair. - `Type` The type of the variable. In the schema, each argument of the mutation specifies the type. If the type ends with `!` indicating it's required, append the input variable type with `!`. In this mutation snippet, createProcurementRequisition is an operation name. Its input variable is $createProcurementRequisition_input: ``` mutation createProcurementRequisition($createProcurementRequisition_input: Procurement_CreateRequisitionRepresentation_CreateInput!) ``` Note: When an input variable is an `id` field that's of the `IdentifierInput` type and the `type` field of the `id` doesn't have a default value, ensure that you specify the `type` field in the input variable. In this sample mutation, the `reason.id` in `input`and `workerId` input variables are both of `IdentifierInput` type. ``` mutation initiateJobChange( $input: Staffing_JobChangesStartDetailsPOSTData_CreateInput!, $workerId: IdentifierInput!) { initiateWorkerJobChange( input: $input, workerId: $workerId ) { date workdayID { id type } } } ``` The `reason.id` and `workerId` input variables include the `type` field: ``` { "input": { "date": "2022-12-19", "reason": { "id": { "id": "32e3a48dc5f24cd2acb4c5c0e852c08a", "type": "WID" } } }, "workerId": { "id": "3bcc416214054db6911612ef25d51e9f", "type": "WID" } } ``` ## Root Mutation Field and Arguments Specify the root mutation field and arguments containing the fields that you send to the mutation: rootMutationField (input: $mutation_input, argument: $variable) Where: - rootMutationField( ) The name of the top-level mutation field, as defined in the FIELDS list of the Mutation root type in the schema. The mutation requires parentheses `( )`, which contains the mutation input arguments. Note: The name of the root mutation field starts with the type of mutation: create, update, delete, and event-driven actions (approve, cancel, close, deny, initiate, submit). - input: $mutation_input - `input` A required argument. For create, update, and business process-related mutations, always specify `input`. - ``$mutation_input`` The input variable for the mutation, as specified in the input variable declaration. The $mutation_input variable contains the fields you send to the mutation. Always begin an input variable with `$`. For input fields that require Workday IDs, check the `Mutation_Prompts` in the Graph API schema to determine whether input prompt values are available for a specific mutation. See [Input Prompt Values for Mutations](/wcp_docs/GUID-285d95ca-d2d1-4e0a-b7df-7e4d9c345240-enHYPHENus.html) - argument: $variable - `argument` The name of any additional mutation argument, as defined in the schema. Besides the `input` argument, a mutation can require additional arguments. - `$variable` An input variable, as specified in the input variable declaration. Always begin an input variable with `$`. In this mutation snippet, `createProcurementRequisition` is a root mutation field in the schema. Its argument is `input`: ``` createProcurementRequisition( input: $createProcurementRequisition_input ) ``` ## Response Data Fields After the root mutation field and its arguments, specify the response fields in `{ }`. Select schema fields from the type returned by the mutation operation. If a schema field is a nested object, enclose its subfields in braces `{ }`. Example: ``` { descriptor workdayID { id } } ``` The mutation returns the data fields in a `data.rootMutationField` JSON object. Example: ``` { "data": { "createProcurementRequisition": { "descriptor": "REQ-7127", "workdayID": { "id": "9312a776a4ad9000236748db7d230000" } } } } ``` ## Query Variables Define all input variables in a JSON map, where: - key The input variable name, as specified in the input variable declaration with the operation name. - value The value, whose type matches the schema type in the input variable declaration. The mutation_input variable is an object map whose structure matches the input type in the schema. For a mutation that updates or deletes an object, specify the mutation_objectId variable with the `id` and `type` fields. To determine the supported identifier types, refer to the argument field description in the schema. Sample $createProcurementRequisition_input query variable: ``` { "createProcurementRequisition_input": { "requester": { "id": { "id": "3aa5550b7fe348b98d7b5741afc65534", "type": "WID" } }, "memo": "Mobile gadget request for project 1", "requisitionLines": [ { "item": { "id": { "id": "c81b4811f29e4014bb5321b57b8e1f31", "type": "WID" } }, "quantity": 5 } ] } } ``` ## HTTP Headers with Graph API Mutations Graph API supports HTTP headers that enable features related to the mutations you submit with the Graph API endpoint. See [Graph API Headers](/wcp_docs/GUID-c0c417b9-540c-47f0-a400-2c6ae9bbd760-enHYPHENus.html). ## Examples This mutation creates a requisition. ``` mutation createProcurementRequisition($createProcurementRequisition_input: Procurement_CreateRequisitionRepresentation_CreateInput!) { createProcurementRequisition(input: $createProcurementRequisition_input) { descriptor workdayID { id } memo company { descriptor } requester { descriptor } requisitionLines { descriptor workdayID { id } itemDescription } } } ``` The query variables: ``` { "createProcurementRequisition_input": { "requester": { "id": { "id": "3aa5550b7fe348b98d7b5741afc65534", "type": "WID" } }, "memo": "Mobile gadget request for project 1", "requisitionLines": [ { "item": { "id": { "id": "c81b4811f29e4014bb5321b57b8e1f31", "type": "WID" } }, "quantity": 5 } ] } } ``` Sample response: ``` { "data": { "createProcurementRequisition": { "descriptor": "REQ-7174", "workdayID": { "id": "48dd03c366c89000135405aca1510000" }, "memo": "Mobile gadget request for project 1", "company": { "descriptor": "Global Modern Services, Inc. (USA)" }, "requester": { "descriptor": "Logan McNeil" }, "requisitionLines": [ { "descriptor": "REQ-7174", "workdayID": { "id": "48dd03c366c89000135406579ba40000" }, "itemDescription": "iPad 2 64GB" } ] } } } ``` This mutation updates the requisition. ``` mutation updateProcurementRequisition ( $updateProcurementRequisition_input: Procurement_EditRequisitionRepresentation_UpdateInput!, $updateProcurementRequisition_requisitionsId: IdentifierInput! ) { updateProcurementRequisition ( input: $updateProcurementRequisition_input, requisitionId: $updateProcurementRequisition_requisitionsId ) { descriptor memo requester { descriptor } workdayID { id } } } ``` The query variables using the returned requisition `id` from the createProcurementRequisition mutation: ``` { "updateProcurementRequisition_input": { "memo": "Mobile gadget request for project 2" }, "updateProcurementRequisition_requisitionsId": { "id": "d5f07ec4595390001501fa530c060000", "type": "WID" } } ``` Sample response: ``` { "data": { "updateProcurementRequisition": { "descriptor": "REQ-7132", "memo": "Mobile gadget request for project 2", "requester": { "descriptor": "Logan McNeil" } } } } ``` This mutation cancels the requisition. ``` mutation cancelProcurementRequisition($cancelProcurementRequisition_input: Procurement_CancelRequisitionRepresentation_CreateInput!, $cancelProcurementRequisition_requisitionId: IdentifierInput!) { cancelProcurementRequisition( input: $cancelProcurementRequisition_input requisitionId: $cancelProcurementRequisition_requisitionId ) { comments descriptor workdayID { id } } } ``` Query variables: ``` { "cancelProcurementRequisition_input": { "comments": "Cancel mobile gadget request" }, "cancelProcurementRequisition_requisitionId": { "id": "48dd03c366c890001369835173860000", "type": "WID" } } ``` Sample response: ``` { "data": { "cancelProcurementRequisition": { "comments": "Cancel mobile gadget request", "descriptor": "REQ-7175", "workdayID": { "id": "48dd03c366c890001369835173860000" } } } } ``` ### Related Information [Generate Queries on Graph API Explorer](/wcp_docs/uip1679531855079.html) [Sample Mutations](/wcp_docs/uhj1671490761964.html) [Workday Graph API](/wcp_docs/vyw1671061988370.html)