Access record data in a component by querying your scripted GraphQL schema.

Before you begin

Role required: admin
  1. Create a GraphQL schema.
  2. Test GraphQL APIs with GraphQL Explorer.
  3. Disable introspective queries in your production environment.
  4. Create a custom component.

Procedure

  1. Navigate to your component directory.
  2. Define the query in your component's index.js file.
    Remove introspective queries
    Do not use introspective queries for components deployed in a production environment.
    Include applicable namespaces
    Include both the application and schema namespaces in the query.
    Defer slow-responding fields
    You can apply the @defer query directive to a fragment to delay the processing of one or more slow-responding fields. Deferring slow-responding fields allows the query to return other fields first.
    Warning: Avoid applying this query directive indiscriminately as it can also cause performance degradations. Conduct performance testing to determine which fields can be deferred for better performance.
    Note: 
    const incidentQuery = `query ($sys_id: String!) {
    query (sys_id: $sys_id) {
        incident {
            _results {
                sys_id {
                    displayValue
                }
            }
        }
    }
}`;
  3. Add the following line to the top of the script to import the createGraphQLEffect API into your component. 
    import {createGraphQLEffect} from '@servicenow/ui-effect-graphql';
  4. Call the query using the createGraphQLEffect API. To learn more about this API, see the Developer Site.
  5. Create action handlers to manage the result of the query. 
    actionHandlers: {
   [DATA_FETCH_REQUESTED]: dataFetchHandler,
   [DATA_FETCH_STARTED]: ({updateState}) => updateState({loading: true}),
   [DATA_FETCH_SUCCEEDED]: ({action, updateState}) => updateState({data: action.payload}),
   [DATA_FETCH_FAILED]: () => { /* handle network error */ },
 }

Example

This example shows a complete component including the query, the GraphQL API call, and action handlers to manage the response.

import {createCustomElement} from '@servicenow/ui-core';
import snabbdom from '@servicenow/ui-renderer-snabbdom';
import {createGraphQLEffect} from '@servicenow/ui-effect-graphql';

const GQL_QUERY = `
query query ($active: Boolean) {
    now {
        mySchema (active: $active) {
            myField {
                value
            }
         }
    }
}`;
  
const DATA_FETCH_REQUESTED = 'DATA_FETCH_REQUESTED';
const DATA_FETCH_STARTED = 'DATA_FETCH_STARTED';
const DATA_FETCH_SUCCEEDED = 'DATA_FETCH_SUCCEEDED';
const DATA_FETCH_FAILED = 'DATA_FETCH_FAILED';
  
const dataFetchHandler = createGraphQLEffect(GQL_QUERY, {
  variableList: ['active'],
  startActionType: DATA_FETCH_STARTED,    // gql http request started
  successActionType: DATA_FETCH_SUCCEEDED // gql request succeeded with result
  errorActionType: DATA_FETCH_FAILED      // gql http network request error (actual schema / server errors will succeed with error objects
});

const component = createCustomElement('now-component', {
  renderer: {type: snabbdom},
  view(state) {
    if(state.loading)
      return <div>Loading...</div>;

    if(!state.data)
      return <div>No Data</div>;

    return <div>My value: {state.data.data.now.mySchema.myField.value}</div>;
  },
  actionHandlers: {
   [DATA_FETCH_REQUESTED]: dataFetchHandler,
   [DATA_FETCH_STARTED]: ({updateState}) => updateState({loading: true}),
   [DATA_FETCH_SUCCEEDED]: ({action, updateState}) => updateState({data: action.payload}),
   [DATA_FETCH_FAILED]: () => { /* handle network error */ },
  }
});