---
category: [Administration & Integrations, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions/Workday Extend]
keyword: [Extend, Workday Graph API, Graph API, GraphQL]
nav: wcp_docs
parent_url: /wcp_docs/
title: Graph API in Extend Pages
layout: subsection
---
## Submitting Queries and Mutations
To submit Graph API queries and mutations from a page, define a PMD endpoint that calls the [Graph API endpoint](/wcp_docs/flw1653707569144.html):
- For queries, call the Graph API endpoint as an inbound endpoint. The `httpMethod` attribute must be POST. For details about inbound endpoints, see [endPoints](/wcp_docs/ujr1530565661647.html).
- For mutations, call the Graph API endpoint as an outbound endpoint. For details about outbound endpoints, see [outboundDataURI](/wcp_docs/yzz1530025276777.html).
In the PMD endpoint, specify the `graphQuery` attribute with either:
- An inline query or mutation, or
- A reference to a Graph Query component.
We evaluate and send the value of `graphQuery` as the request payload of the Graph API endpoint. You can use the `onSend` event to debug the content of the request payload, but you can't use `onSend` to modify the static `query` string. Instead, use the `variables` property for dynamic values.
To catch errors from the query or mutation, specify the `failOnStatus` attribute of the endpoint. Syntax errors in the query or mutation return the 400 status code, so include `400` in the list of codes.
Note: The Graph API endpoint can return the 200 status code with partial response and errors. Note that if the Graph API endpoint response contains `errors[]`, the page treats it as an error, even if the endpoint response status code is 200.
## Inline Query or Mutation in PMD Endpoints
In a PMD endpoint, you can specify an inline Graph API query or mutation in the `graphQuery` attribute using these properties:
- query
A static string containing an inline query or mutation.
The `query` string can contain variable placeholders (with the `$` prefix character), but it can't contain dynamic values. Specify the variable values in `variables`.
To embed a literal string inside the `query` string, use escaped double quotes.
- variables
A map containing dynamic values for the query or mutation, where:
- key
A static string containing the variable name, which should match the $placeholderVariable inside the `query` string.
- value
An object containing the variable value, which can be a native JSON map or a script that returns a map.
This sample PMD endpoint calls an inline Graph API query:
```
{
"name" : "activeWorkers",
"baseUrlType" : "workday-graph",
"httpMethod" : "POST",
"failOnStatusCodes" : [ {
"code" : 400
} ],
"graphQuery" : {
"query" : "query getActiveWorkers($dataSourceVariables: Worker_DataSources!, $limit: BigInt, $offset: BigInt) {
worker(
dataSource: $dataSourceVariables, limit: $limit, offset: $offset) {
data {
businessTitle
workdayID { id }
descriptor
}
total
}
}
",
"variables" : {
"dataSourceVariables" : {
"indexedAllWorkers" : {
"filter" : {
"indexedAllWorkersFilter" : {
"isActive" : "<% pageVariables.isActive %>"
}
}
}
},
"limit" : "<% empty pagingVariables.limit ? 50 : pagingVariables.limit.toInt() %>",
"offset" : "<% empty pagingVariables.offset ? 0 : pagingVariables.offset.toInt() %>"
}
}
}
```
## Graph Query Component in PMD Endpoints
Instead of embedding an inline query or mutation within a PMD endpoint definition, you can create a Graph Query component. Referencing a Graph Query component enables you to simplify PMD endpoints and share reusable queries and mutations across multiple PMDs.
To reference a Graph Query component in a PMD endpoint, specify these `graphQuery` properties:
- queryId
A static string containing the ID of the Graph Query component you want to reference. The `queryId` must match the `id` of the Graph Query component.
- parameters
A map containing parameters sent to the Graph Query component, where:
- key
A static string containing the parameter name, which should match the name in `parameters[]` inside the Graph Query component.
- value
An object containing the parameter value, which can be a native JSON map or a script that returns a map.
Use `parameters` to send dynamic data to a Graph Query. Note that Graph Query components are self-contained modules and don't have page context. Use the parameters to send any app or page-specific variables.
- variables
A map containing dynamic values for the query or mutation, where:
- key
A static string containing the variable name, which should match the $placeholderVariable inside the `query` string.
- value
An object containing the variable value, which can be a native JSON map or a script that returns a map.
If you intend to use a Graph Query component but it's easier to define dynamic query variables in the PMD endpoint, you can specify both `queryId` and `variables` in `graphQuery`. If you use `variables` with `queryId`:
- If the Graph Query component also contains `variables`, the `variables` in the PMD overrides the Graph Query component variables.
- The `variables` and `parameters` properties of `graphQuery` are mutually exclusive.
For sample Graph Query components in PMD endpoints, see [Sample Graph Query Components in PMDs](/wcp_docs/yvb1682352201818.html).
## Specifying Variables
Variables enable your Extend app to pass argument values to a query or mutation. For each variable you include in the query or mutation (with the `$` prefix character), you must specify it as a query variable in the `variables` JSON map.
- For a simple variable such as boolean, text, or integer: Specify the query variable with a simple JSON key-value pair.
- For an object variable, which contains nested fields: Specify the query variable with a JSON map. Example: The `dataSource` query argument is a data source object, which can contain filters with multiple fields.
You have flexibility in how you want to specify variables. Depending on the complexity of the object structure of the variable, you can specify the nested structure in a query variable or in the argument itself.
Example: You can either specify the data source object as a query variable or embed the data source object as an argument.
- This sample specifies the data source object in the dataSourceVariable query variable.
```
"graphQuery": {
"query": "query getActiveWorkers($dataSourceVariable: Worker_DataSources!) {
worker( dataSource: $dataSourceVariable ) {
data {
workdayID { id }
descriptor
}
}
}",
"variables: {
"dataSourceVariable": {
"indexedAllWorkers": {
"filter": {
"indexedAllWorkersFilter": {
"isActive": true
}
}
}
}"
}
}
```
- This next sample embeds the same data source object as an argument. Instead of using a data source variable, this sample uses a simpler boolean query variable.
```
"graphQuery": {
"query": "query getActiveWorkers($active: Boolean) {
worker( dataSource: {
indexedAllWorkers: {
filter: {
indexedAllWorkersFilter: {
isActive: $active
}
}
}
}
) {
data {
workdayID { id }
descriptor
}
}
}",
"variables: {
"active": true
}
}
```
Note: The Query Generator on the Graph API Explorer uses query variables by default. Instead using separate query variables, you can embed the argument fields in the query by selecting Include Variables in Query on the Query Generator.
Copying variables from the Graph API Explorer
You can copy the complete JSON map value of `variables` from the Query Variables section of the Graph API Explorer to the `variables` property of `graphQuery` in the PMD.
Example: Copy the JSON map in the Query Variables section of the Graph API Explorer.
Paste the JSON map into the `variables` property of `graphQuery` in the PMD endpoint.
After you paste the JSON map into the PMD, you can replace hard-coded values with dynamic values using PMD Scripting. This sample replaces the isActive, limit, and offset values from Graph API Explorer with dynamic values using PMD Scripting.
```
"variables" : {
"dataSourceVariable" : {
"indexedAllWorkers": {
"filter": {
"indexedAllWorkersFilter": {
"isActive": "<% pageVariables.isActive %>"
}
}
}
},
"limit" : "<% empty pagingVariables.limit ? 50 : pagingVariables.limit.toInt() %>",
"offset" : "<% empty pagingVariables.offset ? 0 : pagingVariables.offset.toInt() %>"
}
```
Note: The sample `limit` and `offset` variables use `pagingVariables` with a paginated `grid`. The `pagingInfo` attribute of the grid uses the `pagingVariables` to call the paginated requests automatically as the user scrolls down the grid. Note that because the `pagingVariables.limit` and `pagingVariables.offset` are strings, we need to convert them to integer to match the `BigInt` type of the `limit` and `offset` variables, respectively. See "Grid paging with paginated endpoints" in [Concept: grid](/wcp_docs/tgx1652476064414.html).
## Specifying IDs
The Graph API schema defines ID fields as Identifier objects, each containing the `id` and `type` fields. The `type` can be "WID" or a reference type, such as "Employee_ID".
Example: The `Worker` object contains this `workdayID` field:
```
workdayID {
id
}
```
Sample `workdayID` response:
```
"workdayID": {
"id": "cc7fb31eecd544e9ae8e03653c63bfab"
}
```
Note that retrieving the `type` field in a query is optional.
The `id` field path is important with list widgets (such as `instanceList` and `dropdown`, and others). You can use PMD Scripting to specify the `id` field path in the list. Example:
```
{
"type": "instanceList",
"label": "instanceList using a Graph API list",
"id": "listFromGraphApi",
"values": "<%
getWorkersList.data.worker.data
.map (worker => {
{
'id': worker.workdayID.id,
'descriptor': worker.descriptor
}
});
%>"
}
```
For query arguments or mutation inputs that require an instance ID, specify the instance ID as an `id` object. Example:
```
id {
id
type
}
```
For input IDs, you must specify the `type` field. Refer to the `id` field description for the supported types of ID.
## Graph API Response Data
A Graph API request returns the response in a `data` JSON map whose root field is the name of the operation.
Queries return an object collection containing the requested fields in `data[]` and `total`. Example: Response from the `worker` query:
```
{
"data": {
"worker": {
"data": [
{
"workdayID": {
"id": "7687e33f159501d988232f3bc6572e45",
},
"businessTitle": "Customer Service Representative"
},
. . .
],
"total": 496
}
}
}
```
To reference data from a query, use the path `.data.`. Examples: In these sample paths, assume that the Graph API endpoint name is `activeWorkers`, and `worker` is the query.
- activeWorkers.data.worker.total
```
{
"type" : "text",
"label" : "Total number of active workers:",
"value" : "<% activeWorkers.data.worker.total %>"
}
```
- activeWorkers.data.worker.data
```
{
"type" : "grid",
"label" : "Active Workers",
"id" : "workersGrid",
"rows" : "<% activeWorkers.data.worker.data %>",
"rowVariableName" : "thisRow",
"pagingInfo" : {
"endPoint" : "<% endpoints.activeWorkers %>",
"rowCount" : "<% activeWorkers.data.worker.total %>",
"data" : "<% activeWorkers.data.worker.data %>"
},
"columns" : [ {
"type" : "column",
"columnId" : "col1",
"label" : "Worker",
"cellTemplate" : {
"type" : "text",
"value" : "<% thisRow.descriptor %>"
}
} ]
}
```
Mutations return an object containing the requested fields. Example: Response from the `initiateWorkerJobChange` mutation:
```
{
"data": {
"initiateWorkerJobChange": {
"date": "2022-12-09",
"workdayID": {
"id": "ed59a145c84e10002b67c710d98b0000",
}
}
}
}
```
Similarly, to reference data from a mutation, use the path `.data.`. Examples: In these sample paths, assume that the Graph API endpoint name is `initiateJobChange`, and `initiateWorkerJobChange` is the mutation.
- initiateJobChange.data.initiateWorkerJobChange.date
```
{
"type" : "text",
"label" : "Job change date:",
"value" : "<% initiateJobChange.data.initiateWorkerJobChange.date %>"
}
```
- initiateJobChange.data.initiateWorkerJobChange.id.id - This sample `variables` specifies the required `jobChangeId` for the `updateJobChangeBusinessTitle` mutation.
```
"variables" : {
"jobChangeId" : "<% initiateJobChange.data.initiateWorkerJobChange.workdayID.id %>",
"businessTitle" : "<% newTitle.value %>"
}
```
## Sample App
The [Vehicle Registration](https://developer.workday.com/app-catalog/vehicleRegistration) app in the App Catalog pages that submit Graph API queries and mutations in a Vehicle Registration hub.
### Related Information
[Run Graph API Queries on a Page](/wcp_docs/ydz1559023281482.html)
[Submit Graph API Mutations on a Page](/wcp_docs/pnn1671585287177.html)