If you are upgrading to a later release of Stardust from an earlier release, there are a few things you have to take in account. The following sections document the changes required for specific issues.
For general upgrading, refer to the following topics:
Refer to the following section for specific upgrading issues:
For details on how to upgrade a Stardust version, refer to the Installation Guide. For known issues while upgrading, please refer to the Troubleshooting chapter.
To upgrade the audit trail from a previous Stardust version, use the following sysconsole command:
sysconsole upgraderuntime
with the following arguments:
For detailed information on the sysconsole command, refer to chapter The Sysconsole Command of the Operation Guide.
Refer to the release notes of the current Stardust version ( Release Notes 4.1.0 ) for details on runtime upgrades like schema changes that will be performed with this command on earlier versions.
You can perform a model upgrade via the Sysconsole command or from the Eclipse environment.
Please ask your administrator to perform the upgrade or use the sysconsole command option upgrademodel to upgrade to a newer Stardust version:
sysconsole upgrademodel -file <file> -source <source> -target <target>
Whereby:
For more information on using the sysconsole command please refer to the chapter The Sysconsole Command in the Operation Guide.
In case you import a model in Eclipse with an earlier Stardust version than you use, you will be prompted and asked if you want to upgrade to the currently installed version. Click Yes to upgrade the model.
Currently there is no automated facility for upgrading the libraries contained in existing Dynamic Web projects with Stardust facets to the most recent Stardust version. In that case you have to upgrade the Process Manager facets manually as described in detail in the section Upgrading Process Manager Facets of the chapter Creating a Dynamic Web Project in Eclipse .
If you upgrade from versions earlier than 4.1.0, consider the following issues:
A model upgrade is required to adjust the primitive data type of the predefined Business Date data to
type Calendar (was Timestamp).
Please refer to section General Model Upgrade for details on how to upgrade a model with an earlier Stardust version.
If you upgrade from versions earlier than 4.0.1, consider the following issues:
If you use a custom skin in your Portal, which was applied in a version earlier than 4.0.1, you have to re-select it in the Portal Configuration to apply internal changes for default skin preferences.
Please refer to section Selecting the Portal Skin of chapter Configuring general Portal Components in the End User Handbook for details on how to select custom skins.
If you upgrade from versions earlier than 4.0.0, consider the following issues:
Schema changes have been performed in release 4.0.0 In order to account for schema changes, performing a runtime upgrade will be necessary to operate against audit trails created with earlier versions. For details on these schema changes, please refer to section Schema Changes of our Release Notes 4.0.
In version 4.0 groupId and artifactId of the Camel Templating artifacts have been changed. Apply these changes to your environment in case you upgrade from a version earlier than 4.0. Replace the groupId and artifactId names in your POM files with the new groupId and artifactId accordingly.
The following table provides an overview on the groupId and artifactId changes for the particular projects:
| Project | Old GroupId | Old ArtifactId | New GroupId | New ArtifactId |
|---|---|---|---|---|
| json-utils | com.infinity.integration | json-utils | org.eclipse.stardust.engine.camel | stardust-json-utils |
| camel-itext-convertor | com.infinity.integration | camel-itext-convertor | org.eclipse.stardust.engine.camel | stardust-camel-itext-convertor |
| camel-templating | com.infinity.integration | camel-templating | org.eclipse.stardust.ui.web | stardust-web-camel-templating |
For example change
<groupId>com.infinity.integration</groupId> <artifactId>camel-itext-convertor</artifactId>
to
<groupId>org.eclipse.stardust.engine.camel</groupId> <artifactId>stardust-camel-itext-convertor</artifactId>
If you use a custom skin in your Portal, which was applied in a version earlier than 4.0, you have to re-select it in the Portal Configuration to apply internal changes for default skin preferences.
Please refer to section Selecting the Portal Skin of chapter Configuring general Portal Components in the End User Handbook for details on how to select custom skins.
With version 4.0, document centric access control evaluation is included in a newly created security Jackrabbit repository. In case access control has been set for files individually, access control is now evaluated separately without folder hierarchy inheritance.
If you like to use this feature, but you are using a
repository created with an earlier version, you need to configure the AccessControlProvider inside a
WorkspaceSecurity tag after the SearchIndex entry for each workspace.
In this case add the following workspace security section to the workspace template creation entry in your
repository.xml security file:
<Workspace name="${wsp.name}">
...
<!-- Search index and the file system it uses -->
<SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
...
</SearchIndex>
...
<!-- Workspace Security -->
<WorkspaceSecurity>
<!-- Files with ACLs are evaluated separately without Folder hierarchy. -->
<AccessControlProvider class="org.apache.jackrabbit.core.security.authorization.acl.FileACLProvider" />
</WorkspaceSecurity>
Note that for existing repositories the same entry needs to be added in the workspace.xml
file, which resides in the according repository path, to become effective.
Schema changes have been performed in release 3.1.0. In order to account for schema changes, performing a runtime upgrade will be necessary to operate against audit trails created with earlier versions. For details on these schema changes, please refer to section Schema Changes of our Release Notes 3.1.0.
Additionally consider the following issues in case of an upgrade:
If you use an audit trail database that has been created with an
Stardust version earlier than 3.1.0, you have to deselect and select the
database from the server configuration page. Republishing the server updates the
server.xml file with the new resource definition entry for embedded
database usage.
With release 3.1.0, the Stardust JBoss 6 archetype has been renamed from ipp-archetype-jb62-eap-ipp-ear to ipp-archetype-jb6-eap-ipp-ear to support JBoss 6.3 EAP and 6.4 EAP. Please consider this change if you upgrade your Maven project from an Stardust version older than 3.1.0.
A runtime upgrade against audit trails created with earlier versions adds the new predefined process instance link type RELATED to the LINK_TYPE in the audit trail. This runtime upgrade job is optional and only required for usage of new link type RELATED.
Note that this upgrade job is a trivial one and can be applied without any risk!
Exception handling for embedded service factory services changed with version 2.1.0 to return unwrapped exceptions as with regular API calls. Additionally, raised exceptions now properly honor an existing transaction rollback policy. Note that this change might potentially break existing workarounds you have applied in an earlier version.
A runtime upgrade against audit trails created with earlier versions adds the new predefined process instance link type SPAWN to the audit trail. The SPAWN link type describes the case for just creating a new root process instance from an existing one with optionally copying data. This runtime upgrade job is optional if you are not using the spawn functionality.
Note that this upgrade job is a trivial one and can be applied without any risk!
XML namespaces validation has become stricter since version 2.0. You might face issues if you upgrade from an Stardust version earlier than 2.0 and the following points apply:
For example missing namespaces for a child element of an element fails with an XML processing error since Stardust versions 2.0. Make sure that your XMLs follow the correct XML namespacing standards.
Note that Stardust core APIs and services are not impacted because Stardust APIs and services use proper XML namespacing standards.
See the following examples with wrongly or correctly used namespaces:
<my:Parent xmlns:my="http://custom.solution.sungard.com"> <my:Child></my:Child> </my:Parent>
In this example, we use a namespace prefix my for parent and child, which is correct.
<Parent xmlns="http://custom.solution.sungard.com"> <Child></Child> </Parent>
The correct example above uses a default namespace with no prefix.
<my:Parent xmlns:my="http://custom.solution.sungard.com"> <Child></Child> </my:Parent>
Per XML standard, the child element in the wrong XML example above will belong to the default namespace of
the nearest ancestor of the parent element or an empty namespace if no default namespace is defined in the ancestral
tree and not to the http://custom.solution.sungard.com namespace as required.
When you upgrade Stardust, if it is possible to change the client applications (that is embedded / integrated with Stardust), revisit the namespacing for the XML documents used in your solution and make sure that you have standard XML namespaces for your schemas.
In case it is not possible to change the client applications or the XML namespaces, then you will have to analyze each case and implement solutions like in the below example scenario, to indicate to the XML processors in the Stardust product, of the XML namespaces it has to be aware of while processing your XMLs.
There can be many ways a solution may implement services that consume and produce XML. Below is an example - a java-to-wsdl webservice - which a solution implements on top of the Stardust platform and a proposed solution for this specific problem.
A simple SOAP service's interface that provides an operation ("testOperation") which takes a long number ("testInput") and returns a long number.
TestService.java:
package com.sungard.ipp;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.ParameterStyle;
import javax.jws.soap.SOAPBinding.Style;
import javax.jws.soap.SOAPBinding.Use;
@WebService(name = "TestService")
@SOAPBinding(style = Style.DOCUMENT, use = Use.LITERAL, parameterStyle = ParameterStyle.WRAPPED)
public interface TestService
{
@WebMethod(operationName = "testOperation")
public long testOperation(@WebParam(name = "testInput") long testInput);
}A service implementation implements the interface above to create a mock service implementation that simply returns 10 times the testInput.
TestServiceImpl.java:
package com.sungard.ipp;
import javax.jws.WebService;
@WebService(endpointInterface = "com.sungard.ipp.TestService")
public class TestServiceImpl implements TestService
{
@Override
public long testOperation(long testInput)
{
return 10L * testInput;
}
}An XML configuration for the JAX-WS service under META-INF/spring/test-ws-context.xml:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cxf="http://cxf.apache.org/core"
xmlns:jaxws="http://cxf.apache.org/jaxws"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd
http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd">
<import resource="classpath:META-INF/cxf/cxf.xml" />
<import resource="classpath:META-INF/cxf/cxf-servlet.xml" />
<bean id="testServiceImpl" class="com.sungard.ipp.TestServiceImpl" lazy-init="false"/>
<jaxws:endpoint
name="TestService"
address="/TestService"
publish="true"
implementor="#testServiceImpl" >
</jaxws:endpoint>
</beans><soap:Body>
<com:testOperation xmlns:com="http://ipp.sungard.com/">
<testInput>100</testInput>
</com:testOperation>
</soap:Body>Unmarshalling Error: unexpected element (uri:"http://ipp.sungard.com/", local:"testInput"). Expected elements are <{}testInput>
But the below SOAP request will work (note: this means that the SOAP clients may need to be changed when upgrading):
<soap:Body>
<com:testOperation xmlns:com="http://ipp.sungard.com/">
<testInput>100</testInput>
</com:testOperation>
</soap:Body>Solution:
On Stardust version later or equal 2.0, for Java to WSDL, you have to let the JAXP libraries know explicitly that the XML element form default is qualified to pass on the namespacing to operation arguments and attributes.
You will have to create a package-info.java for every package (data and service packages involved in
the SOAP service) like shown below:
@javax.xml.bind.annotation.XmlSchema(namespace="http://ipp.sungard.com", attributeFormDefault=javax.xml.bind.annotation.XmlNsForm.QUALIFIED, elementFormDefault=javax.xml.bind.annotation.XmlNsForm.QUALIFIED) package com.sungard.ipp;
A runtime upgrade for versions earlier than 1.1 adds the following columns to your schema:
In case you are using the JavaScript source file IppProcessPortalClient.js in your external Web application, you need to upgrade it with the new one provided in the ipp-workflow-perspective.jar file of the new Stardust installation.