Import workflows

KIWI™ allows you to import a workflow together with related statuses, screens, issue type screen schemes, custom fields and SIL™ scripts.

Contents

KIWI™ Import Page

1. Go to Jira Administration > Add-ons > KIWI™.
2. Go to the Import page.

3. Select kiwi file to be imported (from the list of kiwi files available in your <JIRA_HOME>/kepler/kiwi directory). Optionally you can select a mapping file, if you want to define your own custom fields mapping. 

4. In case no workflow is selected, an error message appears.

5. Configure the settings for the import in the Import Options section after a workflow is selected.

6. Click the Next button, you will get to Step 2: Actions that are going to be executed.

The actions are grouped into sections by their type: Status, Issue Types, Custom Fields, Screens, Issue Type Screen Schemes and General actions.

Each section can be expanded or collapsed with a simple click the section title.

• • When a section is collapsed, the total number of errors and warnings for the section's actions and the first 2 errors(if there are any) is displayed in Messages column. If you want to see more errors or warnings click to expand the message.
  • Initially all sections are collapsed.
  • When a section is expanded, the errors and warnings related to it and for the actions related to custom fields for each action  is displayed in Messages column.
  • There is a 'Change action' link that helps you re-define your custom fields actions as you need.

7. There is a check-box for the actions that are not mandatory that lets you uncheck the actions that you don't want to be executed in the Approve column. All actions are approved(checked) by default.

8. If certain validation errors happen for some action, error messages are displayed for that action.

9. If certain actions have errors and you try to click the Next button, you will receive an error message "Some of the actions have errors. Can not continue with import until all errors are gone!". Fix the errors and then continue with the import.

10. The actions are determined by using the mapping file(if you have defined and selected one) and the automatic mapping process. Starting with version 1.0.1-beta2, you can change it by using the Change action link. Also, the old way is to change the custom fields mapping by creating or changing the mapping file. Click Go to Configure Import and configure the import with the new mapping file selected.

11. Click the Next button if no validation errors appear, you agree with the actions and want to proceed with the import. 

Even if the workflow was imported successfully, it might be the case that one or more actions finished with an error or warning. All these messages(errors, warnings or info) are listed below the  "Successfully imported workflow" message. For instance, when creating a context for a custom field, if no project corresponding to the context can be found on the Export server, the context is not created and a warning message is displayed. If the generated sil aliases file is empty, an info message is displayed.

Import actions

Following rules should be followed in the import process:

• Workflows are mapped by name. If a workflow with the same name as the exported one is fould in Jira import instance, the existing workflow will be updated to match the exported one, otherwise the workflow will be created
• Statuses are mapped by name
• Issue types are mapped by name
• Issue type screen schemes and screen schemes are mapped by name. If an issue type screen scheme with the same name is found in Jira Import instance, it is updated to match the exported one (to have the same description and issue type -> screen scheme associations), otherwise the Issue type screen scheme will be created
• Screens are mapped by name. Every screen that is exported is analyzed, and if the screen exists on Jira Import instance (is found by name), it will be updated to match the screen from the exported file, otherwise the screen will be created
• Custom fields are mapped using mappings according to the screen selection or from the mapping file. If no mapping is found, custom fields are automatically mapped by name and type. Every custom field available in one of the exported screens is analyzed (exported cf):
  1. if a mapping is found, get the custom field from Jira Import instance where exported cf is mapped and update it to match the exported cf: The name, description, searcher and the context(s) are updated
  2. otherwise if a custom field with the same name and type is found in Jira import instance, the existing custom field will be updated to match the exported custom field: The description, searcher and the context(s) are updated
  3. otherwise the custom field will be created

Change action

Here you can change an action related to custom fields.

1. Click the Change action link for an action, a pop-up showing the current action appears:
   
   

This is the pop-up for the action 'Create Custom Field com.atlassian.jira.plugin.system.customfieldtypes:multiselect (named 'multisel', former id 'customfield_14900')'

2. Choose UPDATE instead of CREATE from the select list near Action if you want to change it to an update action. The select list with compatible custom fields having the same type with the source custom field appears:

You can quit any time by clicking the Get me out of here link.

3. Choose the custom field you want from the select list and click the Change action button. Changed action appears in the list of actions. The warning shows that the project with 'MARPRJ' key used in the context of the custom field 'multisel' does not exist:

Please note a validation error might appear after an action is changed if the new destination custom field selected is already mapped in another action, so you should carefully change your actions.

Validation errors

1. The type for the exported custom field doesn't exist on the server where you execute the import. The app is not installed or not enabled:
   

Solution: Install your missing app, or make sure it is enabled.

 2. The exported custom field doesn't have the same type with the custom field that will be mapped to:

Solution: Change the mapping for the custom field with errors (blitz1 in the example above), by using the Change action link or directly into the mapping file, so as to be mapped on a custom field with the same type.

3. Two or more custom fields are mapped into the same custom field:

Solution: Change your mappings by using the Change action link or directly into the mapping file so that only one custom field is mapped on the custom field from the message. If you change directly into the mapping file, for the example above, customfield_10104 must be displayed only once in the right column.