Prompt Builder User Guide

The Prompt Builder is a tool that lets you create and manage AI prompts without needing to write code. Think of it as a visual workspace where you can build AI prompts, connect your data, transform data with code, test your work, and reuse your creations.

What You Can Do:

  • Build AI prompts - Create prompts for AI to follow when responding to users
  • Connect your data - Pull information from your Salesforce records to make responses more relevant
  • Transform data with code - Use JavaScript to process and enhance your data before sending it to AI
  • Test your work - Try out your AI prompts before making them live
  • Reuse your creations - Save successful prompts to use across different parts of your system

Step 1: Getting Started

  1. Open the Prompt Builder from your SimpleTranslate platform
  2. Choose your starting point:
    • Click “Create New Prompt” to start fresh
    • Select an existing prompt to edit or copy

Step 2: Set Up Your AI Model

  1. Select your AI engine (the type of AI you want to use)
  2. Choose a specific model from the dropdown

Step 3: Understanding System Parameters

When your prompt is called from Salesforce, you automatically get access to these system parameters:

  • data - Contains all the data sent from Salesforce
  • recordId - The ID of the current record (when sent from a Record page)
  • objectApiName - The API name of the current object (when sent from a Record page)

You can use these in your prompts like {{$data}}, {{$recordId}}, or {{$objectApiName}}.

Note: For testing purposes, you can fill in these parameters manually in the Prompt Builder. When the prompt is called from Salesforce, these manual values will be automatically overwritten with the actual data from Salesforce.

Step 4: Create Your Variables (Optional but Powerful)

Variables let you insert additional dynamic information into your prompts.

  1. In the left panel, click “Add Variable”
  2. Choose your variable type:
    • Text: Simple information like names or IDs (constant values)
    • JSON: Structured data from records (constant values)
    • SOQL Query: Pull specific data from Salesforce
  3. Name your variable (example: “customer_name” or “recent_cases”)
  4. Set up the variable:
    • For text: Just give it a name
    • For SOQL: (requires org credential setup at https://www.simpletranslate.io/dashboard/credentials)
      • Select your org credential in the “Choose your Target Credential” dropdown
      • Write a query like SELECT Name, Status FROM Case WHERE AccountId = '{{$recordId}}'

Step 5: Add JavaScript Scripts (Optional - For Simple Data Processing)

JavaScript scripts let you transform and enhance your data before it reaches the AI. Note: Only synchronous functions are supported.

  1. In the left panel, click “Add Script”
  2. Write JavaScript code with an execute() function that will be called
  3. Access your data:
    • Use data to access the Salesforce data
    • Use recordId and objectApiName for record information
    • Access any variables you've created by their names (like accounts, recent_cases, etc.)

Simple Example Script:

function execute() {
  // Get just the account names from the accounts variable
  const accountNames = accounts.map((acc) => acc.Name);
  
  // Count total cases
  const totalCases = recent_cases.length;
  
  // Return the processed data
  return {
    names: accountNames,
    caseCount: totalCases
  };
}

Use script results in your prompts like {{script_name.names}} or {{script_name.caseCount}}

Step 6: Write Your Prompt Messages

  1. Add a System Message (tells the AI how to behave):

    Example: “You are a helpful customer service assistant. Always be polite and professional.”

  2. Add User Messages (what the user will ask):

    Example: “Please help me with my recent order issue.”

  3. Add Variables to Your Messages:
    • Drag variables from the left panel into your message text
    • They'll appear as {{$variable_name}}
    • Example: “Hello {{$customer_name}}, I see you have {{$case_count}} open cases.”
    • Use system data: “Based on this record data: {{$data}}”
    • Use script results: “Account names: {{myScript.names}}”

Step 7: Configure Response Format

  1. Choose response type:
    • Text: Regular conversational responses
    • JSON: Structured data output (for integration with other systems)
  2. If using JSON, define your schema (the structure you want):
    {
  "name": "salesforce_account",
  "strict": false,
  "schema": {
    "type": "object",
    "properties": {
      "Salutation": {
        "type": "string",
        "readOnly": true
      },
      "FirstName": {
        "type": "string",
        "description": "html",
        "readOnly": true
      },
      "LastName": {
        "type": "string",
        "readOnly": true
      }
    },
    "required": []
  }
}

    Learn more about JSON Schema at json-schema.org

Important: When your prompt is called from Salesforce with a JSON schema, that schema will override the one you define here. When called from a Flow, it will use the JSON schema you've defined in the Prompt Builder.

Step 8: Test Your Prompt

  1. Fill in test values for your variables in the left panel
  2. Click “Test Prompt”
  3. Review the response in the right panel
  4. Check token usage to understand costs
  5. Make adjustments and test again until you're satisfied

Step 9: Save and Activate

  1. Give your prompt a unique name (API name)
  2. Add a descriptive label
  3. Click “Save”
  4. Click “Activate” to make it available for use in your system

Common Questions

How do I know if my prompt is working well?

Test frequently! Use the “Test Prompt” button with realistic data. Look for:

  • Responses that make sense and are helpful
  • Consistent formatting
  • Appropriate length (not too short or too long)
  • Relevant use of your variable data

What if my SOQL query isn't working?

Common issues:

  • Make sure field names are spelled correctly and exist in your Salesforce org
  • Use {{$recordId}} to reference the current record
  • Test your query in Salesforce first to make sure it returns data
  • Check that you have permission to access the fields you're querying

When should I use JavaScript scripts?

JavaScript is helpful when you need to:

  • Extract specific values from data (like just the names from a list)
  • Count items in lists
  • Combine multiple pieces of information
  • Format data for better readability

How do I write JavaScript scripts correctly?

Remember these key points:

  • Always wrap your code in a function execute() { }
  • Only use synchronous functions (no async/await or promises)
  • Access your variables directly by their names (like accounts, recent_cases)
  • Use data, recordId, and objectApiName for system parameters
  • Always return an object with the processed data you want to use
  • Keep it simple - basic operations work best

How do I make my AI responses more consistent?

Try these approaches:

  • Use a detailed system message that explains exactly how the AI should behave
  • Provide examples in your prompt of good responses
  • Include specific formatting instructions
  • Use JavaScript to standardize data formats before sending to AI

Can I use data from multiple Salesforce objects?

Yes! Create multiple SOQL variables that query different objects:

  • Variable 1: Account information
  • Variable 2: Recent cases
  • Variable 3: Contact details

Then use all of them in your prompt messages, along with the system {{$data}} parameter.

What's the difference between variables, parameters, and scripts?

Parameters are automatically provided by the system:

  • data - All data sent from Salesforce
  • recordId - Current record ID (when called from a Record page)
  • objectApiName - Current object type (when called from a Record page)

Variables are custom data you define (like SOQL queries for additional information).

Scripts are simple JavaScript code with an execute() function that processes parameters and variables to create new, enhanced data.

What can I access in my JavaScript scripts?

In your execute() function, you can access:

  • All system parameters (data, recordId, objectApiName)
  • All variables you've defined (directly by their variable names)
  • Standard JavaScript functions and methods (synchronous only)

The script must return an object with the processed data you want to use.

When will my JSON schema be used vs. overridden?

Your schema will be used when:

  • Called from a Flow
  • Testing in the Prompt Builder

Your schema will be overridden when:

  • Called directly from Salesforce with a JSON schema parameter

How do I troubleshoot if my prompt isn't working?

  1. Check the test response for error messages
  2. Verify your variables have valid test data
  3. Test your JavaScript scripts separately to ensure the execute() function returns expected data
  4. Make sure your scripts only use synchronous functions
  5. Simplify your prompt and test with basic text first
  6. Review your SOQL queries in Salesforce to ensure they return data
  7. Check your JSON schema if using structured output

Can I copy prompts between environments?

Yes! You can copy the prompt configuration and recreate it in another environment. Just make sure all the referenced fields and objects exist in the target environment.

How many prompts can I create?

There's no strict limit, but keep your prompts organized with clear, descriptive names and labels so you can find them easily later.

Need More Help?

Contact your system administrator or check the platform documentation for advanced features and troubleshooting.