Engagement Center Search

Scopes

The table below shows the scopes that the Engagement Center Search service supports.

For more information about scopes, authorization, and authentication procedures for YaaS services, see Scopes and Authorization.

Search Indexing Data

Based on Elasticsearch, the Engagement Center Search service offers full-text search and matching. For example, you can split the most frequently searched data of a customer and create an index for the customer. This helps to improve the data search performance. You can only search for the data indexed by the Engagement Center Indexing service.

Quick Search

You can do a quick search which calling the persistence search API, a kind of simple proxy that exposes Elasticsearch , without any additional validation added. Quick search is more flexible and general than advanced search. Quick search offers full-text search for the indexed data of customers, transactions, products, sales orders and service tickets.

The parameter q of quick search APIs maps to the query string query of Elasticsearch, which enables you to run queries on any field in your index. Use a space to separate multiple query fields. By default, the logic operator for these multiple query fields is or. You can also define the logic as or and and. If you do not assign the key word to any field, the service searches all fields of the indexed data to find a match.

For more information about the query-string search, see Query String Query.
For more information about quick search, see Quick Search Practices.

Advanced Search

Use the advanced search for complex and special search queries. You need to specify multiple query parameters to run an advanced search. The service only returns results that conform to all query parameters.

Use multiple query parameters to search for service tickets. You can use wildcard query for parameters, including email, firstName, and lastName. Use? for any character. Use * for zero or extra characters. You can use multiple values for parameters, including salesOrderNumber and status. Use a comma to separate the multiple values. Both the salesOrderNumber and status support exact term query.

Use multiple query parameters to search for sales orders. You can use wildcard query for parameters, including firstName and lastName. Use? for any character. Use * for zero or extra characters. You can use multiple values for parameters, including ticketNumber, type, priority, status, customerId and productId. Use a comma to separate the multiple values. All of the fields ticketNumber, type, priority, status, customerId and productId support exact term query.

Use multiple query parameters to search for products. Default value of fields are code and name. You can specify multiple fields for this parameter and use a comma to separate these fields.The parameter language indicates which language of name and description you want to query. If you specify multiple languages, use a comma to separate them. Default language is English. The parameter q is the query string and only supports wildcard matching. By default, The service adds * at the beginning and the end of the value of q. Use and for the parameter default_operator to search for products when all the fields need to match the query string. Otherwise, use or. The default value for the logic operator is or.

For more information, see Advanced Search Practices .

Quick Search Practices

Customer quick search

The example below shows how to use quick search for customers.

Request

• Method: GET
• Request URL:https://api.beta.yaas.io/hybris/cecentersearch/v1/{tenant}/customer/search
• Headers
  • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.cecentercustomer_view.
• URI Parameters
  • {tenant}: The name of the current tenant.
• Query Parameters
  • q: Use the query to search for specific results.
    • Set the value of q to search for all the customers that contain the query value. The query analyzes the value with the standard analyzer to offer full-text search and matching .
      For example: q=hello world
      The service returns all the customers that contain the word hello or world .
    • When you query an exact-value field, such as contactEmail or contactPhone, the query searches for the exact value you specified rather than analyzing the query string .
      For example:q=contactEmail:markus@hybristest.com
    • Use? for any character. Use * for zero or extra characters .
      For example: q=*t?t*
    • Use a space to separate multiple query fields. By default, the logic for those multiple query fields is or .
      For example: q=lastName:*test* firstName:*ran*
    • Use a space to separate multiple query fields. You can define the logic as and .
      For example: q=(lastName:*test* firstName:*ran*) AND middleName:test
      Equals to:q=(lastName:*test* OR firstName:*ran*) AND middleName:test
  • score: Sort by fields. This can be either in the form of fieldname or fieldname:asc/fieldName:desc. The fieldName can either be an actual field within the document, or the special_score name to indicate sorting based on scores. It’s is possible to combine several sorting parameters. How the fields are displayed on the UI depends on the order in which you arrange these sorting parameters .
    For example: customerNumber:asc,id:desc
  • from: Starting index of the hits to be returned. Default number is 0 .
    For Example: 0
  • topNumberofHits: The number of hits to be returned. The default number is 10 .
    For Example: 10

Response

The successful response returns a 200 status code. An example JSON content including the customers looks similar to the following:

[
  {
    "lastName": "test",
    "preferredLanguage": "en_US",
    "metadata": {
      "mixins": {}
    },
    "preferredCurrency": "USD",
    "formattedPhone": "",
    "active": true,
    "customerNumber": "C4404911050",
    "title": "MR",
    "firstName": "test",
    "preferredSite": "default",
    "middleName": "test",
    "company": "",
    "id": "C4404911050",
    "contactPhone": "test"
  },
  {
    "lastName": "Test",
    "preferredLanguage": "en_US",
    "metadata": {
      "mixins": {}
    },
    "contactEmail": "markus@hybristest.com",
    "preferredCurrency": "USD",
    "active": true,
    "customerNumber": "C6355920174",
    "title": "MR",
    "firstName": "test Markus Test Frank test",
    "preferredSite": "default",
    "middleName": "test test test test",
    "company": "",
    "id": "C6355920174",
    "contactPhone": ""
  }
]

Advanced Search Practices

Search for service tickets by using multiple query parameters.

Request

• Method: GET
• Request URL:https://api.beta.yaas.io/hybris/cecentersearch/v1/{tenant}/serviceTicket/advancedSearch
• Headers
  • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_view.
• URI Parameters
  • {tenant}: The name of the current tenant.
• Query Parameters
  • createdFrom: Filter by service ticket date. Start date for searching service tickets. String matching [0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]), 10-10 characters.
    Example: 2015-06-01
  • createdTo: Filter by service ticket date. End date for searching service tickets. String matching [0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]), 10-10 characters.
    Example: 2016-06-30
  • customerId: Filter by customer ID number. You can enter multiple customer ID numbers. Use a comma to separate them.
    Example: C6705827626,C6705827627
  • email: Filter by email. You can enter multiple emails. Use a comma to separate them.
    Example: coco0202003@hybristes.com,coco.tao@hybristest.com
  • firstName: Filter by first name. Enter one first name only. Use * in your search.
    Example: *coco*
  • lastName: Filter by last name. Enter one last name only. Use ? in your search.
    Example: *c?co*
  • priority: Filter by service ticket priority. You can enter multiple service ticket priorities. Use a comma to separate them.
    Example: high,medium
  • productId: Filter by product ID number. You can enter multiple id numbers. Use a comma to separate them .
    Example: 565bc220830ed99b9c81236b,565bc220830ed99b9c81236b
  • status: Filter by service ticket status. You can enter multiple service ticket statuses. Use a comma to separate them.
    Example: open,in_process
  • ticketNumber: Use the query to search for specific results .
    Example: 1000000001,1000000109`
  • topNumberofHits: The number of hits to be returned The default number is 10.
    Example: 10
  • type: Filter by service ticket type. You can enter multiple service ticket types. Use a comma to separate them.
    Example: service_request,repair

Response

The successful response returns a 200 status code. An example JSON content including the service tickets looks similar to the following:

[
  {
    "ticketNumber": "1000000001",
    "metadata": {
      "createdAt": "2016-04-29T06:43:15.024+0000",
      "modifiedAt": "2016-04-29T06:43:15.024+0000",
      "version": 1
    },
    "productId": "565bc220830ed99b9c81236b",
    "typeDescription": {
      "de": "Serviceanfrage",
      "en": "Service Request"
    },
    "shortDescription": "Request for regular maintenance",
    "classification": [
      {
        "classification": "BASIC_TECHNICAL_SKILLS",
        "description": {
          "de": "Technische Grundkenntnisse erforderlich",
          "en": "Basic technical skills required"
        }
      }
    ],
    "priority": "HIGH",
    "type": "SERVICE_REQUEST",
    "processingTime": 15644054,
    "dueAt": "2015-06-30T23:59:59.999+0000",
    "statusDescription": {
      "de": "In Bearbeitung",
      "en": "In Process"
    },
    "createdBy": "coco.tao@hybristest.com",
    "priorityDescription": {
      "de": "Hoch",
      "en": "High"
    },
    "customerFirstName": "coco0202002acd",
    "customerEmail": "coco0202003@hybristes.com",
    "customerId": "C6705827626",
    "modifiedBy": "coco.tao@hybristest.com",
    "customerLastName": "coco0202002cascd",
    "id": "5723028300e879001dd95706",
    "status": "IN_PROCESS"
  }
]

Search for sales orders by using multiple query parameters.

Request

• Method: GET
• Request URL: https://api.beta.yaas.io/hybris/cecentersearch/v1/{tenant}/salesOrder/advancedSearch
• Headers
  • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.order_read.
• URI Parameters
  • {tenant}: Name of the current tenant
• Query Parameters
  • createdFrom: Filter by service ticket date. Start date for searching service tickets. string matching [0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]), 10-10 characters.
    Example: 2015-06-01
  • createdTo: Filter by service ticket date. End date for searching service tickets. string matching [0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]), 10-10 characters.
    Example: 2016-06-30
  • salesOrderNumber: Filter by Sales Order number. You can enter multiple order numbers. Use a comma to separate them.
    Example: 06X301M0,0IF64HDK
  • email: Filter by email address. Enter one email address only. Use * in your search.
    Example: *wang@hybristest*
  • firstName: Filter by first name. Enter one first name only. Use * in your search.
    Example: *ka*
  • lastName: Filter by last name. Enter one last name only. Use ? in your search.
    Example: wa?g
  • status: Filter by service ticket status. You can enter multiple service ticket statuses. Use a comma to separate them.
    Example: CREATED,DECLINE
  • topNumberofHits: The number of hits to be returned. The default number is 10.
    Example: 10

Response

The successful response returns a 200 status code. An example JSON content including the sales orders looks similar to the following:

[
  {
    "metadata": {
      "mixins": {}
    },
    "siteCode": "main",
    "totalPrice": 117.76,
    "created": "2016-05-16T10:27:34.898Z",
    "payments": [
      {
        "status": "SUCCESS",
        "method": "Visa",
        "paymentResponse": "ch_18BiwkCPRlpVRgUIYO40B01k",
        "paidAmount": 117.76,
        "currency": "USD"
      }
    ],
    "tax": {
      "lines": [
        {
          "amount": 10.71,
          "currency": "USD",
          "rate": 10,
          "sequenceId": 0,
          "inclusive": true
        }
      ],
      "total": {
        "amount": 10.71,
        "currency": "USD",
        "inclusive": true
      }
    },
    "subTotalPrice": 107.76,
    "entries": [
      {
        "id": "56603b6c0bce9f7a85ebc49b",
        "amount": 8,
        "unitPrice": 13.47,
        "totalPrice": 107.76,
        "product": {
          "metadata": {
            "mixins": {
              "inventory": "https://api.beta.yaas.io/hybris/schema/b2/hybriscommerce/inventorySchema-v1",
              "taxCodes": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/productTaxCodeMixin-1.0.0"
            }
          },
          "id": "56603b6c0bce9f7a85ebc49b",
          "code": "H18",
          "name": "H18",
          "description": "H18e",
          "published": true,
          "images": [
            {
              "id": "5698db97650ec1adb4da3af2",
              "url": "https://api.beta.yaas.io/hybris/media/v2/public/files/5698db97650ec1adb4da3af2",
              "stored": false
            }
          ],
          "mixins": {
            "inventory": {
              "inStock": true
            },
            "taxCodes": {
              "GE": "increase"
            }
          }
        },
        "tax": {
          "lines": [
            {
              "amount": 9.8,
              "currency": "USD",
              "rate": 10,
              "sequenceId": 0,
              "inclusive": true
            }
          ],
          "total": {
            "amount": 9.8,
            "currency": "USD",
            "inclusive": true
          }
        }
      }
    ],
    "discounts": [],
    "shipping": {
      "total": {
        "amount": 10,
        "currency": "USD"
      },
      "lines": [
        {
          "amount": 10,
          "currency": "USD",
          "code": "fd",
          "name": "Fedex",
          "tax": {
            "total": {
              "amount": 0,
              "currency": "USD",
              "inclusive": false
            }
          }
        }
      ]
    },
    "shippingAddress": {
      "contactName": "kaka",
      "companyName": "",
      "street": "tianfu",
      "streetNumber": "",
      "streetAppendix": "",
      "zipCode": "61400",
      "city": "chengdu",
      "country": "US",
      "state": "AL",
      "contactPhone": ""
    },
    "currency": "USD",
    "id": "0IF64HDK",
    "billingAddress": {
      "contactName": "kaka",
      "companyName": "",
      "street": "tianfu",
      "streetNumber": "",
      "streetAppendix": "",
      "zipCode": "61400",
      "city": "chengdu",
      "country": "US",
      "state": "AL",
      "contactPhone": ""
    },
    "customer": {
      "id": "C2531014710",
      "name": "kakaa 4121 wang",
      "title": "MR",
      "firstName": "kakaa",
      "middleName": "4121",
      "lastName": "wang",
      "email": "kaka4121wang@hybristest.com"
    },
    "status": "CREATED"
  }
]

Search for products by using multiple query parameters.

Request

• Method: GET
• Request URL:https://api.beta.yaas.io/hybris/cecentersearch/v1/{tenant}/product/advancedSearch
• URI Parameters
  • {tenant}: Name of the current tenant.
• Headers
  • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant.
• Query Parameters
  • q: Search for products by key words. Use * in your search. Add * to the beginning and end of the value of q. For example: test Equals to: *test*
  • language: The language of hits to be returned. The default language is English. You can use multiple languages for the name and description fields. If the value of fields include name or description, the query searches for the corresponding language you specified. You can specify multiple languages and use a comma to separate them. The relationship of multiple languages is logic or.
    For example: en,de
  • fields: The default fields to use in the query. You can enter multiple fields. Use a comma to separate them. Default fields are code and name.
    For Example: code,name
    You can else specified the field like this:mixins.ssrvcext.isRegisterable
  • default_operator: Use the logic and or or for the operator to specify the relationship of the multiple fields to query. The default operator logic is or.
    For Example: or
  • topNumberofHits: The number of hits to be returned. The default number is 10.
    For Example: 10
  • unpublishIncluded: To include the unpublished products or not. The default value is false.
    For Example: false

Response

The successful response returns a 200 status code. An example JSON content including the service tickets looks similar to the following:

[
  {
    "mixins": {
      "productbundle": {
        "bundleAspectId": "5354FC1D-7B85-4877-89AF-5F450884890A"
      },
      "productsubscription": {
        "subscriptionAspectId": "5354FC1D-7B85-4877-89AF-5F450884890A"
      }
    },
    "code": "june1",
    "name": {
      "en": "june1"
    },
    "description": {
      "en": "The world's best camera and camcorder in a waterproof smartphone."
    },
    "id": "581ad171d3e735001d171be1",
    "published": true,
    "prices": [
      {
        "priceId": "581af477d726d5001d8493e2",
        "originalAmount": 222,
        "effectiveAmount": 222,
        "currency": "USD"
      }
    ]
  }
]

Error Types

For information about error codes, see the API Reference.