Launch Packages

Overview

One of the main functions of a Portal Application is to launch other published applications/packages and handle the data that goes to and comes back from them. The package launching functionality of the Application Starter Framework allows your Portal Application to send initial data to the launched package and accept data from the launched package when the user returns to the Portal Application.

The system stores input and output data from the package launch functions in different data containers. The following table describes these containers in more detail.

Container	Description
Meta	The Meta container contains meta data that may help to describe the context in which the package is launched. This could include the name of the person launching the package as well as the time and date the package is launched. The system automatically passes this meta information from the starter to the launched package.
DataLog	The DataLog container contains answers to questions within the launched package. A practical use of the DataLog would be to initialize questions in the launched package with certain answers. If you have stored a user's answers during a previous session in the launched package you can also use DataLog to restore that data the next time the package. This allows the user to save and resume a session at a later point in time.
DataItem	The DataItem container contains input/output data that is not directly related to the questions within the package but are the input to/result of some of the processing inside the package. Data from the DataLog and DataItem containers together constitute the session data of the package.
StateItem	This container holds input/output data generated by the launched package that contains the (UI)-state of that package. This includes the opened tab and whether the package session has been initialized.
Report	The Report container stores the HTML/PDF report generated in the launched package.
Selected option	This is the value of the navigation button the user clicked to exit the launched package.
PackageInfo	This is meta data about the package that has been launched.
ValidationResults	This is the result of validation in the package (errorcount, warningcount).
ModificationDate	This is the date of modification of the data.

The package launcher functionality consists of the following functions:

• Launch package
• Create session
• Start session
• Close session
• Get data

The easiest way to launch a package is to invoke the Launch package function in your Portal Application. This launches a published package directly, which means that the system launches the package and returns output data from the launched package when the user exits that package. With direct launch, the Portal Application does not assign an ID to the session the user launches.

Direct Package Launch

To use the direct launch function add a Package launcher node to your logicnet.

Once you have added the node you can go to the Parameters tab of the node and configure the package launch parameters.

Field Name	Description/Use	Type/Options	Optional/Mandatory
Package name	This is the name of the package to launch. This field is case sensitive and you should enter the exact name of the published package to launch.	Text	Mandatory
Package category	This is the project name of the package to launch. If you specify the package category but not the package name the system will launch the active package from that project. If you enter a project name in this field you do not need to enter a package name in the Package name field.	Text	Optional
Option buttons	These are the buttons that should appear in the top bar of the launched package so the user can return to the Portal Application. Each button has the following parameters: Type: submit | save | cancel -  The button type corresponds to the closure options of the content package. Result: This is the value the system will store as the selected option data object when the user returns to the Portal Application. Caption: This is the caption the system displays on the button.	Collection	Optional
Meta data	This is the name of the data container that holds the meta data to pass back to the launched application.	Data Object	Optional
DataItems	This is the name of the data container that holds the data item data to pass to the launched package.	Data Object	Optional
DataLog	This is the name of the data container that holds the input to initialize questions in the launched package.	Data Object	Optional
State	The State container contains input/output data generated by the launched package that contains the (UI)-state of that package. This includes the opened tab and whether the package session was initialized.	Data Object	Optional
Output	This is the name of the data container that stores the DataLog, DataItems, and Report returned from the launched package. The Output data object stores the data returned to the Portal Application from the launched package. When this data is stored, it can be used to restore the session at another time.	Data Object	Optional
Selected option	This is the name of the data object storing the value of the button the user clicked to close the launched package.	Data Object	Optional
Error	This is the name of the data object that stores error details if an error occurs.	Data Object	Optional

Indirect Package Launch

Direct package launch allows users to launch a package from the Portal Application and return to the Portal Application; however, you can use indirect package launch to provide additional function control. You would use indirect package launch, for example, if you wanted to manage the possibility that a user accidentally closed the browser window while in a launched package or if the user's session expires before the user saves their data.

Indirect package launch gives you far more control over the overall package launch process, including making sure you do not lose data accidentally in cases where a user closes their browser window or there is a power outage. It is not a single function—it is a group of functions that breaks the package launch action into smaller steps that identify and store session data so it can be retrieved. The system uses the unique session key to identify the session data, and the first step is to create the temporary session storage and its associated session key.

In the second step the system uses the unique session key to start the session. The session reads and writes data to and from temporary session storage. It is important to note that you should not use the temporary session as permanent data storage, because the system regularly clears sessions as part of general system maintenance. You should store data in designated databases instead.

Indirect Package Launch: Create Session

Create a session by adding a create session node to the logicnet in your Portal Application. Once you have added the node go to the Parameters tab and configure the following items.

Field Name	Description/Use	Type/Options	Optional/Mandatory
Package name	This is the name of the package to launch. This field is case sensitive and you should enter the exact name of the published package to launch.	Text	Mandatory
Package category	This is the project name of the package to launch. If you specify the package category but not the package name the system will launch the active package from that project. If you enter a project name in this field you do not need to enter a package name in the Package name field.	Text	Optional
Option buttons	These are the buttons that should appear in the top bar of the launched package so the user can return to the Portal Application. Each button has the following parameters: Type: submit | save | cancel - The button type corresponds to the closure options of the content package. Result: This is the value the system will store as the selected option data object when the user returns to the Portal Application. Caption: This is the caption the system displays on the button.	Collection	Optional
Meta data	This is the name of the data container that holds the meta data to pass back to the launched application.	Data Object	Optional
DataItem	This is the name of the data container that holds the data item data to pass to the launched package.	Data Object	Optional
DataLog	This is the name of the data container that holds the input to initialize questions in the launched package.	Data Object	Optional
StateItem	The State container holds input/output data generated by the launched package that contains the (UI)-state of that package. This includes the opened tab and whether the package session was initialized.	Data Object	Optional
Output	This is the name of the data container that stores the DataLog, DataItems, and Report returned from the launched package. The Output data object stores the data returned to the Portal Application from the launched package. When this data is stored, it can be used to restore the session at a later time.	Data Object	Optional
Selected option	This is the name of the data object storing the value of the button the user clicked to close the launched package.	Data Object	Optional
Error	This is the name of the data object that stores error details if an error occurs.	Data Object	Optional

Indirect Package Launch: Start Session

Once you have created a session you need to start the session. To start a session add a start session node to the logicnet in your Portal Application. Once you have added the node configure the node parameters on the Parameters tab.

Field Name	Description	Type/Options	Optional/Mandatory
Session key	This is the name of the unique identifier for the session.	Text	Mandatory
Output	This is the name of the data container that stores the DataLog, DataItems, State, and Report returned from the launched package.	Data Object	Optional
Selected option	This is the name of the data object that stores the value of the button the user clicked to close the launched package and return to the Portal Application.	Data Object	Optional
Error	This is the name of the data object that stores error details.	Data Object	Optional

Indirect Package Launch: Close Session

To close a session add a close session node to your Portal Application logicnet. After adding the node you can configure it on the Parameters tab.

Field Name	Description/Use	Type/Use	Optional/Mandatory
Session key	This is the name of the unique identifier for the session.	Text	Optional
Error	This is the name of the data object that stores error details.	Data Object	Optional

Indirect Package Launch: Get Session Data

To retrieve session data, add a get data node to your Portal Application logicnet. Once you have added the node you can configure its parameters on the Parameters tab.

Field Name	Description/Use	Type/Options	Optional/Mandatory
Session key	This is the name of the unique identifier for the session.	Text	Optional
Output	This is the name of the data container that stores the DataLog, DataItems, State, and Report returned from the launched package.	Data Object	Optional
Error	This is the name of the data object that stores error details.	Data Object	Optional