System tools for Optimizely Graph

  • Updated

System tools are built-in features that help Optimizely Opal take action. Each tool performs a specific task, such as creating a campaign, uploading files, or generating images. Think of tools like attachments on a Swiss Army knife. Each one has a distinct purpose that helps you get work done.

In addition to the system tools available in Opal, Optimizely Graph includes a set of system tools to help you with Content Management System-related tasks, such as managing content.

Ask Opal what tools it has at any time. For example, enter "Please list the tools you have with a brief description of what they do and the parameters" into Opal Chat.

Click a tool's name to expand it and learn when to use it, its required and optional parameters, and example prompts for calling the tool. If you do not provide a required parameter, Opal prompts you for it.

The Optimizely Graph tools are available for CMS (SaaS), CMS 12 (PaaS), and CMS 13 (Paas) for users who also have Optimizely Graph.
graph_content_type_schema – Use as your starting point for understanding the content structure within your Optimizely Graph instance. The tool lets you and Opal discover available content types and their fields, which is crucial for constructing accurate GraphQL queries.
  • When to use
    • To explore available content – If you want to know what types of content (for example, articles, products, pages) are stored in your Optimizely Graph instance.
    • To understand content structure – If you need to see the fields and properties associated with a specific content type before querying it.
    • To build GraphQL queries – If you need the exact content type names and field names for use with the graph_content_graphql_executor tool.
  • Parameters
    • (Optional) searchPhrase – A text string to filter content types that are relevant to your question, for example, "news article" or "product details". If left empty, all content types are returned.
    • (Optional) itemMinimumScore – The minimum score for items to be considered relevant based on the search phrase.
    • (Optional) contentTypeFacetLimit – The maximum number of content types to return from the facet.
  • Example prompts
    • What content types are available in Optimizely Graph?
    • Show me the schema for content types related to 'blog posts'.
    • I want to see all content types and their fields that are relevant to 'products'.
    • Can you list content types that might contain information about 'customer reviews'?
graph_content_graphql_executor – Execute custom GraphQL queries against your Optimizely Graph instance. You can retrieve specific content items, filter results, sort, and get aggregated data (facets).
  • When to use
    • To retrieve specific content items – If you need to fetch detailed data for articles, products, pages, or any other content type.
    • To filter content based on criteria – If you want to find content that matches certain conditions, for example, articles published within a date range or products with a specific tag.
    • To sort content results – If you need to order content by fields like publication date, title, or price.
    • To paginate through large datasets – If you need to retrieve content in chunks using skip and limit.
    • To get aggregated data (facets) – If you want to count occurrences of values within a field, for example, the number of articles per author or products per category.
  • Parameters
    • query – The GraphQL query to execute.
    • (Optional) variablesAsJson – A JSON string representing variables for the GraphQL query.
  • Example prompts
    • Get the titles and descriptions of all 'NewsArticle' content types.
    • Find all 'Product' content types where the 'price' is greater than 50 and less than 100, and order them by price in ascending order. Also, show me the 'name' and 'sku' of these products. 
    • Count how many 'BlogPosts' were published each month in 2024, and list their titles.
graph_content_search_tool – Use as a simpler alternative for searching content in Optimizely Graph when constructing complex GraphQL queries might be excessive. It lets you search for content based on a search phrase across a specified content type.
  • When to use
    • For simple keyword searches – If you need to find content items that contain a specific phrase or keyword.
    • When you know the content type – If you are looking for content within a known content type, for example, Search for 'summer sale' in 'Promotions'.
    • As a quick lookup – If the graph_content_graphql_executor tool seems too complex or overextravagant for your immediate need.
  • Parameters:
    • searchPhrase – The search phrase to use when searching for content.
    • (Optional) contentTypeName – The specific content type to search within, for example, "Article" or "Product". If not provided, it defaults to "Data" (which might search across various types depending on configuration).

    • (Optional) outputFieldsAsGraphQLOutput – The specific fields you want to retrieve for the matching content items, in GraphQL output format. If not provided, it defaults to _fulltext. For example, the following:

      "id name createdBy { id name }"
  • Example prompts
    • Search for 'holiday promotions' in the 'Campaign' content type.
    • Find any 'Article' content that mentions 'customer experience' and return their titles and URLs.
    • What 'Product' content contains the phrase 'new features'?
    • Show me all content related to 'Optimizely DXP'.
graph_pinned_result – Manages pinned results and pinned result collections in Optimizely Graph. See Pinned results in the Optimizely Graph documentation.
  • When to use
    • List pinned results or pinned result collections in Optimizely Graph.
    • Add a pinned result collection and associate search phrases with a target content key.
    • Update a pinned result or a collection to change the priority or the active status.
    • Remove a pinned result or a pinned result collection.
    • Retrieve pinned results in a collection with filtering, sorting, and pagination.
  • Parameters
    • operation_id – The unique identifier for the pinned result operation. 
      • 0 – List all pinned results. 
      • 1 – List all pinned result collections. 
      • 2 – List pinned results in specific collection. 
      • 3 – Add or update pinned result collection. 
      • 4 – Remove pinned result collection. 
      • 5 – Add or update pinned result. 
      • 6 – Remove pinned result.
    • (Optional) collection_id – The unique identifier for the pinned result collection. Use this together with operation_id 2 or 3 (in case of update, leave blank in case of add), or 4.
    • (Optional) isActive – Specifies if the pinned result collection should be active. Use this together with operation_id 5.
    • (Optional) key – The key of the pinned result collection. Use this together with operation_id 5.
    • (Optional) language – The language the item will be added for. Use this together with operation_id 5.
    • (Optional) limit – Maximum number of items to return. Use this together with operation_id 0 and 2.
    • (Optional) offset – Number of items to skip for pagination. Use this together with operation_id 0 and 2.
    • (Optional) phrase – Filter items by phrase. Use this together with operation_id 0 and 2.
    • (Optional) phrases – The phrases to add. Use this together with operation_id 5.
    • (Optional) pinned_result_id – The unique identifier for the pinned result. Use this together with operation_id 5 (in case of update, leave blank in case of add), or 6.
    • (Optional) priority – The priority for the item. Use this together with operation_id 5.
    • (Optional) sort – Sort field (for example, "priority" or "created"). Use this together with operation_id 0 and 2.
    • (Optional) targetKey – The target key for the pinned result item. Use this together with operation_id 5.
    • (Optional) title – The title of the pinned result collection. Use this together with operation_id 5.
  • Example prompts
    • Show me the pinned result collections in Optimizely Graph.
    • Create a pinned result collection with the phrase "winter sale" that targets the key winter-promo-page.
    • Update the pinned result with ID 42 and set the priority to 1.
    • List the pinned results in collection 15, sorted by priority.
    • Remove the pinned result collection with ID 7.
graph_synonyms – Manages synonyms in Optimizely Graph. Synonyms help you find content using alternative terms. See Synonyms in the Optimizely Graph documentation.
  • When to use
    • Retrieve the synonym mappings configured in a synonym slot.
    • Add or update synonym mappings so alternative search terms return the correct content.
    • Delete every synonym in Optimizely Graph to reset the synonym configuration.
    • Filter synonym retrieval by language or source routing for multilingual search experiences.
  • Parameters
    • operation_id – The unique identifier for the synonym operation. 
      • 0 – Get synonyms.
      • 1 – Add or update synonyms.
      • 2 – Delete all synonyms.
    • (Optional) language_routing – Language routing parameter to filter synonyms by language.
    • (Optional) source_routing – Source routing parameter to filter synonyms by source.
    • (Optional) synonym_slot – The synonym slot to use. Options include "one" or "two". Default is "one". Use this with operation_id 0 (get) or 1 (put).
    • (Optional) synonyms_body – The synonym mappings in the format: "term1, term2 => target" with each mapping on a new line. Example: "H20 => water\nSiteseeker, Welcome, Episerver => Optimizely". Use this with operation_id 1 (put).
  • Example prompts
    • Show me the synonyms configured in Optimizely Graph.
    • Add a synonym so searches for "Episerver" and "Welcome" return results for "Optimizely".
    • Update the synonyms in slot two with mappings for the rebranded product names.
    • Delete every synonym in Optimizely Graph.
    • Get the synonyms in slot one filtered by language routing "en".