Server Action Libraries
A server action library is a .mtd file that contains one or more Action Groups. Its functionality is limited to processing these Action Groups. At runtime, a solution can send a call to a server action library, with or without parameters. The server action library processes the specified Action Group and returns the result to the calling solution.
The advantage of using a server action library is that, since it operates independently of the main (calling) solution, it can be modified outside the solution. The benefits of this are:
•There is no need to modify the design of the main solution;
•Consequently, there would be no need to deploy a modified main solution on the server (to update the existing solution on the server);
•There is no need for client devices to download the modified solution;
•If you modify a server action library, all that needs to be done is to deploy the server action library to the server so that it overwrites the old server action library. This is a deployment that does not affect the overall runtime workflow.
Note, however, that the overheads (in processing power and time) will be greater when using a an Action Group in a server action library than when using an Action Group in the main solution. Consequently, a server action library should only be used if its main benefit (of independent modification and execution) provides a clear advantage over using an Action Group in the main solution.
MobileTogether Server Advanced Edition
Server action libraries can be deployed to MobileTogether Server Advanced Edition only, not to the standard edition of MobileTogether Server.
Use case
For example, consider a situation in which data is retrieved from a data structure that is outside your control and that changes arbitrarily and at irregular intervals. It might be difficult to modify and deploy a new main solution and update already downloaded solutions each time this data structure changes. However, a server action library could deal with the modifications of the data structure outside the main solution, process the modified data structure, and return data to the main solution so that the returned data conforms to the structure expected by the solution.
The advantages are clear:
•The server action library, since its purpose is limited, is smaller and simpler than the main solution and can be changed easily and quickly.
•The modified external data structure can be processed entirely within the server action library so that data is retrieved from the external data structure and sent to the main solution in a structure that the main solution uses.
•The modified server action library can be deployed to the server in a simple deployment procedure. The main solution, which is also deployed on the server, does not need to be modified in any way. Neither will solutions already downloaded to clients need to be updated.
Example
In our description of server action libraries in this section, we use the example of a simple server action library which reads the contents of a specified folder by using MobileTogether's Read Folder action. This action in the server action library reads information about each item in the folder—subfolder or file—and stores information about the item in an XML tree of the server action library. The data tree is then sent from the server action library to the main solution as the return value of the server action library.
In our example, the key issue to be resolved in the main solution is how to specify which one of three alternative folders should be read. Let us say that the main solution works with three fixed (static and unchanging) datasets that are based on actual collections—one each for books, films, and music. In the main solution, the user selects one of the folders (books, films, or music), and the main solution must read the selected folder. A problem arises if any of the actual underlying collections is changed—because the main solution uses fixed datasets and these will then be outdated. A change could be any of the following: (i) new or modified folder contents, (ii) a modified structure of the data tree containing folder information, and/or (iii) a different folder location.
In our example, we have chosen to consider only a change of folder location. If the fixed datasets were in the main solution and you decided to update these, then the modified main solution would have to be redeployed to MobileTogether Server and be re-downloaded to all affected client devices. This is where the server action library comes in. The (new) folder locations can be specified in the server action library, so that the main solution is not concerned with the folder location. It deals directly with the data about the respective folder, which will be forwarded to it by the server action library. The updates can be carried out in the server action library and the main solution will not need to be modified. The main solution would call an Action Group of the server action library. The Action Group would read the data of the relevant folder, store the folder data in a tree node, and return this data to the main solution. If a folder location changes, then the main solution will have the new data without having to be modified.
The screenshot below shows a control action of the main solution. The action executes a call to an Action Group named ScanFolder (which is defined in the server action library named ServerLibrary.mtd). The call contains a single parameter named $FolderToScan, the value of which is provided by the user of the main solution and stored there in a page source node. This user input indicates the type of collection (books, films, or music) that the user wants to scan. When the call to the Action Group is made at runtime, the Action Group will be executed in the server action library (that is outside the main solution) and the data about the scanned folder will be passed back to the main solution and stored in a solution variable named $FolderReadout. This variable, containing the data of the scanned folder, will replace the contents of the $XML1 page source in the main solution (achieved with the Replace Node(s) action). As a result, the data now contained in $XML1 is the updated information about the scanned folder.
Note the following points about making a call to a server action library and about the screenshot above. To see the relevant settings, you can open the tutorial file named MainSolution.mtd in the ServerActionLibraries folder of the Tutorials folder. In order to scan a real folder during a simulation, you will need to specify, in the server action library file (ServerLibrary.mtd), paths to real folders on your system (see the topic Create a server action library for details).
•The screenshot above shows the Actions dialog of the OnFinishEditing action of the main solution's only combo box control.
•The user's selection in this combo box—which can be one of the values, Books, Films, Music—will be saved in the node $PERSISTENT/Root/UserSelection.
•The server action libraries you want to access from the main solution must be added to the main solution's server action libraries in the Files Pane.
•Once a server action library has been added to a solution (see previous point), then all Action Groups of that server action library will be available automatically in Action dialogs of the solution (see the Action Groups section in the screenshot above).
•In the main solution, typically, a Let action is used to call an Action Group of the server action library (see screenshot above). This is because the Let action's variable ($FolderReadout in the screenshot above) can be easily set to receive the return value of the Action Group (see screenshot above).
•When a call is made to an Action Group, the Action Group's parameters—defined in the server action library—are listed inside the definition of the Let action. The ScanFolder Action Group that is shown in the screenshot above has a parameter named $FolderToScan. You can now define the value that you want this parameter to have when the call is made to the Action Group. In our example, this parameter is the user's selection, which is made via the solution's combo box and stored in the node $PERSISTENT/Root/UserSelection as the value of the $FolderToScan variable.
•The Replace Node(s) action replaces the data of the $XML1 page source in the main solution with the data in the $FolderReadout variable—which is the data returned from the server action library.