Altova MobileTogether Designer

The MapForce Transfer action enables one set of data structures to be converted (mapped) to a second set of data structures. Each data structure of the output set can be written to a file or to a node of a page source.

To carry out the MapForce transfer, you will need to use the following additional components:

•Altova MapForce to design the mapping of one set of input data structures to a set of output data structures. After the mapping has been designed, it is generated as a MapForce Server Execution (MFX or .mfx) file.

•Altova MapForce Server must be located on the same machine as MobileTogether Server. It is called by MobileTogether to process the MFX file and generate the output data structures.

A MapForce design

A MapForce design is created in Altova MapForce; it maps input data structures to one or more output data structures. In the example design shown below, there is one input data structure, which is an Excel file, and one output data structure, which is an XML file. Each data structure (or component in MapForce jargon) has a name. A design can have multiple input components and multiple output components.

After the mapping design has been completed, use MapForce's File | Compile to MapForce Server Execution File command to generate an MFX file. At runtime, the MFX file is used by MapForce Server to generate the output data structure.

In order to use the MapForce Transfer action of MobileTogether, you will need to know the following details of the MapForce design:

•The names of the input and output components that you want to use. (In the design shown above, these are, respectively, SalesByRegionAndMonth and sales-report.) Note that you can specify multiple input and output components. If, in the design, multiple input components are required to generate one output data structure, then they must all be supplied as (input and output) parameters to the MapForce Transfer action.

•In some MapForce designs, value parameters are used as part of the process of generating the mapped output data structure. Each such parameter takes a value, which is used in some way or the other towards generating the output data structure. You will need to know the names of any such parameters that you might need to correctly generate the output data structure.

For more information about creating MapForce designs and how mapping works, see the MapForce user manual. Also see the MapForce Server user manual.

MobileTogether's MapForce Transfer action

The MapForce Transfer action makes a call to MapForce Server, supplying it with an MFX file to process and the required input data. The screenshot below shows a MapForce Transfer action that is based on the mapping design shown above.

The action's settings are as follows:

•Server MFX File Path locates the MFX file to use.

•Input Parameters: Each input parameter specifies an input component of the mapping together with the data that should be used for this input component. You can specify multiple input parameters; make sure that you specify all the input components that are required to correctly generate the output data structure you want. The Input Parameter Name setting specifies the name of the input component (from the MapForce design). You can then choose whether to supply the data for that input component from a page source node or from a file. Then select the node or file. The input component specified in the screenshot below is SalesByRegionAndMonth; since this component is an Excel data structure, an Excel file is supplied that has exactly the same structure as that of the input component. This is necessary for the mapping to be successful.

•Output Parameters: Each output parameter specifies an output component of the mapping together with the location to which the output data structure should be written. You can specify multiple output parameters. The Output Parameter Name setting specifies the name of the output component (in the MapForce design) that you want to generate. You can then choose whether the output data structure should be written to a page source node or to a file. Then select the node or file. The output component specified in the screenshot above is sales-report, and it will be saved to the root element (AllSales) of the $XML2 page source. Note that the entire output data structure will be copied to the node specified. So if an XML fragment is generated, then the entire XML fragment is copied to the specified node. You should make sure that the generated data structure will fit correctly into the structure of the target node.

•Value Parameters: These are name–value pairs that provide values as inputs for use in the mapping. The name part of a pair is the name of an input component in MapForce; the value part is the value to be passed to this component at run time. You can create as many value parameters as you like.

MobileTogether extension functions

MobileTogether provides a range of XPath extension functions that have been specifically created for use in MobileTogether designs. Some functions can be particularly useful with specific actions. For example, mt-available-languages() returns the languages in which the solution is available and could, for example, be used with the Message Box action. If a function is especially relevant to this action, it is listed below. For a full list of extension functions and their descriptions, see the topic MobileTogether Extension Functions.