In this page

Step-by-step guide

This section provides a step-by-step guide to help you migrate your Better PDF Exporter for Jira configuration from Server/Data Center to Cloud.

It assumes that you already understand the differences between the source and target versions. It also assumes that you have administrator access to both.

Step 1: Define your target

Before you begin the migration, define the target configuration you want to achieve in the cloud. This clarity will guide your decisions and ensure each migration step moves you toward the intended end state.

Steps:

  1. Review the cloud documentation.
  2. Analyze your current Server/Data Center PDF templates and views. Use this migration as an opportunity to review the templates' usage and delete the ones that are not used.
  3. Plan your cloud migration in theory, without making changes yet:
    • Check if you have custom or customized templates and/or you use any integration that's not available in the Cloud version.
    • Check out the tutorials and the scripting guide for extra guidance.

Step 2: Get started with the Cloud version

Install the Cloud version of the app and verify it works correctly with the defaults before migrating custom configurations.

Steps:

  1. Install the Cloud version.
  2. Go to Apps (on the Jira left-bar) → Better PDF Exporter for Jira → Get started (button on the top) and follow the guide.
  3. Try a few exports. Don't proceed until the app works with the default resources. If you encounter any problems, feel free to ask our team for help.

Step 3: Migrate your configuration

When you install the app, it automatically creates the default PDF views and resources just like on Server/Data Center. Please note that a few default resources may not have their corresponding versions on Cloud. Those resources and features have been dropped intentionally, or have not been implemented yet. Please refer to the feature parity table or check the known limitations to learn more.

If you don't have any custom or customized PDF templates or views, feel free to skip to Step 4.

Step 3.1: Migrating PDF resources

PDF resources include the PDF templates, Groovy scripts and other configuration files. You can manage these under the PDF templates administration section of the app.

In case you have customized default resources or created custom resources (typically a new PDF template), you need to migrate those manually. Please read the following sections for practical hints. If you are unsure whether you are using custom resources or not, consult with your Jira administrator.

Step 3.1.1: Migrating customized default resources

"Customized default resources" means those PDF templates and Groovy scripts that came with the app built-in, but you modified them. If you have customized any of those resources, then you need to make sure to migrate those manually.

This should be done by comparing the content of your customized resource with the corresponding one in Cloud, and merging all changes you made in the former into the latter. For example, if you customized the issue-fo.vm template in the Server/Data Center version, you should find the default issue-fo.vm template in the Cloud version, and merge those. Use a visual merge tool (like WinMerge or Eclipse's compare and merge editor).

Tips:

  • Don't simply overwrite the Cloud resources with their Server/Data Center counterparts. Only migrate the changes you know you need.
  • If you need to revert a resource to its default state, you can find the default resources on the latest version's Upgrading from... section on the Version history page.
Step 3.1.2: Migrating custom resources

"Custom resources" are PDF templates and Groovy scripts that you created from scratch. If you have a custom resource to migrate, then simply re-create it on Cloud: just create a new resource with the identical name on Cloud, and copy the content from the Server/Data Center resource to this new one.

During the design of the app's Cloud version, we tried our best to make the app 100% compatible with the resources created in the Server/Data Center version, although it's not always possible. Groovy scripts in particular may require modifications. If you find that some template parts or Groovy code is not working on Cloud, feel free to ask our team for help.

Tips:

  • In Groovy scripts, imports of Jira Java API classes will not work. You will have to get the required data from the Jira Cloud REST API (if a suitable endpoint exists).
  • If you use an unsupported integration, you may still get it working if it has a public REST API by following and modifying this recipe. Please refer to the scripting guide for extra guidance.
Step 3.2: Migrating PDF views

PDF views are the export options that appear in the "Export" menus on different Jira screens. You can manage these under the PDF views administration section of the app.

If you changed the configuration of the PDF views on Server/Data Center (created new ones, edited some, deleted some), you just have to re-apply those configuration changes on Cloud. The configuration options are mostly the same on Cloud and Server/Data Center, therefore the migration is trivial.

Step 4: Explore new features

Embrace the full potential of the Cloud version with the new Cloud-only app features:

Questions?

Ask us any time.