Print this page
In this topic
You can perform the following operation with the Ringtail Connect API:
●Query: Requests data from Ringtail.
A GraphQL operation returns data as a JSON object. The structure of a response mirrors the structure of an operation.
For information about JSON notation, see http://www.json.org/.
To request data from Ringtail, you perform a query.
A GraphQL query returns only the data that you specify in the query. To structure a query, you specify the objects and fields that you want to return. You must nest fields within a query until all fields return scalars. A scalar is concrete data, such as the name of a user.
Queries have the following structure:
query {
JSON objects to return
}
Optionally, you can include a unique name for each query, such as query yourQueryName { }.
Note: GraphQL syntax is case-sensitive.
This example illustrates how to structure a query. You can work through the example yourself using the API explorer. For information about how to access the API explorer, see Access and use the Ringtail Connect API Explorer.
The following query looks up the Clean_Enron case, and returns a list of users with their email addresses and portal user categories.
query {
cases(name: "Clean_Enron") {
name
users {
fullName
email
portalCategory
}
}
}
To understand how the query is structured, look at the query line-by-line:
●query {
To request data from Ringtail, use the query operation.
Note: If you do not specify an operation, query is the default operation.
●cases(name: "Clean_Enron") {
To start the query, request the cases object.
In the reference documentation, an exclamation mark (!) indicates that a field is required in an argument. Schema validation indicates that no arguments are required. Because an optional name argument is accepted, you can include the case name to pre-filter the results based on case name.
For information about how to access the reference documentation, see Reference documentation.
●users {
To return all of the users in the case, request the users object.
●The schema indicates that the users object has the Users object type. You can refer to the reference documentation for the Users object to determine which fields you want to request.
{
fullName
email
portalCategory
}
In this example, you request the fullName, email, and portalCategory fields of the Users object.
Variables allow you to represent the values in an argument with dynamic placeholders instead of static data values. This allows you to update the values that are passed in an operation without having to modify the operation itself.
To use a variable, do the following:
1.Define the variable outside of the operation. Do either of the following:
oIn the Ringtail Connect API Explorer, type the variable in the Query Variables pane. For more information about the API explorer, see Access and use the Ringtail Connect API Explorer.
oIn a third-party application, create a variables object.
Variables have the following structure:
{
"variableName": value
}
The variable must be valid JSON syntax.
2.Pass the variable as an argument to the operation:
query($variableName: variableType) {
JSON objects to return
}
You must define both the variable name and the variable type, such as String or Int. For more information about types, see API terminology.
3.Replace the static value in an argument with the variable:
object(argumentKey: $variableName) {
JSON fields to return
}
This example illustrates how to structure a query that includes variables. You can work through the example yourself using the API explorer. For information about how to access the API explorer, see Access and use the Ringtail Connect API Explorer.
The following variable definitions act as placeholders for a user's first and last name.
{
"first_name_of_user": "John",
"last_name_of_user": "Smith"
}
The following query passes the variables, and then returns information about the user whose values you specified in the variable definition.
query ($first_name_of_user: String, $last_name_of_user: String) {
users(firstName: $first_name_of_user, lastName: $last_name_of_user) {
fullName
userName
email
lastLogin
}
}