Supersessions

Introduction

In a production, any session is unique to the production. In some cases, a production sends messages to other productions. In such cases, it can be useful to define a supersession that connects the activities across the productions. To do so, you use the Generate SuperSession ID and SendSuperSession settings.

When supersessions are defined, the supersession ID is displayed as SuperSession property of the message header within the message traces.

Configuring Productions to Use Supersessions

Supersessions are relevant when multiple productions communicate with each other, so generally you perform this configuration within multiple productions.

Setting up supersessions is easiest when the productions communicate via HTTP (which includes SOAP), because there is a default system that relies on a private InterSystems HTTP header. In such cases, to configure a production to use supersessions:

• Enable the Generate SuperSession ID setting in all applicable business services (all business services that generate activity that will result in messages being sent to another production).

• Enable the SendSuperSession setting in all applicable business operations (all business operations that send messages to the other productions).

Wherever the communications between productions do not use HTTP, however, additional work is needed. Specifically:

• Define a convention to represent the supersession ID in the messages that pass between productions.

• For a business operation, add custom code as following:

  1. Call the IncludeSuperSession() of the business operation. This method returns 1 if the SendSuperSession setting is enabled and if the %SuperSession property of the business operation has been set.

  2. When generating the outbound message, use the %SuperSession property as the supersession ID in that message.

  If SendSuperSession is 1, the business operation will automatically use the %SuperSession property in headers for response messages within the production; no custom code is needed.

Also, if you want to customize the supersession identifiers, implement the OnGenerateSuperSession() callback in the business services. See Ens.HostOpens in a new tab, from which this callback is inherited. This method receives the message header, Ens.MessageHeaderOpens in a new tab, as input and should return the supersession ID. The business service will then automatically use your custom value as the supersession identifier.

Supersession Processing Details

If you have to write custom code to implement supersessions, it is helpful to understand the overall flow in more detail. If Generate SuperSession ID is enabled for a business service, then on receiving input:

1. As an initial step, if the business service uses an adapter that uses HTTP, it looks for the VND.InterSystems.Ensemble.SuperSession HTTP header. If this header is not null, the business service uses its value to set its own %SuperSession property.

   For other business services, there is no equivalent step.

2. After any initial processing, if the %SuperSession property of the business service is null, the business service calls the OnGenerateSuperSession() callback. If that method returns a value, the business service uses that value to set its own %SuperSession property.

3. The business service sets the SuperSession value in all message headers, including the response to the caller.

Similarly, if SendSuperSession is enabled for a business operation, then on receiving input:

1. The business operation checks the received message header for a non-null value of the SuperSession property.

2. If SuperSession is not null, the business operation uses that value to set its own %SuperSession property, where it can be used by adapter methods.

3. If the associated adapter uses HTTP, it automatically retrieves the %SuperSession property of the business operation and uses that value in the outgoing HTTP header, specifically VND.InterSystems.Ensemble.SuperSession

   It also uses the same value as the SuperSession property in its response headers