Overview

Lists allow a set of shared data to be stored locally on the phone. A List can be viewed by itself or its items can be included in other messages. An example would be an order message where the customer and ordered items are selected from two separate Lists, one for the customer and one for the order items. The data for a List is stored on the AMS server.

There are three key steps to creating and using a List.

1. Create the List definition
2. Import the data for the List items
3. Add a List Item Field to the required Template

Creating a List

A List is based on a Template. The Template defines the format for a single item in a List and must be created before the List.

This Template must conform to the following rules:

1. It must provide a Field or Meta Data key for the id of the list item. The value for the id must be either an integer or a string.
2. It must provide a Field or Meta Data key to index the list on. This value will be used to group the items into categories for easy selection on the phone. If you do not need a category you must still provide a value to index on. In this case you should use the same value for all items and create it as a Meta Data key so that it is hidden.
3. It must provide a value to filter on. This value is used to allow searching the items on the phone. It should be the value that items differ by the most.
4. The template cannot contain any child templates, i.e. List Cards.

Additionally some things to consider when creating your Template for the List items:

• If an item value does not need to be displayed on the phone then use a Meta Data key
• If an item should not be editable use a String Field
• When all items have the same index they will be displayed immediately on the phone without the category selection step

Once the Template for the list items has been created go to the "Lists" page of the web application, click "Create New List" and select the template created previously then click "Create List".

Summary

The first tab when editing the newly created List allows to to specify a Name and a Description. You can also Tag a List like you would a Template. This will automatically assign this List to matching Mobile Accounts. The remaining options are covered below and allow you to customise the display of list items and their selection dialogs.

Data Maps

A data map is the most important part of the list definition and tells AMS how to encode and group the list's data on the phone. For each of the items on this tab select the source Field from the Template used to defined the List.

Customising Item Display

You can customise the text that is displayed for items and their selection messages.

Import Data

This section allows you to import XML, CSV or TSV (Tab Separated) data for the list and have it encoded. Enter the XML, CSV or TSV directly into the text box, select the format and click "Import Data".

Excel Data

You can easily import data from an Excel Spreadsheet by copying the data from the spreadsheet and pasting into the "Import Data" text area. When you do this select TSV (Tab Separated) as the format. When you select the data in the spreadsheet to import you need to include the column headers. For this reason it is best to set the column headers to be the same as the Export Labels for the matching Fields in the Template used for the the List. This will allow the data in each row to be automatically mapped to the correct Field. If this is not possible you can map the columns manually as part of the next step in the import process. See Import List Data From Excel for an example of this process.

XML Data

The format of the XML should be that of the associated list template eg:

A sample stock list might look like:

Selecting Items From The List In A Message

There are two main ways to select items from the list: single and multiple selection.

Single Selection

To select a single item from a list add a 'List Item' field to the desired Card and select the associated List to use for the items to choose from. The user can then use this field to select a single item from the list.

Multiple Selection

To enable selection of multiple items add a 'List Item' field to a non root template and use that as the Child Template for a List Card inside your main Template. When the user adds an item to the List Card they will first be taken to the associated list to choose their item.

Combining Lists With Other Messages

Whilst it is possible to add list data items to a message, as in the case of the stock order above, doing this for a large number of items could be time consuming. However, if we instead sent a partially completed stock order to the phone and then only required the user to add or remove extra or unwanted items, the process could be completed quickly.

In this order scenario a sales rep is visiting a client and needs to place an order. The rep creates a new customer order history message. This message uses a template that allows a user to enter a customer's details and select whether they want the last order or a recurring base order to be sent back to the phone. When this message is sent it is routed to the sale rep's company server where it processes the request and sends back a stock order message containing either the items ordered last time or a set of items that are regularly ordered. The rep can then reply to this message and adjust the quantities of items, remove unwanted items and add extra ones much more quickly than creating a new order from the start.

Assigning Lists To Mobile Accounts

To assign a List to a Mobile Account you can either:

• Edit the Mobile Account directly and assign manually like you would a Template
• Use a Tag for automatic assignment

List Template Assignment When you assign a List to a Mobile Account you do not need to assign the Template used for the items in that List to the Mobile Account as well. This is handled automatically in the background by the server.