Skip to main content

Writing GraphQL Queries

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

Preparing Input Values for Testing Policy Code Locally​

Semi-Automated Input Data Generation Using shishoctl testcase generate Command​

The shishoctl testcase generate command allows you to generate a JSON file that defines the input data for the policy code from a GraphQL query.

Here is an example of a command that generates JSON-formatted test data from a GraphQL query, which can be used as input for the jobs[].decide.rego policy:

shishoctl testcase generate \
  --type decision \
  --org <YOUR_ORGANIZATION_ID> \
  --query-path (Path to the file storing the GraphQL query)

When using the shishoctl testcase generate command as shown above, the shishoctl command adjusts the format of the generated JSON based on options such as --type. In most cases, using the shishoctl testcase generate command will be more convenient than copying and pasting the data returned from the GraphQL query's test playground.

Manual Creation of Input Data Using the GraphQL Query Test Playground​

The JSON output from testing a GraphQL query in the Playground includes the result of the GraphQL query's execution under the data field, as shown in the example below:

{
  "data": {
    "github": {
      ...
    }
  }
}

By appropriately manipulating the data above, you can prepare input values for the policy code.

However, as described in API definitions for Rego inline policies, how the execution results of a GraphQL query are provided to the policy code varies depending on the policy language in use and the usage context of the policy (for example, under jobs[].decide or jobs[].notify). Therefore, in the following sections, we will show various situations and how to manually create input data for policies in those situations.

Example: For a Rego Policy Specified in jobs[].decide.rego​

For Rego inline policies specified in this field, the execution result of the GraphQL query is assumed to be stored in the input variable. Therefore, when supplying a value to the input variable with commands like opa eval -i input.json ..., you should follow these steps:

  1. Save only the value of the data field from the JSON returned by the Playground into a JSON file (for example, input.json).
  2. Evaluate the policy using a command like opa eval -i input.json ..., specifying the JSON file saved in the preceding step as the value for the input variable.

Below is an example of the JSON file saved in step 1:

{
  "github": {
    ...
  }
}

Example: jobs[].notify.rego​

For Rego inline policies specified in this field, the execution results of the GraphQL query are assumed to be stored in the input.query variable. Therefore, when supplying a value to the input variable with commands like opa eval -i input.json ..., you should follow these steps:

  1. Replace the field name of the data field in the JSON data returned by the Playground with query and save it to a JSON file (for example, input.json).
  2. Evaluate the policy using a command like opa eval -i input.json ..., specifying the JSON file saved in the preceding step as the value for the input variable.

Below is an example of the JSON file saved in step 1:

{
  "query": {
    "github": {
      ...
    }
  }
}

Values Returned from GraphQL Query Test Playground Do Not Match Those on the Linked External Service​

The values returned in the Playground are not actual data retrieved from the external service linked to your Shisho Cloud organization but are randomly generated test data. Even though the data is random, it is designed to be as close as possible to the actual data given to the policy.

info

If you encounter unusual values or have questions about the generated values, please contact the service provider, Flatt Security.

Last updated on