[[workplace-search-api]]
== Workplace Search API

=== Content Sources

[source,rb]
----------------------------
# Create a custom content source
client.create_content_source(body: { name: 'test' })

# Retrieve a content source by ID
content_source_id = client.create_content_source(body: { name: 'books' }).body['id']
client.content_source(content_source_id)

# Delete a content source by ID
client.delete_content_source(content_source_id)

# Retrieve all content sources
client.list_content_sources

# Update a custom content source
body = {
  name: new_name,
  schema: { title: 'text', body: 'text', url: 'text' },
  display: { title_field: 'title', url_field: 'url', color: '#f00f00' },
  is_searchable: true
}
client.put_content_source(id, body: body)

# Issue commands to a Content Source's sync jobs
client.command_sync_jobs(content_source_id, body: { command: 'interrupt' })

# Update a content source icon
# You need to encode the file with Base64:
require 'base64'

path = File.expand_path("#{File.dirname(__FILE__)}/icon.png")
icon = Base64.strict_encode64(File.read(path))
response = client.put_content_source_icons(content_source_id, main_icon: icon, alt_icon: icon)

# Retrieves a content source's automatic query refinement details
client.auto_query_refinement_details(content_source_id)
----------------------------

=== Documents

[source,rb]
----------------------------
# Index Documents
documents = [
  { id: 'e68fbc2688f1', title: 'Frankenstein; Or, The Modern Prometheus', author: 'Mary Wollstonecraft Shelley' },
  { id: '0682bb06af1a', title: 'Jungle Tales', author: 'Horacio Quiroga' },
  { id: '75015d85370d', title: 'Lenguas de diamante', author: 'Juana de Ibarbourou' },
  { id: 'c535e226aee3', title: 'Metamorphosis', author: 'Franz Kafka' }
]

response = client.index_documents(content_source_id, body: documents)

# Retrieve a document by ID from a specified content source
client.document(content_source_id, document_id: '75015d85370d')

# List documents from a custom content source
client.list_documents(content_source_id)

# Delete Documents
client.delete_documents(content_source_id, document_ids: ['e68fbc2688f1', 'c535e226aee3'])

# Delete all documents for a given content source
client.delete_all_documents(content_source_id)

# Delete documents by query
client.delete_documents_by_query(content_source_id, query: query)
----------------------------

[discrete]
[[ws-oauth-authentication]]
=== OAuth Authentication

You need to configure the OAuth Application for Search in order to use the Workplace Search client's `search` and `create_analytics` endpoints. You need to follow the steps in https://www.elastic.co/guide/en/workplace-search/current/building-custom-search-workplace-search.html#configuring-search-oauth[Configuring the OAuth Application for Search] to retrieve the credentials: **Client ID** and **Client Secret** to request access tokens from the authentication server.

The client implements https://www.elastic.co/guide/en/workplace-search/current/building-custom-search-workplace-search.html#authenticating-search-user-confidential[Authenticating Users with a Confidential OAuth Flow]. It provides a helper to obtain the autorization URL directly from the client once you've set the necessary values.

The authorization endpoint is hosted by your Kibana deployment, so you need to provide the client with the https://www.elastic.co/guide/en/enterprise-search/current/endpoints-ref.html#kibana-base-url[base URL of your Kibana instance]. You can do this when you initialize the client:

[source,rb]
----------------------------
client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(http_auth: <access_token>, kibana_url: <kibana_url>)
----------------------------

Or you can set in an existing client:

[source,rb]
----------------------------
client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(http_auth: <access_token>)
client.kibana_url = <kibana_url>
----------------------------

Once you've instantiated a client and the base URL of your Kibana instance is set, you can get the URL for authorization like so:
[source,rb]
----------------------------
# You get the values for client_id and client_secret when configuring the OAuth Application:
client_id = <client_id>
client_secret = <client_secret>
redirect_uri = <redirect_uri>

# Get the authorization URL:
client.authorization_url(client_id, redirect_uri)
> https://kibana_url/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=code&client_id=client_id&redirect_uri=https%3A%2F%2Flocalhost%3A3002

----------------------------

Open the URL to authorize your application. Successful authorization redirects the user in accordance to the redirect URI provided (and configured for the application).

The application server must now request for an `access_token`, which is generated by Workplace Search using the `oauth/token` endpoint, using the **Client ID** and **Client Secret**.

[source,rb]
----------------------------
authorization_code = '<paste code from redirect>'

access_token = client.request_access_token(client_id, client_secret, authorization_code, redirect_uri)

# The access_token can now be used to issue a search request:
client.search(body: { query: 'search query' }, access_token: access_token)
----------------------------

See https://www.elastic.co/guide/en/workplace-search/current/workplace-search-search-api.html#search-api-overview[Search API Overview] for more search parameters.

=== Permissions

[source,rb]
----------------------------
# List permissions
client.list_permissions(content_source_id)

# Get a user permissions
response = client.user_permissions(content_source_id, { user: 'enterprise_search' })

# Clear user permissions
client.put_user_permissions(content_source_id, { permissions: [], user: 'enterpise_search' })

# Add permissions to a user
client.add_user_permissions(
  content_source_id,
  { permissions: ['permission1', 'permission2'], user: user }
)

# Updates user permissions
client.put_user_permissions(content_source_id, { permissions: [], user: user })

# Remove permissions from a user
client.remove_user_permissions(
  content_source_id,
  { permissions: ['permission1', 'permission2'], user: user }
)
----------------------------

=== External Identities

[source,rb]
----------------------------
# Create external identities
body = {
  external_user_id: external_user_id,
  permissions: [],
  external_user_properties: [
    'attribute_name' => '_elasticsearch_username',
    'attribute_value' => 'fernando'
  ]
}
client.create_external_identity(content_source_id, body: body)

# Retrieve an external identity
client.external_identity(content_source_id, external_user_id: external_user_id)

# List external identities
client.list_external_identities(content_source_id)

# Update external identity
body = { external_user_id: external_user_id, permissions: ['permission1'] }
client.put_external_identity(content_source_id, external_user_id: external_user_id, body: body)

# Delete an external identity
client.delete_external_identity(content_source_id, external_user_id: external_user_id)
----------------------------

=== Search

You need to set up <<ws-oauth-authentication>> and use the access token for Search. See https://www.elastic.co/guide/en/workplace-search/current/workplace-search-search-api.html[Search API Reference] for available parameters and more details about search.

[source,rb]
----------------------------
client.search(body: {query: 'search query'}, access_token: access_token)
----------------------------

=== Create Analytics Event

You need to set up <<ws-oauth-authentication>> to use analytics events.

[source,rb]
----------------------------
body = {
  type: 'click',
  query_id: 'search_query_id',
  document_id: 'document_id',
  page: 1,
  content_source_id: 'content_source_id',
  rank: 1,
  event: 'api'
}

client.create_analytics_event(access_token: oauth_access_token, body: body)
----------------------------

=== Synonym Sets

[source,rb]
----------------------------
body = {
  synonym_sets: [
    { 'synonyms' => ['house', 'home', 'abode'] },
    { 'synonyms' => ['cat', 'feline', 'kitty'] },
    { 'synonyms' => ['mouses', 'mice'] }
  ]
}

# Create batch synonym set
client.create_batch_synonym_sets(body: body)

# Delete synonym set
client.delete_synonym_set(synonym_set_id: id)

# List synonym sets
client.list_synonym_sets

# Get a synonym set
client.synonym_set(synonym_set_id: id)

# Update a synonym set
body = { synonyms: ['mouses', 'mice', 'luch'] }
client.put_synonym_set(synonym_set_id: id, body: body)
----------------------------


=== Current User

[source,rb]
----------------------------
# Get the current user
client.current_user

# Get the current user and return the access token
client.current_user(get_token: true)
----------------------------

=== Triggers Blocklist

[source,rb]
----------------------------
# Get current triggers blocklist
client.triggers_blocklist

# Update current triggers blocklist
client.put_triggers_blocklist(body: { blocklist: ['in', 'it', 'page'] })
----------------------------