Configuration Practices for Agentry Based Mobile Application

8/10/2019 Configuration Practices for Agentry Based Mobile Application

1/44

Configuration Practices for Agentry BasedMobile App

This document provides suggested naming conventions for objects created inthe Agentry Editor. Application developers and maintainers are stronglyencouraged to follow these conventions in pursuit of the goals listed below.


2/44


3/44

Configuration Practices for Agentry Based Mobile App

3

TABLE OF CONTENTS

SECTION 1: AGENTRY NAMING CONVENTIONS ......................................................................................... 5 Goals ................................................................................................................................................................. 5 General Naming Conventions ........................................................................................................................ 5

SECTION 2: NAMING CONVENTIONS FOR BUSINESS OBJECTS & PROPERTIES ................................. 5 Objects .............................................................................................................................................................. 5 Properties ......................................................................................................................................................... 6

SECTION 3: NAMING CONVENTIONS FOR SCREEN SETS & SCREENS .................................................. 7 Screen Design .................................................................................................................................................. 7

Screen Sets ...................................................................................................................................................... 7

Naming .............................................................................................................................................................. 8 Screens .............................................................................................................................................................. 9

SECTION 4: NAMING CONVENTIONS FOR ACTIONS ............................................................................... 12 Naming ............................................................................................................................................................ 12 Transmit Actions .............................................................................................................................................. 15 Navigation Actions ........................................................................................................................................... 16 Navigation Actions ........................................................................................................................................... 16 Looping Actions ............................................................................................................................................... 16

Apply Steps ...................................................................................................................................................... 16 For Object ........................................................................................................................................................ 17 Grouping .......................................................................................................................................................... 17

SECTION 5: NAMING CONVENTIONS FOR RULES ................................................................................... 18 Naming ............................................................................................................................................................ 18 Groups ............................................................................................................................................................ 22 General Best Practices ................................................................................................................................. 22

SECTION 6: NAMING CONVENTIONS FOR TRANSACTIONS ................................................................... 25 Transactions .................................................................................................................................................. 25 Naming ............................................................................................................................................................ 25 Properties ........................................................................................................................................................ 26 Merging ............................................................................................................................................................ 26

SECTION 7: NAMING CONVENTIONS FOR FETCHES AND READSTEPS ............................................... 26

SECTION 8: NAMING CONVENTIONS FOR STEPS .................................................................................... 28

SECTION 9: NAMING CONVENTIONS FOR ACTION STEPS ..................................................................... 29 Globals ............................................................................................................................................................ 29 General ............................................................................................................................................................ 30 Naming ............................................................................................................................................................ 30 Groups ............................................................................................................................................................. 30 Usage .............................................................................................................................................................. 31

SECTION 10: NAMING CONVENTIONS FOR COMPLEX TABLES ............................................................ 32 Naming ............................................................................................................................................................ 32 Fields ............................................................................................................................................................... 32 Indexes ............................................................................................................................................................ 32

SECTION 11: NAMING CONVENTIONS FOR DATA TABLES .................................................................... 33 Data Tables ..................................................................................................................................................... 33 Naming ............................................................................................................................................................ 33


4/44


4

Images ............................................................................................................................................................. 33 General ........................................................................................................................................................... 33

SECTION 12: TAGGING ................................................................................................................................. 34

General ............................................................................................................................................................ 34 Styles .............................................................................................................................................................. 34 Naming ............................................................................................................................................................ 34

SECTION 13: NAMING CONVENTIONS FOR JAVA CLASSES .................................................................. 35 Naming ............................................................................................................................................................ 35 Extending Java Classes ................................................................................................................................ 35

SECTION 14: SAP DEVELOPMENT NAMING CONVENTIONS .................................................................. 37


5/44


5

SECTION 1: AGENTRY NAMING CONVENTIONS

GoalsThere are several goals that can be achieved through the use of naming conventions. They include:

1. Program maintainability Whenever someone other than the original application author needs tomake changes to an Agentry application, the learning curve is reduced if they know how objectsrelate to one another and how they are used.

2. Design Assistance An application developer can use naming conventions as a design aid to helpthink abstractly. If a particular step or rule can be easily named, it is more likely to be designed well.Conversely, any difficulty in naming an object might lead a developer to reconsider the designapproach.

3. Consistency Naming objects using predictable convention increases usability. Rules and actionscan be sorted on screen, which will group similar rules together. Similar named screens, transactions

and actions are recognizable as related entities. It makes it easier for someone other than theoriginal author to understand and familiarize themselves with the application at hand.

General Naming Conventions

1. The name should be clear and understandable by other developers.2. All definitions are named with Camel Case and capitalize the first letter (except Complex and Data

Tables), avoiding abbreviations3. The name should describe the object sufficiently enough that a user does not have to select an

object detail screen to understand the purpose of the object.4. Concatenate the name, using an uppercase letter for each word in the name. Try not to use spaces

in the name. This is an identifier, not a user interface string

5. Be internally consistent for example, if you create a calculated property called QtyAccepted, dontcreate a similar property elsewhere called AcceptedQty or QuantityAccepted

6. The conventions listed in this document are strongly encouraged, but not mandatory. You may havepr eferred the prefix Set over Calc, for instance, but given that one is not significantly moreadvantageous than another you should use the preferred name since other applications willimplement the preferred name. If there is a case when a different name more clearly describes theobject, then by all means use it, but use discretion in making a decision to vary from the convention.

7. Unused definitions are removed from Editor8. Actions, ScreenSets and Transactions all stick to preferred Object-Verb naming style9. Silent Actions and Transactions that do not interact with the user should generally be suffixed with

Auto

SECTION 2: NAMING CONVENTIONS FOR BUSINESS OBJECTS & PROPERTIES

Objects Objects should be named using Camel Case/Initial Capitalization:

o WorkOrdero WorkOrderHistoryo Notificationo NotificationReference

Where possible, use the name of the data source. For example, if the object maps to a databasetable, use the database table name.

If the data source has an obfuscated name, use common sense and name it for what it is.Example: MobileFM has a phase table called ae_p_phs_e which is certainly more clearlyunderstandable if the corresponding Agentry object is named Phase


6/44


6

Abbreviations should be avoided, but if necessary should be consistent across all objects andother definitions.

If working on a particular group of objects that are related, Try to preface those object names

with the common group name. For instance, If working on a Stock component with many relatedstock objects like TransferHeader, TransferItem, TransportOrderHeader then preface these withthe Stock component name:

o StockTransferHeadero StockTransferItemo StockTransportOrderHeader

Propertieso Use Camel Case/Initial Capitalizationo Use primitive base Object types (Not Complex Table, Data Table) where possibleo Numeric boundaries and string lengths are set using Globalso IsLocal Boolean exists if necessary

o Boolean property names prefaced with a common prefix, like Is o A Date/Time Fields Time Zone Adjust attribute should be set to use a Glob al called AdjustTimeZone set to From System Connection Local Time

o Where possible, use the property names of the data source. If the object maps to adatabase table, use the database table field names.

Avoid property types that have no meaning at the object level. Choosing these types may causeproblems when trying to polymorph them into other types on transaction screens or auto (silent)transactions. Rather these types should be assigned at the screen level:

o Complex Table Selection Choose String instead on Objecto Data Table Selection Choose String instead on Object

Do not hard-code minimum and maximum boundaries for numeric values or string lengths:o Use Globals that can be overridden

Suggested names: Lngth.WorkOrderDescriptionMin Lngth.WorkOrderDescriptionMax Lngth.ReadingMin Lngth.ReadingMax

IsLocalo It is typical for the local state of an object to be referenced and for other business logic in

the application or backend code to rely on this local state being accessibleo Local means that the object has been newly created on the client and has not yet been

transmitted to the backend system. Acceptable approaches to this:

Key Preface and Evaluation Rule

o Preface the key property assignment with a constant stringstored in a global, like: LOCAL_ o Create an Evaluation rule for each object that compares the

start of the key property to the local global to see if they match,and returns a True response if so

o Drawbacks of this approach: Multiple Evaluate rules must be created if each object

uses a different key name A backend method must be created to make a similar

comparison IsLocal Boolean (Preferred)

o Create an IsLocal Boolean in each objecto Set this property to true in the Add transaction

o Create a single Evaluate rule that checks the IsLocal propertyregardless of object type and returns True or False

o Drawbacks of this approach:


7/44


7

Extra property is needed Booleans

o Easier to identify if prefaced by a common prefix, like Is. IsBreakDown is better thanBreakDown. When seen in the editor or in Java, the designer knows this is a Boolean

IsLocal IsEquipment IsLocation IsEdited

o Other common Boolean prefixes NeedsXmit NeedsProcessing

Date/Timeo The Time Zone Adjust Attribute should be set to use a Global called AdjustTimeZone.

Set this to From System Connection Local Time

SECTION 3: NAMING CONVENTIONS FOR SCREEN SETS & SCREENS

Screen Design

Screen Design, the Key is give the user only what he needs to do his job, and make the screens simple andintuitive

Guide the user through screens, using as few keystrokes as possible. This meansuse dropdowns and default values where ever possible.

Consistent Screen Names, labels, headers Rows per screen so the application looks uniform

Edit and delete enabled only when active Confirmation message before delete Validation messages are consistent and meaningful Data is validated for length and format Naming standards are followed Text is wrapped in multi-line fields, dropdown field sized for data Finally, as you design your screens, keep in mind the form factor of the device that

you will be using when designing your screens and making device choices Windows screen will look very different than PPC screens, and if you will be

deploying on both, you will need to determine what makes sense. For example, ifyou are a utility and need to include a main break form with 50 fields, you mightwant to consider deploying on windows

Screen Setso Row Screen Sets used for List Tiles are suffixed with Tile o Selected Row Screen Sets used for List Tiles are suffixed with TileSelected o Screens

o Names are descriptive and consistent o Names include the Platform as a suffix (e.g., Win32, PPC, All) o Names include the screen type before the Platform suffix (e.g., List, Detail, Tile,

TileList) o Rows is set via a Global, e.g., PPC = 10, Win32 = 20 o Columns are set via a Global. 100 regardless of platform to allow for precise

percentage adjustments o List Screens have a Header Format Rule that displays n of x Objects where n is

the quantity shown on the list, x is the total quantity prior to filtering and Objects isthe Object name pluralized

o Action Buttons should use Images consistently, and should be named identically tothe Action being run


8/44


8

o Fieldso Label Width is set via Global on each Field where appropriateo Fields are ordered from top to bottom in order of precedence if there are references

or relationships between the fields o List Tile Controls have an offset applied to them to shrink the PPC tiles. -6 is the

standard o List Tile Controls have uniform Header Rules that display the quantity followed by a

plural noun describing the Collection displayed (e.g., 5 Work Orders, 2 Equipment, 0Tasks)

o List Tile Controls have appropriate filters added, excluding fields with calculatedvalues

o Top Row on a Selected Row Tile Screen is reserved for Action Push Buttons whereappropriate

o Needs Transmit Icon added to upper right of Top Row on a Selected Row TileScreen

Type Naming convention syntax Examples All {Object}{tile}{List|Detail}[{extra desc for

clarity}]WorkorderListItemDetailItemDetailForRotatingItemItemDetailForLotItem

Naming

Screen Sets should be named using Camel Case/Initial Capitalization and Object-Verb syntax Screen Set Types

o Add Transaction Screen for adding a new object Sometimes also doubles as an Edit Screen Set Use a descriptive suffix when necessary to further describe

CATSRecordAddForWorkOrdero AddTileInline

Transaction Screen used for doing inline Object Adds from a List Tile Controlo DisplayTile

Child read-only Detail Screen hosted on a Tile Display Controlo Edit

Transaction Screen for editing an existing Objecto EditTile

Child Transaction Screen hosted on a Tile Edit Controlo EditTileInline

Transaction Screen used for doing an inline Object Edit against the currentlyselected Tile on a List Tile Control

o Tile Child read-only Detail Screen hosted on a List Tile Control Displayed for all unselected Tiles on the list

o TileSelected Child read-only Detail Screen hosted on a List Tile Control Displayed when a Tile is selected by the user

o Transfer Used for Transfer function data entry

o View Read-only Detail or List Screen


9/44


9

Fetch {FetchName}[{extra desc forclarity}]{Get}

WorkordersGetProjectsGetUserInfoGet

ObjectCollection {ObjectName[plural]}{View} WorkordersViewProjectsViewObject Detail {ObjectName}{View} WorkorderView

ProjectViewTransaction {TransactionName} WorkorderAddRow Tile {ObjectName[plural]} {Tile} WorkorderTile

StockTransferHeaderTileRow SelectedTile

{ObjectName[plural]} {TileSelected} ServiceOrderItemsTileSelectedInstalledBaseProductTileSelected

Tile Edit {ObjectName[plural]} {EditTile} WorkOrderEditTileTile Display {ObjectName[plural]} {DisplayTile} WorkOrderDisplayTileList TileInlineAdd/Edit

{TransactionName} {TileInline} WorkOrderAddTileInlineNotificationEditTileInline

Screens Screens within screen sets should follow the same convention, and also should include the

Platform abbreviation in the Screen name so it can be easily identified:o NotificationDetails_Detail_PPCo NotificationTasks_TileList_Win32

Screens that will be used generically regardless of Platform should be suffixed with All ratherthan a Platform; e.g., AddressList_All

Type Naming convention syntax Examples List {ScreenSetName}_{optional label for

clarity}_{List}_{platform|All}WorkordersView_List_Win32WorkorderDetailsView_Parts_List_PPC

Detail {ScreenSetName}_{optional label forclarity}_{Detail}_{platform|All}

ProjectView_Detail_Win32UserInfoView_Address_All

Tile List {ScreenSetName}{optional label forclarity}_{TileList}_{platform|All}

WorkOrderDetailView_Partners_TileList_PPC

Rowso Rows per screen should be consistent by platform throughout the application when

possible to present a uniform looko Set this using a Global in the UI Groupo PPC rows should be 10o Win32 rows should 20

Columns

o Columns should be set to 100 regardless of platform. 100 units allow the field columnwidths to be thought of as a percentage of the total screen available. This allows formore precise manipulation of screen fields and makes modifications much easier than ifthe screen only supported a small column width

Buttonso Screen Button names should reflect the Action they are tied to, i.e., The Button tied to

the TaskAdd action should be called TaskAddo The Agentry Editor does not automatically change the name of a Button when a new

Action is chosen for it after the Button has already been saved. Keep this in mind andremember to adjust the button name manually if editing a Buttons Action target

o A single Button Sep arator on a button list should be named Separator. Multiple ButtonSeparators should be named with an incrementing top down sequence, e.g.,Seprarator1, Separator2. For example, if two separators exist on a Button list, the

first in position 2 and the second in position 5, the buttons should be namedSeparator1 and Separator2, not Separator2 and Separator5. Button positionstend to move around, so dont try to imbed the Button order position in the name of the


10/44


10

Separator. It is also acceptable to always name the first Separator as simplySeparator without the 1 suffix, then continue with Separator2 for the second

Header Ruleo List Screens should have a Header Format Rule that displays n of x Objects where n is

the quantity shown on the List, x is the total quantity prior to Filtering and Objects is thedescriptive Object name pluralized:

1 of 3 Work Orders 5 of 5 Addresses

Fieldso Label Width

Always set the Label Width on all fields. Do not rely on inheriting the width fromthe field above. While easier to implement, this is bad practice. If the screenfield order changes, it is easy to mess field label widths up without evenrealizing. It is best to always set them and leave nothing to chance

Using a global to set label width is also good practice. That way the width canbe changed by adjusting a single global, rather than having to hard-codeindividual fields

o Field Order Make sure that fields are ordered from top to bottom in order of precedence if

there are references or relationships between the fields. For instance, if theEquipment field cascades off the FunctionalLocation field, theFunctionalLocation field should appear first in the field list order beforeEquipment, even if their screen field positions reflect the opposite . IfEquipment is first in the list in this scenario, you run the risk of the screen fieldsnot populating themselves properly when the transaction screen is firstdisplayed for existing data. This happens because Agentry tries to figure screenfields out in order from top to bottom. Since Equipment comes first and relies onFunctionalLocation for its data, the Equipment field remains blank becauseFunctionalLocation has not yet been initialized due to the incorrect field orderset up by the designer.

o Tile Edit/Display Control This control is used as a host to display/edit transaction data on a traditional

detail screen These controls host a child Screen Set that actually displays the field data This control is very useful for displaying details of a Parent Objects child or

related sibling on a Screen Set that targets the Parent, without having to writeconvoluted targeting Rules or hard-code Object Browser paths to the desiredObject on multiple Screen Fields. This Control accepts a Target Path that pointsto the Object it will be displaying. This way, Detail Screens can be imbedded ina Parent Screen Set, each easily targeting different Objects if desired by usingTile Edit/Display Controls

Keep in mind that this Control is initialized when the host Screen is displayed.The Transaction (Tile Edit) or Object (Tile Display) gather their display dataimmediately, and are not updated if outside Transactions modify the underlyingObject. Detail Screens normally update themselves when the Screen Setstargeted Object is changed, but this is not the case with these Tile Controls.This has been logged as Agentry Bug #31810 - Tile Edit control does not updatefields if underlying object is changed

The row height on the child tile can be optionally modified to shrink the rows ifmore space is needed for PPC. Use a negative number to shrink the rows. Forexample, use -2 to shrink the rows by a small margin

Use the SCREENFIELDVALUE Rule Function Term to reference other fields inComplex Table/Update Rules on the actual child Tile Transaction Screen priorto Agentry release 5.2.4.0. This is currently the only confirmed way to do this

prior to 5.2.4.0. References using the screen set or current screen do not workproperly. This has been corrected in: Details for #31049 - Tile Edit controlworking inconsistently with cascading complex table fields in Agentry 5.2.4. It is


11/44


11

now possible to reference the Child Tile Screen Set/Screen/Field and properlyaccess the data stored in these fields. For example, a child Complex Table fieldmust reference another parent Field to build a parent string via a Rule. TheScreen Field is called PartCodeGroup. The following Rule can be used to buildthe parent string. Notice that the PartCodeGroup Field is accessed using theScreen Set and Current Detail Screen syntax, making this Rule compatiblewith any Platform:

When this Control is in edit mode, you will see the Cancel and Save buttonsappear in the lower-right corner of the Tile. Notice also that any Action Buttonson the Screen or Screen Menus become disabled by default. This is an optionon the parent Screen Set that hosts the Tile Edit Control called Transa ctionBlocking. When toggled on, all other Actions are disabled while theTransaction is being edited. If toggled off, Agentry does not restrict the use ofother Actions during the edit, possibly leading to conflicts. Turning this featureoff is not recommended unless careful design planning has been done toprevent the same object being edited at the same time

This control will also automatically save a Transaction in edit mode if the parentScreen is closed, or if the parent Object is changed via a Roll Button. This maybe confusing or undesired behavior, so leverage the use of this Control with thatfunctionality in mind. A bug has been logged to request that this auto-savebecome optional: Details for #31054 - Tile Edit control saves the transactioninstead of canceling the edit during certain situations

o List Tile Control This control is used as a host to display object data tiles as a list on a traditional

detail screen List Tile Screens should be named with the word Tile prior to the Platform

prefix: e.g., ServiceOrderView_Confirmations_Tile_PPC The List Tile View control can be used to replace the traditional Agentry List

Screen with a much more robust tile-based display complete with push buttons,images and any other Detail Screen control. The tiles will also expand whenclicked, eliminating the need to scroll horizontally which was difficult on thetraditional list

The row height on the child tile can be optionally modified to shrink the rows to

display more tiles on PPC. Use a negative number to shrink the rows. -6 worksas a good modifier. This amount does not alter the height of push buttoncontrols on the tile

Use a global to set the Modify Row Height offset and apply this global to all hostdefinitions. Adjustments can then be easily made by changing the global value,or setting it to zero to disable any offset

Header text should be set via Rule on the Filter/Sort tab of the control. The ruleshould count the collection objects and display the plural noun describing thecollection

5 Work Orders 2 Equipment 0 Tasks

Add appropriate filters on the Filters tab of the control

Do not place Filters on a calculated fields


12/44


12

Tile Child Screenso List Tile Controls display a Row and a Selected Row. These are typically two different

Screen Setso The Row Screen Set name should be suffixed with Tile

This Screen will be shown for all un-selected rows on the list viewo The Selected Row Screen Set Name should be suffixed with TileSelected

This Screen will be shown for all selected rows on the list view Common button actions specific to the Object on this Tile (Edit, View, and

Delete) should be represented by a Push Button on the top row of the PPCScreens. These buttons should show the appropriate image icon for thefunction. This technique makes it easier for a user to interact with the currentlyselected Tile Object, rather than having to search for the menu button along thebottom, or possibly on a Popup menu

A ButtonNeedsXmit Push Button Control should be added to the upper right ofSelected Tiles. This uses the Alert image and indicates that the Object hasbeen changed and requires a Transmit to post these changes. This Button isHidden/Shown using a generic rule:

o Refer to the Product Style Guide document for more specific information o n Tile relatedcontrols, styles and best practices

List Tile Inline Edit Child Screenso List Tile Controls allow adding or editing rows directly. These are specified by supplying

an Add Screen Set and Transaction and/or an Edit Screen Set and Transactiono The Add/Edit Child Screen Set should be named as a Transaction but with a suffix of

TileInline WorkorderEditTileInline AddressAddTileInline

o When referencing other Screen Fields in Rules on an Inline Tile, you cannot use theCURRENTVALUE Rule Function (this needs to be validated against current Agentryrelease). Instead, use the fully qualified Screen Set name and Field name:

Tile Edit/Display Child Screenso Child screens used by Tile Edit/Display parent controls should be suffixed with EditTile

or DisplayTile respectively

SECTION 4: NAMING CONVENTIONS FOR ACTIONS

Naming

Actions should be named using Camel Case/Initial Capitalization Use Object Verb naming style Add a Description to each Action


13/44


13

Determine the action type you are creatingo For Object is selected and not left blank o An Object or functionality based Group has been assigned

Create an appropriate name based on the type Preferred Action verbso Add

Use when adding a new objecto Clear

Use the verb Clear for removing Objects from the Client that do not modify theBack- End via Transaction Update Steps, otherwise use Delete for those thatdo

o CurrentScreenSetClose Special Action used throughout the application tied to most Close Buttons

o Delete Use when deleting an Object from the Client and the Back-End system (SAP,

Maximo)

o Edit Use when editing an existing Object

o Loop Use this as a suffix when the Action runs a Sub-Action used to loop over a

Collection or used to execute until a certain condition is satisfied ComponentAddLoop OperationAddLoopForNewWorkOrder TaskAddLoopUntilCancelled

o Post Action that passes data to the Back-End via a Transaction for processing in a

Bundling StepHandlero Prompt

Used for Actions that display Message Prompts to the user The type of Prompt should be specified as a suffix in the name OperationPromptAdd TaskPromptDeleteConfirm WorkOrderPromptInvalidStatusError

o Reset Runs an Edit Transaction that resets some values

o Status Runs an Edit Transaction that changes the status of an Object Do not use Status as the verb, but the actual status value:

WorkOrderComplete TaskStarted OperationHold

o Transmit Runs a Transmit Action Step

o View Navigates to a Screen Set

Stepso Name steps so that the intention is as obvious as possible

Sub-Action Steps are named identically to the called Actions Looping Sub-Actions are named identically to the called Actions with a Loop

suffix, e.g., DeleteTaskLoop for DeleteTask Message Steps contain the Prompt key word: e.g., ComponentPromptAdd Apply Steps are used only when necessary to increase performance

o

o Sub-Action Steps Name these identically to the Sub-Action being called in most cases For looping Sub-Actions, use the Sub- Action name followed by a Loop suffix


14/44


15/44


15

Type Naming convention syntax Examples Apply2

Navigation Steps These should be named simply with the Screen Set name to be navigated to:

o Navigation Actions viewXXX

Type Naming convention syntax Examples Exit App ExitApplication ExitApplicationNavigation {Screenset|Screen}View WorkorderDetailView

MainScreenViewTimeSheetListView

o Print Report Steps Used to generate a report from a Collection or Object:

Type Naming convention syntax Examples All Print{ReportName} PrintSalesReport

o Transmit Action Steps Used to initiate server communication:

o Transmit Actions TransmitXXX FetchXXX

Type Naming convention syntax Examples Sendinginformationto the serverwithout asearchcriteriascreen

[Silent|Background][{extra desc}]Transmit

TransmitMaterialRequestsTransmitSilentTransmit

Sendinginformationto the serverwith a searchcriteriascreen

{ObjectCollection}Fetch|Get WorkordersFetchPurchaseOrdersGet

o Windows Command Steps Used to invoke an external process:

Type Naming convention syntax Examples All {Name of the external process} AddressMapGet

DirectorySaveFileMake

Transm i t Act ionsUsed: to initiate server communication

Type Naming convention syntax ExamplesSendinginformation to the

server without asearch criteriascreen

[Silent]Transmit[{extra desc}] TransmitTransmitMaterialRequests

SilentTransmit


16/44


16

Type Naming convention syntax ExamplesSendinginformation to theserver with a

search criteriascreen

Fetch{ObjectCollection} FetchWorkordersFetchPurchaseOrders

Navigation Act ions

Used: to go from one screen to another where the target screen does not have a single dedicated function.Typically, this would be used when navigating to a main list screen or a read only detail screen.

Type Naming convention syntax Examples All View{ScreenName} ViewPODetail

ViewWorkorderList

Navigation Act ions

Used: to display a UI warning if a particular state exists or condition has been met.

Type Naming convention syntax Examples All Warn{condition} WarnMaterialRequestAlreadyLocked

WarnCannotEditReservedItem

Loop i ng Ac t i ons

Used: to iterate over a group of objectsIn most every case, a looping action will repeat a particular subaction, so name the looping action as theplural of the subaction.

Type Naming convention syntax Examples All {Plural of Subaction} AddParts would loop over AddPart

App ly S teps

A single Apply Step on an Action should be named Apply. Multiple Apply Steps should benamed with an incrementing top down sequence, e.g., Apply1, Apply2. For example, if two

Apply Steps exist on an Action, the first in position 2 and the second in position 5, the Stepsshould be named Apply1 and Apply2, not Apply2 and Apply5 as would be the Agentrydefault. Step positions tend to move around, so dont try to imbed the Steps order position in

the name of the Apply Step. It is also acceptable to always name the first Apply Step as simplyApply without the 1 suffix, then continue with Apply2 for the second Apply steps are very time consuming in Agentry, especially on PPC devices. Applys actually

perform the device writes. Try to limit usage of Apply steps. Do not use them unnecessarily asthey will severely impact the speed of your application, especially during looping operations thatcreate records

When performing looping operations that create many records, do not Apply each transactionwrite, but rather Apply them all at once after the loop with a single Apply step

o This technique can be risky depending on PPC device. Some devices will run out ofstack space and crash Agentry, or lock it up, never completing the writes. Be carefulwhen writing many records with a single Apply and only do this on a device to devicebasis after testing the performance. It is not possible to use this technique on someslower devices or devices with limited RAM


17/44


17

o If processing a number of transactions in a row using different action steps, use a single Apply when possible. You can employ this technique if none of subsequent transactionsrely on saved data from the previous transaction(s)

For Object

Always supply an object in the For Object propert y drop-down on the Action header. Do notleave it blank. There are many reasons to do so:

o This is proper object oriented application design. Think of an Action as a method andthe For Object as a parameter to that method. You need to pass the proper targetobject type to that method, as in Java or the compiler will throw an error. Following thisstandard eliminates mistakes and ensures proper context, as Agentry will throw an errorduring Check on Publish if there is a mismatch between a target object and the ForObject that the targeted Action accepts

o Properly sets the context for all steps within the action, making it easy to browseproperties of the current object for further targeting and rule creation

o Leaving the For Object blank or setting it incorrectly can lead to multiple copies of a

screen set being created inadvertently. It can also confuse Agentry and lead to targetingissues and other problemso Setting the correct For Object makes for a more readable and easily understood Action

Some Actions dont make use of any Objects: e.g., Transmit, CurrentScreenSetClose. These Actions dont necessarily need a For Object, but to be consistent should still be assigned one.When this case comes up, use the MainObject

Group i ng All Actions should be placed into groups Groups should be object based when possible, but Group names should not exactly match

Object names because that causes a conflict for Agentry during backend Flunky resolution:o WO (for WorkOrder)o RefObject (for ReferenceObject)o Notif (for Notification)

Groups may also be functionality related, in order to keep their size down when there are toomany Actions related to certain objects:

o StockTransfero StockReceipto StockSearch


18/44


19/44


19

Type Naming convention syntax Examples 2 possiblebranches (ie do this orthat

Determine{Action1 Name}Or{Action2 Name} DetermineStartMaterialRequestOrWarnLocked

More than 2branches

Determine{Action1 Name}If{TrueCondition}

DetermineStartWorkorderIfWorkorderCanBeStarted

o Enable Enable Rule for Actions, Screens in a Screen Set, Fields on a Screen

Recommended Syntax:EnableXXXShowXXX

Usage - to enable/disable or hide/show a UI element

Type Naming convention syntax Examples Enable a UIitem

Enable{UI Element}[{UI element type}] EnableStockroomEnableBinnumEdit

Show a UIitem

Show{UI Element}{UI element type} ShowPartsList

o Evaluate (Eval, Count) Returns a Boolean (True, False) if a certain condition is true. Sometimes used

as an Enable Rule or as a sub-rule in Enable, Execute or Validation Rules

Type Naming convention syntax Examples All Eval|Calc{expression} CalcTotalWorkorders

EvalFirstDayofTheWeek

o Execute (Exec) Used primarily as an Execute Rule to determine if a Sub-Action should be run The Action being executed should not be included in the Rule name. The name

should briefly describe the condition that makes the Rule true, keeping itreusable and not necessarily tied to a single Action

Type Naming convention syntax Examples All Execute{If|When}{condition} ExecuteIfWorkorderDoesNotExist

o Find (Search) Used as a Find First Object Where Rule to search a Collection for a specific Object based on logic

Type Naming convention syntax Examples All {Find|Search}{Object

Name}{condition}FindNotificationMatchingWONumFindComponentMatchingDeletedTask

o Format (Current) Used to format a string for display on a List Screen, Column Header, Caption

Header, Field Label, Button, Popup Message or Update RuleType Naming convention syntax Examples

All Format{Expression} FormatWorkorderDetailPaneFormatPartsListHeaderFormatTotalWorkHours

Type Naming convention syntax Examples Missing Format{property}IsRequired{Warning|Err FormatLotnumIsRequiredWarning


20/44


20

Type Naming convention syntax Examples requiredfield

or|Prompt|Message} FormatIdIsRequiredMessage

Fieldvalue isout ofbounds

Format{property}{operator}{Value}{Warning|Error|Prompt|Message}

FormatQtyAcceptedLessThanZeroErrorFormatQtyRejectedGreaterThan100KWarning

Fieldvalue notallowedforcurrentstate

Format{condition}{Warning|Error|Prompt|Message}

FormatOnly1RotatablePartCanBeAcceptedError

o Hide Used for Hidden Rules on Screen Fields The Field name being hidden should not be used in the Rule name unless it is

necessary for clarification. Hidden Rules should generally describe theconditions required for hiding, not the Field being hidden

Type Naming convention syntax Examples All Hide[FieldName][If|When{Condition}] HideEqnum

HideWhenEqnumIsNotNull

o Highlight See Style below

o Image Used to dynamically set the Image to be used for a Screen List Column or

Button Control

Type Naming convention syntax Examples All Image{Object}{Further desc} ImageWorkOrderStatus

ImageAddressCloseButton

o Include Used to include Collection Objects for a Sub-Action Looping Step, List Tile View,

List View, etc

Type Naming convention syntax Examples State Include{When}{state} IncludeWhenOrgIDIsNotNull

Condition Include{If}{condition} IncludeIfLocationEqualsStoreRoom

o Index Used to dynamically set the Index to be used for a Complex Table Screen

Control

Type Naming convention syntax Examples All Index{Property}{Further

desc}IndexEquipmentTileEditIndexFLOC

o InitialValue Used to set the initial state of a Transaction Property before or after data entry

Type Naming convention syntax Examples All InitialValue{property} InitialValueLocation


21/44


22/44


22

Usage - to validate a transaction Create a name that describes the element you are trying to validate

Type Naming convention syntax Examples Testrequiredfield has avalue

Validate{property} ValidateLotnum

Test Fieldvalue idwithin range

Validate{property}{condition} ValidateQtyGreaterThan1

Groups Rules should be placed into Groups matching their type so they can logically and easily be

locatedo Enableo InitialValueo Update

Another alternative is to apply Groups according to a piece of functionality (Stock, Transfer,etc), or use both techniques at once:

o StockEnableo TransferInitialValueo CustomerServiceValidation

General Best Practices When referencing an Object Property, always attach the fully-qualified Object name when

possible. This makes the Rule easier to read and eliminates ambiguity when Agentry runs the

Rule. Without this qualification, Rules sometimes fail to work properly Do not hard-code text constants in Rules when the constant may change or is used in multipleRules. Create a Global and use it instead

Always add a description to the header explaining in brief what the rule is used for Imbed descriptive comments in complex rules to describe the functionality. This will allow other

developers to understand them easily. It will also help the original programmer understand thelogic when viewing an old rule again months or years in the future:


23/44


23

Using the Current Property context should be avoided if possible. Always provide the fully-qualified Property name in the Rule, unless required to do otherwise. This is easier to read anddoes not confuse Agentry

Unless specifically trying to write a specialized generic rule that will be used in multiple spotsthroughout the application, do not use the Current Screen Set context to reference Fields.

Always provide the fully-qualified Screen Set name in a Rule. Doing so may work in certaincircumstances, but not in others. Providing the Screen Set name will work in all cases

o Sometimes the current context syntax can be useful for making rules reusable, e.g.,Using Screen Set\Current Detail Screen Syntax to create a single Rule for use as anUpdate Rule that will function correctly on multiple Platforms within a Screen Set

Create Globals in the application to represent commonly used string checks done in rules. Donot hard-code these into rules with string Constants, as they cannot be easily identified at firstglance. This also allows for internationalization of a product:

o Application.EmptyStringo Application.BlankSpaceo Text.TrueValueo Text.FalseValue

Break commonly used routines into Sub-Rules, rather than repeating the code redundantly inparent Rules:

When writing rules that will be used for displaying text to the user, do not hard-code the Englishtext in the rule. Rule text constants cannot be overridden using Agentry internationalization files,forcing them to be changed in the Editor by a programmer. This is not necessarily an easy taskto track down the offending rules. Instead, create Globals that can be easily modified forinternational usage. These should be placed into a common group like Text. These Rulesinclude:

o Validation Messageo Format (Screen Captions, Column Headers, etc)

o Sub-Action Message Text Parent Rules are used to determine the Index Parent for a child Complex Table Screen Field.

These consist of the values required to seed the Index separated by the Rule NEWLINEcharacter. Order the properties top down starting with the lowest child in the hierarchy. In thefollowing Rule, we are seeding the values for the codeByCodeGroup Index on a Screen Field.codeByCodeGroup has a parent of codeGroupByCatalog which has a Parent of catalog. Thismeans we must supply 2 parent values in the Rule, starting with the child (codeGroupByCatalog)and finishing with the parent (catalog):


24/44


24

Parent Rules are also used to seed Index values when looping over a Complex Table in a Sub- Action Step, but these Rules are set for each index individually. This means that compoundstatements are not necessary, just one individual value per Rule


25/44


25

SECTION 6: NAMING CONVENTIONS FOR TRANSACTIONS

Transactions o Properties

o Use {Verb}{Object} syntaxo Key value on a new Add is assigned a unique calculated value using TIME_TICKS

when possible, prefaced by LOCAL_ o Key value may also be set via a Main Object counter variable if necessaryo Key is assigned Before Data Entry when possi bleo Display Name has been adjusted to be descriptive

o Mergingo All Properties tie back to an Object Property in both Transactions, using dummy

properties if needed in the Object being worked with o All Properties in the Edit Transaction exist with the same name and data type in the

Add/Edit Transaction to Merge into

Naming

Transactions should be named using Camel Case/Initial Capitalization Use Object Verb naming style

Preferred Transaction verbso Add

Use when adding a new objecto Clear

Use the verb Clear for Delete Transactions that do not run any back -endUpdate Steps, otherwise use Delete for those that do

o Delete Use when deleting an Object from the Client and the Back-End system (SAP,

Maximo)o Edit

Use when editing an existing Objecto Post

Transaction that passes up some data to a Bundling Steplet Bundling is used to post all Transactions related to a certain Object at one time,

rather than one by one. This saves round trips to SAP and helps ease theburden on the Agentry and SAP servers

o Reset Edit Transaction that resets some values

o Status These are Edit Transactions that change the status of an Object Do not use Status as the verb, but the actual status value:

WorkOrderComplete TaskStarted OperationHold

Transactions are typically named with the same name as the Action that calls them Transactions that do not require user interaction should be suffixed with Auto to indicate that

they are automatic Some transactions should be suffixed with an additional description when appropriate:

o If adding Notes to a Task Object: TaskAddNoteso If adding a Component to a new WorkOrder Object: ComponentAddForNewWorkOrder

Type Naming convention syntax Examples Interaction withthe user viascreen ormessage/validation

{Object}{Verb} PartAddPartIssuePOLineItemEditWorkorderDelete


26/44


26

Type Naming convention syntax Examples popup

Auto (Silent)without userinteraction

{Object}{Verb}Auto[additionaldescription]

WorkorderDeleteAutoAddressAddAutoPointAddAutoFromRouteCT

Delete Transactionwith no back-endupdate steps

{Object}Clear[Auto] WorkOrderClearAutoAddressClear

Propert ies

Key o The key of an object is some value that is unique among its peer collection. Usually

when a new object is added, we generate a unique local id for it. This is accomplishedby setting the Initial Value for the object property to Rule Before data Entry and runninga rule similar to:

o The above rule combines the string LOCAL_ with a millisecond representation of thecurrent system time, yielding a unique value on this device. This value if often replacedwith a real back-end value upon posting to another system such as Maximo or SAP, butit does its job for us locally until that time

o Using Rule Before data Entry ensures that this local ID is available to other transactionand screen properties during screen data entry and after the transaction is complete.

Always set this value before data entry when possible Display Name

o Change the Display Names of Transaction Properties to something easily readable andidentifiable where needed. The Property name is defaulted into this field, but this ismost likely a code variable name that wont make sense when displayed to a technician.

Agentry will use this text to display for validation errors concerning field length orallowable numeric limits

Merging A few rules must be followed when setting up edit transactions so they will successfully merge

with existing edits/adds: o All properties must tie back to an object property

Do not leave any properties mapped to None. This will cause a merge failure If necessary, create dummy Properties in the target Object to map values back

to o All properties in the edit transaction must exist with the same names and types in the

add/edit transaction to be merged into Do not add any extra properties to the edit transaction or change names of

existing properties. This will cause a merge failure Same Property names but of different data types will cause a merge failure

o Do not use Change Type on properties Changing property types is always un-safe and generally should never be done,

even though the editor supposedly supports this functionality. You can easilycause a merge to fail by changing a property type in either transaction, even ifthey match

SECTION 7: NAMING CONVENTIONS FOR FETCHES AND READSTEPS

1. Use {Verb}{CollectionName} syntax2. In Agentry 3.1.2 and above the Editor will provide suggested names.


27/44


28/44


28

SECTION 8: NAMING CONVENTIONS FOR STEPS

Steps should take the form:

backendActionName where

backendActionName is the name of the backend process This could include:

external SQL script to be executed

the backend step name (Agentry 3.1.4 and above)

some other backend external process (printing, emailing, saving a record to the file system,etc.

o Java Step names should generally match the Transaction or Fetch name callingthem with a Steplet suffix

o Java steps should be created using the New or Existing Source Typeo Read Steps should not be necessary using the Java Backendo SQL and XML Step Names should generally match the Transaction or Fetch name

calling them. Read Steps should describe the Collection being fetched under theParent Object: e.g., GetPartsForWorkOrder

o Groups are always assigned and consistently match the related Object orfunctionality

This will make the steps more easily readable by a human editor who can quickly see what the back endprocess will accomplish without needed to click through to another screen. It will also make debugging easiersince more information will be provided in the debug log files.

In the case of SQL Scripts, the most common case, the backendActionName should describe the action on adatabase table (Insert, Update, Delete, Exec, etc) and the affected table name. It may optionally includeextra descriptive information at the end of the name

Type Naming convention syntax ExamplesSQL Scripts {SqlScriptName} UpdatePOLineItem

UpdateMatRecTransPOLineItemUpdateInvBalancesPOUpdateInvLotAutokeyInsertInvLotInsertMatUseTransDirectIssue

Other externalProcess

{ProcessDescription} SaveWorkOrderFileToDiskPrintWorkorderStatusReportEmailWorkorderStatusReport


29/44


29

SECTION 9: NAMING CONVENTIONS FOR ACTION STEPS

For an action that has multiple actions steps, the editor will, by default, create names like

Step Name Step Type

Step1 TransactionStep 2 TransactionStep 3 ApplyStep 4 TransactionStep 5 ApplyStep 6 TransmitIt is much more user friendly to describe what Step1 through Step 6 are actually doing so that a designerdoes not have to click on a step just to see its details

Step Name Step Type

FinishMR TransactionPrintLabel Transaction

Apply ApplyDeleteMR Transaction

Apply2 ApplyTransmit Transmit

As you can see in the second example, a designer can glance down the step name column and understandwhat the action is doing.Recommendations by Step Type

Step Type Use

Apply Apply{n}Exit Application ExitMessage Message CaptionNavigation Screen Set NamePrint Report Print{ReportName}SubAction Action NameTransaction Transaction Name

Globals A global definition defines a constant value, including data type, for the application. This value can bereferenced throughout the application, both by the attributes of other definition types and for use insynchronization components. A global value cannot be changed on the Client at run-time but can beoverridden during synchronization.

A global is a constant that is set in the application level in the Agentry editor. You set the Global value in oneplace and then reference the global name wherever you need to use that value. This provides a singlechange point for a value that is referenced by many other definitions.

When an application change is necessary concerning this Global, the single value can be adjusted, ratherthan it being necessary to correct many separate definitions where this is used to enable or disablefunctionality. For example, all of our Mobile Products have many features that can be turned on or off oraltered by changing the value of a global. In work manager good examples would be enabling or disablingparts by setting the value true or false or adding additional statuses to the status list by adding them to theglobal.

To set any text string that might need to change if you translate the application into another language

o Multi-Purpose Globals are placed into the Application Group, e.g., Application.BlankSpace, Application.EmptyString


30/44


30

o International Localization strings are in the Text Group, or a Group matching theirfunctionality or Object

o Do not create a Global Group with the same name as an Object. Backend Flunky resolutionconflicts with this. Use an abbreviation or derivation when creating an Objects Group o Put boundary limit Globals into the Lngth Group (Length is a reserved word)

o Functionality (Component) related Globals belong to a functionality based Global Group

General

Globals should be used extensively throughout an Agentry application. They not only benefit theapplication designer but also the end user and system administrator. Globals are used for:o Controlling whether certain functionality is enabled or noto Making an application international by changing the written languageo Helping enforce boundary limits during data entryo Storing hard-coded constant values like:

Statuses

Error/Warning messages Backend specific codeso Acting as a single change point for a value that is referenced by many other definitions.

When an application change is necessary concerning this Global, the single value can beadjusted, rather than it being necessary to correct many separate definition points

o Lookups in Java codeNaming

Globals should be named using Camel Case/Initial Capitalization:o BuildingMaxLengtho PhoneTooLargeMessage

Name Globals so that their purpose can be easily identified, avoiding abbreviations:

o FaxTooLargeMessage is good, FaxMsg is bado ActivityCatalog is good, ActivCat is bado WorkOrderFetch is good, WOFetch is bad

Type Group Naming convention syntax ExamplesEnableFunctionality

Enable Function, module, screen, etc to beenabled

Enable.EnterTimesheet

Property Lengths Lngth Property name Lngth.NotesFunctional ormodule levelgrouping

Modulename

Property name WorkorderStatus.Received

Groups

Keeping Globals well organized can be difficult, but is very important. Not being organized willlead to duplicate unnecessary Globals across multiple Global Groups and can make findingexisting Globals difficult

Globals that are not specific to any particular functionality group but are generally usedthroughout the application should be put into a Group called Application :o Application. BlankSpace = o Application.EmptyString = o Application.LocalPrefix = LOCAL_

Place text strings that are used for international localization purposes in a Group called Text :

o Text.None = -NONE- o Text.PendingDelete = To be deleted o Text. PhoneTooLarge Message = Phone and Extension Length cannot exceed


31/44


31

o Text.TrueValueo Text.FalseValue

Text strings for internationalization can also alternately be placed in a Groupmatching a certain piece of functionality (Stock, CustomerService), or related to aparticular Object (WorkOrder, Task). It is easier to find these though if kept togetherunder the Text Group

Place Globals related to enabling application functionality in a Group called Enable :o LaborTime.EnableAddTime = True o WorkOrder.EnableStart = False

Place Globals related to user interface control in a Group called UI: o UI.Win32RowsTransaction = 20 o UI.ListTileRowAdjustment = 6

Place Field length minimum and maximum related Globals in a Group called Lngth: o Lngth.WorkOrderMinLeno Lngth.NotifDescMaxLen

Place Globals related to a particular object in a Group representing that Object name. Do notuse an exact Object name, as that causes a conflict for the Agentry Flunky parser. This mayinvolve using abbreviations:o WO.EnableStartWO = True o Notif.NewSt atus = NEW o Addr.BuildingMaxLength = 20 o IndObject.TypeObjectComponent = 3

Place Globals related to a particular functionality section in a Group indicating that functionality:

o LaborTime.InProcessDescription = IN PROCESS o LaborTime.CATSCodeDefault = 01 Usage

Object and Transaction Propertieso Create Globals for Minimum and Maximum string lengths, allowable numeric limits or any

other spot where Globals are allowed Place these Globals in the Lngth Group (Length is a reserved word) It is best to create a separate min and max for each property, but sometimes a

property type is re-used in multiple Properties or Objects like a phone number or acode type. In this case, it is acceptable to create a single Global likePhoneNumberMinLength and re-use it for all phone number related Properties

Initial Value data constants should come from Globals, not hand-entered text

constants Screenso Create multiple Globals for Rows and Columns and use these on each Screens header

UI.Win32RowsTransactio n = 20 UI.PPCColumnsTransaction = 100

Screen Fieldso Create multiple Globals for Label Width and use these on each Screen Field

UI.Win32LabelWidthTransaction = 10 UI.PPCLabelWidthDetail = 5

o Some label widths are odd exceptions and these dont always make sense to record asGlobals, e.g., a Screen Field that has a larger than usual label width (20 compared to 12)used only on one Screen in the application. Use common sense and when you have arecurring label width, use a Global


32/44


32

Ruleso Globals are used extensively in rules:

Do not hard-code text constants in rules. Use Globals Put text strings that will be displayed to the user in the Text Group so they may be

overridden in an international/non-English setting

SECTION 10: NAMING CONVENTIONS FOR COMPLEX TABLES

The complex table definition defines a table of records containing multiple fields stored on the Agentry Clientin a structured and searchable format. These records can be searched based on the field used to display thedata to the user. A complex table can contain large amounts of data with records numbering in thethousands. The complex table definition also defines how its data is synchronized.

A complex table consists of the data that is stored as well as the indexes created for that data to make itsearchable as well as create parent child relationships. Any tables created will affect both device memoryand sync time. There is no magical way for reducing the download time, except by reducing the number ofbytes to be downloaded.

Review and challenge:Each and every field in your complex table and decide if it is absolutely necessary each and every index inyour complex table and decide if it is absolutely necessary.

Examine the width of each and every field and try and keep it to minimum

Naming

Complex Tables should be named using Camel case, but with a ct prefix (ctActivityType, e.g.).

Fields

Use Camel Case/Initial Capitalization for naming Fieldso It is safest to create string fields with even number lengths (2, 4, and 10). Odd lengths can

lead to potential problems due to Agentry bugs: - Odd length international string complextable fields crash some Win CE devices

Set String Field lengths via a Global when possible. Maximo employs a data Dictionary that maychange field lengths, so in our product, Globals have been incorporated and are overridden viabackend query during transmit

If possible, use a Number or Identifier as the key field to a Complex Table. These types aremore quickly searched by Agentry

Set string field lengths via Global when possible All Strings should be defined as International with the exception of primary key members Display names have been modified to be descriptive abbreviations for Screen/Dialog display Key field utilizes a Number or Identifier if possible to increase performance

Indexes Use Camel Case/Initial Capitalization for naming Indexes If an Index has a parent, note that in the name, e.g., if the relationship is that the Description

field has a parent of KeyField, then name the Indexes DescriptionByKeyField and KeyField Be wary of changing the Display Name of an Index. It needs to match the actual internal name

due to client bugs. Changing this name exposes Agentry bugs and will sometimes breakstandard functionality:o Details - CT search fails when display name and internal name are not the same on client

upgraded from 5.1.26o Details - Changing CT index display name breaks the CT Search Control by eliminating the

index from the list Compound Indexes can be used as the Key to a Complex Table. The Unique? = Yes Index as

displayed in the Editor must be the lowest child in the hierarchy, i.e., If the Key consists of twofields where Location is the Parent of Equipment, then Equipment must be shown as the UniqueIndex in the Editor. The Unique Index is the first Index added


33/44


33

Remember to clean up unused Indexes at some point. Add a reminder to the Index definitionwhen you believe it is obsolete. Extra indexes waste transmit time and storage space on adevice

Indexes with a parent should be noted in the Index name, e.g., DescriptionByKeyField Display names have been modified to be descriptive abbreviations for Screen/Dialog display When using a Compound Index, the Unique Index must be the lowest child in the hierarchy

SECTION 11: NAMING CONVENTIONS FOR DATA TABLES

Data Tables A data table definition defines a set of records stored on the Client. Each record consists of two fieldscontaining a key and value. A data table is intended to contain a small number of records (less than 100) thatmay be displayed to uses in drop down lists, as well as other uses. There is no built-in search functionality toa data table. A data table is defined at the application level and is available to all modules of the application.

Naming Data Tables should be named using Camel case, but with a dt prefix (dtAccountIndicator, e.g.).

This is a legacy standard that may be eliminated

ImagesThe Image definition type allows you to incorporate bitmap images into the application and to display thoseimages in one or more of several different locations. This can include button icons, icons within list controls,module icons, and images within some of the stock screens within every Agentry application. The AgentryEditor also allows you to specify a mask color for the bitmaps, if desired. The bitmaps themselves areexternal to the definitions on the Editor and are referenced by the Image definition. They are copiedpublished to the Agentry Server during a publish, and are then transferred to the Clients with the otherapplication definitions.

General

For images that dont require a Mask color, add one anyway for a color that is not representedon the Image. Agentry does not properly display Images in certain places if a mask Color is notspecified due to a bug: Details for #19174 Toolbar and List Screen icon images unexpectedlymask out colors when no mask is specified

When creating an Image to be used for a List Screen Column, the dimensions of each childImage in the master should be 16 by 16. Add new Child Images to the right, extending the widthby 16 for each new child:

The above image shows 7 children for a Work Order Object, used to display on the statuscolumn in a list. The 8 th child is used to indicate a change to the Object that requires a transmit.The pink background of the needs transmit image is also used as the Mask color for thismaster Image, so the pink is never displayed on the Client

The above Images are referenced on the List Screen Column as the Icon Image. Use zero-based numbering to display the correct image via Rule. In our case, we have 8 images, so 0 7


34/44


34

SECTION 12: TAGGING

Tags are applied to all definitions.

The ability to tag your definitions was added in Agentry 5.2 as part of the team configuration functionality.This is a similar to a group in that you are assigning a string value called a tag to Agentry definitions such asactions, rules, steps, etc...The purpose of a tag is to identify all configurations that comprise a configuration. This allows you to dothings such as identify all editor configurations needed to create new functionality and export theseconfigurations as modular units to reuse in another application.

General

Tags should be applied to all definitions in an application All definitions in a parent application should be tagged with an indicator referring to that base

application, e.g., Work Manager is tagged with WM

Component definitions should be tagged with an indicator referring to that Component, e.g.,

Address is tagged ADDR, Installed Base is tagged IB, Customer Service Lite is tagged CSLite Sub-Component definitions that are part of a larger component should be tagged with an

indicator referring to the parent Component, e.g., Address is a Sub-Component of CustomerService, so Address is also tagged with CS

If an entire Definition is to be tagged, utilize the Recursively Add feature by applying a tag in theProperties View and then right-clicking it to access the context menu

Agentry Search can be used to search for one OR more tags, but not for definitions that containone tag AND another. AND would be useful to find the definitions that are accidentally taggedand need to be cleaned up. This request has been made: Details for #31956 Agentry Searchby Tag needs to support an AND or OR selection

Styles The Style definition is used to modify the appearance of the user interface from the system defaults. This caninclude different background and foreground colors; specifying a font face (Sans Serif, Times New Roman,etc.), point size, font style (underline, bold, etc.), border styles for certain screen controls, and text alignment(centered, justified, etc.). These styles can be applied to everything from the application as a whole, down toan individual field or button on a single detail screen, and everything in between. Furthermore, these stylescan be applied to the interface at all times, or conditionally via the use of Rules.

Naming

Type Naming convention syntax Examples Tab {Tab}{StyleName} TabClean

Button {Button}{StyleName} ButtonCleanFocusedButton {FocusedButton}{StyleName} FocusedButtonCleanDetailScreen {DetailScreen}{StyleName} DetailScreenCleanField {Field}{StyleName} FieldCleanFocusedField {FocusedField}{StyleName} FocusedFieldCleanHyperlink {Hyperlink}{StyleName} HyperlinkCleanListScreen {ListScreen}{StyleName} ListScreenCleanHeaderLabel {HeaderLabel}{StyleName} HeaderLabelCleanColumnLabel {ColumnLabel}{StyleName} ColumnLabelCleanRow {Row}{StyleName} RowCleanRowHyperlink {RowHyperlink}{StyleName} RowHyperlinkCleanAlternateRow {AlternateRow}{StyleName} AlternateRowClean

AlternateRowHyperlink {AlternateRowHyperlink}{StyleName}

AlternateRowHyperlinkClean


35/44


35

Type Naming convention syntax Examples HighlightRow {HighlightRow}{StyleName} HighlightRowCleanHighlightRowHyperlink {FocusedButton}{StyleName} xClean

SelectedRow {FocusedButton}{StyleName} xCleanSelectRowHyperlink {FocusedButton}{StyleName} xCleanDetailPane {FocusedButton}{StyleName} xClean

SECTION 13: NAMING CONVENTIONS FOR JAVA CLASSES

Naming

Type

Naming convention syntax

Examples

Steplet {TransactionName|FetchName|PushName}{Steplet} AddWorkorderStepletGetWorkordersSteplet

Stephandler {TransactionName|FetchName|PushName|CT|DT}{Stephandler}

AddWorkorderStephandler

POJO {ObjectName} WorkorderItemCATSRecord

BAPI (SAP Only) {Transaction|Fetch|PushName|CT|DT}{BAPI} AddWorkorderBAPIComplex Tables CT{tablename} CTPartsData Tables DT{tableName} DTPriority

Extending Java Classes

Do not change the base classes unless absolutely necessary Create sub-classes in a customer package. (ex: com.sap.customer..workmanager.Workorder) All the common code is packaged com.syclo.sap Product specific code is packaged into com.syclo.sap.(product) Component are packaged into com.syclo.sap.component Simplified and consistent interface for DataTables, ComplexTables and Data Objects Large Step Handler classes have been broken up into individual classes per object Flexible Logger class for more granular logging Support for unit testing via JUnit test classes and test suites


36/44


36


37/44


37

SECTION 14: SAP DEVELOPMENT NAMING CONVENTIONS

This document provides best practices for defining naming conventions for Mobile development objects in

SAP system.

The naming conventions described here are not compulsory. Our intention is to provide generalrecommendations and principles that should help to define your own companywide naming conventions. Asevery company is different in structure and size it is important to gauge what level of granularity is requiredwhen naming objects in your landscape. When enhancing Mobile application common question asked bycustomers are what naming conventions to be followed. Since all mobile development objects are deliveredunder /SYCLO/ namespace it is better to go with follow of base product naming conventions but again it isleft to customers to decided what is good for them.

Well defined naming conventions should help to standardize and facilitate the implementation of your MobileIntegration Scenarios.

Namespace

All Syclo SAP Add-On Objects are developed under namespace /SYCLO/. Whenever youremodifying objects delivered by base product it is recommended that you copy /SYCLO/objects into Z or Y name space.

Packages

Syclo SAP Add-On Objects are organized into various workbench packages. All packages under the/SYCLO/ namespace are predefined. Developer should not create new packages under the/SYCLO/ namespace. For development purpose, create new packages using Y or Z namespace.Naming convention is not enforced in Y or Z namespace.

The following pac kages are defined for the /SYCLO/ namespace: /SYCLO/ - Main package used to grouping multiple packages. No object can be assigneddirectly to this main package.

/SYCLO/CORE Contains objects from Syclo Integration Framework. /SYCLO/UTIL Objects in this package are for internal use. Not released to customer. /SYCLO/CO Contains objects related to SAP Controlling Area Module. /SYCLO/HR Contains objects related to SAP Human Resource Module. /SYCLO/MM Contains objects related to SAP Material Management Module. /SYCLO/PM Contains objects related to SAP Plant Maintenance Module.

If youre trying to enhance any of the objects belonging to above packages. Create Z package hierarchysimilar to product package hierarchy.

ClassesOverall design paradigm for the Syclo SAP Add-On Component is based on ABAP OO; therefore ABAPObject classes are used extensively. Whenever possible, ABAP Object class is the preferred way ofencapsulating business logic. All ABAP OO classes developed should follow the generic naming pattern/SYCLO/CL_xxxxxxxxxxxxxxxxxxxx, when x represent any alphanumeric character.

Mobile Data Object (MDO) Class Handler

These classes handle integration logic between Agentry and SAP backend, such as data fetchor transaction update, for a specific business object. The following naming pattern should befollowed:

/SYCLO/CL_ + pppp + _ + xxx + _DO


38/44


39/44


39

Web Dynpro Assistant Class

Web Dynpro assistant classes should be used for any Web Dynpro applications developed inorder to encapsulate backend business logic or database access. The following namingpattern should be followed: /SYCLO/CL_ + pppp + _WD_ + xxx Where pppp represents the corresponding workbench package name without /SYCLO/prefix, such as CO, HR, MM, or PM; xxx represents any combination of alphanumericcharacters, which should be indicative of the Web Dynpro Component. Maximum length of an

ABAP Object class name is 30 characters.

BAdI Implementation Class

BAdI implementation classes are created to implement enhancement to standard SAP usingstandard BAdI definition. The following naming pattern should be followed: /SYCLO/CL_ + pppp + xxx Where pppp represents the corresponding workbench package name without /SYCLO/prefix, such as CO, HR, MM, or PM; xxx represents any combination of alphanumericcharacters, which should be indicative of BAdI being implemented. Typically we should usethe BAdI definition name for the value of xxx. Maximum length of an ABAP Object classname is 30 characters.

Interface

ABAP Object Interface is one of the foundations for polymorphism in ABAP OO paradigm, and therefore areused extensively by Syclo SAP Add-On Component. All ABAP OO interfaces developed should follow thegeneric naming pattern:

/SYCLO/IF_ + pppp + xxx

Where pppp represents the corresponding workbench package name without /SYCLO/ prefix, such asCO, HR, MM, or PM; xxx represents any combination of alphanumeric characters, which should beindicative of the function of the interface. Maximum length of an ABAP Object interface name is 30characters.

Function Groups

As a general guideline, business logic of the Syclo SAP Add-On Component should be encapsulated using ABAP Object paradigm. However due to the technical constraints of the ABAP programming language,certain tasks still have to be handled using function groups and function modules, such as RFC calls orupdate tasks. The following naming pattern should be followed:

BAPI Wrapper Function Group

These function groups contain BAPI Wrappers for integration with Agentry platform via RFCprotocol and Java Connector. Each function group should contain BAPI Wrappers for aspecific SAP module. The following naming pattern should be followed:

/SYCLO/BAPI_ + pppp

Where pppp represents the corresponding workbench package name without /SYCLO/prefix, such as CO, HR, MM, or PM.

Update Function Group

These function groups contain update function modules that can be called using update taskduring SAP business object update. Update task can guarantee data integrity of LUW during


40/44


40

update, and is the preferred way to handle extension of standard SAP business object update.The following naming pattern should be followed:

/SYCLO/UPD_ + pppp

Where pppp represents the corresponding workbench package name without /SYCLO/ prefix, such asCO, HR, MM, or PM. xxx represents any combination of alphanumeric

characters, which should be indicative of the Web Dynpro Component. Maximum length of an ABAP Object class name is 30 characters.

Function Modules

As indicated in section 6.5, function modules are necessary in order to provide support for RFC calls andupdate task. The general guideline is to use function module only as a skeleton, and encapsulate businesslogic using ABAP Object classes, and call these classes within the function module.

BAPI Wrapper Function Modules

BAPI Wrappers are RFC enabled function modules that serve the role of integration pointbetween Agentry platform and SAP. The following naming pattern should be followed: /SYCLO/ + pppp + _ + xxx + mmm

Where pppp represents the corresponding workbench package name without /SYCLO/ prefix, such asCO, HR, MM, or PM. xxx represents any combination of alphanumeric characters, which should beindicative of the business object the BAPI Wrapper that se t the first 2 character of xxx to either DT, CT,or DO to represent whether the BAPI Wrapper is used for data table, complex table, or standard object in

Agentry. mmm represents the function BAPI Wrapper provides, GET for fetch business object data, CRTfor creation of business object, DEL for deletion of business object, UPD for update business object data.

Programs

Programs are created in order to support background process in Syclo SAP Add-On Component. Thefollowing naming pattern should be followed:

/SYCLO/ + pppp + xxx + _PROG

Where pppp represents the corresponding workbench package name without /SYCLO/ prefix, such asCO, HR, MM, or PM; xxx represents any combination of alphanumeric characters, which should beindicative of the function of the program. Maximum length of an ABAP program name is 30 characters.

Includes

Traditionally include files can be used in programs, function groups, module pools to make ABAP programs

more modular. With the emphasis on ABAP OO paradigm in Syclo SAP Add-On Component, include filesplays a smaller role. When needed, include file should have the following generic naming pattern:

/SYCLO/ + pppp + xxx + _INCL

Where pppp represents the corresponding workbench package name without /SYCLO/ prefix, such asCO, HR, MM, or PM; xxx represents any combination of alphanumeric charac ters, which should beindicative of the function of the include file. Maximum length of an ABAP include file name is 30 characters.Common scenarios when include files are used in Syclo SAP Add-On Component:

Enhancement Framework Implementation

When creating enhancement framework implementation for implicit or explicit enhancement

spot that is not BAdI based, we should always use a include file, instead of coding directlyinside the implementation. The following naming convention should be followed:


41/44


42/44


42

This is the lowest level implementation that actually contains the enhancement logic. Thebelow naming pattern should be followed:

/SYCLO/ + pppp + _ + aaa + xxx

Where pppp represents the corresponding workbench package name without /SYCLO/prefix, such as CO, HR, MM, or PM; aaa is the abbreviation identify the types of SAPmethod where the implementation has been created, for example, BTE for businesstransaction event method, BADI for BAdI event, UPD for update task; xxx representsany combination of alphanumeric characters, which should be indicative of the function ofthe enhancement implementation. Maximum length of an enhancement implementationname is 40 c

Documents

Configuration Practices for Agentry Based Mobile Application