From 763fc4a58979ccb94341951d4fa08f0f53e1481f Mon Sep 17 00:00:00 2001 From: Rishi Sheth <2817944+physik932@users.noreply.github.com> Date: Fri, 28 Apr 2023 10:01:38 -0400 Subject: [PATCH] Remove app from new ticket sidebar, update docs, cut a release (#37) * remove new ticket sidebar as location * bump version * update docs all around * doc update --- .github/CONTRIBUTING.md | 62 +++++++++++++++++++++++++++++++++-------- .github/DEPLOY.md | 26 ----------------- README.md | 32 ++++++++++++--------- package.json | 2 +- src/manifest.json | 3 +- 5 files changed, 72 insertions(+), 53 deletions(-) delete mode 100644 .github/DEPLOY.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 3cb7b09..6b18325 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,34 +1,74 @@ -## How to contribute to the URL Builder App V3 +# How to contribute to the URL Builder App V3 + +## Pull Requests -### Pull Requests When making a pull request, be sure the merging repo is `ibotta/url_builder_app` and not `zendesklabs/url_builder_app`! -#### **Did you find a bug?** +### **Did you find a bug?** * **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/ibotta/url_builder_app/issues). * If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/ibotta/url_builder_app/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring. -#### **Did you write a patch that fixes a bug?** +### **Did you write a patch that fixes a bug?** * Open a new GitHub pull request with the patch. * Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable. -#### **Do you intend to add a new feature or change an existing one?** +### **Do you intend to add a new feature or change an existing one?** * Suggest your change as a new issue and start writing code. * Do not open an issue on GitHub until you have collected positive feedback about the change. GitHub issues are primarily intended for bug reports and fixes. -## Build Instructions +## Setup + +The app is configured to use [Node 18](https://nodejs.org/en/download). We install node using [asdf-vm](https://asdf-vm.com/). + +Once you are setup with Node, you can run `npm install` to get the dependencies ready. + +### References + +- The Zendesk Command Lind Interface is the replacement of the Zendesk Apps Tools (ZAT) CLI and is used to build, test, and package Zendesk apps. You can find out more [in the Developer Docs](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/). +- If you are interested in updating or extending the API references, you can check out the [Zendesk API Reference](https://developer.zendesk.com/api-reference/). + +## Testing Changes + +After you have made local changes, use `npm test` to run tests in Jest. You can use webpack and `zcli` to test changes and live update the plugin: + +In one terminal window: +``` +# in the root directory +npm install +npm test +npm run watch +``` + +In another terminal: +``` +# in the root directory +zcli apps:server dist +``` + +Navigate to a ticket in your Zendesk instance, and append `?zcli_apps=true` to the URL to load your local version of the app. Any CSS, JS or HTML changes should get picked up by Webpack and reloaded live. If you need to change the JSON string for URLs, you'll need to restart the `zcli apps:server dist` command. + +## Compile and deploy from source + +Compiling the app from source uses [zcli](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/). Follow the Zendesk docs to get set up and authenticate to your Zendesk instance. + +After authentication, follow these steps to compile and upload the app for the first time: -`npm run package` - This will build the `dist` folder locally after `validate` has passed. `dist/tmp` will contain the ZIP you need to upload your version of the app. +1) `npm install` +1) `npm test` +1) `npm run build` +1) `zcli apps:validate dist` -- Validate the app and manifest. +1) `zcli apps:create dist` -- This will upload the app after validation to your Zendesk Instance. -### Testing changes using ZCLI +## Updating the App -The Zendesk Command Lind Interface is the replace fo Zendesk Apps Tools (ZAT) and is used to build, test, and package Zendesk apps. You can find out more [in the Developer Docs](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/) +To update the app, you can use `zcli apps:update dist` after the initial upload and creation of the app. -### API Reference +## Generating a ZIP file -If you are interested in updating or extending the API references, you can check out the [Zendesk API Reference](https://developer.zendesk.com/api-reference/). \ No newline at end of file +You can use `zcli apps:package dist` to generate a zip file into `dist/tmp` that you can manually upload. \ No newline at end of file diff --git a/.github/DEPLOY.md b/.github/DEPLOY.md deleted file mode 100644 index 3c69576..0000000 --- a/.github/DEPLOY.md +++ /dev/null @@ -1,26 +0,0 @@ -Note: Run commands in the root app directory. - -Compile the app for DEV -=============== -1) `npm install` -2) `npm run watch` -3) Open a new command line window in the root app directory -4) `zcli apps:server dist` will serve the app to your Zendesk instance. When prompted, enter in a JSON formatted string with URLS (See README for more instructions on format). -5) Navigate to a ticket in your Zendesk instance and append the URL with `?zcli_apps=true` - -Compile the app for PROD -=============== -1) `npm install` -2) `npm run build` - -To run the tests -=============== -1) `npm install` -2) `npm run test` - -Uploading the app -============== -1) `npm install` -2) `npm run build` -3) `npm validate` -- this uses `zcli` to validate any misconfigurations in the `manifest.json` or missing files in `dist`. -4) If you have not created the app in your instance yet, use `zcli apps:create dist` to do so. If you have already uploaded the app, you can use `zcli apps:update dist` to update it. \ No newline at end of file diff --git a/README.md b/README.md index 9e9c5c0..a90a3bd 100644 --- a/README.md +++ b/README.md @@ -14,17 +14,29 @@ A Zendesk App to help you generate links for agents. "zcli": ">=1.0.0-beta.32" ``` -# Usage Instructions +## Usage +### Deploying from ZIP -## Build, Test, and Upload +To quickly install this application, navigate to the latest releases and download the attached `app-.zip`. You can upload this to Zendesk +Attached to the latest release is the `app-.zip` asset that can be [uploaded to your Zendesk instance](https://developer.zendesk.com/documentation/apps/getting-started/uploading-and-installing-a-private-app/#uploading-and-installing-a-private-app-in-zendesk): -This app is not currently available in the Zendesk App Marketplace. However, you can upload a copy of it to your Zendesk instance by following the instructions in [deployment docs](./.github/DEPLOY.md).. +1. In Admin Center, click the Apps and integrations icon () in the sidebar, then select Apps > Zendesk Support apps. +2. Click Upload App. +3. Enter a Name for the app. +4. Click Choose file and select the zip file for your private app. +5. Click Save. +6. In the pop-up box that appears, click Agree and upload this App. +7. When prompted, click Install. -## Changing Settings +#### Build, Test, and Upload + +If you are interested in extending the app or simply building from source, check out the [CONTRIBUTING](./.github/CONTRIBUTING.md#compile-and-deploy-from-source) docs. + +### Changing Settings Once the app is uploaded, you can Install it to the configured areas of Zendesk. You can update the JSON array by entering the Zendesk Admin Center > Apps & Integrations > Private Apps > (Whatever you named the app, or URL BuildeR app V3 by default). -## Configuring the JSON Array of URLs +### Configuring the JSON Array of URLs The following is an example of what can be entered into this app's settings: @@ -55,24 +67,20 @@ This example will generate the following HTML inside the app: ### Sample Placeholders -Below is a list of just a few of the available placeholders. To see the full list of fields, please see the [Zendesk Apps Reference - API Reference](https://developer.zendesk.com/api-reference/apps/introduction/). You can find fields available to [all locations](https://developer.zendesk.com/api-reference/apps/apps-support-api/all_locations/), and the [ticket and new ticket sidebar](https://developer.zendesk.com/api-reference/apps/apps-support-api/ticket_sidebar/). +Below is a list of just a few of the available placeholders. To see the full list of fields, please see the [Zendesk Apps Reference - API Reference](https://developer.zendesk.com/api-reference/apps/introduction/). You can find fields available to [all locations](https://developer.zendesk.com/api-reference/apps/apps-support-api/all_locations/) and the [ticketsidebar](https://developer.zendesk.com/api-reference/apps/apps-support-api/ticket_sidebar/). ``` -* {{ticket.id}} //not available for new tickets +* {{ticket.id}} * {{ticket.description}} * {{ticket.requester.id}} * {{ticket.requester.name}} * {{ticket.requester.email}} * {{ticket.requester.externalId}} -* {{ticket.requester.firstName}} -* {{ticket.requester.lastName}} * {{ticket.requester.user_fields.YYY}} = custom user fields can be used * {{ticket.assignee.user.id}} * {{ticket.assignee.user.name}} * {{ticket.assignee.user.email}} * {{ticket.assignee.user.externalId}} -* {{ticket.assignee.user.firstName}} -* {{ticket.assignee.user.lastName}} * {{ticket.assignee.group.id}} * {{ticket.assignee.group.name}} * {{ticket.custom_field_XXXXXXX}} // XXXXXXX = custom field id @@ -81,8 +89,6 @@ Below is a list of just a few of the available placeholders. To see the full li * {{currentUser.name}} * {{currentUser.email}} * {{currentUser.externalId}} -* {{currentUser.firstName}} -* {{currentUser.lastName}} ``` ## Issues diff --git a/package.json b/package.json index 2dea048..9cb30cc 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "url_builder_app", - "version": "2.0.0", + "version": "3.0.0", "description": "A Zendesk plugin to render URLs", "keywords": [ "zendesk", diff --git a/src/manifest.json b/src/manifest.json index a3a3178..b313c66 100644 --- a/src/manifest.json +++ b/src/manifest.json @@ -9,8 +9,7 @@ "private": false, "location": { "support": { - "ticket_sidebar": "assets/iframe.html", - "new_ticket_sidebar": "assets/iframe.html" + "ticket_sidebar": "assets/iframe.html" } }, "parameters": [