Instructure Developer Documentation Portal
Community
  • Introduction
  • Services
    • Elevate Standards Alignment - AB Connect API
      • Introduction
        • Authentication
        • Addressing Object Properties
        • Requesting Additional Properties in the Response
        • Filtering Using ODATA Like Statements
        • Sorting
        • Facets
        • Paging Data
        • Call Throttling
        • Working with Related Object
        • Error Responses
        • Character Set Support
        • How To Articles, Recommendations and Suggestions
        • Examples
        • Using AB Connect's Embeddable Widgets
      • Reference
        • Standards
        • Standard Collections
        • Events
        • Topics
        • Concepts
        • Assets
        • Asset Definitions
        • Asset Collections
        • Managing and Predicting Relationships
        • Providers
    • Canvas LMS
      • Basics
        • GraphQL
        • API Change Log
        • SIS IDs
        • Pagination
        • Throttling
        • Compound Documents
        • File Uploads
        • API Endpoint Attributes
        • Masquerading
      • OAuth2
        • OAuth2 Overview
        • OAuth2 Endpoints
        • Developer Keys
      • Resources
        • Access Tokens
        • Account Calendars
        • Account Domain Lookups
        • Account Notifications
        • Account Reports
        • Accounts
        • Accounts (LTI)
        • Admins
        • Analytics
        • Announcement External Feeds
        • Announcements
        • API Token Scopes
        • Appointment Groups
        • Assignment Extensions
        • Assignment Groups
        • Assignments
        • Authentication Providers
        • Authentications Log
        • Blackout Dates
        • BlockEditorTemplate
        • Blueprint Courses
        • Bookmarks
        • Brand Configs
        • Calendar Events
        • Collaborations
        • CommMessages
        • Communication Channels
        • Conferences
        • Content Exports
        • Content Migrations
        • Content Security Policy Settings
        • Content Shares
        • Conversations
        • Course Audit log
        • Course Pace
        • Course Quiz Extensions
        • Course Reports
        • Courses
        • Custom Gradebook Columns
        • Developer Key Account Bindings
        • Developer Keys
        • Discussion Topics
        • Enrollment Terms
        • Enrollments
        • ePortfolios
        • ePub Exports
        • Error Reports
        • External Tools
        • Favorites
        • Feature Flags
        • Files
        • Grade Change Log
        • Gradebook History
        • Grading Period Sets
        • Grading Periods
        • Grading Standards
        • Group Categories
        • Groups
        • History
        • InstAccess tokens
        • JWTs
        • Late Policy
        • Learning Object Dates
        • Line Items
        • LiveAssessments
        • Logins
        • LTI Launch Definitions
        • LTI Registrations
        • LTI Resource Links
        • Media Objects
        • Moderated Grading
        • Modules
        • Names and Role
        • New Quiz Items
        • New Quizzes
        • New Quizzes Accommodations
        • New Quizzes Reports
        • Notification Preferences
        • Originality Reports
        • Outcome Groups
        • Outcome Imports
        • Outcome Results
        • Outcomes
        • Pages
        • Peer Reviews
        • Planner
        • Poll Sessions
        • PollChoices
        • Polls
        • PollSubmissions
        • Proficiency Ratings
        • Progress
        • Public JWK
        • Quiz Assignment Overrides
        • Quiz Extensions
        • Quiz IP Filters
        • Quiz Question Groups
        • Quiz Questions
        • Quiz Reports
        • Quiz Statistics
        • Quiz Submission Events
        • Quiz Submission Files
        • Quiz Submission Questions
        • Quiz Submission User List
        • Quiz Submissions
        • Quizzes
        • Result
        • Roles
        • Rubrics
        • Sandboxes
        • Score
        • Search
        • Sections
        • Services
        • Shared Brand Configs
        • SIS Import Errors
        • SIS Imports
        • SIS Integration
        • Smart Search
        • Submission Comments
        • Submissions
        • Tabs
        • Temporary Enrollment Pairings
        • User Observees
        • Users
        • What If Grades
      • Outcomes
        • Outcomes CSV Format
      • Group Categories
        • Group Categories CSV Format
      • SIS
        • SIS CSV Format
      • External Tools
        • LTI
          • Introduction
          • Registration
          • Launch Overview
          • Configuring
          • Variable Substitutions
          • Deep Linking
          • Grading
          • Provisioning
          • PostMessage
          • Platform Notification Service
          • Placements
            • Placements Overview
            • Navigation
            • Homework Submission
            • Editor Button
            • Migration Selection
            • Link Selection (Modules)
            • Assignment Selection
            • Collaborations
        • xAPI
        • Canvas Roles
        • Plagiarism Detection Platform
          • Overview
          • Plagiarism Detection Platform Assignments
          • Plagiarism Detection Platform Users
          • Plagiarism Detection Submissions
          • Webhooks Subscriptions for Plagiarism Platform
          • JWT Access Tokens
      • Data Services
        • Live Events
          • Overview
            • Introduction
            • Setup
            • Caliper
            • Metadata
          • Event Format
            • Canvas
              • Account
              • Asset
              • Assignment
              • Attachment
              • Content
              • Conversation
              • Course
              • Discussion
              • Enrollment
              • Grade
              • Group
              • Learning
              • Logged
              • Module
              • Outcome
              • Outcomes
              • Plagiarism
              • Quiz
              • Rubric
              • Sis
              • Submission
              • Syllabus
              • User
              • Wiki
            • Caliper IMS 1.1
              • Assessment
              • Basic
              • Forum
              • Grading
              • Navigation Events
              • Session
    • Catalog
      • APIs
        • Analytics
        • Bulk Enrollments
        • Catalogs
        • Certificates
        • Completed Certificates
        • Courses
        • Email Domain Set
        • Enrollments
        • Orders
        • Programs
        • Progresses
        • Tags
        • User Registrations
        • Users
        • Waitlist Applicants
    • Credentials
      • Getting Started
      • Authentication
        • Password-Based Authentication
        • Authorization Code-Based Authentication
      • Pagination
      • APIs
        • Assertions
        • Backpack
        • Badgeclasses
        • Issuers
        • Organizations
        • Users
      • Release Notes
    • Data Access Platform
      • Key Concepts
      • Data Formats
      • Rate Limits & Policies
      • Datasets
        • Namespaces
          • canvas
            • canvas types
          • canvas_logs
          • catalog
        • Additional Notes
        • Entity Relationship Diagram
      • Query API
        • Authentication
        • Reference
      • Command Line (DAP CLI)
        • Getting Started
        • Secure Connection
        • Reference
          • dap snapshot
          • dap incremental
          • dap list
          • dap schema
          • dap initdb
          • dap syncdb
          • dap dropdb
      • Client Library
        • Examples
        • Reference
      • Release Notes
      • Status
    • DataSync
      • Interop API
      • Interop Data API
      • Grades Exchange API
      • OneRoster API
      • Platform API
    • Instructure Media
      • API Reference
        • Captions
        • Collection
        • Courses
        • Group
        • Insights
        • Media
        • Media Upload
        • Ping
        • Professional Captioning
        • Tags
        • Transfer Media
        • User
    • Quizzes
      • Quiz API
Powered by GitBook

Copyright © 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.

On this page
  • Constructing the Filter Statement
  • Notes:
  • Building Complex Statements
  • Text Filters
  • Filtering a Specific Field
  • Filtering Across Multiple Text Fields
  • Filtering by Number in Standards
  • Escaping Single Quotes
  • Checking for Empty Properties

Was this helpful?

  1. Services
  2. Elevate Standards Alignment - AB Connect API
  3. Introduction

Filtering Using ODATA Like Statements

The main directive for filtering entities in AB Connect is the inclusion of the filter parameter in the URL query. This document outlines how to use filtering with AB Connect. Examples are given with different endpoints and objects but the general principles are independent of the object type or endpoint. In any case, the filter limits the results that are returned or updated by the request.

At its simplest, the filtering utilizes the following syntax:

`<endpoint URI>?filter[<object of filter>]=<URL encoded filter statement>`

E.g. the following URL retrieves alignable 5th grade math Standards from Kentucky.

`https://api.abconnect.instructure.com/rest/v4.1/standards?filter[standards]=(disciplines.subjects.code%20eq%20%27MATH%27%20and%20education_levels.grades.code%20eq%20%275%27%20and%20document.publication.authorities.descr%20eq%20%27Kentucky%20DOE%27%20and%20utilizations.type%20eq%20%27alignable%27)`

That's a bit messy so let's break it down. The first part is the primary resource endpoint.

`https://api.abconnect.instructure.com/rest/v4.1/standards`

The next bit is the filter parameter. The square brackets contain the type of object being filtered. In this case, we are limiting the Standards being returned.

`filter[standards]`

The value of the filter argument is the URL encoded filter string.

`(disciplines.subjects.code%20eq%20%27MATH%27%20and%20education_levels.grades.code%20eq%20%275%27%20and%20document.publication.authorities.descr%20eq%20%27Kentucky%20DOE%27%20and%20utilizations.type%20eq%20%27alignable%27)`

Let's decode it to make it readable:

`(disciplines.subjects.code eq 'MATH' and education_levels.grades.code eq '5' and document.publication.authorities.descr eq 'Kentucky DOE' and utilizations.type eq 'alignable')`

That makes it a little more readable and clarifies the intent. The specifics of the field names aren't critical here. See the endpoint specific documentation for an explanation of each field.

Constructing the Filter Statement

At an atomic level, the most common filter statement appears like <property> <comparator> '<value>' but some functions are also supported (e.g. isempty(<property>)).

A <property> would be any attribute of the object being filtered. Examples of a property for a Standard would be level or status. Alternatively, a property can be the attribute of a complex property. E.g. for a Standard, <property> could also be number.raw or disciplines.subjects.code.

A <value> could be any value appropriate for the property in question. Values are delimited with single quotes.

Together, various operators, properties and values combine to build a logical statements. The following operators are supported by AB Connect in order of decreasing precedence by group.

Group
Operation
Description

Grouping

( )

Precedence grouping

Primary

func()

Function call. E.g. isempty(concepts) or query('triangle pythagorean theorem') - see below for details)

Unary

not

Logical negation. E.g. not propertyX in ('a', 'b, 'c')

Comparator

eq

Equals. E.g. propertyX eq 'apple'

ne

Not equals. E.g. propertyX ne 'fruit'

gt

Greater than. E.g. propertyX gt 5

ge

Greater than or equal to. E.g. propertyX ge 5

lt

Less than. E.g. propertyX lt 5

le

Less than or equal to. E.g. propertyX le 5

in

The value of the specified property is in the supplied list of values. E.g. propertyX in ('value1', 'value2', 'value3')

Conditional

and

Combine two conditions and return true if both are true, otherwise false. E.g. propertyX eq 5 and propertyY ne 'A'

or

Combine two conditions and return true if either are true, otherwise false. E.g. propertyX eq 5 or propertyY ne 'A'

Notes:

  • Inequality operators can be used with date, number and text attributes but the results vary by attribute type. Date attributes filter chronologically. Number attributes filter numerically. Text attributes filter alphabetically.

Building Complex Statements

AB Connect also supports Boolean operations to combine atomic filter statements into complex statements. You can also use parentheses to group statements together.

  • disciplines.subjects.code eq 'MATH' and education_levels.grades.code eq '5' 5th grade math

  • document.publication.authorities.descr eq 'Kentucky DOE' and not disciplines.subjects.code eq 'MATH' Standards from Kentucky not related to math

  • (disciplines.subjects.code eq 'MATH' and education_levels.grades.code eq '5') or (disciplines.subjects.code eq 'ELA' and education_levels.grades.code eq '7') 5th grade math and 7th grade language arts Standards

Text Filters

One of the major improvements in AB Connect is the text filtering. The text filter is robust, will return results ordered by relevance and includes soft matches like partial matches. The format for text filtering is unique and utilizes a function style notation. There are two formats.

Filtering a Specific Field

When filtering a particular field, include the field name as well as the value you are filtering for: query(<field>, <string>). For example, to filter for Standards that contain the words "adding" and "fractions" in their statement, the filter would look like:

`filter[standards]=(query(statement.descr, 'adding fractions'))`

Note that the text filter is a very soft filter and will often return more Standards than you would expect. The results will be ordered by relevance so the top responses are usually the most important. For example, in the query statement above, the system would return Standards that contain the words "adding fractions" first, followed by Standards that contain "adding" or "fractions". It will also return Standards that contain "add", "addition", etc.

To be more specific, break phrases up into separate statements and be explicit about the Boolean operations to join the queries. The following will only return Standards if they contain both "fractions" and some form of derivation of the word "adding".

`filter[standards]=(query(statement.descr, 'fractions') and query(statement.descr, 'adding'))`

Filtering Across Multiple Text Fields

To retrieve Standards that have the keywords in any general text field, remove the field name from the query statement: query(<string>). E.g.

`filter[standards]=(query('adding fractions'))`

When using this approach, the system will search any fields it considers to be a text field. The specific fields vary by endpoint:

  • Standards:

    • statement.descr

    • statement.combined_descr

    • statement.addendums.descr

    • extensions.descr

    • legends.descr

  • Assets:

    • title

    • Any custom attributes

  • Topics:

    • descr

    • section.descr

  • Concepts:

    • descr

    • context

Filtering by Number in Standards

In Standards documents, numbers are often separated, delimited or decorated with symbols (e.g. "24.B (i)"). Trying to ensure users are typing the numbers EXACTLY as they are entered in the Standards document is difficult. For this reason, AB Connect supports a soft match on the Standards' number.raw, number.enhanced, number.prefix_enhanced and number.root_enhanced fields when the query function is used. It treats any separator between alphanumeric values as a break between numbers and looks for Standards that match numbers returning results by how closely they match the results. In the example listed earlier, it will return Standards that have numbers that contain 24, B AND i first without regards to the separators used in the filter. It will follow that with Standards that contain two of the three, then Standards that contain any one of the numbers. Filtering for "24.B.i" will return the same results in the same order as filtering for "24-b-i" and "24.B (i)".

Escaping Single Quotes

In ODATA, literal strings are quoted using single quotes ('). To include a single quote in a string literal in the filter, use a backslash to escape it ('). For example, to search for the word "don't" in Standards, you would use the following filter:

`filter[standards]=(query('don\'t'))`

Checking for Empty Properties

Sometimes it is handy to search for properties that are empty. What "empty" means depends on the property type so AB Connect has an isempty function that will match true on objects with no properties, arrays with no elements and scalar properties with null values. For example, the following filter will return all assets that are missing a subject.

`filter[assets]=isempty(disciplines.subjects)`
PreviousRequesting Additional Properties in the ResponseNextSorting

Last updated 10 months ago

Was this helpful?

Custom attributes can be defined as text or numbers. If you aren't sure of the types for your custom attributes, contact for guidance.

It is possible to create custom attributes with the same name and different data types in different asset types (or when searching across multiple owners). The treatment of inequalities filtering across multiple data types is deterministic but relatively complex and isn't covered here. Where possible, we recommend you avoid this situation by ensuring your custom attributes don't have name conflicts across data types where possible. For details on the way AB Connect handles filtering across mixed types, contact .

Text properties on related entities as described in

Text properties on related entities as described in

AB Support
AB Support
Filtering Resources by Properties on Related Resources
Filtering Resources by Properties on Related Resources