Skip to main content

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

Body

required

    query

    object[]

    required

    query the identities to be updated

  • Array [

  • indices Index (string)[]

    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.

    queryType QueryType (string)

    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.

    queryVersion ElasticVersion (string)

    Default value: 5.2

    The current Elasticserver version.

    query

    object

    Query parameters used to construct an Elasticsearch query object.

    query string

    The query using the Elasticsearch Query String Query syntax from the Query DSL extended by SailPoint to support Nested queries.

    fields string

    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.

    timeZone string

    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.

    query stringrequired

    The search query using the Elasticsearch Query String Query syntax from the Query DSL extended by SailPoint to support Nested queries.

    type stringrequired

    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.

    queryDsl object

    The search query using the Elasticsearch Query DSL syntax.

    textQuery

    object

    Query parameters used to construct an Elasticsearch text query object.

    terms string[]required

    Words or characters that specify a particular thing to be searched for.

    fields string[]required

    The fields to be searched.

    matchAny boolean

    Indicates that at least one of the terms must be found in the specified fields; otherwise, all terms must be found.

    contains boolean

    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."

    query stringrequired

    The type ahead query string used to construct a phrase prefix match query.

    field stringrequired

    The field on which to perform the type ahead search.

    nestedType string

    The nested type.

    maxExpansions int32

    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.

    size int32

    Possible values: >= 1

    Default value: 100

    The max amount of records the search will return.

    sort string

    Default value: desc

    The sort order of the returned records.

    sortByValue boolean

    The flag that defines the sort type, by count or value.

    includeNested boolean

    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.

    includes string[]

    The list of field names to include in the result documents.

    excludes string[]

    The list of field names to exclude from the result documents.

    aggregationType AggregationType (string)

    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.

    aggregationsVersion ElasticVersion (string)

    Default value: 5.2

    The current Elasticserver version.

    aggregationsDsl object

    The aggregation search query using Elasticsearch Aggregations syntax.

    aggregations

    object

    nested

    object

    The nested aggregation object.

    name stringrequired

    The name of the nested aggregate to be included in the result.

    type stringrequired

    The type of the nested object.

    metric

    object

    The calculation done on the results of the query

    name stringrequired

    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.

    type MetricType (string)

    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.

    field stringrequired

    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.

    name stringrequired

    The name of the filter aggregate to be included in the result.

    type SearchFilterType (string)

    Possible values: [TERM]

    Default value: TERM

    Enum representing the currently supported filter aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The search field to apply the filter to.

    Prefix the field name with '@' to reference a nested object.

    value stringrequired

    The value to filter on.

    bucket

    object

    The bucket to group the results of the aggregation query by.

    name stringrequired

    The name of the bucket aggregate to be included in the result.

    type BucketType (string)

    Possible values: [TERMS]

    Default value: TERMS

    Enum representing the currently supported bucket aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The field to bucket on. Prefix the field name with '@' to reference a nested object.

    size int32

    Maximum number of buckets to include.

    minDocCount int32

    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.

    name stringrequired

    The name of the nested aggregate to be included in the result.

    type stringrequired

    The type of the nested object.

    metric

    object

    The calculation done on the results of the query

    name stringrequired

    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.

    type MetricType (string)

    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.

    field stringrequired

    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.

    name stringrequired

    The name of the filter aggregate to be included in the result.

    type SearchFilterType (string)

    Possible values: [TERM]

    Default value: TERM

    Enum representing the currently supported filter aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The search field to apply the filter to.

    Prefix the field name with '@' to reference a nested object.

    value stringrequired

    The value to filter on.

    bucket

    object

    The bucket to group the results of the aggregation query by.

    name stringrequired

    The name of the bucket aggregate to be included in the result.

    type BucketType (string)

    Possible values: [TERMS]

    Default value: TERMS

    Enum representing the currently supported bucket aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The field to bucket on. Prefix the field name with '@' to reference a nested object.

    size int32

    Maximum number of buckets to include.

    minDocCount int32

    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.

    name stringrequired

    The name of the nested aggregate to be included in the result.

    type stringrequired

    The type of the nested object.

    metric

    object

    The calculation done on the results of the query

    name stringrequired

    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.

    type MetricType (string)

    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.

    field stringrequired

    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.

    name stringrequired

    The name of the filter aggregate to be included in the result.

    type SearchFilterType (string)

    Possible values: [TERM]

    Default value: TERM

    Enum representing the currently supported filter aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The search field to apply the filter to.

    Prefix the field name with '@' to reference a nested object.

    value stringrequired

    The value to filter on.

    bucket

    object

    The bucket to group the results of the aggregation query by.

    name stringrequired

    The name of the bucket aggregate to be included in the result.

    type BucketType (string)

    Possible values: [TERMS]

    Default value: TERMS

    Enum representing the currently supported bucket aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The field to bucket on. Prefix the field name with '@' to reference a nested object.

    size int32

    Maximum number of buckets to include.

    minDocCount int32

    Minimum number of documents a bucket should have.

    sort string[]

    The fields to be used to sort the search results. Use + or - to specify the sort direction.

    searchAfter string[]

    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

    type FilterType (string)

    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.

    value stringrequired

    The value of the range's endpoint.

    inclusive boolean

    Indicates if the endpoint is included in the range.

    upper

    object

    The upper bound of the range.

    value stringrequired

    The value of the range's endpoint.

    inclusive boolean

    Indicates if the endpoint is included in the range.

    terms string[]

    The terms to be filtered.

    exclude boolean

    Indicates if the filter excludes results.

  • ]

  • operation stringrequired

    Possible values: [add, remove, replace]

    The operation to be performed

    replaceScope string

    Possible values: [ALL, ATTRIBUTE]

    The choice of update scope.

    values

    object[]

    required

    The metadata to be updated, including attribute key and value.

  • Array [

  • attributeKey string

    the key of metadata attribute

    attributeValue string[]

    the values of attribute to be updated

  • ]

Responses

Returned if bulk update request created

Schema

    id string

    ID of the task which is executing the bulk update. This also used in to the bulk-update/** API to track status.

    type string

    Type of the bulk update object.

    status string

    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

    created date-time

    Time when the bulk update request was created

Loading...