Developer

Application Definition

When you create a new application project in Agentry Editor, an application definition is automatically created, with its attributes set to default values.

The application definition type represents the mobile application within the project. All definitions for the application are its descendents. The attributes of the application definition affect application-level behaviors, including the application name and version, the appearance of built-in client screens, login and password settings, application-wide screen and user interface behaviors, and other similar items. The application definition is the single root definition in the application hierarchy and as such has no parent definition.

As these attributes can affect security, appearance, and numerous other behaviors of the application, review application definition defaults thoroughly early in the development process.

General Setting Attributes

The general setting attributes for the application provide a project name, the application display name, and a version value.
  • Name: The internal name of the application, which is used for certain checks during publishing.
  • Display Name: The name of the application as it appears in Agentry Client (in the title bar, and in the About dialog that is shown from the Help menu). For a new application project, the default is "Agentry" and should be changed.
  • Version: Appears to the user in the About screen. This value is not related to the application’s publish version number. It is for branding purposes only, and does not impact any aspect of the application’s behavior. Typically, however, this setting does reflect the application’s release version.

Application Setting Attributes

The application setting attributes affect data synchronization for table definitions and client application runtime behaviors.

Table Settings

The following attributes affect the behavior of data synchronization that is related to the two table definition types, data tables and complex tables.
  • Check Data Tables: How often the application checks for new or changed data for the application’s data tables. In between the specified intervals (every transmission, once per day, or once per week), no synchronization components of the application’s data tables are processed during a transmit. A published change to the data table definition overrides this attribute, forcing a reload of the data table during the next Agentry Client transmit.
  • Check Complex Tables: How often the application checks for new or changed data for the application’s complex tables. In between the specified intervals (every transmission, once per day, or once per week), no synchronization components of the application’s complex tables are processed during a transmit. A published change to the complex table definition overrides this attribute, forcing a reload of the complex table during the next Agentry Client transmit.
  • User Request: Whether users can explicitly check for changes to the application’s complex tables and data tables. This setting lets users override the Check Data Tables and Check Complex Tables attribute settings. When User Request is enabled, users can force the synchronization process to include the processing of the data table and complex table definitions’ synchronization components by selecting Start of the navigation path Off-Line Next navigation step Check for Table Updates End of the navigation path in the Agentry Client. This attribute has no effect when Check Data Tables and Check Complex Tables are set to “Every Transmission”.

Client Settings

The following attributes affect various client application behaviors at runtime.
  • When Exiting Client: Enables a warning message to users if there are pending transactions stored on the Agentry Client when they exit the application.
  • Prompt on User Change: Enables a prompt when a user change occurs, informing that a synchronization with the Agentry Server must take place to change users, and giving the current user the option to cancel the change. If this attribute is disabled, the synchronization completes the user change, but without a prompt.
  • Module Menu Item: Whether the menu item for the current module is enabled or disabled in the Agentry Client View menu at runtime. Selecting the current module returns the user to the module’s main screen set, regardless of where he or she may be in the navigation. When disabled, the menu item for the current module is disabled. For applications that have multiple modules, users can always select other module items from the View menu regardless of this setting.
  • Synchronize Clocks: Whether the system time on the client devices resets to that of the Agentry Server host system time during each transmit. The host system time is not the same as the time of the back-end system with which the Agentry Server communicates, rather it is the system time as reported by the operating system. This attribute is typically disabled in deployments involving multiple time zones.
  • Screen Size: The size of all screens that are shown to the user on the Agentry Client. This attribute affects only Agentry Client applications that are running on a Windows PC platform capable of full VGA screen resolution. The screen sizes available for this setting range from 240 x 320 (1/4 VGA) to 1366 x 768. The Screen Size value overrides the screen size attribute for all platform definitions. An “Allow Resize” setting is also available. If any selection other than Allow Resize is made, users cannot resize Agentry Client screens. The screen size for all mobile devices, including smartphones, tablets, and other devices, is always the full resolution of those devices, and users can never resize the screens.
  • Battery Status: Shows the status of the mobile device battery on the Agentry Client. This appears in either the upper or lower portion of the screen, depending on the device. This setting has no effect on the Windows PC builds of the Agentry Client.
  • WinCE Navigation: Enables support for the arrow keys of a device’s hardware keyboard. When a user clicks one of the arrow keys, the focus changes to the next or previous control on that screen. This attribute has no effect on the Windows PC builds of the Agentry Client, where full keyboard navigation is always enabled.
  • Scan Trigger Shortcut Key: For devices that are equipped with a scanner, this attribute allows for the specification of a shortcut key to activate the scanner. This key is universal to the application, and activates both socket and built-in scanners. This attribute has no effect on Agentry Clients that are running on devices not equipped with a scanner.
  • Voice Support: Enables voice support for devices that support this feature.
  • Title Bar Buttons: Whether the close buttons (either an X or an OK button) appear on the title bar of screens within the mobile application. Due to the behavior of Pocket PC devices, we recommend that you do not show these buttons, and that you define actions within the Agentry application project to close screen sets within the application, and that users close the application using either the Start of the navigation path File Next navigation step Exit End of the navigation path menu item, or through an Exit Application action step. On Pocket PC devices, screens that are closed using the title bar’s OK button are not destroyed, but only moved to the end of the “Z” order, hiding them from view. Applications that are closed with the X button do not actually exit. Any defined behaviors for exiting an application are not exhibited. Furthermore, the application itself is still running. The behaviors described here are not present on a Windows PC platform.
  • Theme Selection: Whether the Theme menu item within the Preference menu of the Agentry Client appears. When true (selected), the user can change the Agentry Client theme using this menu. When false, the user cannot change the Agentry Client theme, and the theme used is always the one that is specified in the Default Theme attribute. Allowing users to select a different theme might have unexpected impact on the UI of the Agentry Client if styles are defined and in use.
  • Default Theme: The default theme that appears on the Agentry Client at runtime. If Theme Selection is disabled, the selected Default Theme is always shown and the user cannot change the theme selection. If Theme Selection is enabled, the selected Default Theme is the initially applied theme on the Agentry Client, but the user can select a different theme at any time.
  • Win32 Buttons - Use Large Buttons: Whether to use large buttons, generally intended for touch screen support. This attribute affects only the Agentry Windows Mobile Client. This setting affects button definitions for list and detail screens. Built-in buttons, such as ellipses buttons, icon buttons, and similar controls are not affected. Large buttons do not appear in the Agentry Editor’s layout view or visual screen editor for screen definitions. They appear in the Agentry Test Environment only when the selected platform is Windows.

Application Styles Attributes

The attributes on the Application Styles tab define how styles are to be applied to all components of the application’s user interface. You can override these style settings at lower levels in the application’s structure. The style settings here also determine the styles that are applied to the Agentry Client built-in screens and dialogs, such as those for complex table searches, the transmit dialog, and others. For all style attributes, selecting the default option uses the operating system’s default font and color options.

Screen Set Styles
  • Header: The style to apply to the header when there are multiple screens within an object screen set. Different screen styles help Agentry Client users distinguish between the header area of a multiple screen set and the tabs for that screen.
Screen Styles
  • Tabs: The style to apply to the tab controls that each screen within an object screen set. This attribute has no effect on screens within a transaction or fetch screen set.
  • Buttons: The style to apply to all button definitions on all application screens. This includes buttons that appear on built-in Agentry Client screens as well as buttons within screen definitions.
  • Focused Buttons: The style to apply to the button that currently has the focus. This includes buttons that appear on built-in Agentry Client screens as well as buttons within screen definitions.
Detail Screen Styles
  • Screen: The style to apply to all detail screens that are defined within the application. This affects all portions of the screen that do not include a field or button.
  • Fields: The style to apply to all fields that appear on a detail screen.
  • Focused Fields: The style to apply to the detail screen field that currently has the focus.
  • Read-Only Fields: The style to apply to a detail screen field that is defined to be read-only. If not specified, the Fields style is applied.
  • Hyperlinks: The style to apply to detail screen field labels that are defined to be hyperlinks.
  • In Progress Edit Screens: The style to apply to screens in which changes are currently being made and have not yet been applied. This affects screens that appear in List Tile View and Tile Edit fields.
List Screen Styles
  • Screen: The style to apply to all list screens. This attribute affects all portions of the screen that do not show a list, header label, detail pane, or button.
  • Header Label: The style to apply to all list screen header labels. If no header label is defined, this attribute has no effect on the screen.
  • Column Labels: The style to apply to the column labels on the screen’s list control. This style is applied to the column labels of any screen containing a list control, including both built-in Agentry Client screens as well as list screen definitions, and list view field definitions.
  • Rows: The style to apply to all rows on a list screen. The Hyperlinks optional style overrides the Rows style for cells that include hyperlinks. This style is applied to the list items of any screen that contain a list control, including built-in Agentry Client screens, list screen definitions, and list view field definitions.
  • Alternate Rows: The style to apply to every other row in a list, beginning with the second row. The Hyperlinks optional style overrides the Alternate Rows style for every other row where there are cells containing hyperlinks.
  • Highlight Rows: The style to apply to a row to draw attention to it. Do not set this style attribute at the application level; the platform and list screen definition types both contain a Highlight Rows attribute that you should use instead.
  • Selected Rows: The style to apply to the row or rows that are currently selected by the user in the list control. The optional Hyperlink style is applied to any cells within the selected row that contain a hyperlink.
  • Selected No Focus Row: The style to apply to the row or rows currently selected by the user in the list control, when the input focus is set to a control other than the list. The optional Hyperlink style is applied to any cells within the selected row that contain a hyperlink.
  • Detail Pane: The style to apply to both the foreground (text) and background of a list screen’s detail pane. If no detail pane is defined, this attribute has no effect.

Application Images

  • About Box Dialog Image: An image definition that shows in the Agentry ClientAbout box.
  • Login Dialog Image: An image definition that shows in the Agentry Client login screen.
  • Module Menu Dialog Image: An image that shows in the Agentry Client module selection dialog. This dialog appears after users log in to Agentry Client applications with multiple modules. Within this same module selection dialog, each module may also display an image. The image defined at the application level is separate from the module images. For applications with a single module, this attribute has no effect, as the module selection dialog never appears.

Application Security Attributes

The application security attributes control overall security related to items such as failed login attempts, locking the user out of the client application after failing validation, user ID and password rules, and idle timeout settings.

User Settings
  • Login: Whether users are required to perform a transmit every time the Agentry Client application is started and the user logs in. To set this option to true, you must have an available network connection for the client device, and users are required to perform a successful transmit before they can use the client application.
  • Login Attempts: The maximum number of failed login attempts that may occur before a user is locked out of the application. “Unlimited” never locks the user out. A failed login occurs if the user enters an incorrect password for the User ID when not required to connect to the Server during login; or if the user fails user authentication when the Login attribute is set to true and the number of failed attempts exceeds the value entered here. The resulting behavior of locking out a user is defined in the Lockout Level attribute.
  • Lockout Level: The action to take when a user is locked out of the Agentry Client. The lockout may occur as a result of exceeding the number of login attempts, or may be based on failed attempts to authenticate the user against the back-end system. The available settings for this attribute are:
    • Critical: Requires the entire Agentry Client to be reset, including removing all production data, all application data, and the stored user ID and password. Users must log in to the Agentry Client application, and perform a successful transmit with the Agentry Server before being allowed to access the Agentry Client application.
    • Severe: Requires the removal of all module-level production data, that is, object instances and pending transactions, from the Agentry Client application. Complex table and data table records are not removed. The user must perform a successful transmit with the Agentry Server before being allowed to access the client application.
    • Medium: Exits the Agentry Client, and the user must log into the Agentry Client and perform a successful transmit with the Agentry Server before being allowed to access the client application. No data is removed from the application.
    • None: No lockout behavior should take place. Lockout events are ignored by the Agentry Client.
  • Client Database will be encrypted: When set to true, specifies that the database in which all client data is stored on the client device (including both production data and application data), is encrypted.
User ID
  • Case: The case in which the user ID should be entered and will be stored. The options are mixed case, uppercase, and lowercase. The mixed case option does not require a mixed case user ID, but allows for variable case: User IDs may be all uppercase, all lowercase, or mixed case.
  • Scan User ID: Whether users can enter User IDs using the device’s barcode scanner. This attribute does not require the ID to be scanned, but allows for the option. This attribute has no effect on Agentry Clients running on devices that are not equipped with a barcode scanner.
Password
  • Password Change: Whether users can initiate password changes on the Agentry Client. When true, users can change their passwords based on expiration or pending expiration messages from the back-end system. Users must enter their current (expiring) password, and a new one. Enabling this behavior requires the implementation of logic that processes password changes in the back-end system.
  • Scan Password: Whether users can enter passwords using the device’s barcode scanner. This attribute does not require the password to be scanned, but allows for the option. This attribute has no effect on Agentry Clients running on devices that are not equipped with a barcode scanner.
  • Audit: Whether to audit password entry for the Agentry Client.
    • When turned on, the client sends, upon connection to the server, password validation audit records every time the password is requested on the client, for example upon login, idle timeout, transaction validation, and password change.

    • When turned off, the client does not capture password validation audit records.

Idle Timeout
  • Timeout: Whether to require users to reenter their user IDs and passwords if the device is left idle for a specified length of time. The duration is set as a part of this attribute. Also included in this attribute is whether the user ID is populated automatically.
Client Database Encryption
  • Database Encryption: Whether the client database is encrypted.
  • Screen Sharing : Whether screen sharing is allowed when databases are encrypted.

    An encrypted database can be opened when a user enters the correct credentials when logging in, or if the server authenticates a different set of credentials.

    For the latter, the server works with the client to decrypt the database, thereby allowing the database to be opened and reencrypted with the new set of credentials. The encryption occurs once the client receives the database encryption definition. Once the database is encrypted, it cannot be unencrypted, even if the database encryption definition is changed.

  • Device Sharing: Whether to send transactions to the back end when the user login changes state.

Password Rules

  • Minimum Length: Specifies the minimum number of characters of the password entered on the Agentry Client. The minimum length must be at least 1 to enable the First Character attribute, at least 2 to enable the Character Mix attribute. This minimum length must be equal to or less than the Maximum Length attribute. The default minimum is none, which means no password is required.
  • Maximum Length: Specifies the maximum number of characters of the password entered on the Agentry Client. This value must be equal to or greater than the Minimum Length attribute, or be set to the default, which indicates there is no maximum length.
  • Password Case: Specifies the case in which the user’s password is stored on the Agentry Client and sent to the server. This may be set to mixed case, lowercase only, or uppercase only. The mixed case option does not enforce a mixed case password, but allows for variable case, and specifies that the case of the password characters are not changed from how they are entered by the user.
  • Character Mix: This attribute requires the Minimum Length attribute to be set to at least 2, and requires Agentry Client passwords to contain at least one alphabetical character and one nonalphabetical character. Nonprintable characters do not count as nonalphabetical characters.
  • First Character: This attribute requires the Minimum Length attribute to be set to at least 1, and that the first character of the password must be an alphabetical character.
  • New vs. Old: This attribute specifies that a new password entered by Agentry Client users must differ by at least one character from the previous password. This attribute may be impacted by the Password Case attribute. Mixed case treats the same letters in the old and new password as different if at least one letter is entered in a different case. If the Password Case setting is either uppercase only or lowercase only, case is ignored and the same letters entered in a different case are not treated as a different password.