@W-19036375 - Updates messages to be more uesful (#56)

* chore: updates messages to be more uesful

Author: rvwatch

README.md

@@ -4,7 +4,7 @@
 
 [![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/license/apache-2-0)
 
-A Salesforce CLI plugin for working with AppFramework apps, templates, assets, and services.
+A Salesforce CLI plugin for working with orchestrated apps, templates, assets, and services.
 
 ## Installation
 
@@ -59,7 +59,7 @@ yarn test:nuts
 
 ## Commands
 
-The plugin provides commands for working with AppFramework templates and applications.
+The plugin provides commands for working with templates and apps.
 
 ### Template Commands
 

messages/appframework.create.app.md

@@ -1,86 +1,118 @@
 # summary
 
-Create a new AppFramework app from a template.
+Create a new app from a template.
 
 # description
 
-Creates a new app from an existing template. The app will be initialized with the configuration defined in the template.
+Create a new orchestrated app using an existing template as the foundation. The app is initialized with the configuration, structure, and settings defined in the template, providing a quick start for app development.
+
+You can identify the template to use by either its unique ID or its name. Template IDs are guaranteed to be unique, while template names should be unique within an org. The new app inherits the template's configuration, but can be customized independently after creation.
+
+Use this command to quickly create apps with consistent configurations and accelerate your development workflow. The created app assets appear in Data Cloud and Tableau Next where you can customize as needed. You can manage the app from the App Install History page in Setup.
+
+You must have Data Cloud and Tableau Next enabled in your org and the AppFrameworkManageApp user permission to create apps. Both the template and the new app must be in the same org.
+
+# examples
+
+- Create an app from a template by ID:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --name "my_app" --template-id 01t000000000123
+
+- Create an app from a template by name:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --name "sales_app" --template-name "Sales_Template"
+
+- Create an app with a custom label and description:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --name "analytics_app" --template-name "Analytics_Template" --label "My Analytics App" --description "Custom analytics app"
+
+- Create an app with specific runtime configuration:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --name "dashboard_app" --template-id 01t000000000456 --runtime-method async --log-level debug
+
+- Create an app using a specific API version:
+
+  <%= config.bin %> <%= command.id %> --target-org mySandbox --name "test_app" --template-name "Test Template" --api-version 60.0
 
 # flags.target-org.summary
 
-Username or alias of the target org.
+Login username or alias for the target org.
 
 # flags.target-org.description
 
-Username or alias of the target org. Not required if the `target-org` configuration variable is already set.
+The target org to connect to for creating the app. This org must have Data Cloud and Tableau Next enabled and you must have the AppFrameworkManageApp user permission to create apps. The template must also exist in this org.
 
 # flags.api-version.summary
 
-Override the api version used for api requests made by this command.
+Override the API version used for API requests.
 
 # flags.api-version.description
 
-Override the api version used for api requests made by this command.
+Override the API version used for orchestrator API requests. Use this flag to specify a particular API version when the default version doesn't work with your org's configuration.
 
 # flags.name.summary
 
-Name for the new app (required)
+Name for the new app.
 
 # flags.name.description
 
-A unique identifier for the app. Must be unique within your org.
+A unique identifier for the app. Must be unique within your org. Use descriptive names that help identify the app's purpose. App names should follow your org's naming conventions.
 
 # flags.label.summary
 
-Label for the new app
+Label for the new app.
 
 # flags.label.description
 
-A human-readable label for the app. If not provided, the name will be used.
+A human-readable label for the app. This is displayed on the App Install History setup page and helps users identify the app's purpose. If not provided, the name will be used as the label.
 
 # flags.description.summary
 
-Description of the new app
+Description of the new app.
 
 # flags.description.description
 
-A description of what the app does.
+A description of what the app does and its intended use case. This helps users understand the app's purpose and functionality. The description appears on the App Install History page.
 
 # flags.template-id.summary
 
-ID of the template to use for creating the app
+ID of the template to use for creating the app.
 
 # flags.template-id.description
 
-ID of an existing template to use for creating the app. Either template-id or template-name must be provided.
+The unique identifier of the template to use for generating the new app.
 
 # flags.template-name.summary
 
-Name of the template to use for creating the app
+Name of the template to use for creating the app.
 
 # flags.template-name.description
 
-Name of an existing template to use for creating the app. Either template-id or template-name must be provided.
+The name of the template to use for generating the new app.
 
 # flags.runtime-method.summary
 
-Runtime method for the app (sync or async)
+Runtime method for the app.
 
 # flags.runtime-method.description
 
-Specifies how the app's runtime operates, either synchronously or asynchronously.
+Specifies the runtime method for the app execution. This affects how the app processes data and handles user interactions. Valid values are 'sync' and 'async'.
 
 # flags.log-level.summary
 
-Log level for the app
+Log level for the app.
 
 # flags.log-level.description
 
-Sets the logging level for the app. Valid options are: debug, info, warn, error.
+Sets the logging level for the app. This controls how much diagnostic information is captured during app execution. Valid values are 'debug', 'info', 'warn', and 'error'.
+
+# noTemplateSpecified
+
+No template specified. You must specify either a template ID with --template-id or a template name with --template-name.
 
 # fetchingTemplate
 
-Fetching template information...
+Fetching template details...
 
 # creatingApp
 
@@ -90,35 +122,57 @@ Creating app from template...
 
 Successfully created app with ID: %s
 
-# noTemplateSpecified
+# error.MissingRequiredFlag
+
+Either --template-id or --template-name must be provided.
 
-Either template-id or template-name must be specified.
+# error.MissingRequiredFlag.Actions
+
+- Use --template-id to specify a template by its unique ID
+- Use --template-name to specify a template by its name
+- Get template IDs and names using "sf orchestrator template list"
 
 # error.TemplateNotFound
 
-Template not found. Please check the template ID or name and try again.
+Template not found.
 
 # error.TemplateNotFound.Actions
 
-- Verify that the template exists in your organization
-- Check that you have spelled the template name correctly
-- Try using the template ID instead of the name
+- Verify the template ID or name is correct
+- Use "sf orchestrator template list" to see available templates
+- Check your permissions to view templates
+- Make sure you're connected to the correct org with --target-org
 
 # error.AppCreationError
 
-An error occurred while creating the app: %s
+Failed to create app: %s
 
 # error.AppCreationError.Actions
 
-- Check the error message above for more details
-- Ensure that AppFramework is enabled in your org
-- Ensure that your user has the necessary permissions
+- Verify that you have permission to create apps in the target org
+- Ensure the app name is unique within your org
+- Check that Data Cloud and Tableau Next are enabled in your org
+- Verify your authentication and org connection are valid
+- Try using a different API version with --api-version
 
-# examples
+# error.InvalidAppName
 
-- Create a new app using a template ID:
-  <%= config.bin %> <%= command.id %> --target-org myOrg --name "my_app" --template-id 01t000000000123
-- Create a new app using a template name:
-  <%= config.bin %> <%= command.id %> --target-org myOrg --name "sales_app" --template-name "Sales_Template"
-- Create a new app with additional details:
-  <%= config.bin %> <%= command.id %> --target-org myOrg --name "analytics_app" --template-name "Analytics_Template" --label "My Analytics App" --description "Custom analytics application" --runtime-method async --log-level debug
+App name "%s" is invalid or already exists.
+
+# error.InvalidAppName.Actions
+
+- Choose a unique name that doesn't exist in your org
+- Ensure the name follows your org's naming conventions
+- Use "sf orchestrator app list" to see existing app names
+- Avoid special characters and spaces in app names
+
+# error.InsufficientPermissions
+
+You don't have permission to create apps in this org.
+
+# error.InsufficientPermissions.Actions
+
+- Contact your Salesforce admin to request app creation permissions
+- Verify you're connected to the correct org with --target-org
+- Check that Data Cloud and Tableau Next are enabled in your org
+- Check that your user profile has the AppFrameworkManageApp user permission

messages/appframework.create.template.md

@@ -1,66 +1,92 @@
 # summary
 
-Create a new AppFramework template.
+Create a new template.
 
 # description
 
-Creates a new empty template that can be customized. Templates allow you to define reusable configurations for AppFramework applications.
+Create a new template that can be used as a blueprint for building orchestrated apps. Templates allow you to define reusable configurations, layouts, and settings that can be shared across multiple apps.
+
+Once created, templates appear in Tableau Next where users can use them to create new apps. Templates help standardize app development and ensure consistency across your org.
+
+You must have Data Cloud and Tableau Next enabled in your org and the AppFrameworkManageApp user permission to create templates. The template name must be unique within your org. This command works with production orgs, sandboxes, and scratch orgs that have orchestrated apps configured.
+
+# examples
+
+- Create a basic app template:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --name "my_template"
+
+- Create a template with a label for better identification:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --name "sales_template" --label "Sales Analytics Template"
+
+- Create a dashboard template with a specific subtype:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --name "dashboard_template" --type dashboard --subtype "analytics"
+
+- Create a comprehensive template with all metadata:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --name "analytics_template" --type app --subtype "tableau" --label "Sales Template" --description "Template for sales analytics apps"
+
+- Create a template using a specific API version:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --name "legacy_template" --api-version 60.0
 
 # flags.target-org.summary
 
-Login username or alias for the target org
+Login username or alias for the target org.
 
 # flags.target-org.description
 
-The target org to connect to for creating the template.
+The target org to connect to for creating the template. This org must have Data Cloud and Tableau Next enabled and you must have the AppFrameworkManageApp user permission to create templates.
 
 # flags.api-version.summary
 
-Override the api version used for api requests
+Override the API version used for API requests.
 
 # flags.api-version.description
 
-Override the api version used for api requests to the app framework.
+Override the API version used for orchestrator API requests. Use this flag to specify a particular API version when the default version doesn't work with your org's configuration.
 
 # flags.name.summary
 
-Name for the new template (required)
+Name for the new template.
 
 # flags.name.description
 
-A unique identifier for the template. Must be unique within your org.
+A unique identifier for the template. Must be unique within your org. Use descriptive names that help identify the template's purpose. Template names should follow your org's naming conventions.
 
 # flags.type.summary
 
-Type of template to create
+Type of template to create.
 
 # flags.type.description
 
-Specifies the type of template to create. Valid options are: app, component, dashboard, or lens. Defaults to 'app' if not specified.
+Specifies the type of template to create. Valid values are 'app', 'component', 'dashboard', or 'lens'. Defaults to 'app' if not specified. Choose the type that matches your intended use case for the template.
 
 # flags.subtype.summary
 
-Subtype for the template
+Subtype for the template.
 
 # flags.subtype.description
 
-An optional subtype categorization for the template (e.g., 'tableau' for app templates).
+An optional subtype categorization for the template (e.g., 'tableau' for app templates). Subtypes help organize templates and provide additional context about their intended use or underlying technology.
 
 # flags.label.summary
 
-Label for the new template
+Label for the new template.
 
 # flags.label.description
 
-A human-readable label for the template. This is displayed in the Analytics Studio UI.
+A human-readable label for the template. This is displayed in Tableau Next and helps users identify the template's purpose. Use clear, descriptive labels that explain what the template does.
 
 # flags.description.summary
 
-Description of the new template
+Description of the new template.
 
 # flags.description.description
 
-A description of what the template does. This is displayed in the Analytics Studio UI.
+A description of what the template does and its intended use case. This is displayed in Tableau Next and helps users understand when to use this template. Include information about the template's purpose, features, and any prerequisites.
 
 # fetchingApp
 
@@ -74,9 +100,36 @@ Creating template from app...
 
 Successfully created template with ID: %s
 
-# examples
+# error.TemplateCreationError
+
+Error creating template: %s
+
+# error.TemplateCreationError.Actions
+
+- Verify that you have permission to create templates in the target org
+- Ensure the template name is unique within your org
+- Check that Data Cloud and Tableau Next are enabled in your org
+- Verify your authentication and org connection are valid
+- Try using a different API version with --api-version
+
+# error.InvalidTemplateName
+
+Template name "%s" is invalid or already exists.
+
+# error.InvalidTemplateName.Actions
+
+- Choose a unique name that doesn't exist in your org
+- Ensure the name follows your org's naming conventions
+- Use "sf orchestrator template list" to see existing template names
+- Avoid special characters and spaces in template names
+
+# error.InsufficientPermissions
+
+You don't have permission to create templates in this org.
+
+# error.InsufficientPermissions.Actions
 
-- <%= config.bin %> <%= command.id %> --target-org myOrg --name "my_template"
-- <%= config.bin %> <%= command.id %> --target-org myOrg --name "sales_template" --type app --label "My Custom Template"
-- <%= config.bin %> <%= command.id %> --target-org myOrg --name "dashboard_template" --type dashboard --subtype "analytics"
-- <%= config.bin %> <%= command.id %> --target-org myOrg --name "analytics_template" --type app --subtype "tableau" --label "Sales Template" --description "Template for sales analytics apps"
+- Contact your Salesforce admin to request template creation permissions
+- Verify you're connected to the correct org with --target-org
+- Check that Data Cloud and Tableau Next are enabled in your org
+- Check that your user profile has the AppFrameworkManageApp permission