diff --git a/src/markdown-pages/build-apps/serve-publish-subscribe/catalog.mdx b/src/markdown-pages/build-apps/serve-publish-subscribe/catalog.mdx index 08365c482..1112c18ea 100644 --- a/src/markdown-pages/build-apps/serve-publish-subscribe/catalog.mdx +++ b/src/markdown-pages/build-apps/serve-publish-subscribe/catalog.mdx @@ -1,122 +1,342 @@ --- path: '/build-apps/publish-deploy/catalog' -duration: '30 min' -title: 'Update your Nerdpack's catalog information' +title: "Update your Nerdpack's catalog information" +duration: '10 minutes' template: 'GuideTemplate' description: 'Learn to describe your Nerdpack in the catalog' tileShorthand: - title: 'Update your Nerdpack's catalog information' + title: "Update your Nerdpack's catalog information" description: 'Update catalog info' tags: - nerdpack - catalog --- -## Add images and metadata to your apps + -Application creators can include a description of what their apps do and how they're best used when they build an app. They can also include screenshots, icons, and metadata that help to make them easy to spot amongst other applications. +Add screenshots, descriptions, and other metadata to your Nerdpack, and upload it all to the New Relic One catalog. -Some metadata is added automatically when an app is published: + -- Related entities, listed if there are any. -- Origin label to indicate where the app comes from: local, custom, or public. +## Check your permissions -![app metadata in catalog](../../images/build-an-app/app_metadata.png) +To publish your app or visualization and update its catalog information, you need: -The New Relic One CLI enables you to provide the information and images you want to include with your application. Then it's a matter of kicking off a catalog command that validates the information and saves it to the catalog. +- Access to the account that published it +- The [necessary permissions for managing Nerdpacks](/build-apps/permission-manage-apps) + +## Publish your Nerdpack + +You need to [publish](/build-apps/publish-deploy/publish) Nerdpacks that you create before you can update their catalog information. + +## Update your Nerdpack's catalog metadata + +After you've published your Nerdpack to the New Relic One catalog, update the Nerdpack's metadata to let users know all about your Nerdlets or visualizations. + + + + + +```md fileName=catalog/documentation.md +``` + +```json fileName=catalog/config.json +{ + "tagline": "", + "details": "", + "repository": "", + "whatsNew": "", + "support": { + "email": { + "address": "" + }, + "issues": { + "url": "" + }, + "community": { + "url": "" + } + } +} +``` + + -Update the New Relic One CLI to ensure you're working with the latest version. +Go to [New Relic](https://one.newrelic.com): + +![Homepage](../../../images/serve-publish-subscribe/home.png) + + + + + +Navigate to **Apps**: + +![Navigate to the Apps page](../../../images/serve-publish-subscribe/nav-to-apps.png) + + + + + +Find your published Nerdpack under **New Relic One catalog**: + +![Published app or visualization](../../../images/serve-publish-subscribe/published-app.png) + +Notice that there is no information on the **Apps** or details page other than the Nerdpack's name and the brief description found in _nr1.json_: + +![Published Nerdpack](../../../images/serve-publish-subscribe/demo-app-no-details.png) + +There are no screenshots, icons, details, or what's new features. To add these, your Nerdpack needs a _catalog_ directory. + + + + + +From the root of your Nerdpack, create a _catalog_ directory to house your Nerdpack's screenshots and metadata: + +```sh +nr1 create --type catalog +[output] {success}✔{normal} Component created successfully! +[output] {purple}catalog{normal} is available at "./catalog" +``` + +Inside your _catalog_ directory, you'll find specific files and directories for portraying information about your Nerdpack to your users: + +```sh +ls catalog +[output] README.md additionalInfo.md config.json documentation.md {blue}screenshots +``` + +| File | Description | +|---|---| +| _README.md_ | A markdown file that instructs you how to use the information and metadata in _catalog_ | +| _config.json_ | A JSON file that contains the following fields:

  • `tagline`: A brief headline for the application. This cannot exceed 30 characters.
  • `repository`: The URL for the Nerdpack's remote repository. This cannot exceed 1000 characters.
  • `details`: The purpose of the Nerdpack and how to use it. This cannot exceed 1000 characters. Use newlines for formatting, and don't include any markdown or HTML.
  • `support`: An object that contains:
    • `issues`: A URL for the repository's issues list. For example, the **Issues** tab if using GitHub.
    • `email`: A valid email address for the team supporting the application
    • `community`: A URL for a support thread, forum, or website for troubleshooting and usage support
  • `whatsNew`: A bulleted list of changes in the current release version. This cannot exceed 500 characters. Use newlines for formatting, and don't include markdown or HTML.
Check out our [Pageview Map application's _config.json_](https://github.com/newrelic/nr1-pageview-map/blob/main/catalog/config.json) to see a real-life implementation. +| _documentation.md_ | A markdown file that tells users how to use the Nerdpack's Nerdlets or visualizations. This shows in the detail view's **Documentation** tab. | +| _additionalInfo.md_ | An optional markdown file for any additional information about using your application | +| _screenshots_ | A directory that contains screenshots of your Nerdlets or visualizations. This can contain no more than 6 images. All screenshots must meet the following criteria:

  • 3:2 aspect ratio
  • PNG format
  • landscape orientation
  • 1600 to 2400 pixels wide
| + + + + + +Update your Nerdpack's _documentation.md_ file: + +```md fileName=catalog/documentation.md +Enter your first and last name into the fields provided. When you're done, press **Submit** to see a personalized "Hello!" message. +``` + + + + + +Update your _config.json_ file: + +```json fileName=catalog/config.json +{ + "tagline": "Say hi!", + "details": "DemoApp says Hello to a user.", + "repository": "https://github.com/newrelic/developer-website", + "whatsNew": "feat: Initial commit" +} +``` + + + + + +Include screenshots in your _screenshots_ directory. -```bash -nr1 update + + + + +Submit the information to the New Relic One catalog: + +```sh +nr1 catalog:submit +[output] Uploading screenshots... +[output] {success}✔{normal} Screenshots uploaded +[output] {success}✔{normal} Updated metadata for DemoApp 1.0.0 ``` -Add catalog metadata and screenshots. +Go to the catalog to see your changes: -Run `nr1 create` and then select `catalog` to add a catalog folder to your New Relic One project. The folder contains the following empty files and folder. Add the information as described in the following sections for the process to succeed. +![DemoApp with a tagline](../../../images/serve-publish-subscribe/demo-app-tagline.png) -### screenshots folder +Click your Nerdpack to see the new details: -A directory that must contain no more than 6 images and meet these criteria: +![App details](../../../images/serve-publish-subscribe/demo-app-details.png) -- 3:2 aspect ratio -- PNG format -- landscape orientation -- 1600 to 2400 pixels wide + -### `documentation.md` + -A markdown file that presents usage information pulled into the **Documentation** tab for the application in the catalog. +## Update your Nerdpack's icons -### `additionalInfo.md` +Within a Nerdpack, you can set two types of icons: -An optional markdown file for any additional information about using your application. +- One for your entire Nerdpack, which represents your Nerdpack in the catalog +- One for each of your launchers, which represents your Nerdlets -<> +Replace these icons and publish your Nerdpack to see the changes. -### `config.json` + + + + +Update the _icon.png_ in the root of your Nerdpack. This icon is used in the catalog and the Nerdpack's detail page. -A JSON file that contains the following fields: + + + -- `tagline`: A brief headline for the application. Must not exceed 30 characters. -- `repository`: The URL to the GitHub repo for the application. Must not exceed 1000 characters. -- `details`: Describes the purpose of the application and how to use it. Information must not exceed 1000. Use carriage returns for formatting. Do not include any markdown or HTML. -- `support`: An object that contains: - - `issues`: A valid URL to the GitHub repository's issues list, generally the GitHub **Issues** tab for the repo. - - `email`: A valid email address for the team supporting the application. - - `community`: URL to a support thread, forum, or website for troubleshooting and usage support. -- `whatsNew`: A bulleted list of changes in this version. Must not exceed 500 characters. Use carriage returns for formatting. Do not include markdown or HTML. +If you're building a Nerdpack with one or more launchers, update the _icon.png_ in each of your launcher's subfolders. -Example: + -```json + + +Update your _package.json_ version: + +```json fileName=package.json lineHighlight=4 { - "tagline": "Map your workloads & entities", - "repository": "https://github.com/newrelic/nr1-workload-geoops.git", - "details": "Describe, consume, and manage Workloads and Entities in a geographic \n - model that supports location-specific KPI's, custom metadata, drill-down navigation into Entities \n - and Workloads, real-time configuration, and configuration via automation using the newrelic-cli.", - "support": { - "issues": { - "url": "https://github.com/newrelic/nr1-workload-geoops/issues" + "private": true, + "name": "demo-app", + "version": "1.0.1", + "scripts": { + "start": "nr1 nerdpack:serve", + "test": "exit 0" }, - "email": { - "address": "opensource+nr1-workload-geoops@newrelic.com" + "nr1": { + "uuid": "f2dbc999-e9a3-49b9-933d-5a704c6750bd" }, - "community": { - "url": "https://discuss.newrelic.com/t/workload-geoops-nerdpack/99478" - } - }, - "whatsNew": "\n-Feat: Geographic mapping of Workloads and Entities\n - -Feat: Programmatic alerting rollup of underlying Entities\n - -Feat: Custom KPI measurement per location\n - -Feat: Empty-state edit workflow\n - -Feat: JSON file upload format\n-Feat: Published (in open source docs) guide to automating configuration using the newrelic-cli" + "dependencies": { + "prop-types": "^15.6.2", + "react": "^16.6.3", + "react-dom": "^16.6.3" + }, + "browserslist": [ + "last 2 versions", + "not ie < 11", + "not dead" + ] } ``` - +This allows you to publish a new version of your Nerdpack. + + + + + +[Publish](/build-apps/publish-deploy/publish) your Nerdpack: + +```sh +nr1 nerdpack:publish +``` -Save the metadata and screenshots to the catalog. +Update your `whatsNew` string in _catalog/config.json_: -This validates the information you added to the catalog directory against the criteria described in the previous step, and saves it to the catalog. +```json fileName=catalog/config.json +{ + "tagline": "Say hi!", + "details": "DemoApp says Hello to a user.", + "repository": "https://github.com/newrelic/developer-website", + "whatsNew": "feat: Add new icons" +} +``` + +This will tell users what you added in the latest version of your Nerdpack. + + + + + +Submit this new metadata to the catalog: -```bash +```sh nr1 catalog:submit +[output] Uploading screenshots... +[output] {success}✔{normal} Screenshots uploaded +[output] {success}✔{normal} Updated metadata for DemoApp 1.0.1 ``` - \ No newline at end of file + + +Go to the catalog and [subscribe to your Nerdpack](/build-apps/publish-deploy/subscribe) to see your new icon: + +![DemoApp catalog icon](../../../images/serve-publish-subscribe/demo-app-details-icon.png) + +![DemoApp launcher icon](../../../images/serve-publish-subscribe/demo-app-launcher-icon.png) + + + + + + + +## Resolve issues with submitting catalog information + +Sometimes, when you work with catalog metadata, you may run into issues. Consider some common solutions for resolving these issues. + +### Publish your Nerdpack + +Remember that you can only submit catalog metadata for Nerdpacks that have already been published. If you try to submit information for a Nerdpack that hasn't been published, the CLI will try to help: + +```sh +nr1 catalog:submit +[output] Uploading screenshots... +[output] {error}›{normal} Error: {error}1 error while updating DemoApp 1.0.0 +[output] {error}› +[output] {error}› Invalid Version: Nerdpack version 1.0.0 not found. Have you run `nr1 nerdpack:publish` yet? +[output] {error}›{normal} Code: UNKNOWN +``` + +### Resize your images + +Screenshots for the catalog must meet the criteria specified previously in this guide. If they don't, the CLI will try to help: + +```sh +nr1 catalog:submit +[output] Uploading screenshots... +[output] {error}›{normal} Error: {error}2 errors while updating DemoApp 1.0.1 +[output] {error}›{normal} +[output] {error}›{normal} {blue}catalog/screenshots/screenshot.png +[output] {error}›{normal} {red}Invalid Screenshot: screenshot.png has a size ratio of 4:2. Update size ratio to 3:2. +[output] {error}›{normal} +[output] {error}›{normal} {blue}catalog/screenshots/screenshot.png +[output] {error}›{normal} {red}Invalid Screenshot: screenshot.png has a width of 3054px. Update size to be between 1600px and 2400px. +[output] {error}›{normal} Code: UNKNOWN +``` + +### Check the length of your strings + +Most of the content in _config.json_ has string-length requirements. Make sure you review those requirements and adhere to them when you update your _config.json_ file. Otherwise, you'll see errors when you try to submit your configuration to the catalog: + +```sh +nr1 catalog:submit +[output] Uploading screenshots... +[output] {success}✔{normal} Screenshots uploaded +[output] {error}›{normal} Error: {error}2 errors while updating DemoApp 1.0.1 +[output] {error}›{normal} +[output] {error}›{normal} {blue}catalog/config.json +[output] {error}›{normal} {error}Invalid Metadata: `details` has a character length of 2204. Must be no longer than 1000 characters +[output] {error}›{normal} +[output] {error}›{normal} {blue}catalog/config.json +[output] {error}›{normal} {error}Invalid Metadata: `tagline` has a character length of 266. Must be no longer than 30 characters +[output] {error}›{normal} Code: UNKNOWN +``` \ No newline at end of file