Using GraphQL Schema

GraphQL provides a powerful query language for your APIs enabling clients to get the exact data that they need. It has the ability to get data from multiple resources in a single request by aggregating the requested data to form one result set. GraphQL provides a single endpoint for accessing data in terms of types and fields.

TIBCO Cloud Integration - Flogo (PAYG) provides an out-of-the-box GraphQL trigger which turns your Flogo app into a GraphQL server implementation. Each Flogo flow in the app acts like a GraphQL field resolver. So the output of the flow, must match the return type of the field in the schema.

TIBCO Cloud Integration - Flogo (PAYG) allows you to create GraphQL triggers by dragging and dropping your GraphQL schema file or by navigating to the file. A flow gets automatically created for every query and mutation type in your schema. You must then open the flow and define what kind of data you want the flow to return. This saves you the time and effort to programmatically define data structures on the server.

Note: This section assumes that you are familiar with GraphQL. To learn about GraphQL, refer to the GraphQL documentation.

GraphQL server implementation in TIBCO Cloud Integration - Flogo (PAYG)

To obtain samples of GraphQL schemas and app JSON files, go to https://github.com/project-flogo/graphql.

To use GraphQL in TIBCO Cloud Integration - Flogo (PAYG), you must create a GraphQL trigger. Use one of the methods below to create a GraphQL trigger.
Note: The implementation of GraphQL server in TIBCO Cloud Integration - Flogo (PAYG) currently does not return the specified field ordering in a query when a request is received. It does not affect the correctness of the response returned, but affects the readability and is non-compliant to current specification.
Note: The GraphQL schema must have either .gql or .graphql extension.

For details on the GraphQL trigger refer to the "GraphQL Trigger" section in the TIBCO Flogo® Activities and Triggers Guide.

Creating a new GraphQL trigger

To create a new GraphQL trigger, follow these steps:
  1. Open the app details page.
  2. Click Create. The Add triggers and flows dialog opens.
  3. Under Create new, select Trigger.
  4. Select the GraphQL Trigger card.
  5. Click Browse and navigate to your locally stored GraphQL schema file to upload it.
  6. Click Create. The new GraphQL trigger gets created with a placeholder for a flow attached to it.
Note: Once the trigger is created from the wizard, the trigger configuration is fixed and the Operation Field and Resolver For cannot be changed.
For more information, see the "GraphQL Trigger" section in the TIBCO Flogo® Activities and Triggers Guide.

To implement a single method in your .gql file

To implement a single method, follow these steps:
  1. In TIBCO Cloud Integration - Flogo (PAYG), open the app details page and click Create.
  2. In the Add triggers and flows dialog, click Flow under the Create new.
  3. Enter a name for the flow in the Name text box. Optionally, enter a description for the flow in the Description text box.
  4. Click Create.
  5. Select Start with a trigger.
  6. In the Triggers catalog, select the GraphQL Trigger card.
  7. Follow the on screen prompts to configure the trigger. See the section, "GraphQL Trigger", in the Activities and Triggers Guide for details on configuring the trigger. A flow with the name you specified gets created and attached to the newly created GraphQL trigger. This flow implements the method that you selected.
Tip: If required, you can later make changes to the GraphQL schema file and upload it using the GraphQL trigger without creating a new flow. For more information, see the "GraphQL Trigger" section in the TIBCO Flogo® Activities and Triggers Guide.

To implement all methods defined in your .gql file

You can create flows to implement all methods defined in your .gql file. To do so follow these steps:
  1. In the app details page, click Create. The Add triggers and flows dialog opens.
  2. Select Flow under Create new.
  3. Click GraphQL Schema under Start with.
  4. Click GraphQL Schema and upload your <name>.gql file by either dragging and dropping it to the Add triggers and flows dialog or navigating to it using the browse to upload link. TIBCO Cloud Integration - Flogo (PAYG) validates the file extension. You see a green check mark and the Upload button appears.
  5. Click Upload. TIBCO Cloud Integration - Flogo (PAYG) validates the contents of your schema and if it passes the validation, it creates the flows based on the methods defined in your schema file. One flow is created for each method in your schema. All the flows are attached the same trigger.

Manually attaching a flow to an existing GraphQL trigger in the app

If you have an existing flow in an app, you can manually attach it to a GraphQL trigger. To do so, follow these steps:
  1. Click the flow name to open the flow details page.
  2. Click the icon to the left of your flow. The existing GraphQL triggers in the app display by default.
  3. Select one of the existing GraphQL triggers and follow the on-screen directions.

Limitations on constructs in a GraphQL schema

TIBCO Cloud Integration - Flogo (PAYG) currently does not supports the following GraphQL constructs:
  • Custom scalar types
  • Custom directives
  • Subscription type
  • Cyclic dependency in schema. For example, if you have a type Book which contains an object element of type, Author. The type Author in turn contains an element of type Book which represents the books written by the author. To retreive the Author, it creates a cyclic dependency where the Author object contains the Book object and the Book type in turn contains the Author object.
Related tasks