Mobile Solution Administration

This chapter discusses how to:

• Prepare a solution for packaging.

• Localize solution UI files.

• Customize and localize the Mobile Configurator Client.

• Integrate Mobile Configurator with ERP systems.

• Integrate Mobile Configurator with Mobile Order Capture.

Preparing a Solution for Packaging

Before a Solution can be packaged, it must be prepared for distribution and operation in a mobile environment, and for the transfer of configuration data between mobile and enterprise data stores.

Very little is required to adapt an existing PeopleSoft Configurator Solution for deployment in a Mobile Configurator environment, provided the Solution uses JavaServer Pages.

Depending on the Solution’s implementation, you may need to do one or more of the following tasks:

• Model data must be made specified in the model itself, and not requested from a database or another file. Such externally stored data can be internalized using the Configurator Administration console or Visual Modeler.

  See Internalizing Model Data.

• The restore policy and start page must be set in the CalicoUI.properties (for component models) or CalicoNA.properties (for compound models). You can also set other, optional solution parameters in these properties files. These parameters are:

  • Name (the solution ID).

  • Description.

  • Restore page.

  • The directory that the Solution resides in.

  • Language and country codes.

  • Enable switch to allow the Solution to create new configurations.

  • Solution’s UI Version.

  • Compound model name and version

• If the intended user is non-English-speaking, the Mobile Configurator client must be localized.

  See Localizing Solution UI Files.

• If configuration data is to be passed to and from the components of an ERP system, the Mobile Transfer Service must be integrated.

  See Setting Configuration Restore Policy, Integrating Mobile Configurator with ERP Systems.

You do not need to make additions to the UI files. You also do not need to re-stage the files, as the Packaging Tool can extract them from their deployed or staged locations, however they are distributed.

See Also

Product Modeling with a Component Model

Internalizing Model Data

The Advanced Configurator Administration console can internalize model data for you. It can import externally referenced model data and translate it into internally defined data. The model then becomes self-contained, and can be deployed in a mobile configuration environment needing no access to the product database. You can also include additional attributes in the internalization process.

Note. The Visual Modeler can also internalize data; however, it can only internalize data used within the model. Externally referenced data not used in the model, such as descriptions, can’t be internalized by the Visual Modeler.

To internalize model data:

1. Start the Administration console by selecting Start, Programs, PeopleSoft Applications, Configurator, Administration. Make sure the Configurator Server is started.

2. Select the check box for “Generate self-contained model” to internalize model data.

3. If there is a separate file containing additional external attribute information, enter it in the “Additional attribute file” field.

   Note. Solutions in which external attribute data is queried from the JSP page rather than the model require an extra step in order to internalize this portion of the model’s external data.
   
   The extra step is to create a file that specifies which classes contain the attributes currently being called from the pages.
   
   The file must list the additional classes to be internalized using this format: class\:attribute=type
   
   where type is String, int, float, or Boolean.
   
   For example:
   
   Tires\:description=string
   
   Tires\:sidewall=boolean
   
   Tire\:mfg=string
   
   Wheels\:description=string
   
   Wheels\:mfg=string
   
   The file’s extension can be .txt.

4. Click Compile. The Administration console internalizes data referenced by the appropriate classes in the model as well as any specified in an external attribute file.

Setting Configuration Restore Policy

A user’s request to restore a saved configuration presents a challenge in light of the requirement for that configuration to run on the same, or a compatible version of, the model that it was created with. This is necessary in order to avoid a situation in which picks on the saved configuration do not appear because their corresponding selection points were removed in more recent model updates.

To give you control over which model version is to be used when a saved configuration is restored, a set of standard policies has been established.

The policies are keyed by number as follows:

To implement one of these policies, edit CalicoUI.properties (for component models), or CalicoNA.properties (for compound models), as follows:

• Assign a policy number (1 through 5) to calico.solution.restorePolicy.

• Assign a value to calico.page.restore.

Note. The CalicoUI.properties and CalicoNA.properties files for an application are located in their respective application root directories.

See Also

Product Modeling with a Component Model

Building a Custom User Interface

Localizing Solution UI Files

PeopleSoft Configurator provides templates for localizing text in the Solution UI files. In addition, handling the installer (.msi) files conforms with Win2K methods and practices.

Text strings for localizing the Solution Installer are found in:

• blank.msi—for Packages created with no UI.

• confirm.msi—for Packages created with a configuration UI.

Make sure that these files are in the same directory as the SolPkgr.exe. For more information on localizing your implementation, please refer to the section entitled “Localizing a Windows Installer Package” of the Platform SDK Windows Installer documentation in the MSDN library.

Customizing and Localizing the Mobile Configurator Client

There are a number of reasons you may want to customize the content displayed by the Mobile client. You may want the Mobile client to display your company logo, sales info, or other custom content when it is idle. You may want a way for your mobile user to quickly log into your company support site. You may have a download page that allows your mobile user to quickly access new or updated Solution Installers and other content. This is done easily using standard web page authoring tools and techniques.

The PeopleSoft Mobile Configurator client can be localized and customized without the need to obtain a new version of the executable from PeopleSoft.

Using external HTML files, you can customize these Mobile client UI elements:

• Main window background.

• The target of the Help menu’s On the web item.

• The target of the Help menu’s Updates item.

Customizing the Mobile Client

The Mobile client uses HTML content for the client background area displayed when the client is idle (not actively configuring a product or displaying other content) and when the New Configuration dialog is being displayed.

By default, the Mobile client reads the HTML content from data contained within the client executable (cmc.exe). However, when the Mobile client is launched, it checks for external HTML files in the installation root directory (default location C:\Program Files\PeopleSoft Applications\Mobile Configurator). If it finds external HTML files for this content, it will use them rather than the internal data.

The content for the Help menu’s On the web and Updates items can be replaced using external HTML files. The Updates menu item is only displayed if an external HTML file exists.

To customize the content displayed by the Mobile Client:

1. Use standard web page authoring tools and techniques to create the content page.

2. Name the content page file according to its display requirements, as follows:

   Content shown when...	External file name
   Mobile client is idle.	Idle.htm
   Mobile client is displaying the New Configuration dialog.	FileNew.htm
   User accesses the On the web Help menu item	OnTheWeb.htm
   User accesses the Updates Help menu item (the Updates menu item is only displayed if this external file exists)	Updates.htm

3. Place the content page file in the Mobile client installation root directory. The default installation root directory is C:\Program Files\PeopleSoft Applications\Mobile Configurator (where the cmc.exe) is located. Be sure to include any additional files that the content page is referencing, such as image or sound files.

   Note. If you intend to build an installer for these files, you can locate the Mobile client installation root directory path in the Windows Registry on the client machine under the key:
   
   HKEY_LOCAL_MACHINE\SOFTWARE\PeopleSoft\PeopleSoft Applications\CfgMobile\InstallRoot

The Mobile Configurator client uses the Microsoft Internet Explorer web browser to display the content in the client area and the pop-up windows, so any content appropriate for IE 5.5 (or newer, depending on what is installed on the client machine) can be displayed by the Mobile client. However, keep in mind that the Idle.htm and FileNew.htm content will probably be displayed while the client machine is disconnected and does not have access to the network or Internet, so you should take care to create pages that are displayed correctly when access is unavailable.

Tip for setting up OnTheWeb.htm and Updates.htm

The page the Mobile client initially displays is from the local file, which limits what you can display. To extend display possibilities, include a redirect on the local page to online content or provide links to online content as appropriate.

Localizing the Mobile Client

By default, the Mobile client menu text, dialog text, and messages are in English. Using a Resource Only DLL, you can localize the Mobile client to present text for another language.

The Mobile client menu text, dialog text, messages, and other content are accessed from a Microsoft format resource package. The default resource package is contained within the executable (cmc.exe). However, the Mobile client can load the resources from an external resource package in the form of a Resource Only Dynamic Link Library (DLL). When the Mobile client is launched, it checks for an external DLL file, cmc.dll, in the installation root directory (by default, C:\Program Files\PeopleSoft Applications\Mobile Configurator). If it finds cmc.dll, it loads the resources from the external resource package rather than from the internal package.

For proper operation, all of the Mobile client resources must be present in the external package.

Any tool that can create a Windows resource package in the form of a DLL can be used to create the cmc.dll file. The Mobile Configurator administration installation includes a Microsoft Visual Studio Resource Only DLL project for you to use as a starting point for a localized version.

To localize the client:

The following procedure assumes that you are familiar with how to edit and build a Resource Only DLL.

Warning! When making changes to the cmc.rc as described below, be sure that you don’t change any resource Ids.

1. Create a copy of the sample project and open it with Microsoft Visual Studio (Visual C++). If you are using a tool other than Microsoft Visual C++ create an appropriate project using the source files included with the sample.

2. Open the cmc.rc file:

   • If your localization involves only changing text strings, you can open the cmc.rc file in text mode and modify the strings directly using the text editor. In addition, you may want to change the default HTML content used by the Mobile client as part of your localization.

     See Customizing the Mobile Client.

   • If your localization requires changes to the size or layout of the dialogs, you can open the cmc.rc file using the resource editor rather than the text editor.

3. Replace the English text with text appropriate for your locale.

4. Modify or replace icons and other graphics as needed for your localization.

5. Build the Resource Only DLL. (The details of how to build the DLL depend on the tool used and are beyond the scope of this document.)

6. Copy the resulting cmc.dll file to the directory containing the Mobile client executable (cmc.exe). Typically, this is the Mobile client installation root directory. By default, the installation root directory is C:\Program Files\PeopleSoft Applications\Mobile Configurator.

   Note. If you intend to build an installer for these files, you can locate the Mobile client installation root directory path in the Windows Registry on the client machine under the key:
   
   HKEY_LOCAL_MACHINE\SOFTWARE\PeopleSoft\PeopleSoft Applications\CfgMobile\InstallRoot

Integrating Mobile Configurator with ERP Systems

Mobile Configurator can interface to the Mobile Transfer Service (MTS), which runs on the enterprise Configurator Server. You can configure an instance of the MTS to provide facilities for transporting configurations and configuration-derived artifacts from Mobile Configurator sites to the enterprise for storage management, quoting, order entry, or other processing.

Through an HTTP POST, the Mobile client passes configuration data to the MTS as XML in the .cmc file. The request invokes the Receiver servlet that is running inside the MTS. The servlet in turn invokes the Reader, Handler, and Response implementations specified in the MobileTS.properties file to process the request.

The MTS provides an API for creating site-specific implementations.

MTS Interfaces

The Mobile Transfer Service APIs are:

• calico.mobilets.MobileTSResponse.java

  Interface for a Response. It provides status and content from the uploaded file.

• calico.mobilets.MobileTSReceiver.java

  Interface for a simple rfc1867 upload receiver. It reads an HTTP POST request having a content type of multipart/ form data. It composes an HTTP response containing the HTTPRequest and MIME, content headers, and any additional data about the request.

• calico.mobilets.MobileTSReader.java

  Interface for a MimeReader.

• calico.mobilets.MobileTSHandler.java

  Interface for a Handler. Site-specific implementations process the uploaded configuration files.

Sample Implementations

Also provided are samples for reference as you create your own implementations.

The sample implementations are located on the PeopleSoft Advanced Configurator install in \samples\Configurator\MobileTransferService\Release\ calico\mobilets.

Implementations are:

• MobileTSResponseImpl.java

  A sample MobileTSResponse implementation. Returned by MobileTSHandler.handle().

• MobileTSMultipartReaderImpl.java

  Reads a stream of MIME multipart/ form data.

• MobileTSHandlerImpl.java

  Stores the uploaded file to the local file system in the directory specified in MobileTS.properties.

To use the Transfer Service with these implementations, you must place the implementation class files either:

• In a location that is in the WebLogic server's classpath, or

• In any location and add that location to the WebLogic server's classpath.

Using the Transfer Service

To hook up the Transfer Service to pass configuration data to ERP receivers, first implement the MTS interfaces as required by your ERP system and Solution.

In MobileTS.properties, edit the values for the Handler and Reader classes to reference your implementation classes.

Default location for MobileTS.properties is: C:\bea\weblogic81\config\CalicoDomain\applications\CalicoApp\Web-inf\config

Specify the location of the configuration data file when it is uploaded.

The text of the MobileTS.properties file is:

###################################################
# PROPERTIES FOR CALICO MOBILE - TRANSFER SERVICE
###################################################
# Handler Class
HandlerClass=calico.mobilets.MobileTSHandlerImpl
# Reader Class
ReaderClass=calico.mobilets.MobileTSMultipartReaderImpl

# For sample Handler.
# Directory on local file system where the Transfer Service Sample
Handler places the uploaded file.
# Note: Please use forward slash for separator.
UploadDirName=C:/Temp

Using Source Control

If your Solution files are stored in source control, be sure to include Solution Package (.cci) files as well. It is not necessary to protect the Solution Installer (.msi) files in source control for two reasons: they are not editable, and they can be regenerated from the .cci file.

Integrating Mobile Configurator with Microsoft COM-Compatible Applications

Mobile Configurator includes a COM API, which allows another application to interact with the Mobile Configurator to create, save, and restore configurations.

A description of the API's class and methods is available.

See Also

Mobile Configurator COM API