Use GraphQL Mutation Hooks to synchronize data from Flatfile Workspaces to your application's existing GraphQL API

Communicate with a GraphQL API on every approved record in a Workspace with Workspace GraphQL Mutation Hooks

GraphQL is a standard that specifies a set of queries and mutations and provides a common request and response format for making API requests. A "query" represents reading data and a "mutation" represents inserting, modifying, or deleting data. You can use GraphQL Mutation Hooks within a Flatfile Workspace to submit data to your application's GraphQL API every time a record is approved, or every time an approved record is modified or deleted in a Workspace Sheet.

Here's how to get started:

1. Reach out to your Flatfile representative, or on chat, available at https://flatfile.com to enable Workspace GraphQL Mutation Hooks on your account. There is no charge for using GraphQL Mutation Hooks.
2. Navigate to a Data Template, and select the GraphQL Mutation Hooks tab
   
   
3. Click the "+ Add mutation" button, you will now see the Mutation Hook editor
   
   How to use the mutation editor
   
   The leftmost column is the list of mutations. The green or red circle indicates whether the mutation is Enabled or Disabled.
   The center column allows you to edit the mutation attributes, such as Type, GraphQL Endpoint, Enabled, and Primary Result Field.
   The rightmost column is the mutation body editor. This will accept variables from the related Schema fields and is the request body that will be submitted to your GraphQL API. A sample mutation is provided in the center column to get started.
   
   
4. Select a type (delete, insert, or update)
   
   Understanding mutation types
   

   When, in a Workspace Sheet, a row ...	delete mutation?	insert mutation?	update mutation?
   ... is changed from "In Review" to "Approved" status	no	an insert mutation will be fired, with variables from the newly approved row	no
   ... is changed from "Approved" to "In Review" or "Dismissed" status	a delete mutation will be fired, with the external primary key	no	no
   ... that is in "Approved" status is edited by a user	no	no	an update mutation will be fired, with variables from the edited row, and the external primary key

    

5. Enter your GraphQL endpoint. Note that authentication may fail at this stage, which is expected. You'll need to enter authentication headers in Workspace GraphQL settings, which will be examined later in this guide.
6. Enter your GraphQL mutation body. The name of the outer mutation wrapper must be provided, but the name itself can be anything you choose (in this case "InsertContact"). This screenshot shows calling the "insertContact" mutation with 3 variables, all of type String! (! means not nullable in GraphQL). The "id" is returned, representing the unique id of the newly inserted contact.
   
7. Notice that in the case of "Link to template" fields that create relationships between templates, additional fields are available. In the screenshot above, the Contact template contains a link to a Group template. If the Group has its own GraphQL Mutation Hooks for Insert operation, and an externalId is returned, that variable is available here as $link_group_externalId and can be used for establishing a relational link in your destination system. All other defined fields are also available from the related record.
8. Add the name of the result field that contains the newly inserted record's primary unique identifier to the Primary Result Field text input. In the above screenshot, that's "id".
9. Now, we'll go to a Workspace and add authentication headers. Navigate to a Workspace's Settings page and select the GraphQL Mutation Hooks tab
   
   Add any HTTP header(s) needed for authentication when performing GraphQL mutations. Authentication is per-workspace so that you may use different headers for each Organization you partner with to receive data from. These headers should be set carefully considering the scope of access granted and be long-lived API keys or JSON web token authorization headers. They are not automatically rotated, and must be manually updated when a token expires. Once the headers are set successfully, they will be displayed in the top right:
   
   We can now proceed with mutation setup under Templates > Edit data template > GraphQL
10. Finally, with the correct authentication headers in place, Enable your mutation
11. Navigate to a Workspace that contains the Template in question, and upload a file and select the same Template such that rows appear in the Workspace Sheet's "In Review" tab.
12. Fix any errors in a row, and "Approve" one row, or many rows.
13. A GraphQL mutation will now be fired for each approved row. If there is more than one insert mutation, every insert mutation will be fired sequentially for each approved row.
14. Please allow up to 30 seconds before checking that the data is now available in the destination system. Under high volume of approved rows, mutations are queued and a delay could occur before rows are eventually inserted. This is done to reduce the impact of spikes when approving many rows.
15. Viewing the "Logs" tab on a Template GraphQL Mutation Hook will show successful mutation runs or help diagnose any errors in the mutation syntax or variable names.
    Screenshot of a sample error log: