Retrieve Tenant Resources Based on Search Parameters¶
This section guides you through using the /search
endpoint of the Configuration Management REST
API to search for
tenant resources.
/search endpoint¶
The /search endpoint of the Configuration Management
REST API allows you to perform cross-tenant search for resources.
The search context URL should be as follows:
https://{host}:{port}/t/{tenant-domain}/api/identity/config-mgt/v1.0/search?$filter={search-query}
Here, the value of {search-query} should be in the
form of a configuration management search query. For information on how
to write a search condition that is in the form of a configuration
management search query, see Write a configuration management search
query.
Write a configuration management search query¶
Configuration management search query is a Open Data Protocol based search query supported via Apache CXF.
The configuration management search query is a search condition that is built using primitive configuration management search conditions in the form of a string. The following topics describe the configuration management search conditions that you can use to write a configuration management search query.
Configuration management primitive search condition¶
A primitive search condition is a string in the following form:
{RESOURCE_SEARCH_PARAMETER} {PRIMITIVE_CONDITION_OPERATOR} '{VALUE}'
Following are the parameters of a resource supported in a primitive
search condition and the corresponding values to replace the
{RESOURCE_SEARCH_PARAMETER} placeholder :
| Resource parameter | Value to replace {RESOURCE_SEARCH_PARAMETER} |
|---|---|
| Tenant domain | tenantDomain |
| ID value of the resource type | resourceTypeId |
| Name of the resource type | resourceTypeName |
| ID value of the resource | resourceId |
| Name of the resource | resourceName |
| A key of the attribute | attributeKey |
| Value of the attribute | attributeValue |
Following are the operators supported in a primitive condition and the
corresponding values to replace the
{PRIMITIVE_CONDITION_OPERATOR} placeholder :
| Primitive condition operator | Value to replace {PRIMITIVE_CONDITION_OPERATOR} |
|---|---|
| Equal | eq |
| Not equal | ne |
| Less than | lt |
| Less or equal | le |
| Greater than | gt |
| Greater or equal | ge |
Configuration management complex search condition¶
A complex search condition is generally built by combining primitive search conditions. The simplest form of a complex search condition string is as follows:
{PRIMITIVE_SEARCH_CONDITION_1} {COMPLEX_CONDITION_OPERATOR} {PRIMITIVE_SEARCH_CONDITION_2}
Two complex search condition created as mentioned above can also be joined as follows to form another complex search condition:
{COMPLEX_SEARCH_CONDITION_1} {COMPLEX_CONDITION_OPERATOR} {COMPLEX_SEARCH_CONDITION_2}
Tip
For better readability, it is recommended to use parentheses to group
complex search conditions when you join conditions using a
COMPLEX_CONDITION_OPERATOR.
Following are the operators supported to build a complex search
condition and the corresponding values to replace the
{COMPLEX_CONDITION_OPERATOR} placeholder :
| Complex condition operator | Value to replace {COMPLEX_CONDITION_OPERATOR} |
|---|---|
| AND | and |
| OR | or |
Info
When you join complex search conditions together with complex condition operators, the result is always another complex condition. Therefore, any required search condition can be built as a configuration management complex search condition in this manner.
Search scenarios¶
This section demonstrates the different ways of searching for resources (i.e. different search scenarios). In the scenarios given below, an HTTP GET request is sent to the following location with the {search-query} placeholder value replaced accordingly and encoded for a URL. When you are trying out these scenarios, fill the {host}, {port} and the {tenant-domain} placeholders with the relevant values.
Reference |
|
Sample GET request for the super tenant |
|
Sample CURL command for a tenant |
Assume you have the following resources in your database.
| Name | Resource JSON |
|---|---|
| resource_1 | |
| resource_2 | |
| resource_3 | |
| resource_4 |
There are two approaches to search or filter the resources in your database:
- Meta-data based search
- Attribute-based search
Meta-data based search¶
Use the following meta-data parameters to search for resources.
| Search Parameter of the Resource | {RESOURCE_SEARCH_PARAMETER} |
|---|---|
| Tenant domain | tenantDomain |
| ID value of the resource type | resourceTypeId |
| Name of the resource type | resourceTypeName |
| ID value of the resource | resourceId |
| Name of the resource | resourceName |
Search for resources in a specific tenant domain
The table below shows a sample search query that is used to search for resources that are created in the super tenant domain.
{search-query} |
Response JSON |
|---|---|
tenantDomain eq 'carbon.super' |
click to see the sample response
|
Search for resources in a specific tenant domain using the resource
name
The table below shows a sample search query that is used to search for resources named "resource_1" and "resource_2" in the super tenant domain using the resource name.
{search-query} |
Response JSON |
|---|---|
(tenantDomain eq 'carbon.super') and ((resourceName eq 'resource_1') or (resourceName eq 'resource_2')) |
Click to see the sample response.
|
Attribute-based search¶
There are two parameters in any attribute; a key, and a value. The search queries given below are used to search for a resource using a combination of its attribute parameters.
Note
The configuration management search query does not support a resource search parameter that has multiple primitive search conditions joined by the complex operator ‘and’. For more information, see the section below.
Search for resources using an attribute key, value pair
The table below shows a sample search query used to search for a resource with an attribute, where the key is equal to "from" and the value is equal to "abc.com".
{search-query} |
Response JSON |
|---|---|
(attributeKey eq 'from') and (attributeValue eq ' abc.com ') |
|
Note
Although both resource_1 and
resource_2 have another attribute where the key
is equal to "to", the returned search response only contains the
requested attribute "from". To retrieve all available attributes for a
resource using search, you need to search for the resource using the
resource ID as given below.
For example, to retrieve resource_1 using the resource ID, use the
following search query:
Click to see the search query
| {search-query} | Response JSON |
|---|---|
| resourceId eq 'c9b8913f-3ae4-43f5-9552-a8676fd19646' | Click to see the sample response.
|
Search for resources using an attribute key
The table below shows a sample search query used to search for a resource with an attribute where the key is equal to "from". In this case, the value for the attribute can be any value.
{search-query} |
Response JSON |
|---|---|
attributeKey eq 'from' |
Click to see the sample response
|
Search for resources with multiple attributes using the keys
The table below shows a sample search query for a resource that satisfies the following conditions:
-
Has an Attribute where the key is equal to “from”.
-
Has an Attribute where the key is equal to “to”.
Note
Building the configuration management search query for this
scenario will create the following search query:
attributeKey eq 'from' and attributeKey eq 'to'.
However, the Search API does not allow multiple search conditions joined by the 'and' complex operator for the same Resource search parameter. Therefore, this requirement cannot be achieved using a single search and has to be done in two steps. See the instructions given below for sample search queries.
-
Retrieve all the resources with an attribute where the key is equal to "from".
{search-query}
Response JSON
attributeKey eq
'from''
Click to see the sample response.
{ "resources": [ { "resourceId": "29bd5f2d-54b4-4169-8cac-aa2e9cf5c1ba", "tenantDomain": "carbon.super", "resourceName": "resource_2", "resourceType": "e-mail", "lastModified": "2019-01-14 03:16:59", "files": [], "attributes": [ { "key": "from", "value": "abc.com", "attributeId": "aea8665f-d6d7-4ec3-9449-b6423ed9fddf" } ], "hasFile": false, "hasAttribute": false }, { "resourceId": "c9b8913f-3ae4-43f5-9552-a8676fd19646", "tenantDomain": "carbon.super", "resourceName": "resource_1", "resourceType": "e-mail", "lastModified": "2019-01-14 03:16:48", "files": [], "attributes": [ { "key": "from", "value": "abc.com", "attributeId": "28092ab2-594f-421f-8c7e-9e8d4fbe1a5c" } ], "hasFile": false, "hasAttribute": false }, { "resourceId": "7982a6e0-512a-4ebe-8c14-16f1819967c9", "tenantDomain": "carbon.super", "resourceName": "resource_3", "resourceType": "e-mail", "lastModified": "2019-01-14 03:26:47", "files": [], "attributes": [ { "key": "from", "value": "xyz.com", "attributeId": "589f8423-bf57-4906-bf34-2d821358ed13" } ], "hasFile": false, "hasAttribute": false } ] } -
Search within the results received above for resources with an attribute where the key is equal to "to". This will retrieve search results that satisfies both conditions (i.e. resources with an attribute where the key is equal to "from" and an attribute where the key is equal to "to").
{search-query}
Response JSON
attributeKey eq 'to' and (resourceId eq '29bd5f2d-54b4-4169-8cac-aa2e9cf5c1ba' or resourceId eq 'c9b8913f-3ae4-43f5-9552-a8676fd19646' or resourceId eq '7982a6e0-512a-4ebe-8c14-16f1819967c9')
Click to see the sample response.
{ "resources": [ { "resourceId": "29bd5f2d-54b4-4169-8cac-aa2e9cf5c1ba", "tenantDomain": "carbon.super", "resourceName": "resource_2", "resourceType": "e-mail", "lastModified": "2019-01-14 03:16:59", "files": [], "attributes": [ { "key": "to", "value": "wso2.com", "attributeId": "22f4f25a-3f79-4db3-b805-e53946110fa8" } ], "hasFile": false, "hasAttribute": false }, { "resourceId": "c9b8913f-3ae4-43f5-9552-a8676fd19646", "tenantDomain": "carbon.super", "resourceName": "resource_1", "resourceType": "e-mail", "lastModified": "2019-01-14 03:16:48", "files": [], "attributes": [ { "key": "to", "value": "123.com", "attributeId": "3633269a-cab9-4e14-a264-dddb1a6001ed" } ], "hasFile": false, "hasAttribute": false }, { "resourceId": "7982a6e0-512a-4ebe-8c14-16f1819967c9", "tenantDomain": "carbon.super", "resourceName": "resource_3", "resourceType": "e-mail", "lastModified": "2019-01-14 03:26:47", "files": [], "attributes": [ { "key": "to", "value": "wso2.com", "attributeId": "ffe5acee-d59f-4918-9bfb-85c282490691" } ], "hasFile": false, "hasAttribute": false } ] }