Upgrade Considerations

This section describes considerations for upgrading various AquaLogic Service Bus configuration artifacts. It describes how AquaLogic Service Bus 2.1 and AquaLogic Service Bus 2.5 differ in behavior in specific areas that may impact the configurations you are upgrading. It includes the following topics:

Change in Representation of undo Records

The serialized representation of undo records has changed in 2.5 so that undo records can be upgraded in 2.5 and beyond. However, as a result of this enhancement, the undo feature is unavailable if an upgrade occurs from 2.1 to 2.5. In other words, if you make changes in the 2.1 configuration and then upgrade to 2.5, you cannot (in the 2.5 domain) undo the changes you made in the 2.1 domain. However, you can still see the execution and the activation history in the AquaLogic Service Bus Console.

Some Error Codes Are Not Generated in 2.5

In AquaLogic Service Bus 2.5, error codes BEA-382101, BEA-382102, and BEA-382151 are not generated while preparing an inbound response or outbound request.

In AquaLogic Service Bus 2.1, these errors were generated for the conditions as described in the following listing:

BEA-382101—invalid content assigned to $inbound/transport/response
BEA-382102—invalid content assigned to $outbound/transport/request
BEA-382151—invalid service name assigned to $outbound@name

In AquaLogic Service Bus 2.1, these errors were caught in the binding layer at run time.

In AquaLogic Service Bus 2.5, these errors are caught at design time in the Replace action and result in an error code of BEA-382040, indicating that an Assign action failed.

New Error Codes Require Update

If you use WSS or relied on specific AquaLogic Service Bus 2.1 error codes, either on proxy service error-handlers or client-side code, note the following change in AquaLogic Service Bus 2.5.

Whenever WebLogic Server WSS returns a SOAP fault to AquaLogic Service Bus, the AquaLogic Service Bus message-context has a fault with:

error code: BEA-386201
description: A web service security fault occurred [<root-wss-error>][<root-wss-fault-string>] where:

root-wss-error is the error-code from the WebLogic Server WSS SOAP fault,
root-wss-fault-string is the fault-string from the WebLogic Server WSS SOAP fault.

details: an instance of XML element {http://www.bea.com/wli/sb/errors}WebServiceSecurityFault. This XML element also contains the root-fault error-code, fault-string, and fault-details.

The AquaLogic Service Bus default error handler returns the root SOAP fault to the client.

BEA recommends that you update your error-handlers and/or client-side code to deal with the new error codes.
You can also write an error-handler that maps the new error-codes back to the AquaLogic Service Bus 2.1 error code. However, this is not a BEA-recommended approach.

Users in the IntegrationOperator Role Do Not Have Export Privileges

In AquaLogic Service Bus 2.1, users in the IntegrationOperator role were allowed to export AquaLogic Service Bus configurations; in 2.5 they are not. The workaround is to reassign such users to a different role.

Only One Credential Mapping Provider Allowed

Only one PKI and one username/password credential mapping provider is allowed in AquaLogic Service Bus 2.5.

In AquaLogic Service 2.5, you can configure at most one PKI credential mapping provider and at most one username/password credential mapping provider. In AquaLogic 2.1, you can have multiple PKI credential mapping providers and multiple username/password credential mapping providers. Consequently, if you are upgrading from AquaLogic 2.1 to 2.5 and you created multiple PKI or username/password credential mapping providers in 2.1, you must import all PKI mapping data into a single PKI credential mapping provider and import all username/password mapping data into a single username/password credential mapping provider.

2.1 SLA Alert Logs are Unavailable in 2.5

In 2.1, SLA alerts were captured in the WebLogic Diagnostics Framework (WLDF) log. Migration to a 2.5 domain removes the contents of the 2.1 log. Consequently, the alerts and their details are not displayed in the 2.5 AquaLogic Service Bus Console.

Alerts in the reporting log are also removed if you perform a migration upgrade; logs are retained if you perform an in-place upgrade.

If the 2.1 alerts are issued in E-mail, they continue to be available in the user E-mail accounts after the upgrade. However, if any of those alerts were configured with a JMS action only (that is, with either a JMS queue or JMS topic defined as the JMS destination), the expected behavior is dependent on the method of upgrade you use:

If you perform an in-place upgrade, and if the JMS queues or topics resided in the local 2.1 domain, then the alerts are still available in the AquaLogic Service Bus Console after the upgrade.
If you perform a migration upgrade, you must set up new queues and topics in the 2.5 domain. Consequently, the old JMS actions are lost.

New Alert Summary Field in AquaLogic Service Bus 2.5

In AquaLogic Service Bus 2.1 you could not customize the content of the alert summary field when you defined an E-mail action for an SLA alert. All alert summaries (the contents of which populated the E-mail's Subject line) contained the text: AquaLogic Service Bus Alert. In AquaLogic Service Bus 2.5 a new alert-summary field that you can customize is provided when you configure SLA alerts and pipeline alert actions.

For those SLA alerts that are migrated from 2.1 to 2.5, AquaLogic Service Bus populates the alert summary field with the 2.1 text: AquaLogic Service Bus Alert.

After you complete the upgrade, you can change the message in the alert summary field to something more descriptive. For more information about configuring alert actions, see "Alert" under Proxy Service: Actions in Using the AquaLogic Service Bus Console.

2.5 Alert Destination Resources are Created from 2.1 Alert Rules

A new resource called an Alert Destination is introduced in AquaLogic Service Bus 2.5. It is used to capture a list of recipients that can receive alert notifications from AquaLogic Service Bus. When an SLA alert rule is upgraded from 2.1 to 2.5, the alert actions configured in the 2.1 SLA Alert Rule are extracted and used to create an Alert Destination resource. The SLA Alert Rule is then updated to reference this resource.

The Alert Destination created resides in the same project and folder as the service with which the alert rule is associated. The name of the Alert Destination is specified as Upgraded Alert Destination - xxxxxx, where xxxxxx is a unique number.

The upgrade process creates an Alert Destination for each unique combination of recipients. In other words, if ten SLA Alert Rules with the same set of recipients were upgraded from 2.1, only one Alert Destination resource is created in the same project and folder as the service that is associated with the first SLA Alert Rule.

For information about Alert Destinations, see Alert Destinations in Using the AquaLogic Service Bus Console.

Transport-Level Access Control Changes in 2.5

In AquaLogic Service Bus 2.1, transport-level access control was limited to HTTP and HTTPS proxy services. Access control was enforced by the web-container. The authorization check was done against a weblogic.security.service.URLResource. See

In 2.5, AquaLogic Service Bus has a transport-level access control check on entry to all proxy services, regardless of transport. The call to the authorization service is now done in AquaLogic Service Bus code, the web-container does not do an authorization check anymore. As a side-effect, the check is now done against a com.bea.wli.sb.security.ALSBProxyServiceResource. The default policy on ALSBProxyServiceResource grants access to all requests. You can configure a transport-level access control policy on a proxy service in the AquaLogic Service Bus console, as described in http://download.oracle.com/docs/cd/E13171_01/alsb/docs25/consolehelp/securityconfiguration.html

A policy is composed of one or more policy conditions, grouped together by boolean operators. Most policy conditions can be used to secure any resources (for example is-user-in-role). However, some policy conditions can only be used to secure resources of a specific type. The policy conditions, which can be applied only to URLResource are:

weblogic.entitlement.rules.HttpRequestAttrIsSet
weblogic.entitlement.rules.HttpRequestAttrNumberPredicate
weblogic.entitlement.rules.HttpRequestAttrNumberPredicate
weblogic.entitlement.rules.HttpRequestAttrNumberPredicate
weblogic.entitlement.rules.HttpRequestAttrNumberEquals
weblogic.entitlement.rules.HttpRequestAttrNumberGreater
weblogic.entitlement.rules.HttpRequestAttrNumberLess
weblogic.entitlement.rules.HttpRequestAttrStringEquals

In AquaLogic Service Bus 2.1 you could use these policy conditions to secure HTTP/S proxy services, but these policy conditions are not allowed in AquaLogic Service Bus 2.5.

The context properties passed to the security framework are also different.

Note:

Context properties are passed in a weblogic.security.service.ContextHandler instance. For more information, see

Note:

http://download.oracle.com/docs/cd/E13222_01/wls/docs91/javadocs/weblogic/security/service/ContextHandler.html

Prior to AquaLogic Service Bus 2.5, the web-container passed some URLResource-specific context properties to the security providers. AquaLogic Service Bus 2.5 passes a different set of context properties. Some of these are described in "Adding Policy Conditions" in Security Configuration at:

http://download.oracle.com/docs/cd/E13171_01/alsb/docs25/consolehelp/securityconfiguration.html

As mentioned above, for AquaLogic Service Bus versions after 2.5, all proxy service invocations go through an access control check, including colocated optimized calls, calls to local-transport proxies and calls from the AquaLogic Service Bus test console.
Because URLResource is not used in 2.5, a proxy service's transport-level access control policy is no longer tied to the endpoint's URI. You can change the proxy service URI and the existing policy will still take effect. However, the policy is now dependent on the proxy service location (project and/or folders) and name. Operations such as rename, move, delete and undo for resources, projects, or folders do not effect an authorization provider's policy database. Be careful when performing these operations to avoid losing an access control policy or leaving orphan access control policies in the system. See Known Issue CR222177 in the AquaLogic Service Bus Release Notes at:

http://download.oracle.com/docs/cd/E13171_01/alsb/docs25/relnotes/

The default policy on ALSBProxyServiceResource is automatically created in new AquaLogic Service Bus domains.

During upgrade of AquaLogic Service Bus 2.1 to 2.5, AquaLogic Service Bus checks to see if the default policy on ALSBProxyServiceResource exists in at least one authorization provider. If this policy does not exist, then it is created. Read access to the policy database is optional--if an authorization provider does not support reads, AquaLogic Service Bus displays an alert message:

"AquaLogic Service Bus could not determine if the default ALSBProxyServiceResource policy is present or not because some authorization providers do not implement PolicyReaderMBean. ALSB could not deploy the policy because neither EntitleNet provider nor XACML provider is present. If the policy is indeed missing, the administrator must create it."

Similarly, write access to the policy database is optional. If an authorization provider does not provide write access, AquaLogic Service Bus displays the following alert message:

"AquaLogic Service Bus has determined the default ALSBProxyServiceResource policy is missing. ALSB could not deploy the policy because neither EntitleNet provider nor XACML provider is present. Access to all ALSB proxy services will be denied. The administrator must create the policy using the provider tools."

During a 2.1 to 2.5 upgrade, access control policies on HTTP or HTTPS proxy services are also automatically migrated. If there is a policy on the URLResource matching the service URI, the policy is copied over to the corresponding ALSBProxyServiceResource. The original policy (the one on URLResource) is deleted. There is one exception to this: if the original policy used one of the URLResource-specific conditions, the policy cannot be upgraded. In this case AquaLogic Service Bus creates a policy for this service, which denies all access to the service and writes the following alert to the log file:

"[POLICY MIGRATION] [proxy service: <service>] [authorization provider: <provider>] The 2.1 policy cannot be migrated because it makes use of policy predicates which are specific to URLResource. A deny-all policy will be bound to the proxy. You must re-configure this policy in the console."

Upgrade Guide