This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Retrieving Tenant Resources Based on Search Parameters
- Former user (Deleted)
- divyaa (Unlicensed)
This section guides you through using the /search endpoint of the Configuration Management REST API to search for tenant resources.
See the sections below for instructions:
/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 Writing a configuration management search query.
Writing 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} place holder:
| 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} place holder:
| 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}
Note
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} place holder:
| Complex condition operator | Value to replace {COMPLEX_CONDITION_OPERATOR} |
|---|---|
| AND | and |
| OR | or |
Note
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} with the relevant values.
Reference | Super tenant: https://{host}:{port}/api/identity/config-mgt/v1.0/search?$filter={search-query}
Tenant: https://{host}:{port}/t/{tenant-domain}/api/identity/config-mgt/v1.0/search?$filter={search-query}
|
|---|---|
Sample GET request for the super tenant | https://localhost:9443/t/carbon.super/api/identity/config-mgt/v1.0/search?$filter=tenantDomain eq ‘carbon.super’ |
Sample CURL command for a tenant | curl -k -v --user admin:admin GET 'https://localhost:9443/api/identity/config-mgt/v1.0/search?$filter=%28tenantDomain%20eq%20%27carbon.super%27%29' |
Assume you have the following resources in your database.
| Name | Resource JSON |
|---|---|
| resource_1 | {
"name": "resource_1",
"attributes": [
{
"key": "from",
"value": "abc.com"
},
{
"key": "to",
"value": "123.com"
}
]
}
|
| resource_2 | {
"name": "resource_2",
"attributes": [
{
"key": "from",
"value": "abc.com"
},
{
"key": "to",
"value": "wso2.com"
}
]
}
|
| resource_3 | {
"name": "resource_3",
"attributes": [
{
"key": "from",
"value": "xyz.com"
},
{
"key": "to",
"value": "wso2.com"
}
]
}
|
| resource_4 | {
"name": "resource_4",
"attributes": [
{
"key": "to",
"value": "wso2.com"
},
{
"key": "server",
"value": "smtp.com"
}
]
}
|
There are two approaches to search or filter the resources in your database:
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' |
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')) |
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-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:
{search-query} | Response JSON |
|---|---|
attributeKey eq 'from' |
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''
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')