Tools
System tools
System tools for Optimizely Data Platform (ODP)
8 min
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 Data Platform (ODP) includes a set of system tools designed to support getting campaign information.
Note
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.
When to use
- Create a new realtime audience in ODP with a custom definition and ID.
- Create a new standard audience segment in ODP with a display name and definition.
- Build a new audience segment from a JSON definition to target specific customer behaviors.
- Configure a new ODP segment as part of a personalization or targeting strategy.
Parameters
- type – Type of audience: standard or realtime.
- definition – Definition of the audience in JSON format.
- (Optional) id – ID of the realtime audience to be created (required for realtime).
- (Optional) display_name – Display name of the audience (required for standard).
Example prompts
- Create a realtime ODP audience with id "high_value_customers" and a definition that targets customers with lifetime value over 500.
- I need a new standard audience in ODP called "Newsletter Subscribers" with a definition filtering by email opt-in status.
- Can you create a realtime ODP segment with id "recent_purchasers" and display name "Recent Purchasers" that includes customers who purchased in the last 30 days?
When to use
- Quickly create a real-time ODP audience from a plain-language description without writing JSON.
- Generate one real-time segment at a time using a conversational prompt.
- Build a targeted audience segment when you know the criteria but do not want to manually construct the definition.
Parameters
- user_query – A natural language query of a segment or audience to create in ODP. Use the exact query that the user wrote without rewriting it. The query will be normalized (lowercased, punctuation removed, and extra spaces cleaned).
Example prompts
- Create an ODP segment for customers who abandoned their cart in the last 7 days.
- Build me an ODP audience of users who have made more than 3 purchases in the past month.
- I need a real-time ODP segment for customers located in the United States who opened an email in the last 14 days.
When to use
- Understand what customer data is available in ODP, such as email, loyalty tier, or purchase history.
- Explore which event types are being tracked or inspect the event schema structure.
- Identify available fields before building audience segments or queries.
- Understand data relationships, for example how customers relate to orders or events.
- Answer questions like "what data do we have," "what fields are available," "show me the schema," or "what customer attributes exist."
Parameters
- (Optional) dimensions – Optional comma-separated list of specific dimension or object names to retrieve (for example, customers,events,products). Dimension names must be in lowercase, snake_case, and plural form (for example, customers not Customer). When provided, Opal only returns schema information for the specified dimensions. When omitted or empty, Opal returns the complete schema for all dimensions in the account.
Example prompts
- Show me the full ODP data model schema.
- What customer attributes are available in ODP?
- Fetch the ODP schema for customers and events only.
- What fields are available in the orders dimension in ODP?
When to use
- Look up a specific ODP audience or segment by its unique identifier.
- Inspect the definition, configuration, or metadata of an existing segment.
- Verify the details of a realtime or standard audience before updating or referencing it.
Parameters
- id – ID of segment to be returned.
- type – Type of segment: standard or realtime.
Example prompts
- Show me the details of the ODP realtime segment with id "high_value_customers".
- Get the definition of standard ODP audience "12345".
- Look up the ODP segment "recent_purchasers" — it's a realtime audience.
When to use
- List all available realtime or standard segments in ODP.
- Get an overview of existing ODP audiences and their descriptions.
- Discover which segments are configured before creating or updating one.
Parameters
- type – Type of segment: standard or realtime.
Example prompts
- Show me all realtime ODP segments.
- List all standard audiences in ODP.
- What ODP realtime audiences do we have configured?
an existing ODP dimension.
When to use
- Add fields to an existing dimension, such as customers, events, or orders.
- Create several fields on the same dimension in a single request.
- Add a field that contains sensitive data and mark it as personally identifiable information (PII) so ODP applies the correct access controls.
- Expose a field through the public API key by enabling public read access.
Parameters
- object – The dimension or object name to add fields to (for example, customers, events). Must be lowercase, snake_case, plural form.
- fields – JSON array of field definitions.
- Each field object accepts the following:
- name – Field name in snake_case.
- type – One of string, number, boolean, timestamp
- Each field also accepts the following optional properties:
- display_name – Human-readable label, auto-generated from name if omitted.
- description – Field description string.
- public_read – Enable access through the public API key, defaults to false.
- access_policies – PII access control, an object with a PII property containing enable and suggestible).
Example prompts
- Add a preferred_language string field to the customers dimension in ODP.
- Create fields loyalty_tier (string) and loyalty_points (number) on the customers object.
- Add a field called ssn of type string to customers and mark it as PII.
- Add a boolean field email_opt_in to customers and make it readable through the public API key.
ODP.
When to use
- Add a custom object to your ODP data model to represent a business entity that does not fit an existing dimension, such as Household or Loyalty Program.
- Define a dimension and its primary key before you add fields or relationships to it.
- Extend your ODP schema to support a data source or use case that existing dimensions do not cover.
- Model a physical or organizational entity, such as stores or franchises, that you plan to join to customers or events.
Parameters
- display_name – Human-readable label for the dimension (for example, Household).
- name – API identifier for the dimension. Lowercase letters, numbers, and underscores only. Must start with a letter. Maximum 255 characters (for example, household).
- primary_field_display_name – Human-readable label for the dimension's primary key (for example, Household ID).
- primary_field_name – API identifier for the primary key. Follows the same format rules as name (for example, household_id).
- primary_field_type – Data type of the primary key: string or number.
- (Optional) description – Free-text description of the dimension.
Example prompts
- Create an ODP dimension called "Household" with a string primary key "Household ID."
- Add a "Loyalty Program" object to ODP with a numeric primary key called "Program ID."
- Configure a custom dimension "Stores" in ODP with a string primary field store_id.
- Create a "Subscriptions" dimension in ODP with a string primary key subscription_id and a description explaining that it tracks recurring plans.
value copies continuously to a customer profile field.
When to use
- Sync a value from an events field to the matching customer profile field automatically.
- Persist an event value for longer than RTS (Real-time audiences)'s max 28 days window.
- Configure ongoing data flow from events into customer attributes without manual updates.
- Surface a behavioral signal on the customer profile so segments and campaigns target it.
Parameters
- source_field – The field name on the events dimension to copy from (for example, total_revenue).
- destination_field – The field name on the customers dimension to copy to (for example, lifetime_revenue).
Example prompts
- Link the total_revenue event field to the lifetime_revenue customer field in ODP.
- Create a field link so last_login_device from events updates the customers last_device field.
- Configure a continuous copy from events.email_opt_in to customers.email_opt_in.
- Copy the last_order_date event field onto the customer profile in ODP.
- Both fields must exist in the schema and have compatible data types before you create a link.
- Only events received after you create the link sync to the profile. If a link request fails, review the tool's response for details.
customer identification and merging.
When to use
- Register a type of customer identifier, such as a third-party account ID, so ODP matches and merges profiles on it.
- Add an identifier that campaigns use to message customers, such as a push token.
- Configure an identifier whose values do not map to a single person, such as a shared device token.
- Support a new integration that sends its own identifier values into ODP.
Parameters
- label – Human-readable identifier label, without the suffix (for example, Platform, not Platform ID). Used to derive both the display name and the API name.
- suffix – Identifier type: id, hash, number, token, alias, address, key, or push_token.
- merge_confidence – high (unique per person) or low (shared across people).
- (Optional) description – Short description of the identifier.
- (Optional) messaging – Whether campaigns use the identifier to message customers. Defaults to true when suffix is push_token.
- (Optional) public_read – Whether the public API key reads the identifier. Never enable this for PII. Defaults to false.
Example prompts
- Create a high-confidence identifier in ODP for "Shopify" with suffix id.
- Add a low-confidence "Device" identifier of type token in ODP.
- Configure a push token identifier called "Mobile App" that campaigns use for messaging.
- Create a "Loyalty" identifier in ODP with suffix number and high merge confidence.
between two dimensions in ODP.
When to use
- Link two existing dimensions, such as customers and products, through a parent-child relationship.
- Define how a field on one dimension references records in another dimension.
- Configure the join that queries and reports need to span related objects.
- Connect a custom dimension you created to a standard dimension, such as customers.
Parameters
- display_name – Human-readable name of the relationship, typically the parent field name (for example, First Product).
- name – API name. Lowercase letters, numbers, and underscores only. Must start with a letter (for example, first_product).
- parent_object_name – The dimension that contains the field pointing to another dimension (for example, customers).
- child_object – The dimension referenced by the parent's join field (for example, products).
- join_fields – JSON array of {parent, child} field-name pairs that describe how the two dimensions join.
Example prompts
- Create a relationship in ODP called "First Product" that joins customers.first_product_id to products.product_id.
- Link the orders and customers dimensions using order.customer_id and customers.customer_id.
- Configure a parent-child relationship named primary_store between customers and stores.
- Join my custom households dimension to customers on household_id.
When to use
- Retrieve recent event activity for a specific customer or set of customers in ODP.
- Investigate what events were tracked for a particular user, such as purchases, page views, or email interactions.
- Query ODP event logs to troubleshoot or validate that events are being recorded correctly.
- Analyze customer behavior patterns by querying event data with filters.
Parameters
- queries – The natural language query describing what event log data to retrieve from ODP.
Example prompts
- Show me the last 10 events for the customer with email "[email protected]" in ODP.
- Query ODP event logs for all purchase events in the last 24 hours.
- What events have been tracked for customer ID "abc123" in ODP?
When to use
- Get audience segment suggestions from ODP before committing to a specific definition.
- Explore possible audience configurations when you have a general targeting idea but want recommendations.
- Generate multiple audience segment options to compare before creating one.
Parameters
- None.
Example prompts
- Suggest ODP audiences for targeting high-value customers who have purchased more than three times.
- What ODP audience segments would you recommend for re-engaging users who have not visited in 30 days?
- Suggest some ODP segments for customers interested in electronics based on their browsing behavior.
When to use
- Modify the definition of an existing ODP audience segment.
- Change the display name of a standard audience in ODP.
- Update the targeting criteria for a realtime or standard segment that already exists.
Parameters
- id – Id of the audience to be updated.
- type – Type of audience: standard or realtime.
- definition – The segment definition in JSON format.
- (Optional) description – Description for the segment (required for realtime).
- (Optional) display_name – Display name of the audience (required for standard).
Example prompts
- Update the ODP realtime segment "high_value_customers" to include customers with lifetime value over 1000 instead of 500.
- Change the display name of standard ODP audience "12345" to "VIP Customers".
- Update the definition of the ODP realtime audience "recent_purchasers" to target purchases in the last 14 days instead of 30.
When to use
- Check whether an audience definition is valid before creating or updating a segment in ODP.
- Troubleshoot errors in an ODP audience definition by validating its structure.
- Confirm that a JSON audience definition conforms to ODP requirements before applying it.
Parameters
- definition – Definition of the audience in JSON format to validate.
- type – Type of audience: standard or realtime.
Example prompts
- Validate this ODP audience definition before I create the segment: {"filter": [{"field": "lifetime_value", "operator": "gt", "value": 500}]}.
- Check if this realtime ODP audience definition is valid: {"event": "purchase", "days": 30}.
- Can you validate my standard ODP audience definition to make sure it has no errors?
Note
If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applicationsTurn generative AI off across Optimizely applications.