How to perform Record Level Search?

Prerequisites

Following are the prerequisites for Record Level Search in TeamConnect:

Access Rights: Ensure you have the necessary permissions to access the records you are searching for in TeamConnect.
Authentication Token: Enter valid authentication token for accessing the endpoint.
API Endpoint: Verify the base URL for the TeamConnect API provided by your organization.

How to define Search Criteria?

The TeamConnect API typically allows you to specify search criteria such as:

Field Filters: Use field-specific filters to narrow down results (e.g., search by Name, ID, Status).
Pagination: For large datasets, use pagination parameters to retrieve a subset of results at a time.

Record Level Search refers to the process of searching for records within an object definition. This involves using fields to filter and narrow down the search results.

For more information on the fields commonly used for each object, refer to the Link. Users can search object records by specifying values and conditions. They can also combine fields using AND and OR operators to refine their searches. For more information on the conditions available for each field type, refer to the Link.

The AND operator returns results that include all specified field values according to their conditions. The OR operator retrieves results where any specified field value meets its condition.

Each field has its own search condition and field type, allowing for various criteria to refine the search.

The available field types are:

Boolean
Category
Date
RelativeDate
Enum
LookupItem
Memo
Number
String
Account
Contact
Project

The conditions for each field type can be found in Swagger.

Steps for Searching Records Using a Single Field

Follow the below steps to perform search using a Single field:

Ensure you have valid authentication and authorization.
Identify the search URL for the object definition (available in Swagger)
Choose a field and review its search criteria (also found in Swagger).
Create the search criterion for the field with an applicable condition and value (See the section on How to define Search Criteria and examples below)

You should receive search results with a status of 200 OK. Review the results to confirm that the field values align with the condition and value specified in the request body.

Example Request Body For String type field:

{
"expression": {
"criteria": [
{
"field": "name",
"condition": "NOT_EQUALS",
"value": "Angelica"
}
]
}
}

Example Request Body For Boolean type field:

{
"expression": {
"criteria": [
{
"field": "applyRightsToFiles",
"condition": "EQUALS",
"value": true
}
]
}
}

Example Request Body For Number type field:

{
"expression": {

"criteria": [
{
"field": "invoiceDate",
"condition": "NOT_BEFORE",
"value": "2024-04-03"
}
]
}
}

Example Request Body For ENUM type field:

{
"expression": {
"criteria": [
{
"field": "approvalStatus",
"condition": "NOT_EQUALS",
"value": {
       "value": "REJECTED"
       }
}
   ]
}
}

Example Request Body For Memo type field:

{
"expression": {
"criteria": [
{
"field": "note",
"condition": "IS_BLANK"
}
]
}
}

Example Request Body For OBJECT type (ACCOUNT, CONTACT, PROJECT) field:

{
"expression": {
"criteria": [
{
"field": "createdBy",
"condition": "EQUALS",
"value": {
"id": 3
}
}
]
}
}

Example Request Body For CUSTOM field:

Note: The 'field' value is a combination of the category tree position and the custom field name, separated by two underscores.

{
"expression": {
"criteria": [
{
"field": "INVC_PMPT__list",
"condition": "EQUALS",
"value": {
"treePosition": "ROOT_INDI"
}
}
]
}
}

Example Request Body For Object CATEGORY :

{
"expression": {
"criteria": [
{
"field": "primaryCategory",
"condition": "EQUALS",
"value": {
"treePosition": "DOCU_MOTI"
}
}
]
}
}

Example Request Body For Field Path :

{
"expression": {
"criteria": [
{
"field": "currency.exchangeRate",
"condition": "GREATER_THAN",
"value": "0"
}
]
}
}

Steps for Searching Records with Multiple Fields

You can perform searches for multiple fields in a single request using the “AND” and “OR” operators. Here are the instructions:

Follow the same steps as for searching with a single field.
Choose a field and review its search conditions for the field type in swagger.
Construct a valid request body for the selected fields, including appropriate conditions and values.
Specify your desired operator (AND or OR).

Here is an example:

{
"expression": {
"operator": "AND",//OR
"criteria": [
{
"field": "invoiceNumber",
"condition": "EQUALS",
"value": "Invoice50"
},
{
"field": "invoiceType",
"condition": "EQUALS",
"value": {
"value": "STANDARD"
}
}
]
}
}

Submit the request to the endpoint.
You should receive search results with a status of 200 OK. Review the results to confirm that the field values align with the conditions and values specified in the request body. Additionally, observe how the search results change when using different operators.

Steps for Searching Records using Single field with Multiple Values

You can perform searches for multiple values of a single field in a single request. Here are the instructions:

Follow the same steps as for searching with a single field.
Choose a field and review its search conditions for the field type in swagger.
Construct a valid request body for the selected fields, including appropriate conditions and values.

Note: when we search for a single field with multiple values, values are always be searched with OR condition by default.

Here is an example:

{
"expression": {
"criteria": [
{
"field": "periodEndDate",
"condition": "BETWEEN_INCLUSIVE",
"value": ["2024-05-09", "2024-07-09"]
}
]
}
}

4. Submit the request to the endpoint.

5. You should receive search results with a status of 200 OK. Review the results to confirm that the field values align with the conditions and values specified in the request body. Additionally, observe how the search results change when using different operators.

Note:

Search results for the AND operator will be displayed only when all field conditions and values match.
Search results for the OR operator will be shown when any of the field conditions and values match.
You cannot specify a single field multiple times with the same or different conditions in a single request.