Room Extensions - Design Time

During the life-cycle of the room, parameter values and references are taken from the context and exposed to the extension, which processes the input and returns the result. The room or room part adds the result to the context, so that it is available when other extensions are processed. See graphic below.

Planning the dataflow of an extension during design time means to configure a mapping between context parameters and extension parameters. The mapping determines the sources of the input parameter values and the destination of the output parameter values. The mapping is performed by a room template creator in the template administration. The graphic below shows an example how the mapping is done.

The set of parameters in the template administration encloses constants, external parameters and output parameters of extensions. While the mapping of a constant directly assigns the value, the mapping of external parameters or extension output generates a reference to a variable that is filled at run time, e.g. when the room or room part is created. There are also system parameters that are handled internally and therefore are not displayed in the UI.

Constants are fixed by the template creator at design time. For example the parameter Access (see above graphic) can be private or public. The values are offered in a drop down list box that is filled by a value set provider.
System parameters are contributed by the room. A prominent example is the roomInfo.
External parameters are defined at design time, but the value is filled in manually at run time. The user who creates a room is prompted for the value.
Extension output can be used as input for another extension.

An important issue that must be taken into account is the availability of a parameter. First, the availability of a parameter depends on the extension point. For example, the system parameter NEW_OWNER_OF_ROOM is available only when the extension point ON_SET_OWNER_OF_ROOM is processed. A table in Extension Points and Context describes, which system parameters are available at which extension point. Second, the availability of a parameter may depend on another extension that must execute before and deliver the value as an output parameter.

Obviously, for the template creator it is possible to configure deadlocks (see graphic below). If e.g. extension e ₁ requires parameter p ₂ from extension e ₂ , but extension e ₂ requires parameter p ₁ from extension e ₁ at the same extension point, this cannot work.

Unfortunately a deadlock causes no exception at template creation, the error occurs at room- or room part creation. For the extension developer as well as for the template creator therefore it is important to plan and test the extension usage.

The above graphic shows, how the parameter mapping can be planned. External parameters, system parameters, output parameters and constants are used as input parameters of extensions at a dedicated extension point. Extension 1 uses its output at point 1 as input at point 2. Extension 2 shows that extensions do not need to have input parameters. For example an extension could produce a GUID that is later used to create a unique object. Extensions also do not need to have output parameters. An extension may just report the input, like the status engine does. Extensions even do not need to have any parameters, there could be an extension that just counts how many rooms are created and deleted and reports the value to some backend.

The above graphic gives an example of a parameter-mapping plan. The template creator wants the room to create a document folder that should be named "Documents of %s". At "%s" the creator wants to have the name of the room the folder belongs to. The creator uses the RoomPropertyExtension to extract the room name from the system parameter RoomInfo. The Concat extension allows concatenating the room name and the string constant "Workspace of ". The result is given to the CmRoomExtension, which creates the workspace and outputs the path that is mapped to the start_uri of an iView. All assignments are performed at the same extension point.

The parameter availability is related to another issue, the sequence of the extension execution. There are three mechanisms that influence this sequence:

The Life Cycle
A room is created before it can be deleted. See Extension Points and Context to learn more about the extension point dependencies within the room life-cycle.
Parameter Dependencies
When extension output is later used as extension input, the extension engine automatically resolves these dependencies and executes the extensions in the required order. In case of a deadlock, the engine rolls back and reports an error.
Configured Dependencies
There are use cases, where an extension bases on backend modifications performed by another extension, e.g. one extension creates an object, and a second extension adds permissions. Fort this there is an explicit dependency parameter in the template wizard.