Skip to navigation
Extension app referenceExtension contractsData IO

Custom query language reference

View as Markdown

To implement the DataIO.Version6.SearchRecords action, you must translate a query expression from the Docusign custom query language into one supported by your external system. Docusign established this custom language in order to maintain flexibility without depending on any specific external system. This reference page shows how the query objects are structured.

You can also see an Example of how to use build a query using these objects.

Note that each object contains a $class property that identifies its type. This enables your API proxy to recognize the object type and transform it to the associated type in a different query language.

Reference

IQuery object

The IQuery object represents a query of the external system. The query:

  • Selects the properties specified by attributesToSelect...
  • From the table specified by the from property...
  • And then filters the records based on the queryFilter
PropertyTypeDescription
$classstringIdentifies the object as a query. Will always be:

com.docusign.connected.data.queries@1.0.0.Query
attributesToSelectstring[]The list of attributes to select from the table to query. These values correspond to the attributes returned by the GetTypeDefinitions action.
fromstringRepresents the table to query in the external system. This name corresponds to a record type returned by the GetTypeNames action.
queryFilterIQueryFilterThe filter conditions to apply.

IQueryFilter object

The IQueryFilter object wraps a comparison operation or logical operation.

PropertyTypeDescription
$classstringIdentifies the object as a query filter. Will always be:

com.docusign.connected.data.queries@1.0.0.QueryFilter
operationIComparisonOperation or ILogicalOperationThe operation to filter on

IComparisonOperation object

Compares a value from the data table to a constant.

PropertyTypeDescription
$classstringIdentifies the object as a comparison filter. Will always be:
com.docusign.connected.data.queries@1.0.0.ComparisonOperation
leftOperandIOperandRepresents an operand in the comparison operation. The left operand always refers to an attribute, not a literal.
operatorstringThe comparison operator. Possible values:
  • EQUALS
  • NOT_EQUALS
  • CONTAINS
  • DOES_NOT_CONTAIN
  • LESS_THAN
  • GREATER_THAN
  • LESS_THAN_OR_EQUALS_TO
  • GREATER_THAN_OR_EQUALS_TO
  • STARTS_WITH
  • DOES_NOT_START_WITH
  • ENDS_WITH
  • DOES_NOT_END_WITH
  • IN
  • NOT_IN
  • BETWEEN
  • LIKE
  • CUSTOM
Note: Although the data IO extension supports the operator values listed here, Workflow Builder allows workflow process builders to select only Equal to as the operator.
rightOperandIOperandRepresents an operand in the comparison operation. The right operand always represents a literal.

IOperand object

This object represents an operand to use in a comparison. It can either be a value selected from the table in the external system of record, or a literal value.

PropertyTypeDescription
$classstringIdentifies the object as a comparison operand. Will always be:

com.docusign.connected.data.queries@1.0.0.Operand
namestringRepresents the operand.

If isLiteral is false, this property refers to an attribute of the selected type in the external system of record. If isLiteral is true, this property is a literal value.
typestringThe type of the operand. Possible values:
  • STRING
  • INTEGER
  • DOUBLE
  • LONG
  • DATETIME
  • BOOLEAN
  • ENUM
  • LIST
  • RANGE
  • OTHER
isLiteralbooleanIs true if the operand is a literal value, false if the operand is a value selected from the table.

ILogicalOperation object

This object combines two operations in a logical AND/OR statement. Each suboperation is an IComparisonOperation or ILogicalOperation.

PropertyTypeDescription
$classstringIdentifies the object as a logical operation. Will always be:

com.docusign.connected.data.queries@1.0.0.LogicalOperation
leftOperationIComparisonOperation or ILogicalOperationThe left side of the logical operation.
operatorstringThe logical operator. Possible values:
  • AND
  • OR
isLiteralIComparisonOperation or ILogicalOperationThe right side of the logical operation.

Example

To understand the schema, construct a query to select all Dog records for which the dog is 8 or older and the dog’s name starts with “Francis”. (To implement the search action, you’ll need to perform the opposite transformation: from IQuery to your own system’s query language. But this is a useful exercise for understanding.)

Start by setting the root values. The external service has a table for all Dog objects. The Dog type has properties age and animalName, which you will use in your query. So the root of the query object will look like this:

{
    "$class": "com.docusign.connected.data.queries@1.0.0.Query",
    "attributesToSelect": ["age", "animalName"],
    "from": "Dog",
    "queryFilter": { ... }
}

Now construct the queryFilter. The base operation is a logical AND statement, because you want records for which the dog’s age is greater than or equal to 8 AND the dog’s name starts with “Francis”. Represent this by setting the operation parameter to a ILogicalOperation object.

{
    "$class": "com.docusign.connected.data.queries@1.0.0.Query",
    "attributesToSelect": ["age", "animalName"],
    "from": "Dog",
    "queryFilter": {
        "$class": "com.docusign.connected.data.queries@1.0.0.QueryFilter",
        "operation": {
            "$class": "com.docusign.connected.data.queries@LogicalOperation",
            "leftOperation": { // check dog age },
            "operator": "AND",
            "rightOperation": { // check dog name}
        }
    }
}

Next, write the leftOperation to check the dog’s age. This is a comparison, so use an IComparisonOperation object.

The first operand is an IOperand object representing the dog’s age. Remember that the query will select that value from the table. Indicate the name with the dogName value from the attributesToSelect list. Set type to whatever the data type is in the table. Finally, set isLiteral to false, because this is not a constant value.

For the operator, refer to the possible values in the IComparisonOperation schema. You want to check if the dog’s age is greater than or equal to 8, so use the GREATER_THAN_OR_EQUALS_TO value.

The second operand is a constant value of 8. Set the value in the name field, and set isLiteral to true, because it’s a constant.

{
    "$class": "com.docusign.connected.data.queries@1.0.0.Query",
    "attributesToSelect": ["age", "animalName"],
    "from": "Dog",
    "queryFilter": {
        "$class": "com.docusign.connected.data.queries@1.0.0.QueryFilter",
        "operation": {
            "$class": "com.docusign.connected.data.queries@LogicalOperation",
            "leftOperation": {
                "$class": "com.docusign.connected.data.queries@1.0.0.ComparisonOperation",
                "leftOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "age",
                    "type": "INTEGER",
                    "isLiteral": false
                },
                "operator": "GREATER_THAN_OR_EQUALS_TO",
                "rightOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "8",
                    "type": "INTEGER",
                    "isLiteral": true
                }
            },
            "operator": "AND",
            "rightOperation": { // check dog name}
        }
    }
}

Finally, construct the rightOperation. Again, this is a comparison, so use an IComparisonOperation object. The only difference from the leftOperation is that you are using a string, not an integer, and using the STARTS_WITH operator. This is the final JSON:

Your completed query construction should look like the following:

{
    "$class": "com.docusign.connected.data.queries@1.0.0.Query",
    "attributesToSelect": ["age", "animalName"],
    "from": "Dog",
    "queryFilter": {
        "$class": "com.docusign.connected.data.queries@1.0.0.QueryFilter",
        "operation": {
            "$class": "com.docusign.connected.data.queries@LogicalOperation",
            "leftOperation": {
                "$class": "com.docusign.connected.data.queries@1.0.0.ComparisonOperation",
                "leftOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "age",
                    "type": "INTEGER",
                    "isLiteral": false
                },
                "operator": "GREATER_THAN_OR_EQUALS_TO",
                "rightOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "8",
                    "type": "INTEGER",
                    "isLiteral": true
                }
            },
            "operator": "AND",
            "rightOperation": {
                "$class": "com.docusign.connected.data.queries@1.0.0.ComparisonOperation",
                "leftOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "animalName",
                    "type": "STRING",
                    "isLiteral": false
                },
                "operator": "STARTS_WITH",
                "rightOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "Francis",
                    "type": "STRING",
                    "isLiteral": true
                }
            }
        }
    }
}

Next steps