Session APIs

In this Lesson

In this lesson you will be introduced to the API calls used for managing sessions and their scenes.


Sessions exist to provide an execution environment for a scene.

  • Sessions are created by starting a scene
  • Sessions are destroyed when it’s scene no longer has any open layers

Scenes may be started in three ways

  1. The solution’s initial, home, and supporting scenes are opened when a solution starts.
    These scenes are opened in the session specified by the scene’s location.
  2. A scene transitions is used to move from scene to scene.
    Scene transitions always operate within the same session; the session’s active scene merely transitions from one scene to another.
  3. Agents can request a scene to be opened.
    As described in this lesson.

Scene Requests

A scene request is an API request to start a scene. The scene request specifies, among other things, the name of the session in which the scene should be started (either directly or indirectly, more on that later). If the named session already exists then its scene will be replaced by the requested scene. If the named session does not exist then it will be created and the scene will be started in it.

All scene requests are made by creating an instance of the com.seronix.pump.SceneRequest class and then handing it to the Pump for processing. All scene requests are processed asynchronously. The Pump does not start the scene at the time the request is being made, rather, the requests are queued for execution at a later time. This means it is safe for an agent to request a scene at any points during its execution cycle. The Pump will process scene requests only after all agents have been allowed to run to completion – and only if all agents completed successfully. If an error is raised by any agent the scene requests are discarded.

The SceneRequest class contains the following information

  • Scene ID (String)
    This is the ID of the scene to be started.
  • Requestor Name (String)
    This is the name of the process making the request. When agents are making the request this contains the agent’s ID.
  • Requesting Home ID (short)
    This is the ID of the home in which the requestor is running. When agents are making the request this contains the ID of the home which owns the session in which the agent is running.
  • New Home (boolean)
    This value default to false. Setting this value to true requests a new home be created to contain the scene and its session.
  • Home Affinity (String)
    This value defaults to null. This value only applies to scene requests with new home set to true. This value determines which home should contain the scene. If the Pump receives multiple requests for scenes in a new home it will create one new home for each unique home affinity value found in the queues requests. The new home(s) will contain only those scenes which specified the same affinity. For example, making 6 scenes requests with home affinity A on the first 2, home affinity B on the next 2, and home affinity C on the last 2 would result in the creation of three homes – each containing 2 scenes.
  • Session Name Override (String)
    This value defaults to null. This can be used to override the session name (location) stored in the scene. If this value is null the scene will be started in a session named the same as the scene’s location. If this value is not null then it becomes the name of the session in which the scene is started.
    The session name has no impact on where the scene is placed in the home. The scene’s location determines that – regardless of which session it runs in. A scene name is simply a name space used by the Pump and defaulting a scene’s session name to the location name is merely a useful convention.
  • Activation Layers
    This can be used to override the layers to be opened when the scene is started. If null, the scene’s layers marked as Visible By Default in the scene definition will be the initial open layers. If layer IDs are provided in the request they override the Visible By Default layers in the scene definition and only those layers whose ID are specified in the request will be the initial open layers when the scene starts.
    You can find a layer’s ID by using the Layer menu in the scene editor.
  • Reverse Transition Allowed (Boolean)
    This value defaults to false. When true it makes the scene request act like a scene transition: the reverseSceneTransitionAllowed node in the new scene’s agents will be set to true and a reverse scene transition request would transfer control back to the scene that was in the session at the time this request was made.
  • Context List ( List of NamedValue )
    You may pass context name/value pairs in the request. If specified, the context values will be placed into the session before the scene’s agents are started.

Scene Request APIs

The com.seronix.pump.Pump class provides the API for starting scenes. There are many convenience methods which create the SceneRequest instance for you.

  • startScene(Conversation conv, SceneRequest request)
    Submits the specified scene request.
  • startScene(Agent agent, String sceneId)
    A convenience method which submits a SceneRequest containing the specified scene ID.
  • startScene(Conversation conv, String requestorName, String sceneId)
    A convenience method which submits a SceneRequest containing the specified scene ID and requestor name.
  • startScenes(Agent agent, List sceneIds)
    A convenience method which submits multiple scene requests.
  • startScenes(Conversation conv, String requestorName , List sceneIds )

    A convenience method which submits multiple scene requests for the requestor name.

Other Session Related APIs

Here are a few other session related APIs related to sessions.

  • getSessionNamesForHome(Home home)
    Returns a list of the session names contained in the specified home.
  • closeSession(Conversation conv, String sessionName)
    This method will close the named session if it exists.
  • openNewHome(Agent agent)
    This method will create a new home which contains the solution’s initial scene and any related supporting scenes.
  • startClonedHome(Agent agent)
    This will create a new home which contains the same sessions, scenes, and context as the home containing the agent making the call.
  • clearSessionContext(Conversation conv)
    Clears the session context for the agent’s session.
  • clearSessionContext(Conversation conv, String sessionName)
    Clears the session context for the named session.
  • clearSceneTransitionHistory(Agent agent)
    Clears the Scene transition history for the agent’ session. After calling this method any future requests for a reverse scene transition requests will be a NOOP until a forward scene transition is received.

That concludes this lesson.