Print this page
In this topic
You can perform the following operation with the Ringtail Connect API:
●Query: Requests data from Ringtail.
●Mutation: Modifies data in 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.
To modify data in Ringtail, you perform a mutation.
To structure a mutation, you must specify the following information:
●Mutation name: The type of modification you want to perform.
●Input fields: The data that you want to send to the server. You pass the input fields as an argument to the mutation name. In the reference documentation, an exclamation mark (!) indicates that a field is required in an argument.
●Payload fields: The data that you want to return from the server. You pass the payload fields in the body of the mutation name.
Mutations have the following structure:
mutation {
mutationName(input argument key: {input fields for the mutation!}) {
payload fields for the mutation
}
If a mutation returns an object type as part of the payload, you can ask for nested fields of that object. This can be useful to determine information about an object after you update the object. For example, when you create a new annotation, you can return the new annotation's ID as part of the mutation.
Sometimes, mutations require you to pass information that you cannot figure out without running a query. For example, to add an annotation to a document, you must provide the annotation type ID as an argument in the mutation. You can run a query first to determine the required information, and then perform a mutation using the data that was returned in the query.
Optionally, you can include a unique name for each mutation, such as mutation yourMutationName { }.
Note: GraphQL syntax is case-sensitive.
This example illustrates how to structure a mutation.
Caution: When you modify data through the API explorer, you change the data in Ringtail. We recommend that you test any mutations in a non-production environment or using non-production data.
The following mutation adds an annotation to a page in a document.
mutation {
addAnnotation(caseId: 6077, input: {
mainId: 22,
pageId: 68987,
pageNumber: 1,
annotationTypeId: "10068-31",
x1: 120,
x2: 499,
y1: 960,
y2: 1322,
color: BLACK,
referenceId: "abc"
}) {
totalCount
successCount
successItems {
referenceId
annotationId
}
errorCount
erroredItems {
referenceId
error
}
}
}
To understand how the mutation is structured, look at the mutation line-by-line:
●mutation {
To modify data in Ringtail, use the mutation operation.
●addAnnotation(caseId: 6077, input: {mainId: 22, pageId: 68987, pageNumber: 1, annotationTypeId: "10068-31", x1: 120, x2: 499, y1: 960, y2: 1322, color: BLACK, referenceId: "abc"})
oaddAnnotation is the name of the mutation.
ocaseId is the input argument key that identifies the case. The argument value, 6077, indicates the ID of the case to make the annotation in.
oinput is the input argument key that identifies the annotation. The argument value, {mainId: 22, pageId: 68987, pageNumber: 1, annotationTypeId: "10068-31", x1: 120, x2: 499, y1: 960, y2: 1322, color: BLACK, referenceId: "abc"}, defines the annotation.
In this mutation, the fields for the input argument key are an object, so you enclose them in curly braces.
oIn the reference documentation, an exclamation mark (!) indicates that a field is required in an argument. The caseId, mainId, pageId, and annotationTypeId fields are all required.
For information about how to access the reference documentation, see Reference documentation.
ocolor is an enumeration type, also called an enum. An enum is a scalar that is restricted to a predefined set of values, which are defined in the schema. You can refer to the reference documentation to determine the values that are permitted for each enum.
oannotationTypeId identifies the type of annotation. To determine the IDs of the annotation types that are available in a case, you can run a query before you perform the mutation:
query {
cases(id: 6077) {
annotationTypes {
id
name
}
}
}
●The schema indicates that the addAnnotation mutation has the AnnotationInsertResults object type. You can refer to the reference documentation for the AnnotationInsertResults object to determine which payload fields you want to request:
{
totalCount
successCount
successItems {
referenceId
annotationId
}
errorCount
erroredItems {
referenceId
error
}
}
ototalCount, successCount, and errorCount are optional fields.
osuccessItems and erroredItems are optional objects. You can refer to the reference documentation to determine the fields that you can request for these objects.
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
}
}
