GraphQL - Queries – BCS Epowerhr

GraphQL is a query language that makes it possible to query data from the eSuite application. This document will explain how you can use GraphQL queries to retrieve data.

Authentication

Before you can query any data, you need to authenticate in GraphQL. You can read the documentation for this here.

Once you are authenticated, you should see a green status icon on the website of the GraphQL URL that you have received from epowerhr. Or the software that you are using, tells you are good to go.

What is a query?

A “query” means a request for information. With GraphQL you can request certain information with these queries. Based on the query, GraphQL will retrieve the correct data from the eSuite database and return it to the browser or your software.

Schema in GraphQL

On the website of our GraphQL URL, you are able to consult the list of all the possible objects with all the possible fields. Click on “Schema Reference”. Here you will find detailed information of all the existing objects with all the possible fields.

How to write a query to fetch data

Click on “Operations”

This section is used for writing queries.

A query always starts with the following syntax:

query {

}

Inside this query, you need to provide the information that you wish to retrieve. The information that you can write in this query is bound what is available within GraphQL. This means that not everything is (yet) available to query via GraphQL.

Build the query

Queries only work when you provide the correct information inside the { … }. GraphQL will help you to build the queries correctly.

First you need to put the cursor between the two brackets like the screenshot below:

Now press Control + Spacebar. A pop-up will appear with a list of all the possible objects.

While you type, this list will become shorter until only one result is found. If no results are shown, this means the query doesn’t exist and cannot be executed.

Query searched on "hour".

Query with "yearSchedule”.

Example Query a person and list of persons

In this example, we want to query information of a person.

We start by typing “Person” and check which queries exist.

There are two queries that matches what we’re looking for.

The first query will return only 1 person based on a provided ID by the used and
The second query will return a list of available persons.

For basePerson, GraphQL needs an ID as parameter to find a match. We can provide these parameters or extra information by putting parentheses after the query object.

We need to provide "id" here and after this keyword, we need to write a colon “:”.

We now have the “framework” of this query. But we still need to tell GraphQL which fields we want to see in the result.

Click inside the basePerson() { } query and press Control + Spacebar to see the list of available fields:

Select the fields you want to see, for example, id, firstName, retired.

Note that there are no commas after the fields.

Click the blue run button to execute the query or execute the call in the software that you are using.

We can extend this query with different fields. Some fields are objects and have their own subfields. For example ‘Address’.

When adding address, GraphQL will automatically open a new list of fields related to the Address object. Here we can add fields related to address.

Hit the Run button again and check the differences.

We can make this query as complex as we wish, with the limitation that the fields should exist in this query. For example:

When a query doesn’t need any parameters, we don’t need to write the parentheses.

Common mistakes

Typo’s in query or fields

GraphQL will tell when something is off. For example, a query with a wrong field. GraphQL will underline this field with a red line.

When executing this query, the right pane will contain one or more error messages. You can also hover your mouse on the red line to see the error:

In this example ‘lasttname’ was spelled wrongly. We fix this by removing the ‘t’. We try again:

As you can see, we still have an error. The ‘n’ of name should be a capital ‘N’. GraphQL objects and fields are case-sensitive. So we need to change this from ‘lastname’ to ‘lastName’ in order to make it work.