Bulk-Update Roles' Metadata by Query
POST/roles/access-model-metadata/bulk-update/query
This API initiates a bulk update of metadata for one or more Roles by query. A token with ORG_ADMIN, ROLE_ADMIN ROLE_SUBADMIN authority is required to call this API. The maximum metadata value count for a single role is 25. Custom metadata update, including add, replace need suit licensed.
Request
- application/json
Body
required
Array [
]
Array [
]
query
object[]
required
query the identities to be updated
Possible values: [accessprofiles
, accountactivities
, entitlements
, events
, identities
, roles
, *
]
The names of the Elasticsearch indices in which to search. If none are provided, then all indices will be searched.
Possible values: [DSL
, SAILPOINT
, TEXT
, TYPEAHEAD
]
Default value: SAILPOINT
The type of query to use. By default, the SAILPOINT
query type is used, which requires the query
object to be defined in the request body.
To use the queryDsl
or typeAheadQuery
objects in the request, you must set the type to DSL
or TYPEAHEAD
accordingly.
Additional values may be added in the future without notice.
Default value: 5.2
The current Elasticserver version.
query
object
Query parameters used to construct an Elasticsearch query object.
The query using the Elasticsearch Query String Query syntax from the Query DSL extended by SailPoint to support Nested queries.
The fields the query will be applied to. Fields provide you with a simple way to add additional fields to search, without making the query too complicated. For example, you can use the fields to specify that you want your query of "a*" to be applied to "name", "firstName", and the "source.name". The response will include all results matching the "a*" query found in those three fields. A field's availability depends on the indices being searched. For example, if you are searching "identities", you can apply your search to the "firstName" field, but you couldn't use "firstName" with a search on "access profiles". Refer to the response schema for the respective lists of available fields.
The time zone to be applied to any range query related to dates.
innerHit
object
The innerHit query object returns a flattened list of results for the specified nested type.
The search query using the Elasticsearch Query String Query syntax from the Query DSL extended by SailPoint to support Nested queries.
The nested type to use in the inner hits query. The nested type Nested Type refers to a document "nested" within another document. For example, an identity can have nested documents for access, accounts, and apps.
The search query using the Elasticsearch Query DSL syntax.
textQuery
object
Query parameters used to construct an Elasticsearch text query object.
Words or characters that specify a particular thing to be searched for.
The fields to be searched.
Indicates that at least one of the terms must be found in the specified fields; otherwise, all terms must be found.
Indicates that the terms can be located anywhere in the specified fields; otherwise, the fields must begin with the terms.
typeAheadQuery
object
Query parameters used to construct an Elasticsearch type ahead query object. The typeAheadQuery performs a search for top values beginning with the typed values. For example, typing "Jo" results in top hits matching "Jo." Typing "Job" results in top hits matching "Job."
The type ahead query string used to construct a phrase prefix match query.
The field on which to perform the type ahead search.
The nested type.
Possible values: >= 1
and <= 1000
Default value: 10
The number of suffixes the last term will be expanded into. Influences the performance of the query and the number results returned. Valid values: 1 to 1000.
Possible values: >= 1
Default value: 100
The max amount of records the search will return.
Default value: desc
The sort order of the returned records.
The flag that defines the sort type, by count or value.
Default value: true
Indicates whether nested objects from returned search results should be included.
queryResultFilter
object
Allows the query results to be filtered by specifying a list of fields to include and/or exclude from the result documents.
The list of field names to include in the result documents.
The list of field names to exclude from the result documents.
Possible values: [DSL
, SAILPOINT
]
Default value: DSL
Enum representing the currently available query languages for aggregations, which are used to perform calculations or groupings on search results.
Additional values may be added in the future without notice.
Default value: 5.2
The current Elasticserver version.
The aggregation search query using Elasticsearch Aggregations syntax.
aggregations
object
nested
object
The nested aggregation object.
The name of the nested aggregate to be included in the result.
The type of the nested object.
metric
object
The calculation done on the results of the query
The name of the metric aggregate to be included in the result. If the metric aggregation is omitted, the resulting aggregation will be a count of the documents in the search results.
Possible values: [COUNT
, UNIQUE_COUNT
, AVG
, SUM
, MEDIAN
, MIN
, MAX
]
Default value: UNIQUE_COUNT
Enum representing the currently supported metric aggregation types. Additional values may be added in the future without notice.
The field the calculation is performed on.
Prefix the field name with '@' to reference a nested object.
filter
object
An additional filter to constrain the results of the search query.
The name of the filter aggregate to be included in the result.
Possible values: [TERM
]
Default value: TERM
Enum representing the currently supported filter aggregation types. Additional values may be added in the future without notice.
The search field to apply the filter to.
Prefix the field name with '@' to reference a nested object.
The value to filter on.
bucket
object
The bucket to group the results of the aggregation query by.
The name of the bucket aggregate to be included in the result.
Possible values: [TERMS
]
Default value: TERMS
Enum representing the currently supported bucket aggregation types. Additional values may be added in the future without notice.
The field to bucket on. Prefix the field name with '@' to reference a nested object.
Maximum number of buckets to include.
Minimum number of documents a bucket should have.
subAggregation
object
Aggregation to be performed on the result of the parent bucket aggregation.
nested
object
The nested aggregation object.
The name of the nested aggregate to be included in the result.
The type of the nested object.
metric
object
The calculation done on the results of the query
The name of the metric aggregate to be included in the result. If the metric aggregation is omitted, the resulting aggregation will be a count of the documents in the search results.
Possible values: [COUNT
, UNIQUE_COUNT
, AVG
, SUM
, MEDIAN
, MIN
, MAX
]
Default value: UNIQUE_COUNT
Enum representing the currently supported metric aggregation types. Additional values may be added in the future without notice.
The field the calculation is performed on.
Prefix the field name with '@' to reference a nested object.
filter
object
An additional filter to constrain the results of the search query.
The name of the filter aggregate to be included in the result.
Possible values: [TERM
]
Default value: TERM
Enum representing the currently supported filter aggregation types. Additional values may be added in the future without notice.
The search field to apply the filter to.
Prefix the field name with '@' to reference a nested object.
The value to filter on.
bucket
object
The bucket to group the results of the aggregation query by.
The name of the bucket aggregate to be included in the result.
Possible values: [TERMS
]
Default value: TERMS
Enum representing the currently supported bucket aggregation types. Additional values may be added in the future without notice.
The field to bucket on. Prefix the field name with '@' to reference a nested object.
Maximum number of buckets to include.
Minimum number of documents a bucket should have.
subAggregation
object
Aggregation to be performed on the result of the parent bucket aggregation.
nested
object
The nested aggregation object.
The name of the nested aggregate to be included in the result.
The type of the nested object.
metric
object
The calculation done on the results of the query
The name of the metric aggregate to be included in the result. If the metric aggregation is omitted, the resulting aggregation will be a count of the documents in the search results.
Possible values: [COUNT
, UNIQUE_COUNT
, AVG
, SUM
, MEDIAN
, MIN
, MAX
]
Default value: UNIQUE_COUNT
Enum representing the currently supported metric aggregation types. Additional values may be added in the future without notice.
The field the calculation is performed on.
Prefix the field name with '@' to reference a nested object.
filter
object
An additional filter to constrain the results of the search query.
The name of the filter aggregate to be included in the result.
Possible values: [TERM
]
Default value: TERM
Enum representing the currently supported filter aggregation types. Additional values may be added in the future without notice.
The search field to apply the filter to.
Prefix the field name with '@' to reference a nested object.
The value to filter on.
bucket
object
The bucket to group the results of the aggregation query by.
The name of the bucket aggregate to be included in the result.
Possible values: [TERMS
]
Default value: TERMS
Enum representing the currently supported bucket aggregation types. Additional values may be added in the future without notice.
The field to bucket on. Prefix the field name with '@' to reference a nested object.
Maximum number of buckets to include.
Minimum number of documents a bucket should have.
The fields to be used to sort the search results. Use + or - to specify the sort direction.
Used to begin the search window at the values specified. This parameter consists of the last values of the sorted fields in the current record set. This is used to expand the Elasticsearch limit of 10K records by shifting the 10K window to begin at this value. It is recommended that you always include the ID of the object in addition to any other fields on this parameter in order to ensure you don't get duplicate results while paging. For example, when searching for identities, if you are sorting by displayName you will also want to include ID, for example ["displayName", "id"]. If the last identity ID in the search result is 2c91808375d8e80a0175e1f88a575221 and the last displayName is "John Doe", then using that displayName and ID will start a new search after this identity. The searchAfter value will look like ["John Doe","2c91808375d8e80a0175e1f88a575221"]
filters
object
The filters to be applied for each filtered field name.
property name*
Filter
Possible values: [EXISTS
, RANGE
, TERMS
]
Enum representing the currently supported filter types. Additional values may be added in the future without notice.
range
object
The range of values to be filtered.
lower
object
The lower bound of the range.
The value of the range's endpoint.
Indicates if the endpoint is included in the range.
upper
object
The upper bound of the range.
The value of the range's endpoint.
Indicates if the endpoint is included in the range.
The terms to be filtered.
Indicates if the filter excludes results.
Possible values: [add
, remove
, replace
]
The operation to be performed
Possible values: [ALL
, ATTRIBUTE
]
The choice of update scope.
values
object[]
required
The metadata to be updated, including attribute key and value.
the key of metadata attribute
the values of attribute to be updated
Responses
- 202
- 400
- 401
- 403
- 429
- 500
Returned if bulk update request created
- application/json
- Schema
- Example (from schema)
- Update request created successfully
Schema
ID of the task which is executing the bulk update. This also used in to the bulk-update/** API to track status.
Type of the bulk update object.
Possible values: [CREATED
, PRE_PROCESS
, PRE_PROCESS_COMPLETED
, POST_PROCESS
, COMPLETED
, CHUNK_PENDING
, CHUNK_PROCESSING
]
The status of the bulk update request, could also checked by getBulkUpdateStatus API
Time when the bulk update request was created
{
"id": "2c9180867817ac4d017817c491119a20",
"type": "Role",
"status": "CREATED",
"created": "2020-10-08T18:33:52.029Z"
}
{
"id": "2d82ac17-eb0d-4ba6-9918-dcad6ee0294d",
"type": "ROLE",
"status": "CREATED",
"created": "2024-09-16T18:59:06.871594Z"
}
Client Error - Returned if the request body is invalid.
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
Array [
]
Fine-grained error code providing more detail of the error.
Unique tracking id for the error.
messages
object[]
Generic localized reason for error
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
causes
object[]
Plain-text descriptive reasons to provide additional detail to the text provided in the messages field
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
{
"detailCode": "400.1 Bad Request Content",
"trackingId": "e7eab60924f64aa284175b9fa3309599",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
],
"causes": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
]
}
Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.
- application/json
- Schema
- Example (from schema)
Schema
A message describing the error
{
"error": "JWT validation failed: JWT is expired"
}
Forbidden - Returned if the user you are running as, doesn't have access to this end-point.
- application/json
- Schema
- Example (from schema)
- 403
Schema
Array [
]
Array [
]
Fine-grained error code providing more detail of the error.
Unique tracking id for the error.
messages
object[]
Generic localized reason for error
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
causes
object[]
Plain-text descriptive reasons to provide additional detail to the text provided in the messages field
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
{
"detailCode": "400.1 Bad Request Content",
"trackingId": "e7eab60924f64aa284175b9fa3309599",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
],
"causes": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
]
}
An example of a 403 response object
{
"detailCode": "403 Forbidden",
"trackingId": "b21b1f7ce4da4d639f2c62a57171b427",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The server understood the request but refuses to authorize it."
}
]
}
Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.
- application/json
- Schema
- Example (from schema)
Schema
A message describing the error
{
"message": " Rate Limit Exceeded "
}
Internal Server Error - Returned if there is an unexpected error.
- application/json
- Schema
- Example (from schema)
- 500
Schema
Array [
]
Array [
]
Fine-grained error code providing more detail of the error.
Unique tracking id for the error.
messages
object[]
Generic localized reason for error
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
causes
object[]
Plain-text descriptive reasons to provide additional detail to the text provided in the messages field
The locale for the message text, a BCP 47 language tag.
Possible values: [DEFAULT
, REQUEST
, null
]
An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.
Actual text of the error message in the indicated locale.
{
"detailCode": "400.1 Bad Request Content",
"trackingId": "e7eab60924f64aa284175b9fa3309599",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
],
"causes": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "The request was syntactically correct but its content is semantically invalid."
}
]
}
An example of a 500 response object
{
"detailCode": "500.0 Internal Fault",
"trackingId": "b21b1f7ce4da4d639f2c62a57171b427",
"messages": [
{
"locale": "en-US",
"localeOrigin": "DEFAULT",
"text": "An internal fault occurred."
}
]
}