= Setup and Configuration

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


This section describes how to include the GraphQL viewer's module and set its configuration properties.


include::docs:mavendeps:partial$setup-and-configure-mavendeps-webapp.adoc[leveloffset=+1]


== Update AppManifest

In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the

[source,java]
.AppManifest.java
----
@Configuration
@Import({
        ...
        CausewayModuleViewerGraphQlViewer.class,
        ...
})
public class AppManifest {
}
----


== Configuration Properties

The xref:refguide:config:about.adoc[configuration properties] for the GraphQL viewer fall into a number of categories.

(To make this section easier to read, the `causeway.viewer.graphql.` prefix of all of these configuration properties is omitted).

=== API variant and Schema Style

The most important configuration properties are:

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.api-variant[api-variant]
+
Whether to support relaxed (but non-spec compliant) queries with mutations, or instead to expose an API that is query only.

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.api-scope[api-scope]
+
Whether to include all domain classes in the GraphQL schema (entities and view models), or whether only to include view models.
Which to use depends upon whether the GraphQL client is owned by the same team the owns the backend application.

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.schema-style[schema-style]
+
Whether to use the "simple" schema style (data only, client-driven), the "rich" schema style (includes supporting facets, server-driven) or both schema styles.

These were discussed on the xref:gqlv:ROOT:about.adoc[main page for GraphQL viewer].

=== Customizing the Schema

A number of other configuration properties can customize the schema in various ways.
Normally these can be left as their default:

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.schema.simple.top-level-field-name[schema.simple.top-level-field-name]
+
If using the `SIMPLE_AND_RICH` or `RICH_AND_SIMPLE` schema styles, this configuration defines the name of the top-level field that holds the rest of the _simple_ schema.
+
It defaults to "`simple`".


* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.schema.rich.top-level-field-name[schema.rich.top-level-field-name]
+
If using the `SIMPLE_AND_RICH` or `RICH_AND_SIMPLE` schema styles, this configuration defines the name of the top-level field that holds the rest of the _rich_ schema.
+
It defaults to "`rich`".

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.meta-data.field-name[meta-data.field-name]
+
Defines the field name of the "meta data" structure used to expose the id, logical type name and (for entities) the version of a domain object.
+
The default value for this config property is "`_meta`".


The schema to xref:about.adoc#queries-that-lookup-a-domain-object[look up a domain object] can also be customized:

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.lookup.arg-name[lookup.arg-name]
+
This is the name of the synthetic first argument used to locate the object to be looked up.
+
It defaults to "`object`".

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.lookup.field-name-prefix[lookup.field-name-prefix]
+
Whether to prefix the field name of the domain object's type.
+
This defaults to an empty string, in other words no prefix.

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.lookup.field-name-suffix[lookup.field-name-suffix]
+
Whether to add a suffix to the field name of the domain object's type.
+
This defaults to an empty string, in other words no suffix.

If executing a mutation rather than a query:

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.mutation.target-arg-name[mutation.target-arg-name]
+
This is the name of the synthetic first argument used to locate the object to be mutated.
+
It defaults to "`_target`".



The remaining configuration properties are explained in more detail elsewhere:

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.resources.response-type[resources.response-type]
+
Control whether the xref:about.adoc#resources-blobs-clobs-layouts-icons[Resource controller] is enabled

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.schema.rich.enable-scenario-testing[schema.rich.enable-scenario-testing]
+
Enable xref:testsupport.adoc#scenario-tests[scenario testing].

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.authentication.fallback.username[authentication.fallback.username] and xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.authentication.fallback.roles[authentication.fallback.roles]
+
Are used by the default xref:spi-services.adoc#usermementoprovider[UserMementoProvider] for authentication.

Marshalling SPI:

* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.scalar-marshaller.zoned-date-time-format[zoned-date-time-format], xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.scalar-marshaller.local-date-format[scalar-marshaller.local-date-format] and xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.scalar-marshaller.local-time-format[scalar-marshaller.local-time-format]
+
specify the format that dates and times should be specified as strings, eg "`yyyy-MM-dd`".

