GraphQL in Apps

Apps use GraphQL schemas to describe the type signatures of requests and responses.

Data Schema (data/data_schema.graphql): Defines the types and fields for data retrieved from external systems via Data Pulls
Actions Schema (actions/actions_schema.graphql): Defines the mutations (actions) that can be performed from Gladly

Gladly uses these schemas to understand what data can be displayed and what operations can be performed through the integrated app.

Example

type Order {
    orderId: String
    orderDate: DateTime
}

GraphQL references

Introduction to GraphQL

GraphQL Directives

We utilize only the built-in GraphQL directives (@deprecated, @include, and @skip) plus three additional directives below (@dataType, @childIds, @parentId).

Standard

GraphQL provides several built-in directives that are commonly used in GraphQL schemas. These directives include:

@deprecated – Indicates that a field or enum value is deprecated and should not be used. It takes an optional reason argument to explain why the field is deprecated.
@include(if: Boolean) – Conditionally includes a field in the response based on the value of the if argument. If if is true, the field is included; otherwise, it is omitted.
@skip(if: Boolean) – Conditionally skips a field in the response based on the value of the if argument. If if is true, the field is skipped; otherwise, it is included.

These directives allow us to control the shape and content of GraphQL responses based on runtime conditions and deprecation status.

Add-on

We have added three additional directives for you to use:

@dataType – We use the @dataType directive to associate a GraphQL type with a given data type from a data pull in Gladly. For example, below, you will see the GraphQL type GladlyCustomer is associated with the gladly_customer Data Pull version "1.0"

type GladlyCustomer @dataType(name: "gladly_customer", version: "1.0") {
...
}

@childIds – This directive specifies how child entities are identified within a parent entity. It typically takes a template as an argument, which is used to construct the unique identifiers of child entities based on the parent entity’s data. For example, @childIds(template: "{{.productId}}") might indicate that each child entity’s ID is derived from the productId field of the parent entity.
@parentId – This directive identifies the parent entity associated with a child entity. It often takes a template argument as well, which is used to construct the unique identifier of the parent entity based on the child entity’s data. For instance, @parentId(template: "{{.id}}") could indicate that the parent entity’s ID is derived from the id field of the child entity.

These directives help establish hierarchical relationships between data types in GraphQL schemas, allowing for structured and efficient data retrieval.

Gladly supports the standard GraphQL data types (Int, Float, String, Boolean, ID) and the following additional types.

Data Type	Format	Description
DateTime	String value in ISO8601 date format	DateTime fields can be used in conditionals and can be manipulated.
Currency	String representation of currency value (real number)	Representing currency values as a string ensures no loss of precision. Gladly ensures that no precision is lost when manipulating Currency values.

Validate and Run GraphQL

Once your GraphQL data schema has been written, it is time to validate and test it.
Start by running the vּalidate command.
If your data schema passes validation, please run each GraphQL entry points.

appcfg run data-graphql -d success -q customer -s '{"apiToken": "token"}'

appcfg run data-graphql -d success -q orders -s '{"apiToken": "token"}'