# GraphQL The source GraphQL connector will sync content that can be read by a GraphQL endpoint. This requires the ability to write GraphQL queries and use [dot notation pathing](https://github.com/tidwall/gjson#path-syntax) for JSON objects to get and map the data. ## Configuration walkthrough {% embed url="" %} ## Specifics The GraphQL connector takes a couple GraphQL queries to get the content. Then it takes a set of mappings to put the returned JSON into a Motation file. There are two specific queries that need to be provided. 1. A query to get IDs 2. A query to get each content by ID ***Note:*** Queries cannot include `,` instead, use white space to separate attributes in the GraphQL query. ### **IDs Query** This is a query that can return multiple pieces of content often in an array. The query needs to return a couple attributes of the content. 1. ID 2. Modification date In addition, the pathing to these attributes also need to be provided as **Job Options**. First provide the path to the contents using **contentPath**. Then provide the path to the **ID** and **Mod date** by using the **idPath** and **modDatePath** options. Note that idPath and modDatePath are both relative to inside the content. Meaning the full path to the content ID would be akin to contentPath.idPath. #### Example *Based on Wordpress GraphQL plugin support* ``` idsQuery:query { pages { nodes { id title content modified}} posts { nodes { id title } }} contentPath:data.pages.nodes idPath:id modDatePath:modified ``` ### **Content Query** This is a query that can return a single piece of content by ID. The ID passed into the query will be the same ID gotten from the ID query. In the query, where the ID would go, you use `<|replace_id|>` instead. The connector will then replace that string with the content's ID. This query must return a few values. 1. The ID of the content 2. The definition name for the content 3. Any attribute to be transformed to Motation 4. All necessary data for any picked up Motation Object The path to the ID and definition name must also be provided as **Job Options**. Use **idMapping** to path to the ID of the content. Use **definitionNamePath** to path to the name of the definition of the content. Both options are relative to the root of the Content Query. If the job is expected to pick up categories, the content query must include the array of categories for the content and all necessary data for those categories. #### Example *Based on Wordpress GraphQL plugin support* ``` contentQuery:query { page(id: \"<|replace_id|>\") { id title content __typename }} idMapping:data.page.id definitionNamePath:data.page.__typename ``` ### Attribute/Field Mapping Additional attributes to be mapped into Motation fields need the **mapping** job option set. The mapping job option can be broken into two parts. 1. The path to the attribute 2. The field type Both parts need to be provided in the same option separated by a `:`formatted as follows. `path:fieldType` #### Example *Based on Wordpress GraphQL plugin support* ``` mapping:data.page.title:String mapping:data.page.content:WYSIWYG ``` The available field types can be found in the [dev manual's Motation documentation](https://motivlabs.gitbook.io/impulse-dev-manual/motation/content-motation#motation-fields). Use the `String Name` columns values. ### Binary Field Type Mapping When setting a binary field type you must include additional pathing data for the parent path and file name. There are three options to set these values with. * filepath * A combination of parent path and file name separated by a `/` * i.e., `path/to/file/filename` * parentpath * The parent path of the file. * i.e., `path/to/file` * filename * The file name. * i.e., `filename` The pathing can be added to a **mapping option** separated by `:` #### Example *Based on Wordpress GraphQL plugin support* ``` mapping:data.mediaItem.mediaDetails:Binary:data.mediaItem.mediaItemUrl:filepath OR mapping:data.mediaItem.mediaDetails:Binary:data.mediaItem.mediaItemPath:parentpath:data.mediaItem.mediaItemName:filename ``` ### Array Field Type Mapping It is assumed that a field type `Array` is a value akin to the following. ``` ["one", "two", "three"] ``` ### Category/Tag Field Type Mapping The path to either category or tag field types is expected to be an array. ### Endpoint Config When saving an endpoint for a GitHub repository via REST instead of the UI you must use the following key:value pairs in the payload. * `contentRepo:graphql` * `contentRepoVersion:latest` ### Unsupported GraphQL jobs have no dependency support. The best way to work around this is to create multiple jobs for each content type and use a pipeline the jobs together. GraphQL does not support relationships. GraphQL adapter does not support running as a remote adapter apart from Impulse. ## Adapter Properties | Property | Purpose | Required | | --------------- | ------------------------------------------------------------------ | -------- | | user | The basic auth user to send the GraphQL query as. | false | | password | The basic auth password for the user to send the GraphQL query as. | false | | token | A token for authentication to send the GraphQL query. | false | | graphqlEndpoint | The full URL path to send GraphQL queries to. | true | ## Job Options
NameDescriptionData TypeRequiredDefault Value
idsQueryThe query to get IDs of all contents to be picked up.TextYesNo Default Value
contentPathThe path to the contents array relative to the idsQuery root. TextYesNo Default Value
idPathThe path to the ID of the content relative to the contentPath.TextYesNo Default Value
modDatePathThe path to the mod date of the content relative to the contentPath.TextYesNo Default Value
contentQueryThe query to get a single content by ID.TextYesNo Default Value
idMappingThe path to the ID of a content relative to the contentQuery root.TextYesNo Default Value
definitionNamePathThe path to the definintion name of a content relative to the contentQuery root.TextYesNo Default Value
mappingThe path to an attribute of a content relative to the contentQuery root and the Motation field type of the attribute separated by : formatted as follows path:fieldTypeArrayYesNo Default Value
binaryUrlPathThe path to the URL of a binary relative to the contentQuery root. The URL value will be used to get the binary directly. TextNoNo Default Value
domainMappingThe path to the domain of a content relative to the contentQuery root. TextNoNo Default Value
contentTypeFileThe path to the attribute to check the content's type. If the attribute is not empty and has any value other than false, the content type will be file. Otherwise it will be content. TextNoNo Default Value
categoriesPathThe path to the categories of a content relative to the contentQuery root. TextNoNo Default Value
categoriesIdPathThe path to the ID of a category relative to the categoriesPath. TextNoNo Default Value
categoriesNamePathThe path to the name of a category relative to the categoriesPath. TextNoNo Default Value
categoriesOrderPathThe path to the order of a category relative to the categoriesPath. TextNoNo Default Value
categoriesChildrenPathThe path to the children of a category relative to the categoriesPath. It is assumed children have the same structure as the parent and the same categoriesIdPath will be used. TextNoNo Default Value
tagsPathThe path to the tags of a content relative to the contnetQuery root.TextNoNo Default Value
tagsIdPathThe path to the ID of a tag relative to the tagsPath.TextNoNo Default Value
tagsNamePathThe path to the name of a tag relative to the tagsPath.TextNoNo Default Value
tagsDomainIdPathThe path to the domain ID of a tag relative to the tagsPath.TextNoNo Default Value
tagsDomainNamePathThe path to the domian name of a tag relative to the tagsPath.TextNoNo Default Value
languagesPathThe path to the languages of a content relative to the contentQuery root.TextNoNo Default Value
languagesIdPathThe path to the ID of a language relative to the languagesPath.TextNoNo Default Value
languagesNamePathThe path to the name of a language relative to the languagesPath.TextNoNo Default Value
languagesCodePathThe path to the code of a language relative to the languagesPath.TextNoNo Default Value
languagesCountryNamePathThe path to the country name of a language relative to the languagesPath.TextNoNo Default Value
languagesCountryCodePathThe path to the country code of a language relative to the languagesPath.TextNoNo Default Value
domainsPathThe path to the domains of a content relative to the contentQuery root.TextNoNo Default Value
domainsIdPathThe path to the ID of a domain relative to the domainsPath.TextNoNo Default Value
domainsNamePathThe path to the name of a domain relative to the domainsPath.TextNoNo Default Value
domainsUriPathThe path to the URI of a domain relative to the domainsPath.TextNoNo Default Value
domainsActivePathThe path to the active attribute of a domain relative to the domainsPath.TextNoNo Default Value
domainsDescriptionPathThe path to the description of a domain relative to the domainsPath.TextNoNo Default Value
domainsSystemPathThe path to the system attribute of a domain relative to the domainsPath.TextNoNo Default Value
domainsDefaultPathThe path to the default attribute of a domain relative to the domainsPath.TextNoNo Default Value
domainsKeywordsPathThe path to the keywords array of a domain relative to the domainsPath.TextNoNo Default Value
domainsAliasesPathThe path to the aliases array of a domain relative to the domainsPath.TextNoNo Default Value
foldersPathThe path to the folders of a content relative to the contentQuery root.TextNoNo Default Value
foldersIdPathThe path to the ID of a folder relative to the foldersPath.TextNoNo Default Value
foldersDomainIdPathThe path to the domain ID of a folder relative to the foldersPath.TextNoNo Default Value
foldersDomainNamePathThe path to the domain name of a folder relative to the foldersPath.TextNoNo Default Value
### Example Job Options ### Getting Motation Objects Each Motation object has a set of job options to transform data. The following is an example, using categories and tags, of how to pickup and transform Motation objects. *Based on Wordpress GraphQL plugin support* ``` idsQuery: query {posts {nodes {id title content modified}} posts {nodes {id title}}} contentQuery: query post {post(id: \"<|replace_id|>\") { __typename id title content modified categories {nodes {id name parent { node { id name}} children {nodes { id name}}}} tags {nodes {id name}} comments { nodes {id content}}}} contentPath: data.posts.nodes idPath: id modDatePath: modified mapping: data.post.title:String mapping: data.post.content:WYSIWYG mapping: data.post.categories:Category mapping: data.post.tags:Tag idMapping: data.post.id definitionNamePath: data.post.__typename categoriesPath: data.post.categories.nodes categoriesIdPath: id categoriesNamePath: name categoriesChildrenPath: children.nodes tagsPath: data.post.tags.nodes tagsIdPath: id tagsNamePath: name ``` ### Getting Binary The following is an example of job options to be set for getting binary files. *Based on Wordpress GraphQL plugin support* ``` idsQuery: query medias { mediaItems { nodes { id modified uri}}} contentQuery: query media { mediaItem(id: \"<|replace_id|>\") { id modified uri mediaItemUrl date fileSize parent { node { id uri}} __typename mediaDetails { file sizes { file fileSize height mimeType name sourceUrl width} __typename}}} contentPath: data.mediaItems.nodes idPath: id modDatePath: modified mapping: data.mediaItem.mediaDetails:Binary:data.mediaItem.mediaItemUrl:filepath idMapping: data.mediaItem.id definitionNamePath: data.mediaItem.__typename binaryUrlPath: data.mediaItem.mediaItemUrl contentTypeFile: data.mediaItem.fileSize ``` ## Motation Object Support | Object | Supported | | ------------ | --------- | | Category | Yes | | Definition | Yes | | Domain | Yes | | Folder | Yes | | Language | Yes | | Relationship | No | | Tag | Yes | ## Content Mapper Below are details on how to find the appropriate values to use in the content mapper. * `origin.uniqueId` * Value obtained from **definitionNamePath** option. * `fields.origin.uniqueId` * Path used for **mapping** option. ## Troubleshooting *