Error while editing Workflow Scheme - The entity name must immediately follow the '&' in the entity reference.
Symptoms
The Workflows are missing in the Workflow administration section, and clicking to edit a Workflow Scheme returns an error, as per the screenshots below.
The following error appears in the atlassian-jira.log:
2014-05-12 08:23:13,016 http-bio-8081-exec-16 ERROR local_admin 503x89127x4 1t29hgv 172.16.0.12 /rest/projectconfig/latest/workflowscheme/SBK [common.error.jersey.ThrowableExceptionMapper] Uncaught exception thrown by REST service
com.atlassian.cache.CacheException: java.lang.RuntimeException: com.opensymphony.workflow.FactoryException: Error converting XML to workflow descriptor.: root cause: The entity name must immediately follow the '&' in the entity reference. (line:295 col:68)
at com.atlassian.cache.memory.DelegatingCache.get(DelegatingCache.java:67)
at com.atlassian.jira.workflow.CachingWorkflowDescriptorStore.getWorkflow(CachingWorkflowDescriptorStore.java:67)
at com.atlassian.jira.workflow.JiraWorkflowFactory.getWorkflow(JiraWorkflowFactory.java:37)
at com.opensymphony.workflow.config.DefaultConfiguration.getWorkflow(DefaultConfiguration.java:89)
at com.atlassian.jira.workflow.OSWorkflowManager.getWorkflow(OSWorkflowManager.java:197)
(...)
at java.lang.Thread.run(Unknown Source)
Caused by: java.lang.RuntimeException: com.opensymphony.workflow.FactoryException: Error converting XML to workflow descriptor.: root cause: The entity name must immediately follow the '&' in the entity reference. (line:295 col:68)
at com.atlassian.jira.workflow.CachingWorkflowDescriptorStore$WorkflowCacheLoader.load(CachingWorkflowDescriptorStore.java:142)
(...)
at com.opensymphony.workflow.loader.WorkflowLoader$WorkflowErrorHandler.fatalError(WorkflowLoader.java:125)
at org.apache.xerces.util.ErrorHandlerWrapper.fatalError(Unknown Source)
at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
at org.apache.xerces.impl.XMLScanner.reportFatalError(Unknown Source)
at org.apache.xerces.impl.XMLScanner.scanAttributeValue(Unknown Source)
at org.apache.xerces.impl.XMLNSDocumentScannerImpl.scanAttribute(Unknown Source)
at org.apache.xerces.impl.XMLNSDocumentScannerImpl.scanStartElement(Unknown Source)
at org.apache.xerces.impl.XMLDocumentFragmentScannerImpl$FragmentContentDispatcher.dispatch(Unknown Source)
at org.apache.xerces.impl.XMLDocumentFragmentScannerImpl.scanDocument(Unknown Source)
at org.apache.xerces.parsers.XML11Configuration.parse(Unknown Source)
at org.apache.xerces.parsers.XML11Configuration.parse(Unknown Source)
at org.apache.xerces.parsers.XMLParser.parse(Unknown Source)
at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)
at org.apache.xerces.jaxp.DocumentBuilderImpl.parse(Unknown Source)
at javax.xml.parsers.DocumentBuilder.parse(Unknown Source)
at com.opensymphony.workflow.loader.WorkflowLoader.load(WorkflowLoader.java:75)
at com.opensymphony.workflow.loader.WorkflowLoader.load(WorkflowLoader.java:47)
at com.atlassian.jira.workflow.WorkflowUtil.convertXMLtoWorkflowDescriptor(WorkflowUtil.java:393)
... 205 moreDiagnosis
It is not possible to edit any Workflows or Workflow Schemes, and some transitions might be broken.
Cause
This problem might happen if there are special characters not escaped properly in the one of the Workflows.
Resolution
Take an XML Backup from the JIRA instance and save a copy of the file in a safe directory.
Stop the JIRA instance, to make sure that the users will stop making changes in the data.
Run the following SQL query in the JIRA Database to identify which workflows use the special character '&' in its descriptor:
SELECT * FROM jiraworkflows WHERE descriptor like '%&%';
The query must be adapted according to the character in the error.- Extract the XML Backup zip file, and open the entities.xml file in a text editor.
Browse to the descriptor of the Workflow returned by the query above. Eg:
(...) <Workflow id="xxxxx" name="My Workflow name here"> (...)Search for the step/transition/state containing the special character. Eg:
<results> <unconditional-result old-status="null" status="My & Step" step="6"> (...)Remove the special characters or replace them like the example below:
<results> <unconditional-result old-status="null" status="My and Step" step="6"> (...)Save the changes and compress the entities.xml (along with the activeobjects.xml) into a new zip file.
Important
We highly recommend keeping the original Backup in hand, in case there are any problems during the restore process below.
- Start JIRA again and import the new zip file with the modifications in the workflow into the JIRA instance, using the JIRA XML Restore.
- Once the restore is completed, test whether the Workflow configuration sections are working again.