Add functionality to set Zendesk custom fields and form template #1170
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
AgaDufrat
changed the title
robinjam
reviewed
Aug 24, 2023
robinjam
reviewed
Aug 24, 2023
AgaDufrat
force-pushed
the
zendesk-custom-fields
branch
2 times, most recently
from
3338386
to
433abc9
Compare
The class didn't have a unit test.
Each class is responsible for validation and formatting of the value.
The naming in the Zendesk UI and API reference is inconsistent. Decided to
follow the UI convention, as we are getting the values from a User support
agent who is using the UI [^1]. Types that are not currently used were not
included but the modules should be easy to extend.
We are currently using the following custom field types:
- Text: default Zendesk type
- Date: only the date (formatted as a ISO 8601 string) and omit the time.
The form allows to submit dated in different valid formats. We need to
format and validate it, otherwise `ZendeskAPI::Error::RecordInvalid` will be
raised and the ticket will not be submitted. Since ‘Date’ class is already
defined on the main object, `DateField` is used.
- Drop-down: the option's tag name for the value property, not the option
text displayed in the list. We need to map the displayed text to a name
tag.
See [^2] for more examples and details.
[^1]: https://support.zendesk.com/hc/en-us/articles/4408838961562
[^2]: https://developer.zendesk.com/documentation/ticketing/managing-tickets/creating-and-updating-tickets/#setting-custom-field-values
We want to start populating custom fields in Zendesk. To set the value of one or more custom fields in a ticket, we need to specify an array of objects consisting of `id` and `value` properties. [^1] * ID integers Most Zendesk Support resources, such as tickets and users, are identified by the integer specified by the id attribute of API responses. The term refers to the JSON numeric type, not a C-like int data type. The default numeric type in JavaScript, Ruby, Python, and PHP is sufficient to represent Zendesk Support ID integers. Tested that String also work as an ID but decided to follow Zendesk documentation on this. ID formatting curtesy of rubocop: Style/NumericLiterals: Use underscores(_) as thousands separator and separate every 3 digits with them. (https://rubystyle.guide#underscores-in-numerics) * Value Value depends on the custom field type. Validation and formatting is preformed by each class. This particular implementation (reading ruby classes from a YAML file) introduces a level of abstraction but has the following benefits: - allows us to store all information about the Zendesk Custom fields in a YAML file (the app doesn't seem to have access to the custom fields end point via Zendesk API) - specific Ticket classes don't need to know about the type of field - specific Ticket classes don't need to know about field type - CustomField class is not responsible for validating/formatting values of different types - makes it easy to extend should we want to populate other type of fields such as multi-select. [^1]: https://developer.zendesk.com/documentation/ticketing/managing-tickets/creating-and-updating-tickets/#setting-custom-field-values
We want to start populating custom fields if they are defined for the Zendesk Ticket. Name: custom_fields Type: array Read-only: false Mandatory: fasle Description: Custom fields for the ticket. See Setting custom field values: https://developer.zendesk.com/documentation/ticketing/managing-tickets/creating-and-updating-tickets/#setting-custom-field-values https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#json-format
The custom fields were created in the Zendesk UI by a user with admin permissions. We had to obtain: - custom fields ids - name tag for drop down options
We need to map drop down option description to a name tag configured in Zendesk. If a description is changed or an option added in the UI but not the config/zendesk/custom_fields_data.yml the custom fields will stop getting populated correctly.
The information is included in the custom fields so this removes duplicate information as requested by a Content Designer. It removes the base_comment_snippets from ZendeskTicket. The specific Ticket classes can define whether the information is passed in the body or custom fields. It also moves the [Reason for time constraint] at the end of the ticket body.
Normally the Zendesk tickets default to the "Default Ticket Form. We want to render "Content Request" form because some information in the Content change request tickets is included only in the custom fields (not in the body). The Zendesk user might not see this information if they don’t know to switch to the correct form template. Therefore we want to render the correct form for this ticket. Name: ticket_form_id Type: integer Read-only: false Mandatory: false Description: Enterprise only. The id of the ticket form to render for the ticket From the API reference: https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#json-format
AgaDufrat
force-pushed
the
zendesk-custom-fields
branch
from
433abc9
to
fdf8968
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Context
The current Content Change Request form also doesn't make the most of Zendesk. Making better use of custom fields would allow content design teams to improve internal reporting (e.g. improvement work tickets vs factual inaccuracy tickets).
The form template and custom fields were created in the UI.
Trello card
What
Ticket examples:
Review notes
How to test it
Follow these steps if you are doing a Rails upgrade.