Example Queries

Summary of organisation engagements

This query will return a list of organisations, and details about the engagements for those organisations. One interesting thing to note here: if your token lacks the "engagements" permission then this will still return details about your engagements, but some fields will be redacted based on the sensitivity of the engagement.

query Engagements {
  organisations {
    engagements {
      standardObjective { name }
      beginDate
      endDate
      organisation { name }
      organisationRole
      status
      community {
        name
        language { name }
      }
      sensitivity
      internalNote
      sharedNote

      # last update by a "user"
      lastUserUpdated
      # last update by anything, including an import/automation
      lastUpdated
    }
  }
}

Outcome assessments

This query will return a list of projects and their outcomes. Each outcome will be returned with its communities (taken from its goals; the communities of archived goals are excluded).

query OutcomeProgressStatus {
  projects {
    name
    outcomes {
      name
      communities { id name }
      progressAssessments {
        month
        status
        community { id name }
      }
    }
  }
}

Goal status

This query will return a list of projects and their goals. Each goal will include a progress schema representing work in a particular community (or null for project-level goals). Each progress schema will contain a list of monthly "status" records.

If you only need the current position rather than the whole history, ask for latestProgressSchemaStatus instead of progressSchemaStatuses. It is the most recent of the same records, and is null for a schema that has never been reported.

query ProgressSchemaStatus {
  projects {
    name
    goals {
      name
      goalProgressSchemas {
        community { name }
        progressSchemaStatuses {
          month
          status
        }
        latestProgressSchemaStatus {
          month
          status
        }
      }
    }
  }
}

Project report status

This query will return a list of projects and their quarterly reports.

query ProjectReportStatus {
  projects {
    name
    status
    projectReports {
      status
      approvalDate
      approver { name }
      startDate
      endDate
    }
  }
}

Project report responses

This query demonstrates how to access structured response data from project reports using the responseValues field. This field provides unified access to both simple field values and grid data.

query ProjectReportResponses {
  projects {
    name
    projectReports {
      id
      status
      responseValues {
        name
        value
        type
        gridName
        row
      }
    }
  }
}

The responseValues array contains all field responses with: - name: The field name from the template - value: The field value (JSON-decoded) - type: Either "simple" for regular fields or "grid" for grid row data - gridName: The grid name (only for grid fields) - row: The row identifier (only for grid fields)

Organisation partners

This query will return a list of organisation partners and selected subfields for demonstration purposes. Note that some attributes of the organisation partner object are also objects with their own attributes.

query OrganisationPartners {
  organisations {
    organisationPartners {
      isChurch
      targetDepth
      partnersReach
      organisationPartnerSectors
      projectPartners {
        projectPartnerRoles {
          id
        }
      }
      status
    }
  }
}

Scripture completion data

This is a query that returns data about scripture title completion or progress. It also introduces the concept of a MangoSelector, we will explore an example of its usage here.

For scripture goals a "title group" generally refers to one book of the bible and a "title" refers to a passage of scripture within the book, which may be a chapter or any range of scripture.

Each plan-and-progress record tracks either a whole title group or a single title, never both, so exactly one of goalTitleGroup and goalTitle is set on each record. A title may carry a pericope — the scripture reference it covers, such as "John 2:1-3:31" — from which the API derives a chapters count. That count is fractional, because a pericope need not cover whole chapters: "John 2:6-4:27" counts as 2.3 chapters, being 80% of chapter 2, all of chapter 3 and 50% of chapter 4. Titles with no pericope have a null chapter count.

query Q($filter: MangoSelector) {
  projects {
    id
    name
    goals {
      # The scripture scope of the goal, in chapters: the sum over the
      # goal's titles that have a pericope. Null if none of them do.
      chapters
      goalProgressSchemas {
        community {
          id
          name
        }
        productionPlanAndProgresses(query: { selector: $filter })
        {
          goalTitleGroup {
            id
            name
          }
          goalTitle {
            id
            name
            pericope
            chapters
          }
          goalProductionStage {
            id
            standardStage {
              id
              name
            }
          }

          # The first is manually entered by a user, the
          # latter is calculated by the system. If `progress`
          # is null or zero then use `calculatedProgress`,
          # otherwise use `progress`.
          progress
          calculatedProgress
        }
      }
    }
  }
}

We need to pass a variable to $filter, we can do so in graphiql by entering it in the Variables tab. Your GraphQL client will provide their own method of passing in variables.

This is an example to specify the $filter variable in order to select only the records that track a title group, leaving out the per-title records within those groups.

{
  "filter": {
    "$not": {
      "goalTitleGroupId": null
    }
  }
}

Selecting on goalTitleId instead gives you the other half — the records reported against an individual title, which are the ones that carry a pericope.

{
  "filter": {
    "$not": {
      "goalTitleId": null
    }
  }
}

Scripture completion in chapters

Where titles have pericopes, progress can be measured in chapters rather than as a proportion of each title. chapterProgress does that for one production stage: it sums (title chapters × progress) across the goal's pericope titles, taking each title's own progress where one has been reported and falling back to the progress of its title group where one has not.

Compare it with the goal's chapters to express completion as a fraction. Both are null when the goal has no titles with pericopes.

query ChapterProgress($stage: ID!) {
  projects {
    name
    goals {
      name
      chapters
      productionStages {
        id
        standardStage { name }
      }
      goalProgressSchemas {
        community { name }
        chapterProgress(goalProductionStageId: $stage)
      }
    }
  }
}

$stage is the id of a production stage on the same goal — one of the id values returned by productionStages above.

{
  "stage": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}