Configuration Practices for Agentry Based Mobile Application
January 11, 2017 | Author: nandoo | Category: N/A
Short Description
Download Configuration Practices for Agentry Based Mobile Application...
Description
Configuration Practices for Agentry Based Mobile App This document provides suggested naming conventions for objects created in the Agentry Editor. Application developers and maintainers are strongly encouraged to follow these conventions in pursuit of the goals listed below.
Configuration Practices for Agentry Based Mobile App
Provided by SAP Mobile - Rapid Innovation Group
Applicable Releases: Agentry 5.X and 6.X - which Includes all SAP based mobile products running on Agentry
Version 1.0
2
Configuration Practices for Agentry Based Mobile App
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
3
Configuration Practices for Agentry Based Mobile App
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
4
Configuration Practices for Agentry Based Mobile App
SECTION 1: AGENTRY NAMING CONVENTIONS
Goals There 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 to make changes to an Agentry application, the learning curve is reduced if they know how objects relate to one another and how they are used. 2. Design Assistance – An application developer can use naming conventions as a design aid to help think 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 design approach. 3. Consistency – Naming objects using predictable convention increases usability. Rules and actions can 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 the original 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 abbreviations 3. 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”, don’t create a similar property elsewhere called “AcceptedQty” or “QuantityAccepted” 6. The conventions listed in this document are strongly encouraged, but not mandatory. You may have preferred the prefix “Set” over “Calc”, for instance, but given that one is not significantly more advantageous than another you should use the preferred name since other applications will implement the preferred name. If there is a case when a different name more clearly describes the object, then by all means use it, but use discretion in making a decision to vary from the convention. 7. Unused definitions are removed from Editor 8. Actions, ScreenSets and Transactions all stick to preferred Object-Verb naming style 9. 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 WorkOrder o WorkOrderHistory o Notification o NotificationReference
•
Where possible, use the name of the data source. For example, if the object maps to a database table, 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 clearly understandable if the corresponding Agentry object is named Phase
•
5
Configuration Practices for Agentry Based Mobile App
• •
Properties
Abbreviations should be avoided, but if necessary should be consistent across all objects and other 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 related stock objects like TransferHeader, TransferItem, TransportOrderHeader then preface these with the Stock component name: o StockTransferHeader o StockTransferItem o StockTransportOrderHeader
o o o o o o o
Use Camel Case/Initial Capitalization Use primitive base Object types (Not Complex Table, Data Table) where possible Numeric boundaries and string lengths are set using Globals IsLocal Boolean exists if necessary Boolean property names prefaced with a common prefix, like “Is” A Date/Time Field’s Time Zone Adjust attribute should be set to use a Global called AdjustTimeZone set to “From System Connection Local Time” Where possible, use the property names of the data source. If the object maps to a database table, use the database table field names.
Avoid property types that have no meaning at the object level. Choosing these types may cause problems 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 Object o 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 IsLocal o 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 accessible o 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 string stored 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 object o Set this property to true in the Add transaction o Create a single Evaluate rule that checks the IsLocal property regardless of object type and returns True or False o Drawbacks of this approach: 6
Configuration Practices for Agentry Based Mobile App
•
•
Extra property is needed Booleans o Easier to identify if prefaced by a common prefix, like “Is”. IsBreakDown is better than BreakDown. 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/Time o 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 and intuitive Guide the user through screens, using as few keystrokes as possible. This means use 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, if you are a utility and need to include a main break form with 50 fields, you might want to consider deploying on windows Screen Sets o 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 is the Object name pluralized o Action Buttons should use Images consistently, and should be named identically to the Action being run
7
Configuration Practices for Agentry Based Mobile App
o
Fields
o o o o o o o
Type All
Label Width is set via Global on each Field where appropriate Fields are ordered from top to bottom in order of precedence if there are references or relationships between the fields List Tile Controls have an offset applied to them to shrink the PPC tiles. -6 is the standard 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, 0 Tasks) List Tile Controls have appropriate filters added, excluding fields with calculated values Top Row on a Selected Row Tile Screen is reserved for Action Push Buttons where appropriate Needs Transmit Icon added to upper right of Top Row on a Selected Row Tile Screen
Naming convention syntax {Object}{tile}{List|Detail}[{extra desc for clarity}]
Examples WorkorderList ItemDetail ItemDetailForRotatingItem ItemDetailForLotItem
Naming
• •
Screen Sets should be named using Camel Case/Initial Capitalization and Object-Verb syntax Screen Set Types
o Add
o o o o o o o o o
Transaction Screen for adding a new object Sometimes also doubles as an Edit Screen Set Use a descriptive suffix when necessary to further describe CATSRecordAddForWorkOrder AddTileInline Transaction Screen used for doing inline Object Adds from a List Tile Control DisplayTile Child read-only Detail Screen hosted on a Tile Display Control Edit Transaction Screen for editing an existing Object EditTile Child Transaction Screen hosted on a Tile Edit Control EditTileInline Transaction Screen used for doing an inline Object Edit against the currently selected Tile on a List Tile Control Tile Child read-only Detail Screen hosted on a List Tile Control Displayed for all unselected Tiles on the list TileSelected Child read-only Detail Screen hosted on a List Tile Control Displayed when a Tile is selected by the user Transfer Used for Transfer function data entry View Read-only Detail or List Screen 8
Configuration Practices for Agentry Based Mobile App
Fetch
{FetchName}[{extra desc for clarity}]{Get}
WorkordersGet ProjectsGet UserInfoGet
Object Collection
{ObjectName[plural]}{View}
WorkordersView ProjectsView
Object Detail {ObjectName}{View}
WorkorderView ProjectView
Transaction
{TransactionName}
WorkorderAdd
Row Tile
{ObjectName[plural]} {Tile}
WorkorderTile StockTransferHeaderTile
Row Selected Tile
{ObjectName[plural]} {TileSelected}
ServiceOrderItemsTileSelected InstalledBaseProductTileSelected
Tile Edit
{ObjectName[plural]} {EditTile}
WorkOrderEditTile
Tile Display
{ObjectName[plural]} {DisplayTile}
WorkOrderDisplayTile
List Tile Inline Add/Edit
{TransactionName} {TileInline}
WorkOrderAddTileInline NotificationEditTileInline
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_PPC o NotificationTasks_TileList_Win32 Screens that will be used generically regardless of Platform should be suffixed with “All” rather than a Platform; e.g., AddressList_All
Type
Naming convention syntax
Examples
List
{ScreenSetName}_{optional label for clarity}_{List}_{platform|All}
WorkordersView_List_Win32 WorkorderDetailsView_Parts_List_PPC
Detail
{ScreenSetName}_{optional label for clarity}_{Detail}_{platform|All}
ProjectView_Detail_Win32 UserInfoView_Address_All
Tile List
{ScreenSetName}{optional label for clarity}_{TileList}_{platform|All}
WorkOrderDetailView_Partners_TileList_PPC
• Rows
o Rows per screen should be consistent by platform throughout the application when possible to present a uniform look
o Set this using a Global in the UI Group o PPC – rows should be 10 o Win32 – rows should 20 • Columns o
Columns should be set to 100 regardless of platform. 100 units allow the field column widths to be thought of as a percentage of the total screen available. This allows for more precise manipulation of screen fields and makes modifications much easier than if the screen only supported a small column width
Buttons o Screen Button names should reflect the Action they are tied to, i.e., The Button tied to the TaskAdd action should be called TaskAdd o 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 and remember to adjust the button name manually if editing a Button’s Action target o A single Button Separator on a button list should be named “Separator”. Multiple Button Separators 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 named “Separator1” and “Separator2”, not “Separator2” and “Separator5”. Button positions tend to move around, so don’t try to imbed the Button order position in the name of the 9
Configuration Practices for Agentry Based Mobile App
Separator. It is also acceptable to always name the first Separator as simply “Separator” without the “1” suffix, then continue with “Separator2” for the second Header Rule o 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 the descriptive Object name pluralized: 1 of 3 Work Orders 5 of 5 Addresses
Fields o
o
o
Label Width Always set the Label Width on all fields. Do not rely on inheriting the width from the field above. While easier to implement, this is bad practice. If the screen field order changes, it is easy to mess field label widths up without even realizing. 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 can be changed by adjusting a single global, rather than having to hard-code individual fields 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 the Equipment field cascades off the FunctionalLocation field, the FunctionalLocation field should appear first in the field list order before Equipment, even if their screen field positions reflect the opposite. If Equipment is first in the list in this scenario, you run the risk of the screen fields not populating themselves properly when the transaction screen is first displayed for existing data. This happens because Agentry tries to figure screen fields out in order from top to bottom. Since Equipment comes first and relies on FunctionalLocation for its data, the Equipment field remains blank because FunctionalLocation has not yet been initialized due to the incorrect field order set up by the designer. 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 Object’s child or related sibling on a Screen Set that targets the Parent, without having to write convoluted targeting Rules or hard-code Object Browser paths to the desired Object on multiple Screen Fields. This Control accepts a Target Path that points to the Object it will be displaying. This way, Detail Screens can be imbedded in a Parent Screen Set, each easily targeting different Objects if desired by using Tile 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 data immediately, and are not updated if outside Transactions modify the underlying Object. Detail Screens normally update themselves when the Screen Set’s targeted 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 update fields if underlying object is changed The row height on the child tile can be optionally modified to shrink the rows if more space is needed for PPC. Use a negative number to shrink the rows. For example, use -2 to shrink the rows by a small margin Use the SCREENFIELDVALUE Rule Function Term to reference other fields in Complex Table/Update Rules on the actual child Tile Transaction Screen prior to 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 work properly. This has been corrected in: Details for #31049 - Tile Edit control working inconsistently with cascading complex table fields in Agentry 5.2.4. It is 10
Configuration Practices for Agentry Based Mobile App
now possible to reference the Child Tile Screen Set/Screen/Field and properly access the data stored in these fields. For example, a child Complex Table field must reference another parent Field to build a parent string via a Rule. The Screen Field is called PartCodeGroup. The following Rule can be used to build the parent string. Notice that the PartCodeGroup Field is accessed using the Screen Set and “Current Detail Screen” syntax, making this Rule compatible with any Platform:
o
When this Control is in edit mode, you will see the Cancel and Save buttons appear in the lower-right corner of the Tile. Notice also that any Action Buttons on the Screen or Screen Menus become disabled by default. This is an option on the parent Screen Set that hosts the Tile Edit Control called “Transaction Blocking”. When toggled on, all other Actions are disabled while the Transaction is being edited. If toggled off, Agentry does not restrict the use of other Actions during the edit, possibly leading to conflicts. Turning this feature off is not recommended unless careful design planning has been done to prevent the same object being edited at the same time This control will also automatically save a Transaction in edit mode if the parent Screen is closed, or if the parent Object is changed via a Roll Button. This may be confusing or undesired behavior, so leverage the use of this Control with that functionality in mind. A bug has been logged to request that this auto-save become optional: Details for #31054 - Tile Edit control saves the transaction instead of canceling the edit during certain situations
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 when clicked, eliminating the need to scroll horizontally which was difficult on the traditional 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 works as a good modifier. This amount does not alter the height of push button controls on the tile Use a global to set the Modify Row Height offset and apply this global to all host definitions. 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 rule should count the collection objects and display the plural noun describing the collection 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
11
Configuration Practices for Agentry Based Mobile App
Tile Child Screens o List Tile Controls display a Row and a Selected Row. These are typically two different Screen Sets o The Row Screen Set name should be suffixed with “Tile” This Screen will be shown for all un-selected rows on the list view o 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 PPC Screens. These buttons should show the appropriate image icon for the function. This technique makes it easier for a user to interact with the currently selected Tile Object, rather than having to search for the menu button along the bottom, or possibly on a Popup menu A “ButtonNeedsXmit” Push Button Control should be added to the upper right of Selected Tiles. This uses the Alert image and indicates that the Object has been changed and requires a Transmit to post these changes. This Button is Hidden/Shown using a generic rule:
o
Refer to the “Product Style Guide” document for more specific information on Tile related controls, styles and best practices
List Tile Inline Edit Child Screens o 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 Transaction o 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 the CURRENTVALUE Rule Function (this needs to be validated against current Agentry release). Instead, use the fully qualified Screen Set name and Field name:
Tile Edit/Display Child Screens o 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 12
Configuration Practices for Agentry Based Mobile App
• • •
•
Determine the action type you are creating o “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 verbs o Add Use when adding a new object o Clear Use the verb “Clear” for removing Objects from the Client that do not modify the Back-End via Transaction Update Steps, otherwise use “Delete” for those that do 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 StepHandler o 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 Steps o 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 13
Configuration Practices for Agentry Based Mobile App
Type
TaskDelete would be TaskDeleteLoop
Naming convention syntax
Examples
All
The name of the action the subaction calls
PartAdd
Looping Actions
{actionName} {Loop}
PartAddLoop would loop over PartAdd
o Transaction Steps Name these identically to the Transaction: Used: to initiate one or a series of transactions 1. Use {Verb}{Object} syntax 2. Where possible, the Verb should correspond to the label of the UI interface element that initiates the Action that calls the transaction (that lives in the house that Jack built…) 3. Where possible, the Action name should be identical to the Transaction name that it calls. Ex: If I have an Edit Button that calls the EditWorkorder Action, my transaction name should be EditWorkorder as well.
Type
Naming convention syntax
mapped to a {Verb}{Object} single transaction mapped to a series of transaction
Type
Examples EditWorkorder DeletePart
{Verb}{Object} – use the verb and object that corresponds to the primary purpose of the action
UpdatePOLineItem
Naming convention syntax
Examples
mapped to a single transaction
{Object}{Verb}
WorkorderEdit PartDelete
mapped to a series of transaction
{Object}{Verb} – use the verb and object that corresponds to the primary purpose of the action
POLineItemUpdate
o Message Steps
Type All
Should be named as if it were a Message Sub-Action. Start with the Object being used, followed by the word “Prompt”. Finish with a suffix describing the Prompt. Sometimes an Object name is not appropriate, so use your best judgment: AddressPromptDeleteConfirm ComponentPromptAdd PromptTransmitProceed
Naming convention syntax
Examples
[Object]{Prompt}{Condition|Description} MaterialRequestPromptAlreadyLocked ReservedItemPromptCannotEdit PromptCannotProceed TaskPromptConfirmDelete NotificationPromptVerifyComplete
o Apply Steps Type All
Naming convention syntax Apply{N}
Examples Apply1
14
Configuration Practices for Agentry Based Mobile App
Type
Naming convention syntax
Examples Apply2
o Type
Navigation Steps These should be named simply with the Screen Set name to be navigated to: Navigation Actions viewXXX Naming convention syntax
Examples
Exit App
ExitApplication
ExitApplication
Navigation
{Screenset|Screen}View
WorkorderDetailView MainScreenView TimeSheetListView
o Print Report Steps Type All
Used to generate a report from a Collection or Object:
Naming convention syntax Print{ReportName}
Examples PrintSalesReport
o Transmit Action Steps
Used to initiate server communication:
o Transmit Actions Type
TransmitXXX FetchXXX
Naming convention syntax
Examples
Sending [Silent|Background][{extra desc}] information Transmit to the server without a search criteria screen
Transmit MaterialRequestsTransmit SilentTransmit
Sending {ObjectCollection}Fetch|Get information to the server with a search criteria screen
WorkordersFetch PurchaseOrdersGet
o Windows Command Steps Type All
Used to invoke an external process: Naming convention syntax {Name of the external process}
Transmit Actions Used: to initiate server communication Type Naming convention syntax Sending [Silent]Transmit[{extra desc}] information to the server without a search criteria screen
Examples
AddressMapGet DirectorySaveFileMake
Examples Transmit TransmitMaterialRequests SilentTransmit
15
Configuration Practices for Agentry Based Mobile App
Type
Naming convention syntax
Sending Fetch{ObjectCollection} information to the server with a search criteria screen
Examples FetchWorkorders FetchPurchaseOrders
Navigation Actions 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 All
Naming convention syntax View{ScreenName}
Examples ViewPODetail ViewWorkorderList
Navigation Actions Used: to display a UI warning if a particular state exists or condition has been met. Type All
Naming convention syntax Warn{condition}
Examples WarnMaterialRequestAlreadyLocked WarnCannotEditReservedItem
Looping Actions Used: to iterate over a group of objects In most every case, a looping action will repeat a particular subaction, so name the looping action as the plural of the subaction. Type All
Naming convention syntax {Plural of Subaction}
Examples AddParts would loop over AddPart
Apply Steps • A single Apply Step on an Action should be named “Apply”. Multiple Apply Steps should be named 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 Steps should be named “Apply1” and “Apply2”, not “Apply2” and “Apply5” as would be the Agentry default. Step positions tend to move around, so don’t try to imbed the Step’s order position in the name of the Apply Step. It is also acceptable to always name the first Apply Step as simply “Apply” 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 as they will severely impact the speed of your application, especially during looping operations that create records • When performing looping operations that create many records, do not Apply each transaction write, 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 of stack space and crash Agentry, or lock it up, never completing the writes. Be careful when writing many records with a single Apply and only do this on a device to device basis after testing the performance. It is not possible to use this technique on some slower devices or devices with limited RAM
16
Configuration Practices for Agentry Based Mobile App
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 transactions rely on saved data from the previous transaction(s) For Object • Always supply an object in the “For Object” property drop-down on the Action header. Do not leave it blank. There are many reasons to do so: o This is proper object oriented application design. Think of an Action as a method and the “For Object” as a parameter to that method. You need to pass the proper target object type to that method, as in Java or the compiler will throw an error. Following this standard eliminates mistakes and ensures proper context, as Agentry will throw an error during “Check on Publish” if there is a mismatch between a target object and the “For Object” that the targeted Action accepts o Properly sets the context for all steps within the action, making it easy to browse properties 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 targeting issues and other problems o Setting the correct “For Object” makes for a more readable and easily understood Action • Some Actions don’t make use of any Objects: e.g., Transmit, CurrentScreenSetClose. These Actions don’t necessarily need a For Object, but to be consistent should still be assigned one. When this case comes up, use the MainObject Grouping
• •
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 too many Actions related to certain objects: o StockTransfer o StockReceipt o StockSearch
17
Configuration Practices for Agentry Based Mobile App
SECTION 5: NAMING CONVENTIONS FOR RULES Naming
• • • • • • • • • • • • • • •
• •
Rules should be named using Camel Case/Initial Capitalization Determine the rule type you are creating Create an appropriate name based on the type. A good name should give you a good idea of what the rule is going to do and on what object or property it is going to act Consider that if the rule is hard to name, your design might need reconsideration. There are always exceptions, but for the most part, the ability to create a good clear descriptive name will assist in designing the rule itself Try to avoid abbreviating rule prefixes. Warning, Execute, Calculate, Evaluate are all better than Warn, Exec, Calc, Eval Rules should begin with a verb and describe the function of the rule. Acceptable prefixes include but are not limited to, e.g., Determine, Enable, Evaluate, Execute, Find, Format, Hide, Highlight, Image, Include, Index, InitialValue, LookupGlobal, Parent, Style, Update, Validate Rules are placed into logical Groups, usually by Rule type, but sometimes by Object or Component functionality Rules have a useful description Target Paths are fully-qualified when possible to include the parent Object or Screen Set, avoiding “Current” as a context Globals are always used instead of hard-coded text constants Comments are embedded where appropriate in all Rules to document functionality Commonly used routines are broken into Sub-Rules, rather than duplicating the functionality in parent rules redundantly Rules are International localization friendly, always using Globals for text that will be presented to the user Parent rules list the compound Properties separated by NEWLINEs in child to parent order Use groups. Agentry explicitly provides groups for most of the following kinds of rules: o Action rules o Enable Rules o Evaluation Rules o Execution Rules o Find Rules o Format Rules o Hidden Rules o Include Rules o Image Rules o Index Rules o InitialValue Rules o Parent Rules o Style Rules o Update Rules o Validation Rules If a Rule Group does not exist by default, add it yourself Providing consistent names for each of these types of Rules will make clear their usage when seen out of context. Adding a Group name will group them in the Rule Editor Context Menus and make it easier to find them in a long list of rules when you need them for a given Editor task Rules should begin with a Verb, describing the function of the Rule. These Verbs are usually the same as the Group the Rule belongs to, but this is not always the case o
Determine (Action, Decide) Used to dynamically pick the Action for a Sub-Action Step Some actions contain multiple sub-action steps that will only execute under certain conditions. Some Actions branch to different sub-actions via rule: 18
Configuration Practices for Agentry Based Mobile App
Type
Naming convention syntax
Examples
2 possible Determine{Action1 Name}Or{Action2 Name} DetermineStartMaterialRequestOrWarnLocked branches (ie – do “this or that” More than 2 branches
Determine{Action1 Name}If{True Condition}
DetermineStartWorkorderIfWorkorderCanBeStarted
o
Enable Enable Rule for Actions, Screens in a Screen Set, Fields on a Screen Recommended Syntax: EnableXXX ShowXXX
Usage - to enable/disable or hide/show a UI element
Type
Naming convention syntax
Examples
Enable a UI item
Enable{UI Element}[{UI element type}]
EnableStockroom EnableBinnumEdit
Show a UI item
Show{UI Element}{UI element type}
ShowPartsList
o
Type All
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
Naming convention syntax Eval|Calc{expression}
Examples CalcTotalWorkorders EvalFirstDayofTheWeek
o
Type All
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 it reusable and not necessarily tied to a single Action Naming convention syntax Examples Execute{If|When}{condition} ExecuteIfWorkorderDoesNotExist
o
Type All
Find (Search) Used as a “Find First Object Where” Rule to search a Collection for a specific Object based on logic Naming convention syntax Examples {Find|Search}{Object Name}{condition}
FindNotificationMatchingWONum FindComponentMatchingDeletedTask
o
Type All
Type Missing
Format (Current) Used to format a string for display on a List Screen, Column Header, Caption Header, Field Label, Button, Popup Message or Update Rule Naming convention syntax Examples Format{Expression}
FormatWorkorderDetailPane FormatPartsListHeader FormatTotalWorkHours
Naming convention syntax
Examples
Format{property}IsRequired{Warning|Err FormatLotnumIsRequiredWarning
19
Configuration Practices for Agentry Based Mobile App
Type
Naming convention syntax
Examples
required field
or|Prompt|Message}
FormatIdIsRequiredMessage
Field value is out of bounds
Format{property}{operator}{Value}{Warn FormatQtyAcceptedLessThanZeroError ing|Error|Prompt|Message} FormatQtyRejectedGreaterThan100KWarning
Field Format{condition}{Warning|Error|Prompt FormatOnly1RotatablePartCanBeAcceptedErr value not |Message} or allowed for current state
o
Type All
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 the conditions required for hiding, not the Field being hidden
Naming convention syntax
Examples
Hide[FieldName][If|When{Condition}] HideEqnum HideWhenEqnumIsNotNull
o o
Type All
Highlight See Style below Image Used to dynamically set the Image to be used for a Screen List Column or Button Control
Naming convention syntax
Examples
Image{Object}{Further desc} ImageWorkOrderStatus ImageAddressCloseButton
o
Type
Include Used to include Collection Objects for a Sub-Action Looping Step, List Tile View, List View, etc… Naming convention syntax
Examples
State
Include{When}{state}
IncludeWhenOrgIDIsNotNull
Condition
Include{If}{condition}
IncludeIfLocationEqualsStoreRoom
o
Type All
Naming convention syntax Index{Property}{Further desc}
o
Type All
Index Used to dynamically set the Index to be used for a Complex Table Screen Control Examples IndexEquipmentTileEdit IndexFLOC
InitialValue Used to set the initial state of a Transaction Property before or after data entry
Naming convention syntax InitialValue{property}
Examples InitialValueLocation
20
Configuration Practices for Agentry Based Mobile App
Type
Naming convention syntax
o
Type All
Naming convention syntax o
Type
Type All
Naming convention syntax
Examples ParentEqnum ParentCodeGroupForPart
Style (Highlight) Used to dynamically provide UI style formatting
Naming convention syntax Style{UI Element}{extra desc}
o
Type
Examples LookupGlobalNotifType LookupGlobalWOPriority
Parent Used to determine the Index Parent seed value for a child Complex Table Screen Field or Complex Table Looping Sub-Action The name should describe the child Screen Field we are looking up the Parent for. An optional suffix for clarification is acceptable: e.g., ParentEquipmentForNotification
Parent{Screen Field}{extra desc}
o
Simple Update
LookupGlobal Used to look up a Data Table Global value in the dtApplicationConfig Table dtApplicationConfig should act as a repository for backend related Globals that affect client or java functionality. We currently populate this table via a java routine in SMART WM for SAP and the Customer Service Component. The data comes from the SAP Config Panel that is part of the SAP architecture. For example, we maintain the current Work order Assignment Type in Wo.AssignmentType. We also keep the default Notification Type in Notif.Type. This way the values can be modified by an administrator via the SAP web interface, rather than needing to change Globals in the Agentry Eclipse Editor. The Client then uses these LookupGlobal Rules to access the values and make logic decisions
LookupGlobal{Global Name}
All
Examples
Examples StyleHighlightToday StyleHeaderLabelCoffee StyleScreenStandard
Update Used on Screen Fields to override the mapped Object/Transaction value and instead display formatted data
Naming convention syntax Update{property}
Examples InitialValueLocation
Update Update{property}When|If{Condition} UpdateTotalQtyWhenBackorderGreaterThanZero given a condition or state
o
Validate Used in Transaction Validation Rules to pop Warnings/Errors according to business logic Recommended Syntax: ValidateXXX 21
Configuration Practices for Agentry Based Mobile App
Usage - to validate a transaction Create a name that describes the element you are trying to validate
Type
Naming convention syntax
Examples
Test required field has a value
Validate{property}
ValidateLotnum
Test Field value id within range
Validate{property}{condition}
ValidateQtyGreaterThan1
Groups
•
•
Rules should be placed into Groups matching their type so they can logically and easily be located o Enable o InitialValue o Update Another alternative is to apply Groups according to a piece of functionality (Stock, Transfer, etc…), or use both techniques at once: o StockEnable o TransferInitialValue o 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 multiple Rules. 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 the logic when viewing an old rule again months or years in the future:
22
Configuration Practices for Agentry Based Mobile App
Using the “Current Property” context should be avoided if possible. Always provide the fullyqualified Property name in the Rule, unless required to do otherwise. This is easier to read and does not confuse Agentry Unless specifically trying to write a specialized generic rule that will be used in multiple spots throughout 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 certain circumstances, 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 an Update 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. Do not hard-code these into rules with string Constants, as they cannot be easily identified at first glance. This also allows for internationalization of a product: o Application.EmptyString o Application.BlankSpace o Text.TrueValue o Text.FalseValue Break commonly used routines into Sub-Rules, rather than repeating the code redundantly in parent Rules:
When writing rules that will be used for displaying text to the user, do not hard-code the English text 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 task to track down the offending rules. Instead, create Globals that can be easily modified for international usage. These should be placed into a common group like “Text”. These Rules include: o Validation Message o 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 NEWLINE character. Order the properties top down starting with the lowest child in the hierarchy. In the following 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. This means we must supply 2 parent values in the Rule, starting with the child (codeGroupByCatalog) and finishing with the parent (catalog):
23
Configuration Practices for Agentry Based Mobile App
Parent Rules are also used to seed Index values when looping over a Complex Table in a SubAction Step, but these Rules are set for each index individually. This means that compound statements are not necessary, just one individual value per Rule
24
Configuration Practices for Agentry Based Mobile App
SECTION 6: NAMING CONVENTIONS FOR TRANSACTIONS Transactions
o
o
Properties o Use {Verb}{Object} syntax o 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 necessary o Key is assigned “Before Data Entry” when possible o Display Name has been adjusted to be descriptive Merging o 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 verbs o Add Use when adding a new object o Clear Use the verb “Clear” for Delete Transactions that do not run any back-end Update 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 Object o 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 the burden 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: TaskAddNotes o If adding a Component to a new WorkOrder Object: ComponentAddForNewWorkOrder
• • •
Type
Naming convention syntax
Interaction with {Object}{Verb} the user via screen or message/validation
Examples PartAdd PartIssue POLineItemEdit WorkorderDelete
25
Configuration Practices for Agentry Based Mobile App
Type
Naming convention syntax
Examples
popup Auto (Silent) without user interaction
{Object}{Verb}Auto[additional description]
Delete Transaction {Object}Clear[Auto] with no back-end update steps
WorkorderDeleteAuto AddressAddAuto PointAddAutoFromRouteCT WorkOrderClearAuto AddressClear
Properties
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 accomplished by setting the Initial Value for the object property to “Rule Before data Entry” and running a rule similar to:
The above rule combines the string “LOCAL_” with a millisecond representation of the current system time, yielding a unique value on this device. This value if often replaced with a real back-end value upon posting to another system such as Maximo or SAP, but it does its job for us locally until that time o Using “Rule Before data Entry” ensures that this local ID is available to other transaction and 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 and identifiable where needed. The Property name is defaulted into this field, but this is most likely a code variable name that won’t make sense when displayed to a technician. Agentry will use this text to display for validation errors concerning field length or allowable numeric limits o
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 easily cause a merge to fail by changing a property type in either transaction, even if they match
SECTION 7: NAMING CONVENTIONS FOR FETCHES AND READSTEPS 1. Use {Verb}{CollectionName} syntax 2. In Agentry 3.1.2 and above the Editor will provide suggested names.
26
Configuration Practices for Agentry Based Mobile App
Type
Naming convention syntax
Examples
Fetch
{Fetch|Get}{Object}
FetchWorkorders GetWorkorders
Read Step
{Fetch|Get}{Object} {Fetch|Get}{Object}For{ParentObject}
GetParts GetPartsForWorkorder
27
Configuration Practices for Agentry Based Mobile App
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 o o o o
Java Step names should generally match the Transaction or Fetch name calling them with a “Steplet” suffix Java steps should be created using the New or Existing Source Type Read Steps should not be necessary using the Java Backend SQL and XML Step Names should generally match the Transaction or Fetch name calling them. Read Steps should describe the Collection being fetched under the Parent Object: e.g., GetPartsForWorkOrder Groups are always assigned and consistently match the related Object or functionality
This will make the steps more easily readable by a human editor who can quickly see what the back end process will accomplish without needed to click through to another screen. It will also make debugging easier since 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 a database table (Insert, Update, Delete, Exec, etc) and the affected table name. It may optionally include extra descriptive information at the end of the name Type
Naming convention syntax
Examples
SQL Scripts
{SqlScriptName}
UpdatePOLineItem UpdateMatRecTransPOLineItem UpdateInvBalancesPO UpdateInvLotAutokey InsertInvLot InsertMatUseTransDirectIssue
Other external Process
{ProcessDescription}
SaveWorkOrderFileToDisk PrintWorkorderStatusReport EmailWorkorderStatusReport
28
Configuration Practices for Agentry Based Mobile App
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 Transaction Step 2 Transaction Step 3 Apply Step 4 Transaction Step 5 Apply Step 6 Transmit It is much more user friendly to describe what Step1 through Step 6 are actually doing so that a designer does not have to click on a step just to see its details Step Name
Step Type
FinishMR PrintLabel Apply DeleteMR Apply2 Transmit
Transaction Transaction Apply Transaction Apply Transmit
As you can see in the second example, a designer can glance down the step name column and understand what the action is doing. Recommendations by Step Type Step Type
Use
Apply Exit Application Message Navigation Print Report SubAction Transaction
Apply{n} Exit Message Caption Screen Set Name Print{ReportName} Action Name Transaction Name
Globals A global definition defines a constant value, including data type, for the application. This value can be referenced throughout the application, both by the attributes of other definition types and for use in synchronization components. A global value cannot be changed on the Client at run-time but can be overridden during synchronization. A global is a constant that is set in the application level in the Agentry editor. You set the Global value in one place and then reference the global name wherever you need to use that value. This provides 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 be adjusted, rather than it being necessary to correct many separate definitions where this is used to enable or disable functionality. For example, all of our Mobile Products have many features that can be turned on or off or altered by changing the value of a global. In work manager good examples would be enabling or disabling parts by setting the value true or false or adding additional statuses to the status list by adding them to the global. 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 29
Configuration Practices for Agentry Based Mobile App
o o o o
International Localization strings are in the “Text” Group, or a Group matching their functionality or Object Do not create a Global Group with the same name as an Object. Backend Flunky resolution conflicts with this. Use an abbreviation or derivation when creating an Object’s Group Put boundary limit Globals into the Lngth Group (Length is a reserved word) 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 the application designer but also the end user and system administrator. Globals are used for: o Controlling whether certain functionality is enabled or not o Making an application international by changing the written language o Helping enforce boundary limits during data entry o Storing hard-coded constant values like: Statuses Error/Warning messages Backend specific codes o 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 be adjusted, rather than it being necessary to correct many separate definition points o Lookups in Java code
Naming
Globals should be named using Camel Case/Initial Capitalization: o BuildingMaxLength o PhoneTooLargeMessage
Name Globals so that their purpose can be easily identified, avoiding abbreviations: o FaxTooLargeMessage is good, FaxMsg is bad o ActivityCatalog is good, ActivCat is bad o WorkOrderFetch is good, WOFetch is bad
Type Enable Functionality Property Lengths Functional or module level grouping
Group Enable Lngth Module name
Naming convention syntax Function, module, screen, etc to be enabled Property name Property name
Examples Enable.EnterTimesheet Lngth.Notes WorkorderStatus.Received
Groups
Keeping Globals well organized can be difficult, but is very important. Not being organized will lead to duplicate unnecessary Globals across multiple Global Groups and can make finding existing Globals difficult Globals that are not specific to any particular functionality group but are generally used throughout 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. PhoneTooLargeMessage = “Phone and Extension Length cannot exceed” 30
Configuration Practices for Agentry Based Mobile App
o o
Text.TrueValue Text.FalseValue Text strings for internationalization can also alternately be placed in a Group matching a certain piece of functionality (Stock, CustomerService), or related to a particular Object (WorkOrder, Task). It is easier to find these though if kept together under 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.WorkOrderMinLen o Lngth.NotifDescMaxLen
Place Globals related to a particular object in a Group representing that Object name. Do not use an exact Object name, as that causes a conflict for the Agentry Flunky parser. This may involve using abbreviations: o WO.EnableStartWO = “True” o Notif.NewStatus = “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 Properties o 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 a code type. In this case, it is acceptable to create a single Global like PhoneNumberMinLength and re-use it for all phone number related Properties Initial Value data constants should come from Globals, not hand-entered text constants Screens o Create multiple Globals for Rows and Columns and use these on each Screen’s header UI.Win32RowsTransaction = “20” UI.PPCColumnsTransaction = “100” Screen Fields o 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 don’t always make sense to record as Globals, 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 a recurring label width, use a Global
31
Configuration Practices for Agentry Based Mobile App
Rules o
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 Client in a structured and searchable format. These records can be searched based on the field used to display the data to the user. A complex table can contain large amounts of data with records numbering in the thousands. 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 it searchable as well as create parent child relationships. Any tables created will affect both device memory and sync time. There is no magical way for reducing the download time, except by reducing the number of bytes 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 in your 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 Fields o 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 complex table fields crash some Win CE devices Set String Field lengths via a Global when possible. Maximo employs a data Dictionary that may change field lengths, so in our product, Globals have been incorporated and are overridden via backend query during transmit If possible, use a Number or Identifier as the key field to a Complex Table. These types are more 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 break standard functionality: o Details - CT search fails when display name and internal name are not the same on client upgraded from 5.1.26 o 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 two fields where Location is the Parent of Equipment, then Equipment must be shown as the Unique Index in the Editor. The Unique Index is the first Index added 32
Configuration Practices for Agentry Based Mobile App
Remember to clean up unused Indexes at some point. Add a reminder to the Index definition when you believe it is obsolete. Extra indexes waste transmit time and storage space on a device 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 fields containing a key and value. A data table is intended to contain a small number of records (less than 100) that may be displayed to uses in drop down lists, as well as other uses. There is no built-in search functionality to a 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
Images The Image definition type allows you to incorporate bitmap images into the application and to display those images 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 Agentry Editor also allows you to specify a mask color for the bitmaps, if desired. The bitmaps themselves are external to the definitions on the Editor and are referenced by the Image definition. They are copied published to the Agentry Server during a publish, and are then transferred to the Clients with the other application definitions. General
For images that don’t require a Mask color, add one anyway for a color that is not represented on the Image. Agentry does not properly display Images in certain places if a mask Color is not specified due to a bug: Details for #19174 – Toolbar and List Screen icon images unexpectedly mask out colors when no mask is specified When creating an Image to be used for a List Screen Column, the dimensions of each child Image in the master should be 16 by 16. Add new Child Images to the right, extending the width by 16 for each new child:
The above image shows 7 children for a Work Order Object, used to display on the status column in a list. The 8th 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 this master 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 zerobased numbering to display the correct image via Rule. In our case, we have 8 images, so 0 – 7
33
Configuration Practices for Agentry Based Mobile App
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 as actions, rules, steps, etc... The purpose of a tag is to identify all configurations that comprise a configuration. This allows you to do things such as identify all editor configurations needed to create new functionality and export these configurations 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 Customer Service, 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 the Properties 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 contain one tag AND another. AND would be useful to find the definitions that are accidentally tagged and need to be cleaned up. This request has been made: Details for #31956 – Agentry Search by 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 can include 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 to an individual field or button on a single detail screen, and everything in between. Furthermore, these styles can 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}
ButtonClean
FocusedButton
{FocusedButton}{StyleName}
FocusedButtonClean
DetailScreen
{DetailScreen}{StyleName}
DetailScreenClean
Field
{Field}{StyleName}
FieldClean
FocusedField
{FocusedField}{StyleName}
FocusedFieldClean
Hyperlink
{Hyperlink}{StyleName}
HyperlinkClean
ListScreen
{ListScreen}{StyleName}
ListScreenClean
HeaderLabel
{HeaderLabel}{StyleName}
HeaderLabelClean
ColumnLabel
{ColumnLabel}{StyleName}
ColumnLabelClean
Row
{Row}{StyleName}
RowClean
RowHyperlink
{RowHyperlink}{StyleName}
RowHyperlinkClean
AlternateRow
{AlternateRow}{StyleName}
AlternateRowClean
AlternateRowHyperlink
{AlternateRowHyperlink}{StyleNa AlternateRowHyperlinkClean me}
34
Configuration Practices for Agentry Based Mobile App
Type
Naming convention syntax
Examples
HighlightRow
{HighlightRow}{StyleName}
HighlightRowClean
HighlightRowHyperlink
{FocusedButton}{StyleName}
xClean
SelectedRow
{FocusedButton}{StyleName}
xClean
SelectRowHyperlink
{FocusedButton}{StyleName}
xClean
DetailPane
{FocusedButton}{StyleName}
xClean
SECTION 13: NAMING CONVENTIONS FOR JAVA CLASSES
Naming Type
Naming convention syntax
Examples
Steplet
{TransactionName|FetchName|PushName}{Steplet}
AddWorkorderSteplet GetWorkordersSteplet
Stephandler
{TransactionName|FetchName|PushName|CT|DT}{Stepha AddWorkorderStephandler ndler}
POJO
{ObjectName}
Workorder Item CATSRecord
BAPI (SAP Only)
{Transaction|Fetch|PushName|CT|DT}{BAPI}
AddWorkorderBAPI
Complex Tables
CT{tablename}
CTParts
Data 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
35
Configuration Practices for Agentry Based Mobile App
36
Configuration Practices for Agentry Based Mobile App
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 general recommendations and principles that should help to define your own companywide naming conventions. As every company is different in structure and size it is important to gauge what level of granularity is required when naming objects in your landscape. When enhancing Mobile application common question asked by customers are what naming conventions to be followed. Since all mobile development objects are delivered under /SYCLO/ namespace it is better to go with follow of base product naming conventions but again it is left to customers to decided what is good for them. Well defined naming conventions should help to standardize and facilitate the implementation of your Mobile Integration Scenarios.
Namespace All Syclo SAP Add-On Objects are developed under namespace ‘/SYCLO/’. Whenever you’re modifying 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 packages are defined for the ‘/SYCLO/’ namespace: /SYCLO/ - Main package used to grouping multiple packages. No object can be assigned directly 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 you’re trying to enhance any of the objects belonging to above packages. Create Z package hierarchy similar to product package hierarchy.
Classes Overall design paradigm for the Syclo SAP Add-On Component is based on ABAP OO; therefore ABAP Object classes are used extensively. Whenever possible, ABAP Object class is the preferred way of encapsulating 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 fetch or transaction update, for a specific business object. The following naming pattern should be followed: ‘/SYCLO/CL_’ + pppp + ‘_’ + xx…x + ‘_DO’
37
Configuration Practices for Agentry Based Mobile App
Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the business object. Maximum length of an ABAP Object class name is 30 characters.
Exchange Object Class Handler These classes handle change detection logic and exchange persistence layer update for a specific SAP business object. The following naming pattern should be followed: ‘/SYCLO/CL_’ + pppp + ‘_’ + xxxxxx + ‘_EX_HNDLR’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xxxxxx’ represents any combination of alphanumeric characters, which should be indicative of the business object. Typically ‘xxxxxx’ is the first 5 or 6 characters of the exchange table name after removing ‘/SYCLO/’ prefix. For example, if the exchange table is ‘/SYCLO/AUFNR_EX’, then ‘xxxxxx’ is set to ‘AUFNR’. Maximum length of an ABAP Object class name is 30 characters.
Persistent Classes As a rule of thumb, persistent classes should be used to update tables created for Syclo SAP Add-On Component, with the exception of exchange table update, which can be handled by Exchange Object Class Handler base class. Each persistent class handles update for a single transparent table. The following naming pattern should be followed: ‘/SYCLO/CL_’ + pppp + ‘_PERS_’ + xx..x ‘/SYCLO/CA_’ + pppp + ‘_PERS_’ + xx..x - Generated automatically by class builder ‘/SYCLO/CB_’ + pppp + ‘_PERS_’ + xx..x - Generated automatically by class builder Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the table being updated. Typically ‘xx…’ is the first 9 characters of the name of the table being updated after removing ‘/SYCLO/’ prefix. For example, if the table is ‘/SYCLO/DO001’, then ‘xx…x’ is set to ‘DO001’. Maximum length of an ABAP Object class name is 30 characters.
Exception Classes Exception class is the counterpart of message class in ABAP OO, and is the preferred method for runtime exception handling. The following naming pattern should be followed: ‘/SYCLO/CX_’ + pppp + ‘_’ + xx…x’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the exception. Exception class is a special category of ABAP OO class, maximum length of exception class name is 30 characters.
Business Object Model Class Data for a typical SAP business object are stored in multiple tables. As each persistent class only handles update for a single transparent table, we should always create and use a Business Object Model class to encapsulate the business logic involved to update data for a SAP business object. The following naming pattern should be followed: ‘/SYCLO/CL_’ + pppp + ‘_BOM_’ + xx…x’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the business object. Maximum length of an ABAP Object class name is 30 characters.
38
Configuration Practices for Agentry Based Mobile App
Web Dynpro Assistant Class Web Dynpro assistant classes should be used for any Web Dynpro applications developed in order to encapsulate backend business logic or database access. The following naming pattern should be followed: ‘/SYCLO/CL_’ + pppp + ‘_WD_’ + xx…x’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ 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.
BAdI Implementation Class BAdI implementation classes are created to implement enhancement to standard SAP using standard BAdI definition. The following naming pattern should be followed: ‘/SYCLO/CL_’ + pppp + ‘xx…x’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of BAdI being implemented. Typically we should use the BAdI definition name for the value of ‘xx…x’. Maximum length of an ABAP Object class name is 30 characters.
Interface ABAP Object Interface is one of the foundations for polymorphism in ABAP OO paradigm, and therefore are used extensively by Syclo SAP Add-On Component. All ABAP OO interfaces developed should follow the generic naming pattern: ‘/SYCLO/IF_’ + ‘pppp’ + ‘xx…x’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the function of the interface. Maximum length of an ABAP Object interface name is 30 characters.
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 or update tasks. The following naming pattern should be followed:
BAPI Wrapper Function Group These function groups contain BAPI Wrappers for integration with Agentry platform via RFC protocol and Java Connector. Each function group should contain BAPI Wrappers for a specific 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 task during SAP business object update. Update task can guarantee data integrity of LUW during
39
Configuration Practices for Agentry Based Mobile App
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 as ‘CO’, ‘HR’, ‘MM’, or ‘PM’. ‘xx…x’ 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 and update task. The general guideline is to use function module only as a skeleton, and encapsulate business logic 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 point between Agentry platform and SAP. The following naming pattern should be followed: ‘/SYCLO/’ + ‘pppp’ + ‘_’ + ‘xx…x’ + ‘mmm’
Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’. ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the business object the BAPI Wrapper that set the first 2 character of ‘xx…x’ 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, ‘CRT’ for 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. The following naming pattern should be followed: ‘/SYCLO/’ + ‘pppp’ + ‘xx…x’ + ‘_PROG’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative 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 files plays a smaller role. When needed, include file should have the following generic naming pattern: ‘/SYCLO/’ + ‘pppp’ + ‘xx…x’ + ‘_INCL’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative 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 directly inside the implementation. The following naming convention should be followed:
40
Configuration Practices for Agentry Based Mobile App
‘/SYCLO/’ + ‘pppp’ + ‘_EFI_’ + ‘xx…x’ + ‘_INCL’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the function of the enhancement implementation. Maximum length of an ABAP include file name is 30 characters.
BAPI Wrapper Template Include Syclo SAP Add-On Integration Framework provides a standard BAPI Wrapper include template, which should be used by all BAPI Wrapper by default. ‘/SYCLO/CORE_BAPI_TEMPLATE_INCL’
Web Dynpro Component Web Dynpro is the standard UI for Syclo SAP Add-On Component. The following naming pattern should be followed: ‘/SYCLO/’ + ‘pppp’ + ‘xx…x’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the function of the web dynpro component. Maximum length of a Web Dynpro Component name is 25 characters.
Enhancement Implementation Enhancement framework is the new concept introduced in Netweaver 7.0 based SAP systems. The framework provides support for centrally manage all enhancements to SAP system. Under enhancement framework, enhancement spot identifies the location where enhancement is possible, and enhancement implementation contains the actual code base with the enhancement logic. There are two categories of enhancement implementation: composite enhancement implementation, and single enhancement implementation.
Composite enhancement implementation Composite enhancement implementations have been pre-defined for Syclo SAP Add-On Component, and follow the naming pattern below: ‘/SYCLO/’ + ‘pppp’ This is the top level composite enhancement implementation, where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’. ‘/SYCLO/’ + ‘pppp’ + ‘_’ + ‘aaaa’
This is the level 2 composite enhancement implementation, where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘aaaa’ identify the functionality category of the enhancement implementation. At this time, the only valid value is ‘EXCH’ for Exchange Persistency Layer related enhancement
Single enhancement implementation
41
Configuration Practices for Agentry Based Mobile App
This is the lowest level implementation that actually contains the enhancement logic. The below naming pattern should be followed: ‘/SYCLO/’ + ‘pppp’ + ‘_’ + ‘aa…a’ + ‘xx…x’ Where ‘pppp’ represents the corresponding workbench package name without ‘/SYCLO/’ prefix, such as ‘CO’, ‘HR’, ‘MM’, or ‘PM’; ‘aa…a’ is the abbreviation identify the types of SAP method where the implementation has been created, for example, ‘BTE’ for business transaction event method, ‘BADI’ for BAdI event, ‘UPD’ for update task; ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the function of the enhancement implementation. Maximum length of an enhancement implementation name is 40 characters.
Tables Transparent tables created for Syclo SAP Add-On Component should follow the below naming pattern: ‘/SYCLO/’ + ‘xx…x’ Where ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the function of the table if possible. Maximum length of an ABAP program name is 16 characters. Due to the length limitation of table name, abbreviation is often used. Common scenarios when transparent tables are created in Syclo SAP Add-On Component:
Exchange Table Exchange tables are components of Exchange Persistence Layer of the Syclo SAP Add-On Component. They contain change detection data for master data or transaction data in SAP that related to mobile applications. The following naming convention should be followed: ‘/SYCLO/’ + ‘xx…x’ + ‘_EX’ Where ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the function of the exchange table, typically set to the technical field name for the business object key. Maximum length of a transparent table name is 16 characters.
Views Data dictionary view object allows us to define alternative view of a transparent table (projection view), combine multiple tables via condition (database view), maintain fields from multiple tables (maintenance view), or allows search help from multiple tables (help view). The following naming pattern should be followed: ‘/SYCLO/’ + ‘xx…x’ + ‘_V’ Where ‘xx…x’ represents any combination of alphanumeric characters, which should be indicative of the purpose of the view. Maximum length of view is 16 characters.
42
Configuration Practices for Agentry Based Mobile App
43
www.sap.com
© 2013 SAP AG. All rights reserved. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, SAP HANA, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business Objects is an SAP company. Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL Anywhere, and other Sybase products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Sybase Inc. Sybase is an SAP company. Crossgate, m@gic EDDY, B2B 360°, and B2B 360° Services are registered trademarks of Crossgate AG in Germany and other countries. Crossgate is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.
View more...
Comments
