--- schema_version: "1" id: 8f9d9680a76467de322c459c99af4c05d7a22a7e762cc1911fbd67a37f133f20 title: Data Roles (deprecated) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-roles.md canonical_url: https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-roles source_site: developer.salesforce.com content_type: documentation content_hash: e9753e8320f3519daca95aab6e15c5fb2eb39ddffefee7b02cc4498bdad8b6ce products: - B2C Commerce - Salesforce APIs --- Data Roles (deprecated) # Data Roles (deprecated) Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage. **Version:** 25.6 ## Servers * `https://{host}/s/-/dw/data/v25_6` Protocols: https. ## Security * `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager. * OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token) * Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required. * `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter. * API key in header: x-dw-client-id ## Operations ### GET Get public Access Roles `GET /roles` Operation ID: `Get public Access Roles`. Tags: roles. Security: oauth2\_application. Action to get all the access roles with no filtering. #### Parameters * `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0). * `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25). * `select` (query, string) The property selector. * `expand` (query, array of string) List of expansions. #### Responses * **default** Media type: `application/json, text/xml`. Schema: `roles`. ### GET Get Access Role `GET /roles/{id}` Operation ID: `Get Access Role`. Tags: roles. Security: oauth2\_application. Action to get a single access role. This endpoint may return the following faults: * 404 - RoleNotFoundException - Thrown if the access role with the given id does not exist. #### Parameters * `id` (path, string, required) The id of the requested access role. Minimum length: 1. * `expand` (query, array of string) The list of expansions. #### Responses * **404** `RoleNotFoundException` - Thrown if the access role with the given id does not exist. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `role`. ### PUT Create Access Role `PUT /roles/{id}` Operation ID: `Create Access Role`. Tags: roles. Security: oauth2\_application. Action to create an access role. This endpoint may return the following faults: * 400 - IdConflictException - Thrown when id in query parameter is different from the id in the body. * 403 - RoleOperationNotAllowedException - Thrown when an access role with the id "Support" or "Business Support" should be created. * 409 - RoleAlreadyExistsException - Thrown when an access role with the given id already exists. #### Parameters * `id` (path, string, required) The id of the access role to create. Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `role`. #### Responses * **400** `IdConflictException` - Thrown when id in query parameter is different from the id in the body. Media type: `application/json, text/xml`. Schema: `fault`. * **403** `RoleOperationNotAllowedException` - Thrown when an access role with the id "Support" or "Business Support" should be created. Media type: `application/json, text/xml`. Schema: `fault`. * **409** `RoleAlreadyExistsException` - Thrown when an access role with the given id already exists. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `role`. ### DELETE Delete Access Role `DELETE /roles/{id}` Operation ID: `Delete Access Role`. Tags: roles. Security: oauth2\_application. Action to delete an access role. This endpoint may return the following faults: * 403 - RoleOperationNotAllowedException - Thrown if deletion of the given role is not allowed * 404 - RoleNotFoundException - Thrown if the given role does not exist #### Parameters * `id` (path, string, required) The id of the access role to delete. Minimum length: 1. #### Responses * **204** * **403** `RoleOperationNotAllowedException` - Thrown if deletion of the given role is not allowed Media type: `application/json, text/xml`. Schema: `fault`. * **404** `RoleNotFoundException` - Thrown if the given role does not exist Media type: `application/json, text/xml`. Schema: `fault`. ### GET Get role permissions `GET /roles/{id}/permissions` Operation ID: `Get role permissions`. Tags: roles. Security: oauth2\_application. Retrieves a list of permissions assigned to the given role. This endpoint may return the following faults: * 404 - RoleNotFoundException - If the specified access role does not exist. #### Parameters * `id` (path, string, required) The id of the requested access role. Minimum length: 1. #### Responses * **404** `RoleNotFoundException` - If the specified access role does not exist. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `role_permissions`. ### PUT Set role permissions `PUT /roles/{id}/permissions` Operation ID: `Set role permissions`. Tags: roles. Security: oauth2\_application. Assigns permissions to the given role. This will replace the current permission assignments. For the 'Administrator' role only adjustments for custom module permissions will be processed but other given permissions will be ignored. This endpoint may return the following faults: * 400 - DefaultLocalePermissionMissingException - If no permission for the 'default' locale is given (permission for 'default' locale is mandatory). * 400 - DuplicatePermissionException - If a permission is listed more than once within a scope. * 400 - InvalidPermissionTypeException - If the type of a given permission does not match the expected type. * 400 - InvalidPermissionValueException - If a permission value is given that is either unknown or not supported for a certain permission. * 400 - InvalidPermissionValueScopeException - If values are given permission multi values are used where only single values are support or vice versa (e.g. setting 'values' attribute of ModulePermissionWO in organization scope). * 400 - SystemFlagMissingException - If the 'system' flag is not set for a module permission. * 400 - UnknownPermissionException - If the id of a given permission could not be resolved to a permission. * 400 - UnknownSiteIdException - If a site specific permission is given for a site that is not known. * 404 - RoleNotFoundException - If the specified access role does not exist. * 409 - ResourceStateConflictException - In case of state token conflicts. #### Parameters * `id` (path, string, required) The id of the access role for which the permissions will be set. Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `role_permissions`. #### Responses * **400** `DefaultLocalePermissionMissingException` - If no permission for the 'default' locale is given (permission for 'default' locale is mandatory). or `DuplicatePermissionException` - If a permission is listed more than once within a scope. or `InvalidPermissionTypeException` - If the type of a given permission does not match the expected type. or `InvalidPermissionValueException` - If a permission value is given that is either unknown or not supported for a certain permission. or `InvalidPermissionValueScopeException` - If values are given permission multi values are used where only single values are support or vice versa (e.g. setting 'values' attribute of ModulePermissionWO in organization scope). or `SystemFlagMissingException` - If the 'system' flag is not set for a module permission. or `UnknownPermissionException` - If the id of a given permission could not be resolved to a permission. or `UnknownSiteIdException` - If a site specific permission is given for a site that is not known. Media type: `application/json, text/xml`. Schema: `fault`. * **404** `RoleNotFoundException` - If the specified access role does not exist. Media type: `application/json, text/xml`. Schema: `fault`. * **409** `ResourceStateConflictException` - In case of state token conflicts. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `role_permissions`. ### POST Search for Users on a public Access Role `POST /roles/{id}/user_search` Operation ID: `Search for Users on a public Access Role`. Tags: roles. Security: oauth2\_application. Searches for users of the specified access role. The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes: * login - String * email - String * first\_name - String * last\_name - String * external\_id - String * last\_login\_date - Date * is\_locked - Boolean * is\_disabled - Boolean The output of the query can also be sorted. These are the list of sortable attributes: * login - String * email - String * first\_name - String * last\_name - String * external\_id - String * last\_login\_date - Date This endpoint may return the following faults: * 400 - MalformedSearchParameterException - Thrown if the query is ill-formed. * 404 - RoleNotFoundException - If the specified access role does not exist. #### Parameters * `id` (path, string, required) Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `search_request`. #### Responses * **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed. Media type: `application/json, text/xml`. Schema: `fault`. * **404** `RoleNotFoundException` - If the specified access role does not exist. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `user_search_result`. ### GET Get Users assigned to an Access Role `GET /roles/{id}/users` Operation ID: `Get Users assigned to an Access Role`. Tags: roles. Security: oauth2\_application. Action to get all the users assigned to the specified access role. This endpoint may return the following faults: * 404 - RoleNotFoundException - Thrown if the access role with the given id does not exist. #### Parameters * `id` (path, string, required) ID of the access role. Minimum length: 1. * `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0). * `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25). * `select` (query, string) The property selector. #### Responses * **404** `RoleNotFoundException` - Thrown if the access role with the given id does not exist. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `users`. ### PUT Assign User to Access Role `PUT /roles/{id}/users/{login}` Operation ID: `Assign User to Access Role`. Tags: roles. Security: oauth2\_application. Action to assign a user to an access role This endpoint may return the following faults: * 400 - InvalidRoleException - Thrown if the access role with the given id does not exist. * 400 - InvalidUserLoginException - Thrown if a user with the given login does not exist. * 403 - UserOperationNotAllowedException - Thrown if the operation is not allowed. #### Parameters * `id` (path, string, required) ID of the access role. Minimum length: 1. * `login` (path, string, required) Login of the user. Minimum length: 1. #### Responses * **400** `InvalidRoleException` - Thrown if the access role with the given id does not exist. or `InvalidUserLoginException` - Thrown if a user with the given login does not exist. Media type: `application/json, text/xml`. Schema: `fault`. * **403** `UserOperationNotAllowedException` - Thrown if the operation is not allowed. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `user`. ### DELETE Unassign User to Access Role `DELETE /roles/{id}/users/{login}` Operation ID: `Unassign User to Access Role`. Tags: roles. Security: oauth2\_application. Action to unassign a user to an access role This endpoint may return the following faults: * 403 - UserOperationNotAllowedException - Thrown if the admin user is unassigned from the Administrator role. * 404 - RoleNotFoundException - Thrown if the access role with the given id does not exist. * 404 - UserNotFoundException - Thrown if a user with the given login does not exist. #### Parameters * `id` (path, string, required) ID of the access role. Minimum length: 1. * `login` (path, string, required) Login of the user. Minimum length: 1. #### Responses * **204** * **403** `UserOperationNotAllowedException` - Thrown if the admin user is unassigned from the Administrator role. Media type: `application/json, text/xml`. Schema: `fault`. * **404** `RoleNotFoundException` - Thrown if the access role with the given id does not exist. or `UserNotFoundException` - Thrown if a user with the given login does not exist. Media type: `application/json, text/xml`. Schema: `fault`. ## Schemas ### roles Document representing a list of access roles. * `count` (_integer (int32)_) * `data` (_array of role_) The list of access roles. * `expand` (_array of string_) * `next` (_string_) * `previous` (_string_) * `select` (_string_) * `start` (_integer (int32)_) Minimum: 0. * `total` (_integer (int32)_) _Example_ ``` { "count": 2, "data": [ { "description": "The administrator has the rights to perform tasks related to the overall administration of the merchant organization and its users and roles. This access role is not site-specific and will grant the user access to the entire organization.", "id": "Administrator", "link": "https://example.com/s/-/dw/data/{version}/roles/Administrator", "user_count": 1, "user_manager": false, "users": [ { "disabled": false, "email": "ocapi@example.com", "first_name": "Ocapi", "last_name": "LocaleDude", "locked": false, "login": "localeDude", "preferred_data_locale": "default", "preferred_uilocale": "default" } ] }, { "description": "Read and Write Site Preferences of multiple Sites ", "id": "MultiSite-Full-ReadWriteSitePreferences", "link": "https://example.com/s/-/dw/data/{version}/roles/MultiSite-Full-ReadWriteSitePreferences", "user_count": 1, "user_manager": false, "users": [ { "disabled": false, "email": "ocapi_bfl@example.com", "first_name": "Ocapi", "last_name": "MultiSite-Full-ReadWriteSitePreferences", "locked": false, "login": "MultiSite-Full-ReadWriteSitePreferences", "preferred_data_locale": "default", "preferred_uilocale": "default" } ] } ], "expand": [ "users", "permissions" ], "select": "(**)", "start": 0, "total": 20 } ``` ### fault Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error). * `arguments` (_object_) A map that provides fault arguments. Data can be used to provide error messages on the client side. Additional properties: `object`. * `cause` (_cause_) * `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given * `message` (_string_) The message text of the java exception. * `stack_trace` (_string_) * `type` (_string_) The name of the java exception. ### role Document representing an access role. * `creation_date` (_string (date-time)_) * `description` (_string_) The role description. * `id` (_string_) The role ID. * `last_modified` (_string (date-time)_) * `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified. * `permissions` (_role\_permissions_) The permissions assigned to the access role. Available through expands. * `user_count` (_integer (int32)_) Number of users assigned to the role. * `user_manager` (_boolean_) Flag whether this role is allowed to manage users or other access roles. * `users` (_array of user_) The users assigned to the access role. Available through expands. _Example_ ``` { "description": "Allowed to manage locales", "id": "LocaleManager", "link": "https://example.com/s/-/dw/data/{version}/roles/LocaleManager", "user_count": 1, "user_manager": false, "users": [ { "disabled": false, "email": "ocapi@example.com", "first_name": "Ocapi", "last_name": "LocaleDude", "locked": false, "login": "localeDude", "preferred_data_locale": "default", "preferred_uilocale": "default" } ] } ``` ### role\_permissions Document listing the permissions assigned to a certain role (accessible by type). * `functional` (_role\_functional\_permissions_) The functional permissions. * `locale` (_role\_locale\_permissions_) The locale permissions. * `module` (_role\_module\_permissions_) The module permissions. * `webdav` (_role\_webdav\_permissions_) The WebDAV permissions. _Example_ ``` { "functional": { "organization": [ { "name": "Delete_All_Catalogs", "type": "functional", "value": "ACCESS" }, { "name": "Manage_All_Catalogs", "type": "functional", "value": "ACCESS" }, { "name": "WebDAV_Security_Logs_Access", "type": "functional", "value": "ACCESS" } ], "site": [ { "name": "Manage_Site_Catalog", "type": "functional", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "ACCESS" } }, { "name": "Manage_Site_Library", "type": "functional", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "ACCESS" } }, { "name": "Manage_Site_PriceBooks", "type": "functional", "values": { "SiteGenesis": "ACCESS" } }, { "name": "Manage_Site_Inventory", "type": "functional", "values": { "SiteGenesis": "ACCESS" } } ] }, "locale": { "unscoped": [ { "locale_id": "de", "type": "locale", "value": "ACCESS" }, { "locale_id": "default", "type": "locale", "value": "READONLY" }, { "locale_id": "en", "type": "locale", "value": "READONLY" }, { "locale_id": "en_US", "type": "locale", "value": "ACCESS" }, { "locale_id": "fr_FR", "type": "locale", "value": "ACCESS" } ] }, "module": { "organization": [ { "application": "bm", "name": "jobmonitor", "type": "module", "value": "READONLY" }, { "application": "bm", "name": "jobschedules", "system": true, "type": "module", "value": "ACCESS" } ], "site": [ { "application": "bm", "name": "library_content_libraries", "system": true, "type": "module", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "READONLY" } }, { "application": "bm", "name": "library_folder", "system": true, "type": "module", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "ACCESS" } }, { "application": "bm", "name": "library_content", "system": true, "type": "module", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "READONLY" } } ] }, "webdav": { "unscoped": [ { "folder": "/catalogs/apparel-catalog", "type": "webdav", "value": "ACCESS" }, { "folder": "/catalogs/electronics-catalog", "type": "webdav", "value": "READONLY" }, { "folder": "/catalogs/storefront-catalog-en", "type": "webdav", "value": "READONLY" }, { "folder": "/catalogs/storefront-catalog-non-en", "type": "webdav", "value": "READONLY" }, { "folder": "/libraries/SiteGenesis", "type": "webdav", "value": "ACCESS" }, { "folder": "/libraries/SiteGenesisGlobal", "type": "webdav", "value": "READONLY" } ] } } ``` ### search\_request Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource. * `count` (_integer (int32)_) The number of returned documents Minimum: 1. Maximum: 200. * `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling Minimum: 0. * `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional * `query` (_query_, required) The query to apply * `select` (_string_) The field to be selected. * `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional. * `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result. Minimum: 0. ### user\_search\_result Document representing an user search result. * `count` (_integer (int32)_) The number of returned documents * `data` (_array of object_) * `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling Minimum: 0. * `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional * `hits` (_array of user_) The sorted array of search hits. Can be empty. * `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page. * `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page. * `query` (_query_) The query passed into the search * `select` (_string_) The field to be selected. * `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional. * `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result. Minimum: 0. * `total` (_integer (int32)_) The number of returned documents _Example_ ``` { "count": 1, "hits": [ { "disabled": false, "email": "ocapi@example.com", "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c", "first_name": "Ocapi", "last_login_date": "2017-01-11", "last_name": "SiteGenesisDude", "locked": false, "login": "SiteGenesisDude", "preferred_data_locale": "default", "preferred_uilocale": "default" } ], "query": { "text_query": { "fields": [ "login" ], "search_phrase": "Dude" } }, "select": "(**)", "start": 0, "total": 1 } ``` ### users Document representing a list of users. * `count` (_integer (int32)_) The number of returned documents. * `data` (_array of user_) The list of users. * `expand` (_array of string_) The list of expands set for the search request. Expands are optional. * `next` (_string_) The URL of the next result page. * `previous` (_string_) The URL of the previous result page. * `select` (_string_) The fields that you want to select. * `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result. Minimum: 0. * `total` (_integer (int32)_) The total number of documents. _Example_ ``` { "count": 2, "data": [ { "disabled": false, "email": "ocapi@example.com", "first_name": "Ocapi", "last_login_date": "2017-01-12", "last_name": "RoleDude", "locked": false, "login": "roleDude", "preferred_data_locale": "default", "preferred_uilocale": "default" }, { "disabled": false, "email": "ocapi@example.com", "first_name": "Ocapi", "last_name": "SecondRoleManager", "locked": false, "login": "secondRoleManager", "preferred_data_locale": "en", "preferred_uilocale": "de" } ], "select": "(**)", "start": 0, "total": 2 } ``` ### user Document representing a user. * `creation_date` (_string (date-time)_) * `disabled` (_boolean_) Flag whether the user is disabled. * `email` (_string_, required) The email address. Maximum length: 256. * `external_id` (_string_) The external id. This attribute is only valid when the user uses centralized authentication. Maximum length: 256. * `first_name` (_string_) The first name. Maximum length: 256. * `last_login_date` (_string (date)_) Last login of the user. * `last_modified` (_string (date-time)_) * `last_name` (_string_, required) The last name. Maximum length: 256. * `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified. * `locked` (_boolean_) Flag whether the user is locked. * `login` (_string_) The user login. Maximum length: 256. * `password` (_string_) The password. This attribute is only used to set the password upon user creation. This attribute is only valid when the user does not use centralized authentication. * `password_expiration_date` (_string (date-time)_) The user password expiration time * `password_modification_date` (_string (date-time)_) The time, where the password was last modified * `preferred_data_locale` (_string_) The effective preferred data locale of the user. A locale is only considered if the user has at least read permission on the locale. * `preferred_ui_locale` (_string_) The preferred UI locale of the user. * `roles` (_array of string_) List of role ids the user is assigned to. _Example_ ``` { "disabled": false, "email": "someUserl@example.com", "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c", "first_name": "John", "last_name": "Doe", "locked": false, "login": "someUser", "password_expiration_date": "2016-01-14T16:48:07Z", "password_modification_date": "2016-04-14T16:48:07Z", "preferred_data_locale": "default", "preferred_ui_locale": "en-US", "roles": [ "FirstRole", "SecondRole" ] } ``` ### cause * `cause` (_cause_) * `message` (_string_) * `type` (_string_) ### role\_functional\_permissions Document listing the functional permissions assigned to a certain role. * `organization` (_array of role\_functional\_permission_) The list of organization functional permissions. * `site` (_array of role\_functional\_permission_) The list of site functional permissions. _Example_ ``` { "organization": [ { "name": "Delete_All_Catalogs", "type": "functional", "value": "ACCESS" }, { "name": "Manage_All_Catalogs", "type": "functional", "value": "ACCESS" }, { "name": "WebDAV_Security_Logs_Access", "type": "functional", "value": "ACCESS" } ], "site": [ { "name": "Manage_Site_Catalog", "type": "functional", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "ACCESS" } }, { "name": "Manage_Site_Library", "type": "functional", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "ACCESS" } }, { "name": "Manage_Site_PriceBooks", "type": "functional", "values": { "SiteGenesis": "ACCESS" } }, { "name": "Manage_Site_Inventory", "type": "functional", "values": { "SiteGenesis": "ACCESS" } } ] } ``` ### role\_locale\_permissions Document listing the locale permissions assigned to a certain role. * `unscoped` (_array of role\_locale\_permission_) The list of unscoped locale permissions. _Example_ ``` { "unscoped": [ { "locale_id": "de", "type": "locale", "value": "ACCESS" }, { "locale_id": "default", "type": "locale", "value": "READONLY" }, { "locale_id": "en", "type": "locale", "value": "READONLY" }, { "locale_id": "en_US", "type": "locale", "value": "ACCESS" }, { "locale_id": "fr_FR", "type": "locale", "value": "ACCESS" } ] } ``` ### role\_module\_permissions Document listing the module permissions assigned to a certain role. * `organization` (_array of role\_module\_permission_) The list of organization module permissions. * `site` (_array of role\_module\_permission_) The list of site module permissions. _Example_ ``` { "organization": [ { "application": "bm", "name": "jobmonitor", "type": "module", "value": "READONLY" }, { "application": "bm", "name": "jobschedules", "system": true, "type": "module", "value": "ACCESS" } ], "site": [ { "application": "bm", "name": "library_content_libraries", "system": true, "type": "module", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "READONLY" } }, { "application": "bm", "name": "library_folder", "system": true, "type": "module", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "ACCESS" } }, { "application": "bm", "name": "library_content", "system": true, "type": "module", "values": { "SiteGenesis": "ACCESS", "SiteGenesisGlobal": "READONLY" } } ] } ``` ### role\_webdav\_permissions Document listing the WebDAV permissions assigned to a certain role. * `unscoped` (_array of role\_webdav\_permission_) The list of unscoped WebDAV permissions. _Example_ ``` { "unscoped": [ { "folder": "/catalogs/apparel-catalog", "type": "webdav", "value": "ACCESS" }, { "folder": "/catalogs/electronics-catalog", "type": "webdav", "value": "READONLY" }, { "folder": "/catalogs/storefront-catalog-en", "type": "webdav", "value": "READONLY" }, { "folder": "/catalogs/storefront-catalog-non-en", "type": "webdav", "value": "READONLY" }, { "folder": "/libraries/SiteGenesis", "type": "webdav", "value": "ACCESS" }, { "folder": "/libraries/SiteGenesisGlobal", "type": "webdav", "value": "READONLY" } ] } ``` ### query Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following: * match\_all\_query - returns all records. * term\_query - matches records where a field (or fields) exactly match some simple value (including null). * text\_query - matches records where a field (or fields) contain a search phrase. * boolean\_query - formulates a complex boolean expression using query objects as criteria. * filtered\_query - allows for filtering of records based on both a query and a filter. Type: `any`. ### sort Document representing a sort request. * `field` (_string_, required) The name of the field to sort on. * `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used. Allowed values: `asc`, `desc`. _Example_ ``` { "field": "id", "sort_order": "asc" } ``` ### result\_page Data that can be used to get the next and previous page of a Data API results object. * `count` (_integer (int32)_) The number of returned documents. * `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling * `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result. ### role\_functional\_permission Document representing a functional permission. * `name` (_string_, required) The name of the functional permission. Minimum length: 1. * `type` (_string_, required) The permission type ("functional"). Minimum length: 1. * `value` (_string_) The non domain specific value for the functional permission, e.g. ACCESS or READONLY. * `values` (_object_) The map of value per domain for the functional permission, e.g. ACCESS or READONLY per domain name. Additional properties: `string`. _Example_ ``` { "name": "Delete_All_Catalogs", "type": "functional", "value": "ACCESS" } ``` ### role\_locale\_permission Document representing a locale permission. * `locale_id` (_string_, required) The related locale id of the locale permission. Minimum length: 1. * `type` (_string_, required) The permission type ("locale"). Minimum length: 1. * `value` (_string_) The non domain specific value for the locale permission, e.g. ACCESS or READONLY. * `values` (_object_) The map of value per domain for the locale permission, e.g. ACCESS or READONLY per domain name. Additional properties: `string`. _Example_ ``` { "locale_id": "en", "type": "locale", "value": "READONLY" } ``` ### role\_module\_permission Document representing a module permission. * `application` (_string_, required) The permission application (e.g. "bm", "csc"). Minimum length: 1. * `name` (_string_, required) The related menu action name of the module permission. Minimum length: 1. * `system` (_boolean_) Flag to indicate a system menu action. This is `false` for custom menu actions. * `type` (_string_, required) The permission type ("module"). Minimum length: 1. * `value` (_string_) The non domain specific value for the module permission, e.g. ACCESS or READONLY. * `values` (_object_) The map of value per domain for the module permission, e.g. ACCESS or READONLY per domain name. Additional properties: `string`. _Example_ ``` { "application": "bm", "name": "jobmonitor", "type": "module", "value": "READONLY" } ``` ### role\_webdav\_permission Document representing a WebDAV permission. * `folder` (_string_, required) The related folder of the WebDAV permission. Minimum length: 1. * `type` (_string_, required) The permission type ("webdav"). Minimum length: 1. * `value` (_string_) The non domain specific value for the WebDAV permission, e.g. ACCESS or READONLY. * `values` (_object_) The map of value per domain for the WebDAV permission, e.g. ACCESS or READONLY per domain name. Additional properties: `string`. _Example_ ``` { "folder": "/catalogs/apparel-catalog", "type": "webdav", "value": "ACCESS" } ``` ### bool\_filter Document representing a boolean filter. A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters. **Example:** (id="myId" AND coupon\_id="couponOne") query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { bool\_filter: { operator: "and", filters: \[ { term\_filter: { field: "id", operator: "is", values: \["myId"\] } }, { term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } } \] } } } } **Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20) query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { bool\_filter: { operator: "or", filters: \[ { term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } }, { range\_filter: { field: "redemption\_count", from: 1, to: 20 } } \] } } } } **Example:** NOT(enabled=false OR coupon\_id="special") query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { bool\_filter: { operator: "not", filters: \[ { term\_filter: { field: "enabled", operator: "is", values: \[false\] } }, { term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } } \] } } } } * `filters` (_array of filter_) A list of filters, which are logically combined by an operator. * `operator` (_string_, required) The logical operator the filters are combined with. Allowed values: `and`, `or`, `not`. ### bool\_query A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match **Example:** (id = 'foo' AND description LIKE 'bar') query: { bool\_query: { must: \[ { term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } }, { text\_query: { fields: \["description"\], search\_phrase: "bar" } } \] } } **Example:** (id = 'foo' OR description LIKE 'bar') query: { bool\_query: { should: \[ { term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } }, { text\_query: { fields: \["description"\], search\_phrase: "bar" } } \] } } **Example:** (NOT (id = 'foo' AND description LIKE 'bar')) query: { bool\_query: { must\_not: \[ { term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } }, { text\_query: { fields: \["description"\], search\_phrase: "bar" } } \] } } **Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false)) query: { bool\_query: { must: \[ { text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } }, { text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } } \], must\_not: \[ { term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } } \] } } * `must` (_array of query_) List of queries that must match. * `must_not` (_array of query_) List of queries that must not match. * `should` (_array of query_) List of queries that should match (i.e., at least one query must match). ### filter Document representing a filter. A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following: * term\_filter - matches records where a field (or fields) exactly match some simple value (including null). * range\_filter - matches records where a field value lies in a specified range. * query\_filter - provides filtering based on a query. * bool\_filter - provides filtering of records using a set of filters combined with a specified operator. Type: `any`. ### filtered\_query A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter. **Example:** query : { filtered\_query: { query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } }, filter: { term\_filter: { field: "enabled", operator: "is", values: \[ false \] } } } } * `filter` (_filter_, required) The (possibly complex) filter object. * `query` (_query_, required) The query object. ### match\_all\_query A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints. **Example:** query: { match\_all\_query: {} } Type: `any`. ### nested\_query A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe" { "query": { "bool\_query": { "must": \[ { "nested\_query": { "path": "order.shipping\_addresses", "query": { "bool\_query": { "must": \[ { "bool\_query": { "must": \[ { "term\_query": { "fields": \[ "order.shipping\_addresses.first\_name" \], "operator": "is", "values": \[ "John" \] } } \] } }, { "bool\_query": { "must": \[ { "term\_query": { "fields": \[ "order.shipping\_addresses.last\_name" \], "operator": "is", "values": \[ "Doe" \] } } \] } } \] } }, "score\_mode": "avg" } } \] } } } * `path` (_string_, required) * `query` (_query_, required) * `score_mode` (_string_) Allowed values: `avg`, `total`, `max`, `none`. ### query\_filter Document representing a query filter. A query filter wraps any query and allows it to be used as a filter. **Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false)) query : { filtered\_query: { query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } }, filter: { query\_filter: { query: { term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] } } } } } } * `query` (_query_, required) The query to use as a filter. ### range2\_filter Document representing a range comparison with a range filter, named Range2Filter. A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range. The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to". The second range (R2) is defined by "from\_value" and "to\_value". The filter mode specifies the method used to compare the two ranges: * overlap: R1 overlaps fully or partially with R2 * containing: R1 contains R2 * contained: R1 is contained in R2 The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive. A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. **Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017) "query" : { "filtered\_query": { "filter": { "range2\_filter": { "from\_field": "valid\_from", "to\_field": "valid\_to", "filter\_mode":"overlap", "from\_value": "2007-01-01T00:00:00.000Z", "to\_value": "2017-01-01T00:00:00.000Z" } }, "query": { "match\_all\_query": {} } } } * `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap. Allowed values: `overlap`, `containing`, `contained`. * `from_field` (_string_, required) The field name of the field that starts the first range. * `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive. * `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. * `to_field` (_string_, required) The field name of the field that ends the first range. * `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive. * `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. ### range\_filter Document representing a range filter. A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive. A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. **Example:** ( redemption\_count BETWEEN (0,10\] ) query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { range\_filter: { field: "redemption\_count", from: 0, to: 10, from\_inclusive: false } } } } * `field` (_string_, required) The search field. * `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. * `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive. * `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. * `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive. ### term\_filter Document representing a term filter. A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only. **Example:** (id="my\_id") query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { term\_filter: { field: "id", operator: "is", values: \["my\_id"\] } } } } **Example:** (id IN ("my\_id","other\_id")) query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { term\_filter: { field: "id", operator: "one\_of", values: \["my\_id","other\_id"\] } } } } **Example:** (description=NULL) query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { term\_filter: { field: "description", operator: "is\_null" } } } } * `field` (_string_, required) The filter field. * `operator` (_string_, required) The operator to compare the field's values with the given ones. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. * `values` (_array of object_) The filter values. ### term\_query A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query . **Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields. **Example:** (id="my\_id") query: { term\_query: { fields: \["id"\], operator: "is", values: \["my\_id"\] } } **Example:** (id IN ("my\_id","other\_id")) query: { term\_query: { fields: \["id"\], operator: "one\_of", values: \["my\_id","other\_id"\] } } **Example:** (id=null) query: { term\_query: { fields: \["description"\], operator: "is\_null" } } **Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword')) query: { term\_query: { fields: \["id", "description"\], operator: "one\_of", values: \["generic","keyword"\] } } * `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator. Minimum items: 1. * `operator` (_string_, required) Returns the operator to use for the term query. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. * `values` (_array of object_) The values the field(s) are compared against, combined with the operator. ### text\_query A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields. **Example:** (coupon\_id contains "xmas" ) query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "xmas" } } **Example:** (coupon\_id contains "xmas" OR description contains "xmas") query: { text\_query: { fields: \["description", "coupon\_id"\], search\_phrase: "xmas" } } **Example:** (description contains "holiday" AND description contains "bojo") query: { text\_query: { fields: \["description"\], search\_phrase: "holiday bogo" } } * `fields` (_array of string_, required) The document fields the search phrase has to match. Minimum items: 1. * `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.