--- version: "Working version" language: "en" --- # Documentation ## One Visualizer to Rule Them All Create diagrams, documentation, and formatted code directly in Confluence---without switching tools. Whether you're starting fresh, pasting existing syntax, or using ready-made templates, Visualizer works the way you do. Check out the[supported formats](https://docs.apps.avisi.com/en/visualizer/latest/supported-formats.md) ![image-20250617-111600.png](https://docs.apps.avisi.com/__attachments/a_6f3f70963acabda4d9909e24d3d1241b99c0259a3cb435259c4a5b27ad9be35b/image-20250617-111600.png?cb=f7bd22e11983756c78a6f05279d6c1ff) One visualizer to support many formats ## Say What You Want, See What You Mean Don't know the syntax? No problem. Simply describe your idea in plain language---*"Add a validation step after checkout"*---and Visualizer brings it to life. Edit just as easily by typing what needs to change. Focus on what you want to communicate, not how to format it. ![image-20250617-111644.png](https://docs.apps.avisi.com/__attachments/a_9f6a105ab0ffce063c995677ae09140701cdf116b394c7424305ed01313b836f/image-20250617-111644.png?cb=fd7f7c0f95f0283a1df60a6f18114adf) Use natural language for editing diagrams ## Built for Confluence, Where Your Team Works Diagrams and docs live right inside your Confluence pages, staying in sync with your content. Scale, version, and export without hassle. From flowcharts and system designs to API docs and source code, Visualizer supports 20+ formats---all in one place. [**Try Visualizer for Confluence**](https://marketplace.atlassian.com/apps/1229840/visualizer-for-confluence-markdown-plantuml-mermaid-erd?hosting=cloud&tab=overview)**!**🔗 --- version: "Working version" language: "en" --- # Adding the macro in confluence You can add the "Visualizer for Confluence" macro to a Confluence page by typing `/[FORMAT]`, for example `/Markdown`or `/PlantUML`. ![image.gif](https://docs.apps.avisi.com/__attachments/a_90fc1289ad07ba64a106bcfa92f27f63f87cdf87423aff0e58fe1cde86802c8e/image.gif?cb=2270276406d59cd608d8d8f65800d6b2) Type /format to get started For all available macro's type `/Visualize`, Confluence will suggest all macro's for available formats. You can also find an overview of all supported file types [here](supported-formats.md). ![image-20250617-112737.png](https://docs.apps.avisi.com/__attachments/a_7d3cffd95740bfa95abcc2b46c8371b030c223347000c1334789003d9642a9d7/image-20250617-112737.png?cb=f7bd22e11983756c78a6f05279d6c1ff) ## Using the Visualizer Editor ### Creating Diagrams Visualizer's flexible approach ensures you can work the way you want---quickly create diagrams from source code or turn plain ideas into visuals without needing specific syntax. When editing the macro, you can start by using source code or describing your idea. ![image-20250617-112809.png](https://docs.apps.avisi.com/__attachments/a_30c166cdad8a4fda330b86df76b724a2fc92fe1d95caf3fd6b084c4ce51d6e90/image-20250617-112809.png?cb=abfa0b06bf7f2ee182d768473a7f23a2) Instruct Visualizer using Natural Language #### Start with what suits you: * Paste pre-existing syntax, like PlantUML or Mermaid code. * Use a template as a starting point to save time and guide your diagram structure. * Or, describe your diagram in plain language. For example: * *"An activity diagram that explains the checkout process in the Webshop."* #### *Edit the diagram using instructions* *You can use your own words to add, remove or change steps from your diagram or documentation.* ![image-20250617-112844.png](https://docs.apps.avisi.com/__attachments/a_aba4aeb2c8e8d7c6d253d618ee744427ca1a7aeb32a41ce5d06e544d66839bc7/image-20250617-112844.png?cb=fd7f7c0f95f0283a1df60a6f18114adf) Edit your diagram using Natural Language ***Example use-cases*** * *Add a 'You may also like items' step after the order review.* * *Change the language of the diagram to German* #### Visualize and refine: Select the "Update preview" button to generate or update your diagram. Continue refining it with natural language instructions or by editing the source code directly. #### **Insert the diagram:** Use the "Save" button to add the finalized diagram to your Confluence page. ### **Inserting source code** Visualizer makes embedding and formatting source code easy with syntax highlighting and line numbering for over 30 programming languages. Use the selector to choose your language, and instantly render clean, readable code directly on your Confluence page. ![image-20250617-112916.png](https://docs.apps.avisi.com/__attachments/a_1aacfb7b55d28184c5eaea82da8d9f54e58de2ca7bba7752cb784562a5bfe846/image-20250617-112916.png?cb=257f2d14e1e1deb2838a03caa1499d53) **Enhance with Natural Language Instructions:** In addition to pasting code, you can refine it using natural language commands within the Visualizer editor. This makes editing and improving code faster and more intuitive. **Example use-cases** * Add comments: *"Add comments explaining the purpose of each function."* * Organize code: *"Group the imports together at the top."* ### Creating Documentation Visualizer makes creating and editing technical documentation effortless, right inside Confluence. Whether you're starting fresh or refining existing content, Visualizer supports the formats you need while letting you work in the way that feels most natural. ![image-20250617-113002.png](https://docs.apps.avisi.com/__attachments/a_325fdd76fdd3a44e86d4ac8c121903882d546df0cf10b0b2d07c2d94eeafacac/image-20250617-113002.png?cb=b103caa45ac04139b2f9641c6696a2a5) Create API documentation using Visualizer **Flexible Options to Suit Your Workflow:** * Write in plain language to quickly build structured documentation. * Paste pre-existing docs, and easily update them with natural instructions. **Example usecases:** * **OpenAPI:** Define and edit API endpoints, request methods, and response formats. * **Markdown:** Create clean and easy-to-read README files or user guides. * **AsciiDoc:** Draft detailed user manuals with headings, lists, and tables. * **AsyncAPI:** Document message-driven architectures and ensure your events are well-defined. Visualizer adapts to your needs---whether you're drafting API documentation, editing system specifications, or sharing guides with your team. By supporting key formats, it streamlines documentation workflows while keeping everything organized in Confluence. ## Version Control Visualizer gives you the flexibility to experiment and refine your diagrams without worry. During an active session, version history is automatically saved, allowing you to go back to any previous version of your work. ![image-20250617-113041.png](https://docs.apps.avisi.com/__attachments/a_bbf44121df1e71f0a28c332902245c01f793d88c53aa0d685d72a714885cd182/image-20250617-113041.png?cb=5146eb179e18ed39e5da323486c9e57e) Version control This ensures you can iterate freely---whether you're building a diagram, refining documentation, or organizing source code---without losing track of progress. Visualizer uses Google Gemini for the generation of diagrams and documentation. Please be aware that this output can sometimes be misleading or incorrect. Use caution and verify the generated content to ensure accuracy and reliability. --- version: "Working version" language: "en" --- # Connect end of support Visualizer for Jira is migrating to Atlassian's new Forge platform. The migration will be finished before Connect (the current platform) is end of support. The new version will be fully compatible if the platform allows. ## Roadmap | | **Expected** | | |--------------------------|---------------------------|----------------------------------------------------------------------------------------------------------------------------------| | Connect on Forge version | 2026-09-29 IN DEVELOPMENT | This version is the first step in the migration. This is the app on the new platform with the current platform modules embedded. | | Forge only | 2026-12-30 | Fully compatible app on Forge | ## Q\&A Q: What is the current status of your Connect-to-Forge migration Well underway, specification is almost done, implementation starting Q: Whether a Forge version is already available Not yet... but stay tuned and check the roadmap Q: Your roadmap and expected timeline for the migration (if applicable) Current ETA is well before the end of the year. Q: Any planned changes to functionality, permissions, or pricing as part of the migration The Forge app is currently being specced and will use Forge features to be a better app than it's Connect predecessor. That said, we will strive for 100% backwards compatibility. Q: Whether existing customers will need to perform any actions during the transition Probably not, but if we run into something, we will communicate about it as soon as we know it. Q: Any known limitations or dependencies related to the Forge version Not that we see now. --- version: "Working version" language: "en" --- # How to use the app * [Adding the macro in confluence](https://docs.apps.avisi.com/en/visualizer/latest/adding-the-macro-in-confluence.md) * [Supported formats](https://docs.apps.avisi.com/en/visualizer/latest/supported-formats.md) * [Troubleshooting](https://docs.apps.avisi.com/en/visualizer/latest/troubleshooting.md) --- version: "Working version" language: "en" --- # Installation * [Installation](https://docs.apps.avisi.com/en/visualizer/latest/installation.md) --- version: "Working version" language: "en" --- # Installation Visualizer for Confluence can be installed directly from within Confluence Cloud: * Log in as an **Administrator** * Navigate to "**Settings"** and then "**Find new apps"** * Search for "**Visualizer for Confluence"** * Click on the "**Try it free"** button Alternatively, if you are logged in as an administrator, you can click on the "**Try it free"** button in the marketplace. --- version: "Working version" language: "en" --- # Legal, privacy & security [License Agreement](https://docs.apps.avisi.com/en/legal-atlassian/latest/license-agreement.md) 🔗 [Privacy Policy](https://docs.apps.avisi.com/en/legal-atlassian/latest/privacy-policy.md) 🔗 --- version: "Working version" language: "en" --- # Relevant links [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1229840/visualizer-for-confluence-markdown-plantuml-mermaid-erd) 🔗 [Support](https://avisi-support.atlassian.net/servicedesk/customer/portal/62) 🔗 [Git for Confluence](https://marketplace.atlassian.com/apps/1211675/git-for-confluence-markdown-plantuml-graphviz-mermaid?hosting=cloud&tab=overview) 🔗 --- version: "Working version" language: "en" --- # Supported formats The following formats are supported. Please [reach out](https://avisi-support.atlassian.net/servicedesk/customer/portal/62) 🔗 to us if you are missing a format type you'd like to have supported! * AsciiDoc * BlockDiag * BMPN * Bytefield * Ditaa * ERD * Excalidraw * GraphViz * Markdown * Mermaid * NomNoml * OpenAPI (Swagger) * Pikchr * PlantUML * Source code (This includes syntax highlighting of many languages and line numbers) * SVGBob * Umlet * Vega * Vega-Lite * WaveDrom Visualizer currently does not support natural language instructions for Excalidraw, Bytefield, Pikchr, Vega and Vega-Lite --- version: "Working version" language: "en" --- # Troubleshooting **Notification** If an image can not be renderd a "Syntax error" will be shown. **Wrong render format selected** If you are trying to render a diagram, it could be that you have selected the wrong source format in the selector. Check if you've selected the correct format. **Mistakes in the source** There might be a mistake in the source, please check your source content for mistakes that prevent the app from rendering you diagram. If that did not resolve your issue, please reach out to us in our [service desk](https://avisi-support.atlassian.net/servicedesk/customer/portal/62). --- version: "Working version" language: "en" --- # Documentation ![image-20250617-124209.png](https://docs.apps.avisi.com/__attachments/a_a495d9cb1feb5b9f82c28de784249a80f46a7ec3ddd74cc052a1aba26646bb52/image-20250617-124209.png?cb=7c0eb178c170426a00a8cf0e5a2bb81b) Welcome to the documentation for the TOPdesk Jira Integration.This integration allows you to connect Jira and TOPdesk to help your teams work better together. You can find more information about this integration in the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1222136/) 🔗. Before you get started, here are some tips you can use before setting up the integration: * [Before you start](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/before-you-start.md) If you prefer to directly start configuring, here's a link to a step-by-step installation: * [Installation](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/installation.md) --- version: "Working version" language: "en" --- # 02-12-2020 ## API settings When saving the API settings in the Jira instance, there will be a success or error message. In this way you can find out if the API settings are set correct. For more details, see: * [Installation](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/installation.md) ## Map Jira project field In all post functions you can now map the Jira field: Project. In this way the Jira project can be shown in the TOPdesk instance. ![image-20250617-141033.png](https://docs.apps.avisi.com/__attachments/a_1f0a644c1290fa3d221016feee0af258aa6a5b551ac93c4f2bfc973da3924210/image-20250617-141033.png?cb=4291266d5dd690c221280b931371ef43) --- version: "Working version" language: "en" --- # 07-08-2023 ## Hide TOPdesk tab If there are no configurations set in the TOPdesk Jira integration app, the TOPdesk tab under activity on a Jira issue will be hidden. ![image-20250617-140241.png](https://docs.apps.avisi.com/__attachments/a_26e8f0b1e262995e6afbfa1eae36ef84f9a31e438299b07ec83347125a4c15da/image-20250617-140241.png?cb=2712f5cb9f81b9815e1e3131db1f24eb) This tab will be hidden when no configurations are set for TOPdesk Jira integration on this project. ## Issue context module Integration of TOPdesk on Jira issues has been moved from "Issue glance module" to "Issue context module". Fields are now shown on a separate panel on Jira issues. Preferences in having this panel open/closed are stored per user by Atlassian. ## Dark mode support TOPdesk Jira integration now supports Jira dark theme. --- version: "Working version" language: "en" --- # 07-09-2020 ## Field mapping New in this release is the ability to add field mapping to incidents. Using the post function create/update incident you can choose which Jira field you would like to map with the TOPdesk incident field. See example below. ![image-20250617-142112.png](https://docs.apps.avisi.com/__attachments/a_0da51bf78455342e950a926ae9442363fcce71d2cbe9215eaaa17f02bf405dfe/image-20250617-142112.png?cb=f3f4376ece4c1a5868c63f57dd46ce38) ## Update incidents The post function update incidents is new. With this post function it is possible to update fields in the TOPdesk incident triggering a workflow transition in Jira. More explanation about configuring a workflow can be found [here](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest.md). --- version: "Working version" language: "en" --- # 08-11-2022 ## Rich text support With this release we are expanding the rich text support in our application. When you now update the description in Jira with an action sequence from TOPdesk it will now look more alike. ![image-20250617-140311.png](https://docs.apps.avisi.com/__attachments/a_49448d4519ca7c0f6861ac4a7e1a24cfc90ff4d3e1a6c1987444005ca290c19c/image-20250617-140311.png?cb=e898577173f97a9504d5073089675920) ## Blueprints Action sequences can be tricky to create and extend. With our integration we already made it easy to generate some simple create and update action sequences. We have now updated our documentation with blueprints to show the possibilities of action sequences. These new blueprints will show how to add more fields, transition an issue and how to update the priority. For more information you can check our new documentation. * [Configure action sequences](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/configure-action-sequences.md) ## Transitioning issues It is now possible to transition a Jira issue from a TOPdesk action sequence. This is great for keeping your Jira operators in touch with the status of the incident or change. When watching a Jira issue, you'll be automatically notified by Atlassian when the status changes, making transitions a very usefull feature! You can check the new transition blueprint for more information. * [Transition an issue](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/transition-an-issue.md) --- version: "Working version" language: "en" --- # 13-11-2020 In this release a new post function is introduced: TOPdesk: transition change. With this post function it is possible to transition the status of the linked TOPdesk change. Read more about this post function here: * [Transition Change/Incident](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/transition-change.md) --- version: "Working version" language: "en" --- # 14-12-2020 In this release a new post function is introduced: "TOPdesk: transition incidents". With this post function it is possible to transition the status of the linked TOPdesk incident. This post function can be used on a workflow transition. For example: The Jira issue transitions from "Selected to development" to "In Progress". Add the post function to this workflow transition and select Incident status: Ready to start. When the issue is transitioned to the status Selected for development, the status of the linked incident will be set to "Ready to start". Read more about this new post function here: * [Transition Change/Incident](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/transition-change.md) This release contains a fix for selecting fields in the incident/change details in the Jira admin section. Fields that are already selected for the incident/change details in the Jira issue panel are not visible in the list of options anymore. --- version: "Working version" language: "en" --- # 15-09-2022 With this release it's now possible to send back comments to TOPdesk that are invisible to the caller. In the activity stream tab called "TOPdesk", you can toggle a checkbox to make the comment invisible before sending. This is turned on by default for easy internal communication. **Note** : Sending invisible to caller messages are currently only available for **incidents**. This is due to a limitation in TOPdesk. Read more on enabling communication here: * [Comments, actions, attachments](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/comments-actions-attachments.md) --- version: "Working version" language: "en" --- # 17-10-2022 ## Sending attachments to TOPdesk With this release we are excited to announce the ability to send attachments to TOPdesk from Jira. Inside the TOPdesk activity stream in Jira you will now see a new field for adding attachments to the linked TOPdesk change or incident. ![image-20250617-140636.png](https://docs.apps.avisi.com/__attachments/a_c38562b8eda786175db24335a39e9d4a6df94e4704c7fd206b158e5a36774227/image-20250617-140636.png?cb=8b600bb0c29d27e728ebeb8dcdba9125) **Note** : Sending invisible to caller attachments are currently only available for **incidents**. This is due to a limitation in TOPdesk. ## Invisible to caller preference The invisible to caller checkbox for incidents will now remember the last checked state. This will make it easier for users to indicate their prefered state. Jira admins can configure a fallback default inside the TOPdesk integration settings. ## Other changes * Newly generate update action sequences now also include the updating of the Jira issue description. --- version: "Working version" language: "en" --- # 18-05-2022 ## Watch actions and attachments 🔝 With this release, it's possible to watch actions that are placed (as comments) or images that are uploaded on a TOPdesk incident and/or change. With this functionality, it's possible for you to get insight in the latest updates made in TOPdesk, without logging out of your Jira environment. Read more on this first release regarding communication here: * [Comments, actions, attachments](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/comments-actions-attachments.md) ![image-20250617-140849.png](https://docs.apps.avisi.com/__attachments/a_7eadd2bc5d794aa806d707e90619dfb51ed5ae78c8ec7d873f86fbaa33578939/image-20250617-140849.png?cb=c16bdd2fa027b97765414182345598b7) --- version: "Working version" language: "en" --- # 18-12-2024 ## View Jira User Name in a response to TOPdesk We've added a short prefix to every response made in Jira to a TOPdesk change or Incident. This way you no longer have to guess which user sent the response. ![image-20250617-140112.png](https://docs.apps.avisi.com/__attachments/a_c5e0d03ce7f40a22de58e9c99e16dec8d718287a16ae93a6a6e64a747d393aff/image-20250617-140112.png?cb=79e5a56c39e3931ceae94633649b269b) The user's name is based on their privacy settings in Jira. If the user has configured a specific display name, and hidden their real name, their configured display name will be used. --- version: "Working version" language: "en" --- # 19-06-2020 ## Summary This release includes new e-mail API settings, where the Jira user and TOPdesk person can be linked based on the e-mail address. ## Details Note: the new version has to be accepted since we need new API rights to match the e-mail addresses in both Jira and TOPdesk. ### **What has changed?** The creator of a TOPdesk change from Jira will be visible in TOPdesk as the TOPdesk person. The match between the Jira user and the TOPdesk person will be made based on validation of the e-mail address. Creating a TOPdesk change (based on the workflow transition setting in Jira) will result in the TOPdesk person being the caller of the change. See below: ![image-20250617-142230.png](https://docs.apps.avisi.com/__attachments/a_9b54270385b5a9ff17a6790d58e8ead0267f3e5c7fbcb45ad16a6304c22af242/image-20250617-142230.png?cb=df6a2652b2a6791d41e26be8b42f8739) --- version: "Working version" language: "en" --- # 19-4-2022 An extra field is now available for display in the issue view. *Processing status* is what is displayed in the TOPdesk ui under the label *status*. Previously only *status* was available, but this value from the API confusingly does not map to *status* in the ui. *Processing status* does. The TOPdesk ui provides both, so we decided to just add *processing status* and leave *status*. --- version: "Working version" language: "en" --- # 27-06-2022 With the latest release it's now possible to communicate back and forth from Jira to TOPdesk. In the activity stream tab called "TOPdesk", you can now sent a comment to TOPdesk. The comment will be visible as action in TOPdesk. Read more on enabling communication here: * [Comments, actions, attachments](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/comments-actions-attachments.md) --- version: "Working version" language: "en" --- # 27-10-2020 ## **Update incidents / changes from TOPdesk to Jira** We have created a new action sequence which can be used to update fields from TOPdesk to Jira. The action sequence can be downloaded from Jira and imported in your TOPdesk instance. You can manually change the fields you would like to update within the action sequence in TOPdesk. Connect the action sequence to your TOPdesk incidents or changes to give updates to the linked Jira issues. Read more about updating an Jira issue on the page below: * [From context menu](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/update-an-issue-in-jira.md) ## **Configure incident details** In the Jira issue panel you can choose which TOPdesk fields you would like to show. Previously this was only possible for changes. Now it is also possible to configure the incident fields you would like to be shown in the Jira issue panel. More information can be found here: * [Additional configuration](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/additional-configuration.md) --- version: "Working version" language: "en" --- # 28-09-2023 ## Enable custom external number field Introducing our latest update that simplifies issue syncing like never before. We understand the challenges you faced with external tools and the External Number field in TOPdesk. That's why we've listened to your feedback and rolled out a game-changing solution. Now, you have the power to choose any textual optional field from TOPdesk, making your integration smoother and more flexible than ever. Elevate your workflow and efficiency with this tailored solution. By default TOPdesk Jira Integration uses TOPdesk's External Number field for all its syncing operations. Now you can configure this field to be any optional text field. Simply go to Incident and Change settings and select a optional field for each. When you clear the field the Topdesk Jira Integration will fall back to the default External Number field. ![image-20250617-140139.png](https://docs.apps.avisi.com/__attachments/a_49ccdb9a618c2f888ea6d9e058e7df0dedc4dfa42686a0558d4c45b988a2d510/image-20250617-140139.png?cb=9a5d13366a99d6e91d4ed301a0273f3d) **All currently configured post functions will be affected**. I.e. an old post function that created an Incident when a Jira issue is created will now write the Jira Issue Key to the newly selected field. --- version: "Working version" language: "en" --- # Action sequences The TOPdesk Jira Integration makes it possible to create or update a Jira issue based on activity in TOPdesk. We use TOPdesk's action sequences to make that happen. A Jira administrator can download pre-filled action sequences in the Jira app. A TOPdesk operator can import these action sequences in TOPdesk. On the 7 of March 2023 TOPdesk have released a [blog post](https://blog2.topdesk.com/updates/action-sequences-new-changes-for-an-improved-topdesk-experience) 🔗 detailing visual changes to the Action Sequences. This documentation has been updated to reflect these changes to the best extend possible. ## Pre-filled action sequences The Jira TOPdesk integration allows you to download pre-filled action sequences to make it easier to configure your automation process. A Jira admin can configure and download these action sequences in Jira. A TOPdesk operator can then import these in TOPdesk. * [Create/update Jira issue](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/from-topdesk-to-jira-introduction.md) **Action sequences are only downloadable once for the following reason:** The action sequence generates an authentication key that is not saved on our servers. Because the key is not saved somewhere, a new key is generated each time an action sequence is created. ### Extending pre-filled action sequences Extending pre-filled action sequences require a deep understanding of Jira's issue, fields and workflows. We recommend that only Jira admins and TOPdesk operators perform these modifications. Pre-filled action sequences can be modified in TOPdesk or a JSON editor. By default only some fields are copied from the TOPdesk change or incident to the Jira issue. To get familiar with modifying action sequences we provide a few blueprints with differing functionalities. * [Configure action sequences](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/configure-action-sequences.md) --- version: "Working version" language: "en" --- # Additional configuration ## Jira issue glance When a TOPdesk incident or change is linked to a Jira issue, you can access its information in the Jira issue glance. ### Where to find the TOPdesk glance You can find the TOPdesk issue glance on the right-hand side of the issue. When no change or incident is linked, the TOPdesk glance will not be shown. ![image-20250617-150039.png](https://docs.apps.avisi.com/__attachments/a_d593888690957edb02ec64a75abacada0aacadf28fa425c9a9fb10f7cebe49f8/image-20250617-150039.png?cb=cab2622a9875d55f6f05e14ec4c2262a) Issue glance in Jira ### Information in the TOPdesk glance When a user open the issue glance, they have access to information of the linked change or incident: ![image-20250617-150106.png](https://docs.apps.avisi.com/__attachments/a_01e08a3d652bf9267f76af32c2152846249ec6368008ef28e47f5bc9fe30f214/image-20250617-150106.png?cb=2a5393b309cd3850457bd1d7a6ca80c8) ## Change details For linked changes, you can configure what fields will be displayed in the issue glance. By default, users have access to the following fields: * Brief description * Status * Change type / incident type * Created You can show more or hide fields in the change details configuration: 1. Select ![image-20250617-150122.png](https://docs.apps.avisi.com/__attachments/a_f2537de5b1ef6334226662ae857424f6c1614d33ed666aea619487e92ba0effc/image-20250617-150122.png?cb=5f3a7b27dd3b0ab8774fca31251d3ef0) \> **Apps**. 2. Find TOPdesk Integration in the menu on the left and open **Change details** You're now presented with the fields that are visible. You can hide fields and change the order of the fields. To add more fields, use the select button at the bottom of the page. ![image-20250617-150135.png](https://docs.apps.avisi.com/__attachments/a_5baaef058cfb8d789776cf0e481237ef600d54c8d1de036399b7b3d6398d8e61/image-20250617-150135.png?cb=996faed414242223223ad2c67110e153) ## Incident details For linked incidents, you can configure what fields will be displayed in the issue glance. By default, users have access to the following fields: * Brief description * Status (**Note** : This does not map to status in the TOPdesk ui, use *processing status* instead) * Processing status * Created * Creator * Last modified * Modifier You can show more or hide fields in the incident details configuration: 1. Select ⚙️ \> **Apps**. 2. Find TOPdesk Integration in the menu on the left and open **Incident details** You're now presented with the fields that are visible. You can hide fields and change the order of the fields. To add more fields, use the select button at the bottom of the page. ## Change External Number Field Inside the Change settings you can configure a different optional field that will be used in place of the External Number field. ![image-20250617-150200.png](https://docs.apps.avisi.com/__attachments/a_dae54c5d953e9ab45a0652ef6511522655c6cdc3a0da72c2baf6014ddd1408cd/image-20250617-150200.png?cb=9a5d13366a99d6e91d4ed301a0273f3d) **All currently configured post functions will be affected**. I.e. an old post function that created an Change when a Jira issue is created will now write the Jira Issue Key to the newly selected field {% endhint %} ## Incident External Number Field Inside the Incident settings you can configure a different optional field that will be used in place of the External Number field. **All currently configured post functions will be affected**. I.e. an old post function that created an Incident when a Jira issue is created will now write the Jira Issue Key to the newly selected field {% endhint %} --- version: "Working version" language: "en" --- # Advanced * [Additional configuration](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/additional-configuration.md) * [Troubleshooting](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/licensing-issues.md) --- version: "Working version" language: "en" --- # Before you start You've decided you'd like to connect your TOPdesk and JIRA environments to help your teams work better together. These steps will help you get on your way, even before you start configuring. 1. Define the use case of your integration 2. Map out the **TOPdesk** process you'd like to connect to JIRA. You can either write it out, or draw it in a process flow (recommended) 3. Map out the **JIRA** process you'd like to connect to TOPdesk. The workflow in JIRA gives you a starting point 4. Define the exacts areas where you want to post a function to the other system, either from TOPdesk to JIRA or the other way around 5. Complete walkthrough on paper of your new, integrated process. 6. Start configuring! Best practices: * Make sure your JIRA and TOPdesk admins are involved * Start with a single post function te learn the basics * Involve your end users for testing and feedback ![image-20250617-124504.png](https://docs.apps.avisi.com/__attachments/a_48d421fd5fd01a4116e8f3c5d5b98b3254978fc6843eeb786cc8c40b6cd647cf/image-20250617-124504.png?cb=70ccc2518e89e81124e5319d3c69c701) --- version: "Working version" language: "en" --- # Comments, actions, attachments ## Communication With this functionality, we would like to make it possible to communicate back and forth between TOPdesk en Jira. You can sent actions and attachments from TOPdesk to Jira and comments from Jira to TOPdesk. ### Example of communication A customer creates a first line call in the TOPdesk help desk. The TOPdesk operator sends the incident through to Jira. In Jira, a different person is handling the incident but hasn't got enough information: a screenshot is missing. This can be solved by enabling attachments. ## From TOPdesk to Jira ### Enable actions and attachments You can use the settings to turn the comment stream on/off. Follow the steps below to do this: * Navigate to settings -\> Apps * Find the TOPdesk integration in the side bar * Navigate to change/incidents settings (you need to configure them both separately) * Turn on the checkbox to show actions and attachments. Here's an example on how actions and attachments sent from TOPdesk look like in the TOPdesk activity stream tab: ![image-20250617-145725.png](https://docs.apps.avisi.com/__attachments/a_6ae1825c0466ac5f692e0ccbd58b5b6e477227a5d9b36b415c6c148ab04630ed/image-20250617-145725.png?cb=c700d21b51455140b38f15e9a2a2fbc4) ## From Jira to TOPdesk You can use the settings to turn the the option to send comments on/off. Follow the steps below to do this: * Navigate to settings -\> Apps * Find the TOPdesk integration in the side bar * Navigate to change/incidents settings (you need to configure them both separately) * Turn on the checkbox to send comments from Jira to TOPdesk Here's an example on how to sent comments from Jira to TOPdesk. This comment will be created as an action in TOPdesk. ![image-20250617-145800.png](https://docs.apps.avisi.com/__attachments/a_a2bdab2c4c5ea87796bc6fefb30d428d40469a6d5c88d8551954c1cfb448830d/image-20250617-145800.png?cb=2022ac906a1d481fe807f56fe7c6419b) Please note that only comments in the "TOPdesk" activity stream tab will be sent to TOPdesk. Comments placed in the "comments" activity stream tab will not be sent through. ### Invisible to caller Making a comment invisible to the caller will result in it only being available in the TOPdesk operator portal. Customers will only be able to see the public or not invisible to caller messages. Here's an example on how a visible and invisible message look inside of the TOPdesk activity stream tab: ![image-20250617-145824.png](https://docs.apps.avisi.com/__attachments/a_9ecd1e95b8b92522f76cdbbefe8084fe31b85ec84af1ecbd18e1377808d748ee/image-20250617-145824.png?cb=8d6d408c23839d499d6f8b88445f7de4) **Note** : Sending invisible to caller messages are currently only available for **incidents**. This is due to a limitation in TOPdesk. ### Attachments Sending an attachment can be done by selecting a file via the 'Choose File' button. When saving, the file will be uploaded to TOPdesk and will be available to the caller. Along side the attachment you can add a comment. This comment will be send separately from the attachment so two new message wil appear. **Note** : Sending invisible to caller attachments are currently only available for **incidents**. This is due to a limitation in TOPdesk. --- version: "Working version" language: "en" --- # Communication * [Comments, actions, attachments](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/comments-actions-attachments.md) --- version: "Working version" language: "en" --- # Configure action sequences Extending pre-filled action sequences require a deep understanding of Jira's issue, fields and workflows. We recommend that only Jira admins and TOPdesk operators perform these modifications. The imported pre-filled action sequence has a default configuration in which some fields are copied from the TOPdesk change or incident to the Jira issue. You can extend this configuration by editing the body of the action sequence. This can be done via the editor inside TOPdesk or via a JSON editor. ## TOPdesk fields You can find a list of available TOPdesk fields in the DataDict in TOPdesk: * Open the **TOPdesk Menu** on the top-left. * Choose **Help**. * Choose **DataDict**. **Note**: not all fields are equal between incidents and changes. ### Jira issue body Everything inside the `issue` field of the pre-filled action sequence body will be passed forwards to Jira's Create and Update endpoints. You can read more about the available fields in their [API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post) 🔗. ### Jira issue fields To get the ID's for the Jira fields you can use their [API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-fields/#api-rest-api-3-field-get) 🔗. ### Jira Transitions To get the transition ID's for company managed projects: * Select ⚙️ \> **Issues**. * Navigate to **workflows**. * Edit the workflow that is linked to the correct project. * Go into **text** mode. * Then in the column **Transitions (id)** you find the ID's. For team managed projects: * Find an existing issue key, i.e. TEST-123. * Use Atlassian's [Transition API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-transitions-get) 🔗 together with the issue key. * **Note**: only the transitions that are available at that moment are shown. Once the changes have been made to the action sequence don't forget to save it or import it again when the changes have been made outside of TOPdesk. ## Blueprints To get familiar with modifying pre-filled action sequences we provide some blueprints that cover different use cases. These blueprints only modify the body of an create or update action sequence and expect to be used in pre-filled action sequences. Pre-filled action sequences already contain all the necessary fields for authentication and should not be modified. * [Updating a field](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/updating-a-field.md) * [Transition an issue](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/transition-an-issue.md) * [Set a priority](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/set-a-priority.md) --- version: "Working version" language: "en" --- # Configure the post function ## Post function When an issue transitions through its workflow, we can add post functions to make changes in TOPdesk incidents or changes. We do this by adding a post function to a workflow transition. ### Configure a post function Here is how a Jira admin can add and configure the post function: 1. Select ⚙️ \> **Work items**. 2. Click **Workflows** and then **Edit** for the relevant workflow. 3. Select the transition: * In diagram mode, select the transition arrow. * In text mode, select the transition's name from the **Transitions (id)** column. 4. Open the post functions tab: * In diagram mode, click **Post functions** in the properties panel to show the triggers configured for the transition. * In text mode, select the **Post functions** tab. 5. Click **Add post function**. 6. Choose **TOPdesk: ....** post function and click **add**. 7. Set the **parameters** for the post function and click **add**. 8. Choose **Publish Draft** to finalize your changes. ### TOPdesk post functions The TOPdesk Jira Integration introduces new post functions to Jira. #### **For changes** * TOPdesk: create change * TOPdesk: update change [Create/update change](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/create-a-change-in-topdesk.md) #### For incidents * TOPdesk: create incident * TOPdesk: update incident [Create/update incident](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/create-an-incident-in-topdesk.md) #### For transitioning the TOPdesk status * TOPdesk: transition change * TOPdesk: transition incident [Transition Change/Incident](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/transition-change.md) When you have added or updated the post function, don't forget to publish it by clicking the **Publish Draft** link. --- version: "Working version" language: "en" --- # Connect end of support TOPdesk for Jira is migrating to Atlassian's new Forge platform. The migration will be finished before Connect (the current platform) is end of support. The new version will be fully compatible if the platform allows. ## Roadmap | | **Expected** | | |---------------------------------|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Connect on Forge version | 2026-09-23 RELEASED UNDER APPROVAL BY ATLASSIAN | This version is the first step in the migration. This is the app on the new platform with the current platform modules embedded. This is a necessary step in order to be able to migrate configuration and data to the new platform | | Full Forge, with legacy support | 2026-11-30 | We are fully migrated to the new platform. This means you can finish migrating TOPdesk action sequences to point to the new platform. At the same time we will still support the old configuration by keeping the legacy app up and running. | | Forge only | 2027-01-31 | The legacy support will be removed. This is a hard deadline, from this day on, Atlassian will no longer accept incoming calls from our legacy platform. | ## Q\&A Q: What is the current status of your Connect-to-Forge migration Well underway, specification is almost done, implementation starting Q: Whether a Forge version is already available Not yet... but stay tuned and check the roadmap Q: Your roadmap and expected timeline for the migration (if applicable) Current ETA is well before the end of the year. Q: Any planned changes to functionality, permissions, or pricing as part of the migration The Forge app is currently being specced and will use Forge features to be a better app than it's Connect predecessor. That said, we will strive for 100% backwards compatibility. Q: Whether existing customers will need to perform any actions during the transition There will be at least an explicit upgrade confirmation, at minimum including accepting the Forge scopes. Q: Any known limitations or dependencies related to the Forge version Not that we see now. --- version: "Working version" language: "en" --- # Create/update Change ## Post function parameters A TOPdesk change can be created automatically when an issue transitions through its workflow. We do this by adding a post function to a workflow transition. When you add a [TOPdesk post function](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/from-jira-to-topdesk-introduction.md), you can fill out certain parameters. Here is an overview of what these parameters do. ## Create change The create change parameters allow you to choose what kind of TOPdesk change will be created. | Field | Description | |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Template | This is the change template that is used to create the change | | Fallback requester | The name of the fallback user to use to create the change. The post function will attempt to create the changed based on the logged in Jira user. In case this user is not found as a user in TOPdesk, the fallback user configured here will be used. | If you only want to create a TOPdesk change under certain circumstances, leave this empty and add a [conditional configuration](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/create-a-change-in-topdesk.md#Conditional-configuration). ## Field mapping Field mapping allows you to copy fields from the Jira issue to the TOPdesk change. | Field | Description | |----------------------|------------------------------------------------------| | Jira issue field | The Jira issue field to copy the value from (source) | | TOPdesk change field | The TOPdesk field to copy the issue to (destination) | The following field types are supported: ### Jira field types * String field * Option field * Datetime field * Date fields * Jira project field * Issuekey field ### TOPdesk field types * Text field * Date field After you have selected the fields that you want to map, make sure to click on the **Add field mapping row** to apply the mapping. ## Conditional configuration The conditional configuration allows you to create a TOPdesk change based on the value of one or more issue fields. It also allows you to choose a template based on the value of the issue field(s). To add a condition: * Click on the **Add new condition** button. * Click on the **+** icon for each condition. ### If these match..." This is where you add one or more rules for your condition. | Field | Description | |-------------|------------------------------------------------| | Issue field | The Jira issue field that you want to match on | | Value | The value that you want to match | ### Then do this... This is where you choose the configuration when your rules are met. | Field | Description | |-----------|------------------------------------------------------------------------------------| | Template | The template to use when the if part matches | | Requester | The fallback requester to use if the logged in user is not a user found in TOPdesk | You can add multiple conditions to a single post function. ## Update change When the post function **create change** is used in a Jira workflow, you can add another post function to update this same change. This post function is called **update change**. This post function can be set on a workflow transition to update fields in the TOPdesk change. It is important to keep in mind that post functions are set in a specific order. A new post function will automatically be placed before other post functions. With the **update change** post function it might be important to process this post function *after* other post functions. For example the post function that sets the status of the Jira issue: 1. Set issues status to the linked status.... 2. ..... 3. ..... 4. Update Change in TOPdesk --- version: "Working version" language: "en" --- # Create/update Incident ## Post function A TOPdesk incident can be created automatically when an issue transitions through its workflow. We do this by adding a post function to a workflow transition. The post function will automatically copy the title and description of the Jira issue to the TOPdesk incident. And it will fill out an external number that directs links the TOPdesk incident to the Jira issue. ## Post function parameters When you add a [TOPdesk post function](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/from-jira-to-topdesk-introduction.md), you can fill out one parameter. Here is an overview of what this parameter does. | Field | Description | |--------|---------------------------------------------------------------| | Caller | This is the TOPdesk caller that creates the TOPdesk incident. | ## Field mapping Field mapping allows you to copy fields from the Jira issue to the TOPdesk incident | Field | Description | |------------------------|------------------------------------------------------| | Jira issue field | The Jira issue field to copy the value from (source) | | TOPdesk incident field | The TOPdesk field to copy the issue to (destination) | The following field types are supported: ### Jira field types * String field * Option field * Datetime field * Date fields * Jira project field * Issuekey field ### TOPdesk field types * Text field * Date field After you have selected the fields that you want to map, make sure to click on the **Add field mapping row** to apply the mapping. ## Update incident When the post function **create incident** is used in a Jira workflow, you can add another post function to update this same incident. This post function is called **update incident**. This post function can be set on a workflow transition to update fields in the TOPdesk incident. It is important to keep in mind that post functions are set in a specific order. A new post function will automatically be placed before other post functions. With the **update incident** post function it might be important to process this post function *after* other post functions. For example the post function that sets the status of the Jira issue: 1. Set issues status to the linked status.... 2. ..... 3. ..... 4. Update Incident in TOPdesk --- version: "Working version" language: "en" --- # From linked event Action sequences can be triggered from a linked events making automation easy. ## Create an event Here is how a TOPdesk operator with the correct permissions can create an event: 1. Open the **Event Explorer**: TOPdesk Menu \> Modules \> Action Management \> Event Explorer. 2. Click on the **Create new event** button. 3. Select the **card type** for which you want to create an event. 4. Enter a **name** and choose a **type** that triggers the event. 5. Check the box for **active** if you want to activate the event already. (If you choose not to activate it yet, remember to activate it before testing the integration.) 6. Optionally: fill out any **conditions** and **parameters** that apply to your use case. 7. **Save** the event. The TOPdesk operator can configure the conditions and parameters of the event to make it specific for your use case. This event will trigger the creation of the Jira issue. ## Activate the action sequence After creating the event you can finally link the created action sequence. 1. Go to TOPdesk Menu \> Modules \> **Automated Actions**. 2. Find the action sequence you have previously create/imported. 3. Double click the action sequence to start editing. 4. Click the **Configure triggers** icon ![image-20250617-144149.png](https://docs.apps.avisi.com/__attachments/a_1cd35f53d38e82bd06eb1835d21e6530deb3d85312a39642ccc9c0e8fc0474f7/image-20250617-144149.png?cb=91558a781e0a4f7db209a0b512147a40) . 5. Choose the **event** you want to link this action sequence to and click **Apply**. 6. Click the **Close edit mode** button at the bottom of the page. 7. Check the box for **Activate action** and one or more boxes where it should be **applied**. 8. Make sure to save your changes by clicking the **Save** button at the bottom of the page. You can now test the integration by triggering the event that you created. Make sure that the event and the action sequence are activated before testing the complete flow. --- version: "Working version" language: "en" --- # From Jira to TOPdesk * [Post functions](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/from-jira-to-topdesk-introduction.md) * [Configure the post function](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/configure-the-post-function.md) --- version: "Working version" language: "en" --- # Post functions The TOPdesk Jira Integration makes it possible to create a change request or an incident in TOPdesk based on activity in Jira. A Jira administrator can configure workflows that automate this functionality. ## Jira workflows Jira issues have a life cycle within Jira. This life cycle start with the creation of the issue and can have many steps before the issue is closed. These steps are configured in workflows. Atlassian has written about workflows in their documentation here: [Working with workflows](https://confluence.atlassian.com/adminjiracloud/working-with-workflows-776636540.html) 🔗. ### Workflow post functions When an issue transitions through its workflow, Jira carries out a number of post functions. For example: There is a post function that updates the status of the issue. Another post function updates the change history of the issue. A Jira admin can configure post functions and use them to automate functionality in Jira. Post functions can be used to automatically add a comment to the issue, for example. You can find more information about post functions in Atlassian's documentation: [Advanced workflow configuration](https://confluence.atlassian.com/adminjiracloud/advanced-workflow-configuration-776636620.html#Advancedworkflowconfiguration-postfunctions) 🔗. * [Configure the post function](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/configure-the-post-function.md) --- version: "Working version" language: "en" --- # From TOPdesk to Jira * [Action sequences](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/action-sequences.md) * [Create/update Jira issue](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/from-topdesk-to-jira-introduction.md) * [Configure action sequences](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/configure-action-sequences.md) --- version: "Working version" language: "en" --- # Create/update Jira issue To generate a pre-filled action sequence follow steps below. Once generated these action sequences be triggered in a couple of ways. ## Create an action sequence To make configuration easier, a Jira admin can download a pre-configured action sequence that can be imported directly into TOPdesk. This action sequence is pre-filled with required information such as authentication details. To create a pre-filled action sequence: 1. Login to Jira as an **administrator**. 2. Select ⚙️ \> **Marketplace apps**. 3. Open **Action sequences** under **TOPdesk integration** in the menu on the left. 4. Click on the **New action sequence** button. 5. Fill out the form and click save. 1. **Name**: Choose a name that helps you recognize what the action sequence is for. This name will be added to the action sequence in TOPdesk and it will be used in the overview in Jira. 2. **Action sequence type**: Choose the type of action sequence - create or update 3. **TOPdesk type**: Choose the type of TOPdesk card that you want to use this with. 4. **Only applicable to the create action sequence:** 1. **Jira project**: Choose the project in which the issues are going to be created. 2. **Jira issue type**: Choose the issue type for the issues that are going to be created. 6. **Download** the action sequence and close the page. These pre-filled action sequences contain authentication details. Don't share them with third parties that you don't trust. You can revoke access to an action sequence in the overview. When the pre-filled action sequence is created, the integration generates an authentication key for you. This key is not saved on our servers, so we don't have access to it. When you create another action-sequence, a new key will be generated. ## Import the action sequence Here is how a TOPdesk operator can import the action sequence: 1. Login to TOPdesk. 2. Go to TOPdesk Menu \> Modules \> **Action Management**. 3. Under **New** choose **Automated Action**. 4. Choose the **card type** and select **Create action**. 5. If you already know what **Trigger** you need you choose the appropriate **Trigger** (see: [Trigger action sequence](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/from-topdesk-to-jira-introduction.md#Trigger-action-sequence)). This can also be configured at a later moment. 6. Click on **Configure the action** at the bottom of the page. 7. Click on **Import an action** in the middle of the page. 8. Choose the **action sequence** you have downloaded before. 9. Click on **Finish your automated action** at the bottom of the page. If Topdesk gives the following error: "The card can't be saved because of a syntax error." make sure that the description field on the **Configure the action** page has a value. ## Trigger action sequence An action sequence can be triggered by the following executions: 1. Linked events 2. Action sequence available in context menu ### Linked Events In TOPdesk you can configure events which can be used to automatically trigger actions. Events can be generic, such as the creation of a new card. Or they can be very specific, where the action is only triggered when the specific details of the event are met. If you want to know how to configure linked events, contact your TOPdesk Customer success manager. * [From linked event](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/create-an-issue-in-jira.md) ### Context menu Action sequences can be made available in the context menu of a field in TOPdesk. By clicking on the action sequence the action sequence is activated. * [From context menu](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/update-an-issue-in-jira.md) --- version: "Working version" language: "en" --- # Installation The TOPdesk Jira integration works with an app that needs to be installed in Jira. In the app, you can then configure the API details of TOPdesk. This is necessary to have Jira and TOPdesk communicate with each other. ## Step 1: Install the app in Jira A Jira admin can install the app in Jira by following these steps: 1. Login to Jira as an **administrator**. 2. Select ⚙️ \> **Apps**. 3. Search for the **TOPdesk Jira integration** app and open it. 4. Click on **Try it free** or Buy now at the top of the page. Jira will let you know when the app is installed successfully. ## Step 2: Create a functional operator in TOPdesk The Jira app needs access to your TOPdesk instance. We're going to create a functional operator in TOPdesk with sufficient rights to the relevant TOPdesk API's. In step 3, we're going to use this functional operator to give the Jira app access to TOPdesk. ### 2.1: Create an operator 1. **Create a new operator**: TOPdesk Menu \> New \> Supporting Files \> Operator. 2. In the surname field, fill out **Jira integration**. 3. Fill out the mandatory **Site** field. 4. Select under TOPdesk login to **add login credentials**. 5. **Save** the new operator. ### 2.2: Create a permission group 1. **Create a new permission group**: TOPdesk Menu \> New \> Supporting files \> Permission Group. 2. Give it a clear name, such as **Jira integration permissions**. 3. **Enable** the permissions as stated in the 4 tabs below. 4. **Save** the new permissions group. #### Call Management | Permission | Read | Write | Create | |--------------------|------|-------|--------| | First line calls | ✅ | ✅ | ✅ | | Second line calls | ✅ | ✅ | ✅ | | Standard Solutions | ✅ | ✅ | ✅ | #### Change Management | Permission | Read | Write | Create | |------------------------------|------|-------|--------| | Request for Simple Change | ✅ | ✅ | ✅ | | Request for Extensive Change | ✅ | ✅ | ✅ | | Templates | ✅ | | | #### Supporting Files | Permission | Read | |------------|------| | Persons | ✅ | #### Reporting API | Permission | Read | Write | |---------------------------|------|-------| | REST API | ✅ | | | Use application passwords | | ✅ | ![image-20250617-135706.png](https://docs.apps.avisi.com/__attachments/a_c5a88d6b08d49d23f6e76a324e7bdaa8956a5ead46c3111e454b540b486cdfa6/image-20250617-135706.png?cb=37a9b3fa94a352471a92bebb6b7dcc87) The permissions that need to be configured ### 2.3: Link the operator to the permission group 1. At the top of the permission group, select the **Operators** tab. 2. Select the blue **Links Wizard** . (If you can't find this button, make sure to save the permission group first). 3. Find and **check the box** for the Jira integration operator you created earlier. 4. Select the **Link** button. ### 2.4: Create an application password The TOPdesk Jira Integration requires an application password, not the password used to login to the web interface. To create an application password: 1. Login with the Jira integration operator you created earlier. 2. Select ![image-20250617-135751.png](https://docs.apps.avisi.com/__attachments/a_9990460d7338dafe18734799b9487ee85c4d20e2f275ffba9c665bdb5615e20a/image-20250617-135751.png?cb=02131cd76b28c461b3a26fde56609c94) and choose **My Settings**. 3. Go to **Application passwords** and click on the **Add** button. 4. For Application name, choose **TOPdesk Jira Integration**. 5. Choose an expiration date in the future and select **Create**. 6. Save the application password so you can use it in the next step. ## Step 3: Configure the TOPdesk API details in Jira Once the app is installed in Jira and you created a functional operator in TOPdesk, you can fill out the API details in Jira. You can find the API settings by following these steps: 1. Login to Jira as an **administrator**. 2. Select ⚙️ in the top right corner 3. Select **Marketplace Apps** 4. Find **TOPdesk integration** in the menu on the left and open **API settings**. On the API settings page, you are presented with three fields that are used to give the app access to TOPdesk. | Input field | Description | |----------------------|---------------------------------------------------------------------------------------------------------------------------------------------| | Url | This is the URL that points to your TOPdesk SaaS instance. The URL is typically in the format `https://.topdesk.net/tas/api`. | | Username | This is the name of the functional operator that you created in *2.1: Create an operator.* | | Application password | This is the application password of the functional operator that you created in step *2.4: Create an application password*. | ![image-20250617-135836.png](https://docs.apps.avisi.com/__attachments/a_ea347b9283de1f27cd4e37e299e9a243f6ea3fb419f3b2102338f25a1ea5c379/image-20250617-135836.png?cb=a0ce447e3b629a3c95ba1af809d6a800) When you have correctly filled in the API settings, you will get the following success message: ![image-20250617-135846.png](https://docs.apps.avisi.com/__attachments/a_42696c216337d4a8787cc68621d1e88fa8341a54ad685a55e793d33685f7609c/image-20250617-135846.png?cb=d49809ab0ab9126b25c3e17a9dfbf283) If there is something wrong, you will get the following error message: ![image-20250617-135852.png](https://docs.apps.avisi.com/__attachments/a_ce9cdf0b087e8c224e9535c3d600e04626244a87a088c45b5a67b6d01ceddb75/image-20250617-135852.png?cb=19cd1dbe7585de418179e9bc97b73803) If you need any help with the installation, you can reach out to our service desk: 🔗 ## Installation complete When the API settings are set correct, you are connected to TOPdesk. You can now start to create issues from Jira or changes/incidents from TOPdesk. * [From Jira to TOPdesk](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/from-jira-to-topdesk.md) * [From TOPdesk to Jira](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/from-topdesk-to-jira.md) --- version: "Working version" language: "en" --- # Troubleshooting ## Invalid license Throughout the integration we check if your license is still active. When Atlassian tells us there is an issue with your license, we display a message to indicate this. To verify your license in Jira: * Log in as an Administrator. * Navigate to Settings → Apps. * Navigate to the menu item 'Manage apps' in the section 'Atlassian Marketplace'. * Look for TOPdesk Jira Integration and expand the entry. ## Get support If you need any help with your license, please open a [support request](https://avisi-support.atlassian.net/servicedesk/customer/portal/55) 🔗 in our Service Desk. ## Whitelist IP Some TOPdesk instances require IP addresses to be whitelisted in order to access TOPdesk. The current ip to whitelist is: 34.91.243.90. --- version: "Working version" language: "en" --- # Links [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1222136/) 🔗 [Support](https://avisi-support.atlassian.net/servicedesk/customer/portal/55) 🔗 [Roadmap](https://trello.com/b/o5ZnYd51/topdesk-jira-integration-public-roadmap) 🔗 [Product demo](https://youtu.be/IUMshoOph2U) 🔗 --- version: "Working version" language: "en" --- # Release notes * [18-12-2024](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/18-12-2024.md) * [28-09-2023](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/28-09-2023.md) * [07-08-2023](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/07-08-2023.md) * [08-11-2022](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/08-11-2022.md) * [17-10-2022](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/17-10-2022.md) * [15-09-2022](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/15-09-2022.md) * [27-06-2022](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/27-06-2022.md) * [18-05-2022](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/18-05-2022.md) * [19-4-2022](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/19-4-2022.md) * [14-12-2020](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/14-12-2020.md) * [02-12-2020](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/02-12-2020.md) * [13-11-2020](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/13-11-2020.md) * [27-10-2020](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/27-10-2020.md) * [07-09-2020](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/07-09-2020.md) * [19-06-2020](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/19-06-2020.md) --- version: "Working version" language: "en" --- # Security Policy ## Avisi Apps Security Policy The [Avisi Apps Security Policy](https://docs.apps.avisi.com/en/legal-atlassian/latest/security-policy.md) can be found in the [Avisi Apps Legal documentation](https://avisi-support.atlassian.net/wiki/spaces/Legal/pages/4298178675/Documentation). The rest of this page documents information that is specific for the TOPdesk Jira integration. ## Hosting The TOPdesk Jira integration runs on Google Cloud. Google Cloud has published a security statement, which you can find here: [Google Cloud Security Statement](https://cloud.google.com/security) 🔗. ## Product security Our products process sensitive information. We make sure that our products are as secure as possible by attending to the following things: * TLS 1.2+ encrypted connections to and from our servers. * TLS 1.2+ encrypted connections between our servers. * HSTS to prevent downgrade attacks and cookie hijacking. * MITM-attack prevention. ## Backups We make sure that your data is stored safely by making daily backups of your data. --- version: "Working version" language: "en" --- # Security / Privacy [Privacy policy](https://docs.apps.avisi.com/en/legal-atlassian/latest/privacy-security.md) 🔗 [Security policy](https://docs.apps.avisi.com/en/topdesk-jira-integration/latest/security-policy.md) --- version: "Working version" language: "en" --- # Set a priority Setting priority is almost the same as adding a field to the `fields` object. Setting a priority makes it clear for your Jira operators which issues to handle first. Syncing the priority in TOPdesk to Jira is a great way to keep everyone on the same page. ## Getting Jira priority id's To get the ID's for the Jira priorities you can use their [API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-priorities/#api-rest-api-3-priority-search-get) 🔗. ## HTTP Body In this case, the default **update issue** action sequences has been used that is generated for changes. In this case the `priority` field is added. JSON { "issue": { "fields": { "priority": { "id": "1" }, "summary": "${briefdescription}", "description": "<#list _progresstrail.requests as request>${request.richtext!}" } }, "change": { "id": "${unid}", "number": "${number}" } } ## Mapping priorities The previous example could be a great start, but most likely you don't want to configure an action sequence per Jira priority level. It would be better to use the priority from TOPdesk and sync that to Jira. This can be done by defining a field mapping inside your action sequence. To create this field mapping, you will have to know all the priority id's from the TOPdesk priorities and the Jira priorities. There doesn't seem to be an easy way of getting all TOPdesk priority id's so one way is to bruteforce this via an action sequence and reading the logs to see the priority id. Once you have the required priority id's you can create a mapping like the example below. ![image-20250617-145622.png](https://docs.apps.avisi.com/__attachments/a_2e39e4ba3c2477261b22b1e227dffdb1f53ce2e6e0468d5d5cd6447355c17573/image-20250617-145622.png?cb=1979758e110581e13828f292f703d611) After adding the value mapping to the action sequence you can reconfigure the body. JSON { "issue": { "fields": { "priority": { "id": "${_map(priorityid, 'priority mapping')}" }, "summary": "${briefdescription}", "description": "<#list _progresstrail.requests as request>${request.richtext!}" } }, "change": { "id": "${unid}", "number": "${number}" } } Now, when executing the action sequence, the `priorityid` from TOPdesk will be converted to a Jira priority id before the HTTP request is made. --- version: "Working version" language: "en" --- # Transition an issue Transitioning an issue can be helpful to let your Jira operators know the status of the linked incident or change. When the Jira operator is watching an issue, they will get notified by Atlassian when the status of an issue changes. With this in mind, transitions can be triggered via linked events in TOPdesk when customers add comments to incidents or changes. ## Getting Jira transition id's To get the transition ID's for company managed projects: * Select ⚙️ \> **Issues**. * Navigate to **workflows**. * Edit the workflow that is linked to the correct project. * Go into **text** mode. * Then in the column **Transitions (id)** you find the ID's. For team managed projects: * Find an existing issue key, i.e. TEST-123. * Use Atlassian's [Transition API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-transitions-get) 🔗 together with the issue key. * **Note**: only the transitions that are available at that moment are shown. ## HTTP Body In this case, the default **update issue** action sequences has been used that is generated for changes. In this case transition id `31` is a placeholder id. JSON { "issue": { "transition": { "id": 31 } }, "change": { "id": "${unid}", "number": "${number}" } } It is also possible to update fields along side transitioning an issue. JSON { "issue": { "fields": { "summary": "${briefdescription}", "description": "<#list _progresstrail.requests as request>${request.richtext!}" }, "transition": { "id": 31 } }, "change": { "id": "${unid}", "number": "${number}" } } ## Binding to an event One way of using these transitions is by binding them to TOPdesk events. This way we can configure action sequences per status change. ![image-20250617-145503.png](https://docs.apps.avisi.com/__attachments/a_cb7f1231db1d08bde5b1f9cdda620c4b4390e1284be0468e49f4b719a80ae499/image-20250617-145503.png?cb=307b49dd78ac65b8207caf364161dda6) In this example you can see that when the change status changes to "In progress" the "Demo action sequence" is called, which is the action sequence defined earlier on this page. [Next Page](https://docs.apps.avisi.com/llms-full.txt/1)