diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f1b7396..8f40fd4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,22 +4,23 @@ By participating in this project, you agree to abide our [code of conduct] -**✨ Thank you for contributing to z4j! ✨** +Thank you for contributing to z4j -PBU projects are open to contributions! Below are some instructions on best practices and standards used when contributing to this project! +Below are some instructions on best practices and standards used when contributing to this project! ## Style Guide - This project uses [google's java style guide]. - We follow (and enforce) [conventional commits] in this repo. ## Set up your machine -`z4j` is written in java 21, runs on [graal community distro], and uses [gradle] as its build tool. +`z4j` is written in java 21, compiled with the [graalvm], and uses [gradle] as its build tool. -### Prerequisites: +### What you need locally: - Gradle doesn't need to be installed locally, a [gradle wrapper] is provided with this repo. - Docker or Podman installed and running at compile time - [Graal-CE 21] - [Git] +- a decent IDE like IntelliJ #### Getting Started Create your own fork of `z4j`, clone your fork and call the gradle wrapper to build the project @@ -30,7 +31,7 @@ cd z4j ./gradlew build ``` ## IDE -Any IDE specific documentation will reference IntelliJ configured to [delegate build and run actions to gradle]. +Any IDE specific documentation in this repo will reference IntelliJ, specifically one configured to [delegate build and run actions to gradle]. # Testing @@ -45,6 +46,8 @@ To run the tests, you will need: 1. A Zendesk account with the Help Center activated, along with an API token for access. 2. Users with [different roles] created in your Zendesk instance. 3. [Environment variables] configured in your test environment +4. [Custom ticket fields] configured in your sandbox +5. [Expected locales] enabled in your help center. ### Required Roles for Testing @@ -58,6 +61,8 @@ You'll need to set up the following users in your Zendesk account:
User Configuration View a user's configured role by navigating to {domain}.zendesk.com/admin/people/team/members, then selecting a user. + + @@ -127,6 +132,7 @@ A dropdown menu to categorize the ticket's subject. * **Field ID**: `40971535122835` **Field values:** + | Field option title | Tag | | :----------------- | :---- | | Delivery | `delivery` | @@ -142,6 +148,7 @@ A dropdown menu to specify the type of refund being processed. * **Field ID**: `45241019372563` **Field values:** + | Field option title | Tag | Default | | :----------------- | :---- |:---:| | Full Refund | `full_refund` | | @@ -217,6 +224,16 @@ A multi-select dropdown for reporting one or more errors. --- +## Expected Locales +A few locales are to be enabled. See Zendesk's current docs on how to do that. + +The following languages are required for testing: +- Spanish (`es`) +- French (`fr`) +- English (`en`) + +--- + ## Testing Strategy One of the most important parts of contributing to z4j is getting tests right. A test is written adequately if: @@ -292,6 +309,8 @@ This method is a little tricky to test for negative tests because the only way t [branches of code]:https://medium.com/@zubairkhansh/branch-testing-and-branch-coverage-3fb4bbd9f949 [code of conduct]:CODE_OF_CONDUCT.md [conventional commits]:https://www.conventionalcommits.org/en/v1.0.0/ +[Custom ticket fields]:#custom-ticket-fields-setup +[Expected locales]:#Expected-Locales [delegate build and run actions to gradle]:https://www.jetbrains.com/help/idea/work-with-gradle-projects.html#delegate_build_gradle [different roles]:#Required-Roles-for-Testing [google's java style guide]:https://google.github.io/styleguide/javaguide.html @@ -299,7 +318,7 @@ This method is a little tricky to test for negative tests because the only way t [gradle]:https://gradle.org/maven-and-gradle/ [gradle wrapper]:https://docs.gradle.org/current/userguide/gradle_wrapper_basics.html [Git]:https://gist.github.com/Jonathan-Zollinger/8d9a231a57f3d33ff813989c34df00e0 -[graal community distro]:https://www.graalvm.org/release-notes/JDK_21/ +[graalvm]:https://www.graalvm.org/release-notes/JDK_21/ [Graal-CE 21]:https://www.graalvm.org/jdk21/docs/ [Environment Variables]:#Required-Environment-Variables [source function]:https://gist.github.com/Jonathan-Zollinger/96160f971741f5f3a8749d10127e7764 diff --git a/build.gradle.kts b/build.gradle.kts index 0e1dab2..51ef51a 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -38,6 +38,7 @@ dependencies { "lombok"("org.projectlombok:lombok:${lombokVersion}") runtimeOnly("org.yaml:snakeyaml") testImplementation("net.datafaker:datafaker:$dataFakerVersion") + testImplementation("ch.qos.logback:logback-classic") } java { @@ -87,11 +88,6 @@ tasks.jacocoTestReport { xml.required.set(true) html.required.set(true) } - classDirectories.setFrom(files(classDirectories.files.map { - fileTree(it) { - exclude("lol/pbu/Application.class") - } - })) } tasks.test { diff --git a/cleanup_categories.ps1 b/cleanup_categories.ps1 new file mode 100644 index 0000000..9cab475 --- /dev/null +++ b/cleanup_categories.ps1 @@ -0,0 +1,77 @@ +#Requires -Version 5.1 + +<# +.SYNOPSIS + This script paginates through all pages of the GET /api/v2/help_center/categories endpoint and deletes all categories. +.DESCRIPTION + This script will first check for the presence of the following environment variables: + - Z4J_URL: The URL of your Zendesk instance (e.g., https://your-subdomain.zendesk.com) + - Z4J_TOKEN: Your Zendesk API token. + - Z4J_ADMIN_EMAIL: The email address of a Zendesk admin. + + If all environment variables are present, it will then: + 1. Paginate through all categories. + 2. Delete each of those categories. +.NOTES + Author: Jonathan + Date: $(Get-Date -Format "yyyy-MM-dd") +#> + +param() + +#region Environment Variable Validation +$requiredEnvVars = @("Z4J_URL", "Z4J_TOKEN", "Z4J_ADMIN_EMAIL") +$missingEnvVars = @() + +foreach ($var in $requiredEnvVars) { + if (-not (Test-Path "env:$var")) { + $missingEnvVars += $var + } +} + +if ($missingEnvVars.Count -gt 0) { + Write-Error "The following environment variables are not set: $($missingEnvVars -join ', ')" + exit 1 +} +#endregion + +$Z4JUrl = $env:Z4J_URL +$apiToken = $env:Z4J_TOKEN +$adminEmail = $env:Z4J_ADMIN_EMAIL + +$credentials = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${adminEmail}/token:${apiToken}")) +$headers = @{ + "Authorization" = "Basic $credentials" + "Content-Type" = "application/json" +} + +$nextPage = "$Z4JUrl/api/v2/help_center/categories" + +do { + try { + Write-Host "Fetching categories from $nextPage" + $response = Invoke-RestMethod -Uri $nextPage -Method Get -Headers $headers + + if ($null -ne $response.categories) { + foreach ($category in $response.categories) { + Write-Host "Deleting category: $($category.name) (ID: $($category.id))" + $deleteUrl = "$Z4JUrl/api/v2/help_center/categories/$($category.id)" + try { + Invoke-RestMethod -Uri $deleteUrl -Method Delete -Headers $headers + Write-Host "Successfully deleted category: $($category.name)" + } + catch { + Write-Error "Error deleting category with ID $($category.id): $_" + } + } + } + + $nextPage = $response.next_page + } + catch { + Write-Error "Error fetching categories: $_" + exit 1 + } +} while ($null -ne $nextPage) + +Write-Host "Category cleanup complete." \ No newline at end of file diff --git a/cleanup_user_segments.ps1 b/cleanup_user_segments.ps1 index 568b07a..4f7b908 100644 --- a/cleanup_user_segments.ps1 +++ b/cleanup_user_segments.ps1 @@ -5,9 +5,9 @@ This script paginates through all pages of the GET /api/v2/help_center/user_segments endpoint and deletes any user segment that is not built-in. .DESCRIPTION This script will first check for the presence of the following environment variables: - - ZENDESK_URL: The URL of your Zendesk instance (e.g., https://your-subdomain.zendesk.com) - - ZENDESK_API_TOKEN: Your Zendesk API token. - - ZENDESK_ADMIN_EMAIL: The email address of a Zendesk admin. + - Z4J_URL: The URL of your Zendesk instance (e.g., https://your-subdomain.zendesk.com) + - Z4J_TOKEN: Your Zendesk API token. + - Z4J_ADMIN_EMAIL: The email address of a Zendesk admin. If all environment variables are present, it will then: 1. Paginate through all user segments. @@ -21,7 +21,7 @@ param() #region Environment Variable Validation -$requiredEnvVars = @("ZENDESK_URL", "ZENDESK_API_TOKEN", "ZENDESK_ADMIN_EMAIL") +$requiredEnvVars = @("Z4J_URL", "Z4J_TOKEN", "Z4J_ADMIN_EMAIL") $missingEnvVars = @() foreach ($var in $requiredEnvVars) { @@ -36,9 +36,9 @@ if ($missingEnvVars.Count -gt 0) { } #endregion -$zendeskUrl = $env:ZENDESK_URL -$apiToken = $env:ZENDESK_API_TOKEN -$adminEmail = $env:ZENDESK_ADMIN_EMAIL +$Z4JUrl = $env:Z4J_URL +$apiToken = $env:Z4J_TOKEN +$adminEmail = $env:Z4J_ADMIN_EMAIL $credentials = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${adminEmail}/token:${apiToken}")) $headers = @{ @@ -46,7 +46,7 @@ $headers = @{ "Content-Type" = "application/json" } -$nextPage = "$zendeskUrl/api/v2/help_center/user_segments" +$nextPage = "$Z4JUrl/api/v2/help_center/user_segments" do { try { @@ -57,7 +57,7 @@ do { foreach ($segment in $response.user_segments) { if ($segment.built_in -eq $false) { Write-Host "Deleting user segment: $($segment.name) (ID: $($segment.id))" - $deleteUrl = "$zendeskUrl/api/v2/help_center/user_segments/$($segment.id)" + $deleteUrl = "$Z4JUrl/api/v2/help_center/user_segments/$($segment.id)" try { Invoke-RestMethod -Uri $deleteUrl -Method Delete -Headers $headers Write-Host "Successfully deleted user segment: $($segment.name)" diff --git a/src/main/resources/z4j.yaml b/src/main/resources/z4j.yaml index ec029e8..7de98a7 100644 --- a/src/main/resources/z4j.yaml +++ b/src/main/resources/z4j.yaml @@ -14,7 +14,7 @@ paths:

Returns a list of all system and custom ticket fields in your account.

For end users, only the ticket fields with visible_in_portal set to true are returned.

Consider caching this resource to use with the{@link TicketClient}.

-

Allowed For

+

lookup relationships) to + href="/api-reference/ticketing/lookup_relationships/lookup_relationships/'>lookup relationships) to another object such as a user, ticket, or organization

@@ -114,13 +114,13 @@ paths:

Note: Tags can't be re-used across custom ticket fields. For example, if you configure a tag for a checkbox field, you can't use that tag value for a dropdown (tagger) field option. The use of tags isn't validated and can prevent editing in the future.

-

See About custom field types in the Zendesk +

See About custom field types in the Zendesk Help Center.

-

Allowed For

+

Field limits

+

List Comments

-

Allowed For

+

Returns a number of ticket properties though not the ticket comments. To get the comments, use List Comments

+

Pagination.

-

Allowed for

+

This endpoint supports pagination as described in Pagination.

+

Pagination

+

Pagination.

+

See Pagination.

responses: "200": description: OK Response @@ -559,7 +559,7 @@ paths: summary: Create Category by Locale description: |-

You must specify a category name and locale. The locale can be omitted if it's specified - in the URL. Optionally, you can specify multiple translations for + in the URL. Optionally, you can specify multiple translations for the category. The specified locales must be enabled for the current Help Center.

Allowed for