Advanced.embedded.customization

Epicor 9 Advanced Embedded Customization Course 9.04.507

Disclaimer This document is for informational purposes only and is subject to change without notice. This document and its contents, including the viewpoints, dates and functional content expressed herein are believed to be accurate as of its date of publication. However, Epicor Software Corporation makes no guarantee, representations or warranties with regard to the enclosed information and specifically disclaims any applicable implied warranties, such as fitness for a particular purpose, merchantability, satisfactory quality or reasonable skill and care. As each user of Epicor software is likely to be unique in their requirements in the use of such software and their business processes, users of this document are always advised to discuss the content of this document with their Epicor account manager. All information contained herein is subject to change without notice and changes to this document since printing and other important information about the software product are made or published in release notes, and you are urged to obtain the current release notes for the software product. We welcome user comments and reserve the right to revise this publication and/or make improvements or changes to the products or programs described in this publication at any time, without notice. The usage of any Epicor software shall be pursuant to an Epicor end user license agreement and the performance of any consulting services by Epicor personnel shall be pursuant to Epicor's standard services terms and conditions. Usage of the solution(s) described in this document with other Epicor software or third party products may require the purchase of licenses for such other products. Where any software is expressed to be compliant with local laws or requirements in this document, such compliance is not a warranty and is based solely on Epicor's current understanding of such laws and requirements. All laws and requirements are subject to varying interpretations as well as to change and accordingly Epicor cannot guarantee that the software will be compliant and up to date with such changes. All statements of platform and product compatibility in this document shall be considered individually in relation to the products referred to in the relevant statement, i.e., where any Epicor software is stated to be compatible with one product and also stated to be compatible with another product, it should not be interpreted that such Epicor software is compatible with both of the products running at the same time on the same platform or environment. Additionally platform or product compatibility may require the application of Epicor or third-party updates, patches and/or service packs and Epicor has no responsibility for compatibility issues which may be caused by updates, patches and/or service packs released by third parties after the date of publication of this document. Epicor® is a registered trademark and/or trademark of Epicor Software Corporation in the United States, certain other countries and/or the EU. All other trademarks mentioned are the property of their respective owners. Copyright © Epicor Software Corporation 2010. All rights reserved. No part of this publication may be reproduced in any form without the prior written consent of Epicor Software Corporation.

ED83790 90521-900-9205-583507 9.04.507 Revision: November 11, 2010

TOC | 3

Contents Advanced Embedded Customization Course......................................................................5 Before You Begin....................................................................................................................6 Audience.........................................................................................................................................................6 Prerequisites...................................................................................................................................................6 Environment Setup.........................................................................................................................................7 Workshop Constraints.............................................................................................................................7

Customization Overview........................................................................................................9 The Script Editor Feature..............................................................................................................................10 Script Editor Context Menu...........................................................................................................................11 Event Handlers.............................................................................................................................................11 Workshop - Review the Script Editor............................................................................................................14 Launch a Customization........................................................................................................................14 Review the Default Script......................................................................................................................15 Identify Scripting Regions......................................................................................................................16 Use the Test Code Feature....................................................................................................................17

The Customization Tool Set.................................................................................................18 ToolBox.........................................................................................................................................................18 Workshop - Add the PictureBox Control................................................................................................19 Assembly Reference Manager.....................................................................................................................22 Workshop - Create Assembly References.............................................................................................24 Workshop - Automatically Generate the Assembly Reference..............................................................25 Custom Object Explorer...............................................................................................................................25 Workshop - Review the Custom Object Explorer..................................................................................27 Options Menu...............................................................................................................................................31 Custom XML Editor......................................................................................................................................32 Data Tools.....................................................................................................................................................32

Custom Code Wizards.........................................................................................................33 Workshop - Use the Business Logic Assembly Reference Wizard...............................................................34 Workshop - Use the Extended Property Wizard...........................................................................................35 Workshop - Use the Add User Defined Table as Child Wizard.....................................................................37 Test the User-Defined Wizard................................................................................................................37 Workshop - Use the Business Logic Method Call Wizard............................................................................39 Workshop - Use the Business Logic Wizard.........................................................................................40 Author a Routine....................................................................................................................................41 Add an EpiNotificationEvent..................................................................................................................42

Code Examples....................................................................................................................43 UI Controls and Form Events.......................................................................................................................43 Workshop - Work with Embedded Dashboards.....................................................................................44 Modify Infragistics Components....................................................................................................................46 Modifying Sub Processes.............................................................................................................................46

Epicor 9 | 9.04.507

4 | Advanced Embedded Customization Course Workshop - Modify Sub Processes.......................................................................................................48

Tracing Options....................................................................................................................52 Workshop - Create the Tracing Log..............................................................................................................53 Configure and Start a Trace Log............................................................................................................53 Create an XML Trace Report.................................................................................................................53 Disable Tracing .....................................................................................................................................54

Customization Maintenance................................................................................................55 Workshop - Use Customization/Personalization Maintenance.....................................................................56 Export a Customization ........................................................................................................................56 Import a Customization File...................................................................................................................56 Review and Verify the Imported Customization File..............................................................................57

Conclusion............................................................................................................................58

Epicor Software

Advanced Embedded Customization Course | 5

Advanced Embedded Customization Course This course provides customization techniques that reach beyond the basics of text boxes and grids. It explores how to further customize a program through its code using the C# or VB.NET programming languages. It also introduces several wizards to create custom code without requiring knowledge of the programming languages. Embedded customization is the ability to modify aspects of your interface and application functionality. This includes the ability to model changes, track changes, pilot changes, and deploy and rollout changes to the user community. Upon successful completion of this course, you will be able to: •

Differentiate between personalization and customization (or server-side) tools.

•

Locate a common business object's methods and properties in the Object Explorer.

•

Identify the essential toolset available to assist in creating embedded customizations and custom code.

•

Create a simple routine and assign it to the appropriate event handler using the Form Event Wizard.

•

Generate a sub-process customization and identify a process call for that sub-process.

•

Use the Script Editor to evaluate the parts of a UI script and understand the approrpiate placement for customized code entry.

•

Understand common data objects and methods you need to complete typical customizations.

•

Use the Sheet Wizard to embed a dashboard into a form.

•

Explore the business objects referenced by a program through Tracing Options.

•

Use Customization Maintenance to verify the controls and code associated with a specific customization.

Epicor 9 | 9.04.507

6 | Advanced Embedded Customization Course

Before You Begin Read this topic for information you should know in order to successfully complete this course.

Audience Specific audiences will benefit from this course. •

System Administrator

•

IT/Technical Staff

Prerequisites In order to complete the workshops in this course, all necessary modules must be licensed and operating in your training environment. For more information on the modules available, contact you Epicor Customer Account Manager [email protected]. It is also important that you understand the prerequisite knowledge contained in other valuable courses. •

Navigation, Personalization, and Advanced Personalization Course - In this course, you will discover how to navigate throughout the system, create personalizations to customize your system experience and learn how to import and export these personalizations so that others in your work team can use them.

•

Embedded Customization Course - This course covers all aspects of the customization model which is built into the framework for Epicor 9 and beyond. Users may personalize their environment if given the authority. This course goes beyond the personalization aspects to allow system administrators to deploy standard customizations based on their specific business requirements. This includes adding and removing data elements, modifying component properties, adding VBScript code points to run before and after data field modifications, and much more.

•

Database Concepts Course - This course reviews the table and field name identification process using Field Help, Customization Tools, and Data Dictionary Viewer functionality. It also describes table linking procedures and requirements, Dataset Relationships Tracker features, and join type definition and specification.

•

Some of the material in this course addresses object oriented programming conventions and specifically, VB.Net and C# programming language syntax to author code. The following can be useful as ancillary study materials: •

A general reference or text on Object Oriented concepts

•

A language reference for Visual Basic, Visual Basic .NET, or C#

•

Previous coursework in .NET framework with a concentration in namespaces

•

Additional information from Microsoft® Developer's Network

•

The Epicor ICE User Experience and Customization Guide available from any Customer Account Manager

Epicor Software

Before You Begin | 7

Environment Setup The environment setup steps and potential workshop constraints must be reviewed in order to successfully complete the workshops in this course. Your Epicor 9 training environment, in which the Epicor 9 demonstration database is found, enables you to experience Epicor 9 functionality in action but does not affect data in your live, production environment. The following steps must be taken to successfully complete the workshops in this course. 1.

Verify the following or ask your Epicor 9 system administrator to verify for you: •

Your Epicor 9 training icon (or web address if you are using Epicor Web Access) points to your Epicor 9 training environment with the Epicor 9 demonstration database installed. Do not complete the course workshops in your live, production environment. Note It is recommended that multiple Epicor 9 demonstration databases are installed. Contact Support or Systems Consulting for billable assistance.

•

The Epicor 9 demonstration database is at the same service pack and patch as the Epicor 9 application. Epicor's education team updates the Epicor 9 demonstration database for each service pack and patch. If your Epicor 9 system administrator upgrades your Epicor 9 application to a new service pack or patch, he or she must also download the corresponding Epicor 9 demonstration database from EPICweb > Support > Epicor 9 > Downloads and install it. If this is not performed, unexpected results can occur when completing the course workshops.

•

Your Epicor 9 system administrator restored (refreshed) the Epicor 9 demonstration database prior to starting this course. The Epicor 9 demonstration database comes standard with parts, customers, sales orders, and so on, already defined. If the Epicor 9 demonstration database is shared with multiple users (that is, the database is located on a server and users access the same data, much like your live, production environment) and is not periodically refreshed, unexpected results can occur. For example, if a course workshop requires you to ship a sales order that came standard in the Epicor 9 demonstration database, but a different user already completed this workshop and the Epicor 9 demonstration database was not restored (refreshed), then you will not be able to ship the sales order. Epicor's education team has written the course workshops to minimize situations like this from occurring, but Epicor cannot prevent users from manipulating the data in your installation of the Epicor 9 demonstration database.

2.

Log in to the training environment using the credentials manager/manager. If you are logged into your training environment as a different user, from the Options menu, select Change User.

3.

From the Main menu, select the company Epicor USA (EPIC03).

4.

From the Main menu, select the Main Plant.

Workshop Constraints Below is a list of workshops in this course that can be performed only once in each instance of a restored (refreshed) database. Where applicable, a detailed explanation of the workshop constraints is documented in the workshop itself. •

Workshop - Create the Tracing Log

For the purpose of this course, it is important to follow all of the steps provided in each workshop. While this course provides education on the customizing functionality, it is essential that any activated customizations in the course

Epicor 9 | 9.04.507

8 | Advanced Embedded Customization Course are deactivated or removed. Removing these customizations ensures the appropriate default training environment is available.

Epicor Software

Customization Overview | 9

Customization Overview There are five layers to the Epicor Customization Model but only two are available for modification: personalization and customization. These layers are considered the User Interface (UI) and modifications to these layers affect how screens display. The difference between the two UI layers is that Personalization follows the User ID and Customization follows the company and the module. Customization allows you to change the UI permanently and roll it out to the entire company. Use Business Process Management (BPM) to incorporate modifications to the Business Logic to enhance changes to the UI. This tool allows you to create custom routines you can execute before or after the execution of business objects used in a program. Selecting the Tool The Epicor application provides a number of powerful tools that assist in the customization of both the client side interface as well as the server logic that governs the use of the business objects accessed by each form. In addition, the modification can entail the consumption and use of information from systems outside the application. Selecting the appropriate tool to create the customization is perhaps the most crucial step in the modification process, because the tool carries with it both a series of benefits and constraints. In general, the rule of thumb when you select the appropriate tool set is to select Business Process Management (BPM) for server-side modifications that adjust or circumvent the established order and functionality of the business objects accessed by a particular form. Conversely, for modifications that require UI changes and the enforcement of other rules at the time of data entry or retrieval in the UI, Embedded Customization is most likely the best choice. Finally, retrieve, consume, and publish data from the manufacturing application to external applications, Service Connect can provide the most appropriate solution to build the workflow necessary to accommodate data transactions of this type. This course focuses on the embedded customization (EC) capability which applies solely to the ability to modify user interface components. EC modifications, which save to the server, affect only the client side display and logic. Example A common dilemma is often the need to make certain fields in the application mandatory that the application does not require as purchased. While this modification at first might make sense using EC, remember that the enforcemenet of data entry into a specific field on the UI ensures everyone required to enter data in the field. Any external applications (such as web services enabled forms) do not observe the client side modification. In this case, the tool of preference is Business Process Management. Business Process Management or Embedded Customization? The term advanced customization is perhaps too vague in scope. It implies an extension to any type of modification you can accomplish within the application that significantly impacts the way a business object might function. While this course exclusively focuses on the embedded customization tool set in the application, the Business Process Management (BPM) module allows the user to create custom routines. You can execute custom routines before, after, or in lieu of the execution of the business objects in the application. BPM employs method directives you can author within the application using the Progress® 4GL code and the BPM method directive wizard that assists you in setting up triggers for actions. For more information and training on the BPM functionality and server-side modifications that affect the business logic of the application, see the Business Process Management course.

Epicor 9 | 9.04.507

10 | Advanced Embedded Customization Course

The Script Editor Feature The Script Editor is a complete development environment. It includes tools that allow you to enter, format, and test code. You can enter code directly in the Script Editor or use the Customization Code Wizards. A form's original code displays along with code from any previously created customizations. Everything about the form displays within this tool. Use the Script Editor to make code level customizations to the current form. Below are key elements of the Script Editor: •

The Interface: When you open the Script Editor, you see the code for the current program. The interface explains how to get around inside the Editor.

•

The Context Menu: To help you create custom code, the Script Editor has a context menu that contains a variety of additional functions.

•

Script Editor Basic Code: All form scripts have default sections. These are explained in the following workshop.

•

Script Editor Event Handlers: An event handler is a special method you can use to run code at particular times.

Some useful methods are listed below. GetNativeControl Use this method to retrieve a reference to base control on the form. This method requires a string parameter controlGUID which is the unique identifier for the specific control. The following line of code demonstrates general coding conventions: Dim ctrl As Control = csm.GetNativeControlReference(“5483cdef-3049-4705-b597-28ae93bc7fdf”) The example below shows use of the method when casting to a specific control type: Dim eucSales As EpiUltraCombo = CType(csm.GetNativeControlReference(“5483cdef-3049-4705-b597-28ae93bc7fdf”), EpiUltraCombo) AddForeignKeyView Use this method to add an undatable ForeignKeyView to the EpiTransaction object. Once this method is called, the added ForeignKey is available for control binding. This method is used in conjunction with business logic adapters. Use of this method requires the following parameters: 1.

ViewName (String: This is the the Foreign Key View name and must be unique.

2.

dsData (DataSet): This is an empty DataSet of the Foreign Key Views Type.

3.

TableName (String): This represents the table name that corresponds to the view in the DataSet.

The following lines of code demonstrate the use of this method: '// Add Adapters Table to List of Views '// This allows you to bind controls to the custom child view Dim dsData As DataSet = CType(ud01Adapter.UD01Data, DataSet) Dim fkvUD01 As ForeignKeyDataView = csm.AddForeignKeyView(“MyUD01View”, dsData, “UD01”) NotifyForeignKeyView Method Use this method to update a ForeignKeyView added by the AddForeignKeyView() method. This method notifies controls bound to the Foreign Key View that the data has changed. This method is almost always used in conjunction

Epicor Software

Customization Overview | 11 with business logic adapters. Use of this method requires the same parameters as the AddForeignKeyView method. The following lines of code demonstrate the use of this method: '// notify with updated data csm.NotifyForeignKeyView("UD01", CType(ud06Adapter.UD01Data, DataSet), "UD01")

Script Editor Context Menu To help you create custom code, the Script Editor has a context menu that contains various additional functions. Besides default standards like cut, copy, and paste, the context menu also has default commands that can help you both enter and keep custom code standard. Use these commands to perform actions like tab, comment, bookmark, and so on. You can access the right-click menu directly inside the Script Editor. The following sub-menus are included in the menu options: •

Edit Menu: This menu offers quick access to edit, cut, paste, and other editing tools.

•

File Menu: This menu allows you to quickly access the New, Open, Close, Save, and Save As commands to record your customization in stages. This way, if you have problems with a new version of custom code, you can always restore a previous version that works correctly.

•

Advanced Menu: This menu includes several options to assist you in the creation of custom code.

•

Bookmarks: Bookmarks set quick access points in a lengthy script.

•

Options Menu: This menu defines how the Script Editor displays custom code or how to establish the coding environment.

Event Handlers Event Handlers are special methods you can use to run code at particular times. Example An event handler is called when you open and close a UI APP, when certain events relative to the data occurs, or when a business logic call occurs. These methods "listen" for events fired by objects in the application. In addition, event handlers are extremely common methods you can use to establish active "listeners" for specific events. These objects (methods + data) are available to programs throughout the application using the custom coding engine and are passed to custom assembly when the UI opens. InitializeCustomCode() This is the first method called in custom Code Initialize module level variables. It can create custom EpiDataViews and add them to the transaction object. Note Wizards also put variable initializations and method calls in this method.

The InitializeCustomCode() handler does the following: •

It can initialize module level variables

•

It can create custom EpiDataViews and add them to the Transaction Object

•

The Form Event Wizard places variable code initializations and calls within this method

Epicor 9 | 9.04.507

12 | Advanced Embedded Customization Course The last method called in custom code is DestroyCustomCode(). It cleans up module level variables' Customization wizards such as the Rule Wizard. Both of these methods are generated automatically and appear in the Script Editor. The DestroyCustomCode() handler does the following: •

It cleans up any remaining module level variables

•

The Form Event Wizard places variable code initializations and calls within this method.

[ViewName]_BeforeRowChanges() Handles EpiDataView.EpiRowChangingEvent event This event handler is called when changing rows of a multi-row EpiDataView. It is not triggered when a new EpiDataView is loaded as this is triggered through the ListChanged event handler. It monitors changes in a row's data. If any data changes occur, the event runs. If an EpiDataView is loaded, this event handler does not run. [ViewName]_AfterRowChange() Handles EpiDataView.EpiRowChanged event This event handler is called after exiting the row is changed. It does not fire when a new row is added or only one row is present. This handler must be used in combination with ListChanged() and it does not run if you add a new row to the grid. [Table/ViewName]_BeforeFieldChange() Handles DataTable.ColumnChanging event This event handler is called before leaving a bound field. It can validate a specific field value and if not valid, the user can be prevented from leaving the control until a legitimate value is entered. To prevent users from leaving a field that is not validated, use the following code: VB Code: Throw New EpiUIException () When the Validation condition is not met C# Code: throw new EpiUIException (); When the Validation condition is not met [Table/ViewName]_AfterFieldChange() Hanldles DataTable.ColumnChanged event This event handler is called after leaving a bound control. It can perform a call to another adapter and fill in data (similar to validating a part and filling in a description). This event handler does the following: •

It can run a call to another adapter.

•

After it runs a call, it can then fill in data within the field.

[ViewName]_DataView_ListChanged() Handles DataView.Listchanged event This event handler is useful when only one row is present. It must be used in combination with AfterRowChanged(). Some UIs also have an AfterGetByID() method which can be used instead. This method is called frequently. This event handler does the following: •

This event can validate the entered value.

•

If the value is not valid, then you can prevent the user from leaving the field until a correct value is entered.

Epicor Software

Customization Overview | 13 Retrieve() This event handler is called when you click the Retrieve button on the toolbar. The Retrieve button is added to the toolbar if the EpiRetrieveToolName property is set for a panel. In the event handler code, args.ToolName is the value that is set. Use this event handler if the data should refresh with data from the database. [FormName]_Load() Called From End of EpiBaseForm_Load() This is used for events that fire during the UI Form_Load() but after the InitilizeCustomCode() method runs. [FormName]_Closing() Handles EpiBaseForm.Closing() This event handler is used to clean up module level variables. [ViewName]_EpiViewNotification() Handles This event runs the EpiDataView.EpiViewNotification event. It is triggered right after a dataView is loaded into a program. Essentially, this event signals the application to indicate data is ready for you to view and edit. It pre-populates default values on GetNew. Examples might unique ID generation in a UD table or default values generation. AfterGetByID Use this event handler to duplicate behavior. Customization Wizards do not generate code for this method. oTrans_[AdapterName]_BeforeAdapterMethod() This event handler runs just before an adapter runs. You can use it to validate data, check for required fields, and so on. This method can be canceled which causes the corresponding AfterAdapterMethod call to cancel as well. oTrans_[AdapterName]_AfterAdapterMethod() This event handler handles the oTrans_ordAdapter.AfterAdapterMethod. It activates just after an adapter is executed and performs the following: •

It populates default values into a form.

•

It updates an external business object.

•

It runs the code just after a business layer call completes.

Event Sequences Events execute in a specific order at start up or shutdown. Events for the Startup Sequence execute when the form launches in this order: 1.

InitializeCustomCode()

2.

[FormName]_Load()

Events for the Shutdown Sequence execute when the form closes in this order: 1.

[FormName]_Closing

2.

DestroyCustomCode()

Epicor 9 | 9.04.507

14 | Advanced Embedded Customization Course

Workshop - Review the Script Editor The Script Editor provides a text view of the custom code routine(s) used in a customization. If you use a Customization Wizard to create an event or row rule, that code appears in the Script Editor.You can enter the code directly in the Script Editor as required. The workshop assumes the Developer Mode is active and you are logged in with appropriate permissions to generate customizations. Each form has a default code shell that initially displays within this sheet. You can then add and edit this shell to create code level programs within your customization. This workshop is a tour of the Script Editor interface. The actual code and context menus are discussed in later workshops.

Launch a Customization Navigate to Sales Order Entry. Menu Path: Sales Management > Order Management > General Operations > Order Entry 1. In the Select Customization screen, select the Base Only check box and click OK. The Sales Order Entry form displays. 2. From the Tools menu, select Customization. 3. Select the Script Editor tab and maximize the screen. 4. Review the interface as described below: •

All Code check box: Use this to see all the code the framework generates in display mode only.

•

Program Selection: The first decision you must make is whether to use the VB.NET or the C# program. Once you make the decision and save the customization, all other modifications must be in that language.

•

Current tab: This tab displays all system and custom code. All lines of code are numbered.

•

Test Code: This command is available under the Tools menu. Use this command to verify the code will compile successfully.

•

Comments: Comments are lines of text that define specific sections of code but are not part of the code itself. It is recommended to use comments to describe custom code at all times. Below is a sample of comment lines which always appear in green on the screen. Comments in C#: // ** Wizard Insert Location - Do Not Remove 'Begin/End Wizard Added Module Level Variables' Comments! * // Begin Wizard Added Module Level Variables ** // End Wizard Added Module Level Variables ** // Add Custom Module Level Variables Here ** * Comments in VB.NET: '// ** Wizard Insert Location - Do Not Remove 'Begin/End Wizard Added Module Level Variables' Comments! * '// Begin Wizard Added Module Level Variables ** '// End Wizard Added Module Level Variables ** '// Add Custom Module Level Variables Here **

Epicor Software

Customization Overview | 15

Review the Default Script 1. In the Script Editor tab, select the VB code option. The following is the base display of code inside the Script Editor for a sales order form. It is divided into five sections described in the following task. ************************************************** '// Custom VB.NET code for SalesOrderForm '// Created: 12/13/2007 8:59:16 AM '//************************************************** SECTION 1 Imports System Imports System.Data Imports System.Diagnostics Imports System.Windows.Forms Imports System.ComponentModel Imports Microsoft.VisualBasic Imports Epicor.Mfg.UI Imports Epicor.Mfg.UI.FrameWork Imports Epicor.Mfg.UI.ExtendedProps Imports Epicor.Mfg.UI.FormFunctions Imports Epicor.Mfg.UI.Customization Imports Epicor.Mfg.UI.Adapters Imports Epicor.Mfg.UI.Searches Imports Epicor.Mfg.BO SECTION 2 Module Script SECTION 3 '// ** Wizard Insert Location - Do Not Remove 'Begin/End Wizard Added Module Level Variables' Comments! ** '// Begin Wizard Added Module Level Variables ** '// End Wizard Added Module Level Variables ** '// Add Custom Module Level Variables Here ** SECTION 4 Sub InitializeCustomCode() '// ** Wizard Insert Location - Do not delete 'Begin/End Wizard Added Variable Intialization' lines ** '// Begin Wizard Added Variable Intialization '// End Wizard Added Variable Intialization '// Begin Custom Method Calls '// End Custom Method Calls End Sub SECTION 5 Sub DestroyCustomCode() '// ** Wizard Insert Location - Do not delete 'Begin/End Wizard Added Object Disposal' lines **

Epicor 9 | 9.04.507

16 | Advanced Embedded Customization Course '// Begin Wizard Added Object Disposal '// End Wizard Added Object Disposal '// Begin Custom Code Disposal '// End Custom Code Disposal End Sub

End Module

Identify Scripting Regions Use the display of the script from the previous task or view it through the Script Editor. The Base code can be divided into regions which are described below. 1. Review the top-most commented section. This includes information on the date the customization script was created and the form in which it is located. 2. Examine SECTION 1: Each of the import statements is used to import namespace. The Script Editor automatically imports the most common namespace including the System namespace that includes the basic classes for .NET functionality. All other namespace are based on this System namespace. 3. Examine SECTION 2: The Module Script begins the actual script that includes the system code and any customized code. The editor default module script is divided among three major areas: 1.

Wizard-Added variables and Custom Level variables

2.

Wizard-Added Variable Initialization and Custom Method Calls

3.

Destroy Custom Code Note Each of these areas determines variables placement and scripts to author code. Foreign-key views and other variables are added automatically.

4. Examine SECTION 3: Any area that begins with '// (VB.net) or // (C #) indicates comments. These sections usually display in green. They guide custom code entry and document what the next routine is, which is helpful for other developers. 5. Examine SECTION 4: The Sub InitializationCustomCode() indicates the beginning of code and methods for a specific routine. 6. Examine SECTION 5: The Sub DestroyCustomCode section is the application's way to clean up and refresh for the next routine. All sub-routines initialize and then destroy (refresh) in preparation for the next routine or event.

Epicor Software

Customization Overview | 17

Use the Test Code Feature The Script Editor is available as a sheet inside the Customization Tools Dialog Box. It divides the screen into several areas. You may want to maximize the window so you have a large space to work. Notice import statements have already been created. 1. From the Tools menu, select Test Code. Note You should use the compiler to test all codes entered through the Script Editor. It allows you to quickly check for syntax errors and other problems in the code. Most code can compile on the spot, but some complex code may require you to exit the form.

2. View the test results at the bottom of the Script Editor. You may need to maximize the window to view the results. In this example, no custom code has been entered, so the compile displays Custom Code Compiled Successfully. 3. Once the compile displays Custom Code Compiled Successfully, exit the customization and close Sales Order Entry.

Epicor 9 | 9.04.507

18 | Advanced Embedded Customization Course

The Customization Tool Set The customization tool set consists primarily of the Customization Tools Dialog. This is the main control center on the user interface where you can create embedded customizations. This course is primarily concerned with the Tools menu options of the Customization Tools Dialog window. In addition, the completion of the scenarios throughout the course involves property modifications, use of each of the application wizards, as well as extensive scripting in the Script Editor. The Tools menu contains the following options: •

Toolbox: This provides access to text boxes, labels, grids, and additions to the UI which are bound to Data Values. Although this course uses few of the options available in the Toolbox, it does not go into details. For more information on the Customization Toolbox, refer to the Embedded Customization course.

•

Assembly Reference Manager: An assembly is sometimes referred to as a package. These are .dll files that contain all the objects and methods associated with a specific form. The Assembly Reference Manager is an easy way to work with existing assemblies.

•

Object Explorer: The Object Explorer allows you to access information about business objects. It includes UI Objects, Data Objects and Adapters.

•

Script Editor: The Script Editor displays all the code behind a specific field. As you create events or add objects to a form, the code displays in the Script Editor.

•

Options: This provides options for using grids.

•

Custom XML Editor: As you use wizards, create controls, and modify control properties, the customization tools automatically create the .xml code that runs the customization. All layers of this code display within the XML View sheet and you can modify them within the Custom XML Editor.

•

Data Tools: You can use the Data Tools menu to design Foreign Key Views. It is a powerful tool that allows you to link related tables together so they display the information you need.

ToolBox Use the ToolBox to create custom controls on all sheets. When you select the Toolbox command from the Tools menu, it displays on top of your current form. Click the buttons on the Toolbox to create custom controls on the form like text boxes, grids, check boxes, and so on. The following toolbox elements are used during this course: •

EpiLabel: the label associated with the grid

•

EpiTextBox: the element that captures and stores string values

•

EpiButton: works in tandem with the Form Event wizard to set up the event handled by the button

•

EpiUltraCombo: field that populates through hard-coded values or through values specified in a table

•

EpiGroupBox: visual element you can use to group screen elements

•

EpiDateTimeEditor: allows you to capture and store date/time values

•

EpiPicture Box: allows you to display images

Each item in the ToolBox represents a specific control you can add to the interface. Each of these controls has its own set of properties and methods. You can use them to create sub procedures within the Script Editor to assign unique tasks to the controls that depend on user input or the occurrence of some event.

Epicor Software

The Customization Tool Set | 19

Workshop - Add the PictureBox Control In the following scenario, inventory control requests that pictures of the parts be included in part master records, when possible. To accomplish this request, use the Form Event Wizard to modify the Part Maintenance UI screen. The wizard generates triggers that indicate when the picture displays and creates custom code that tells the application how to find the picture and how to determine which picture to use. This workshop demonstrates how to add a new picture box to the Part Master for a specific part. This workshop assumes the Developer Mode is active and you are logged in with appropriate permissions to generate customizations.

Create a Picture Box Navigate to Part Maintenance. Menu Path: Sales Management > Order Management > Setup > Part 1. In the Select Customization window, select the Base Only check box and click OK. 2. From the Tools menu, select Customization. 3. If the Clear Confirmation message displays, click Yes. This clears the screen of any data in preparation for customization. 4. Once the Customization Tools Dialog window displays, select the Script Editor sheet. It is very important to declare the programming language you want to use for the customization before you make any changes to the form. This example uses the VB.Net programming language. 5. Select the VB field. 6. From the Tools menu, select Toolbox. 7. Click the EpiGroupBox button. 8. In the Select Layer Type window, select Customization and click OK. 9. Place the group box near the Part field. 10. In the Customization Tools Dialog window, select the Properties sheet and change the Text property to Part Picture. 11. From the Toolbox, select the EpiPictureBox. 12. Create a picture box within the group box. 13. In the Name property, enter picPartAttachment. The application generates the Name property automatically when you create the new element. It uses the first three characters of EPI. In this case, the new name is epiPictureBox1.You can only change this name property at the time you create the field. Once you insert the picture box, you can use handlers to execute the code.

Epicor 9 | 9.04.507

20 | Advanced Embedded Customization Course

Set Up the Handler for the Picture Box This example uses two handlers to ensure the code executes based on a variety of events. Specifically, the AfterRowChange and ListChanged event handlers trigger the picture box to display for a part. 1. Select the Wizards > Form Event Wizard sheet. 2. In the Select Event Type field, select ListChanged. 3. In the Views field, select AutoAttachPart. 4. Click the blue right arrow button to add an event. The new event moves to the event listing. 5. In the Select Event Type field, select AfterRowChange to add another event. 6. In the Views field, select AutoAttachPart. 7. Click the blue right arrow button to add the event. The new event moves to the event listing. 8. Click Update All Event Code. This signals the application to write the new event handler code into the Script Editor. To view the generated code, select the Script Editor sheet. 9. Click Save. 10. In the Name field, enter XXXPicBox (where XXX are your initials). Spaces are not allowed when you generate a customization name. 11. In the Description field, enter XXX Part with Picture Box (where XXX are your initials). Spaces are allowed when you enter a value in the description field. 12. Click Save. An Add/Edit Comment box displays. Good practice is to enter notes that pertain to this customization for other users. 13. In the Customization Comments window, enter Add a picture box and click OK. The application automatically records your user name and date of the comment. Now that handlers are established, enter custom code into the Script Editor to define the picture box file.

Author a Routine 1. Navigate to the Script Editor sheet. Maximize the screen. 2. Add the first code just below '// Add Custom Module Level Variables Here ** and before the Sub InitializeCustomCode() entry: Dim mFileName As String

Epicor Software

The Customization Tool Set | 21 3. The next code identifies the filename as a string. Enter the code after the Sub InitializeCustomCode() entry but before the comments: mFileName = String.Empty 4. Add the code below after Sub DestroyCustomCode () area of the Script Editor and directly beneath the End Sub statement. Private Sub SetPictureBoxIconFromAttachMent() Dim edvPartAttach As EpiDataView = CType(oTrans.EpiDataViews("AutoAttachPart") , EpiDataView) If (Not(edvPartAttach Is Nothing) And (edvPartAttach.dataView.Count > 0)) Then Dim fileName As String =edvPartAttach.dataView(0)("FileName") If (mFileName fileName) Then mFileName = mFileName picPartAttachment.Image = System.Drawing.Image.FromFile(fileName) End If Else mFileName = String.Empty picPartAttachment.Image = Nothing End If End Sub

5. Immediately below this area, look for the event handlers added in the Form Event Wizard that begins with Private Sub AutoAttachPart_AfterRowChange. Just below the 'Add Event Handler Code ' line, enter: SetPictureBoxIconFromAttachMent() For each event handler, you need to add a method call to reference the routine that you have just authored. 6. Immediately below this piece of code, look for Private Sub AutoAttachPart_DataView_ListChanged entry. Just below the 'Add Event Handler Code ' line, enter: SetPictureBoxIconFromAttachMent() 7. Click Save and in the Customization Comments window, click OK. Test the code to ensure its accuracy. 8. In the Customization Tools Dialog window, from the Tools menu, select Test Code. A message displays in the lower portion of the screen that indicates the status of the compiled code. Review each line to correct the compilation error, if necessary. 9. If successful, click Save. 10. Close the Customization Tools Dialog window and exit Part Maintenance. The final step to this customization is to add an image that displays on the Part Maintenance UI screen.

Add the Image and Test the Part Turn off the Developer Mode. To populate the Part Maintenance screen with the image, enter the image as an attachment to the specific part record.

Epicor 9 | 9.04.507

22 | Advanced Embedded Customization Course This task assumes you are working with the embedded version of this course, launched from the Epicor 9 application. Before you start, click the Casting image link at the bottom and notice the picture displays. Right-click the picture, select Save Picture As, and save it to your Desktop. If you are working with the .pdf version of this course, search for any picture in your local machine, for example, C:\Documents and Settings\All Users\Documents\My Pictures\Sample Pictures. Navigate to Part Maintenance. Menu Path: Sales Management > Order Management > Setup > Part 1. Click the Part button and browse for and select CS-87-4578. 2. From the Actions menu, select Attachments. You can also click the Attachment icon on the toolbar to add attachments. 3. At the bottom of the Attachments screen, click New. You may need to maximize the Part Maintenance screen to see the button. 4. In the Doc Type field, select Part Master Link. 5. In the File name, click Browse to search for a picture. Locate the picture you saved on your Desktop or search for any file on your local machine. 6. Click OK and click Save. 7. Exit Part Maintenance and return to the Main menu. 8. From the Options menu, select Change UserID and log back in. Use the same ID and password: manager/manager. 9. Select the Developer Mode and reopen Part Maintenance. 10. In the Select Customization window, select the XXXPicBox customization and click OK. 11. Browse for and select part CS-87-4578. The picture you selected displays next to the part number. 12. Exit Part Maintenance.

Assembly Reference Manager The Assembly Reference Manager displays a list of all the native assemblies you can use within the application. Use this interface's tree view to find and select an assembly; this displays the assembly's main information. You can then use this program to add custom code to the selected assembly. The Assembly Reference Manager (ASM) allows you to quickly locate and add custom assembly references to a customized form. Customization must often call methods external to the form set in which the customization is written in order to bring in necessary data. Use assembly references when calling an adapter from another table in the application.

Epicor Software

The Customization Tool Set | 23 Below are key points: •

An Assembly is a piece of code that joins UI objects, data objects, and adapters. Sometimes called packages, assemblies are .dll files that group all the objects together to create a specific form.

•

An Adapter locates specific information and connects a UI object with a data object. Adapters use an assembly to pull in the data they require. Example A developer may need to access data only contained in the Customer master record and add that as a custom text field in the Sales Order > Ship To sheet. To do this, the Customer Adapter is called within Shipment Entry and the assembly references for the customer must be added for the adapter to work properly (for example, Epicor.Mfg.AD.Customer.dll, Epicor.Mfg.BO.Customer.dll, and Epicor.Mfg.IF.ICustomer.dll).

You can add assembly references at any point during the customization process but you should add them at the same time you call the adapters to ensure correct script compilation. If you do not add references to a script that contains one or more adapters, the script test throws an error that indicates the methods are not defined. There are four assembly types: •

BO: This assembly type displays the business object file required for the adapter.

•

IF: This assembly type displays the interface framework file required to display the fields and data the business object generates.

•

AD: This assembly type displays the adapter code object that connects the business object to the interface framework file.

•

UI: This assembly type calls a specific user interface object such as a sales order form required by the business object.

As a general rule, use the AD, BO, and UI assemblies at the same time for every adapter. Business Logic Assembly References Wizard You can use this wizard to add assembly references required for the custom code to use a selected Adapter. The wizard first looks for the specific adapter and then automatically brings in the correct assemblies for that object.

Epicor 9 | 9.04.507

24 | Advanced Embedded Customization Course

Workshop - Create Assembly References Use the Assembly Reference Manager to add custom assemblies. The workshop assumes the Developer Mode is active and the user is logged in with appropriate permissions to generate customizations. You can use Assembly Reference Manager to manually add an Assembly Reference or you can run the Business Logic Assembly Reference wizard. This workshop demonstrates how to use Customer Shipment Entry to manually add custom assemblies. Navigate to Customer Shipment Entry. Menu Path: Material Management > Shipping / Receiving > General Operations > Customer Shipment Entry 1. In the Select Customization window, select the Base Only check box and click OK. 2. From the Tools menu, select Customization. 3. In the Customization Tools Dialog window, from the Tools menu, select Assembly Reference Manager. 4. Click Add Custom Reference. The Add Assembly Reference window displays. 5. In the File name field, enter *customer.* and click Open. 6. From the file listing, double-click Epicor.Mfg.AD.Customer.dll. 7. Repeat steps 4 - 6 to add the next two assemblies: •

Epicor.Mfg.BO.Customer.dll

•

Epicor.Mfg.IF.ICustomer.dll

8. Click OK to close the Custom Assembly Reference Manager window. Remain in the Customization Tools Dialog window.

Epicor Software

The Customization Tool Set | 25

Workshop - Automatically Generate the Assembly Reference You can use the Business Logic Assembly References Wizard within any customization. It groups appropriate assemblies together based on the selected adapter and writes the code to the Script Editor. You can launch this wizard multiple times in a customization, if necessary. This workshop demonstrates how to use the wizard to add the same custom assemblies. 1. In the Customization Tools Dialog window, from the Tools menu, select Wizards > Customization Wizards. This opens the Customization Code Wizard dialog box. 2. In the Customization Code Wizard Dialog window, select Reference Adapter/BL Assemblies and click Launch Wizard. 3. In the Step 1 of 1 window, select Get Adapters. All the adapters available within the application populate in the list. 4. From the Adapter listing, search for and select the CustomerAdapter. There are adapters for every business object in the application. Adapters are used to retrieve data but require a reference to an assembly to operate. Three assemblies (BO, IF, and AD) populate in the window for the Customer Adapter. 5. Click Finish and click Close to close the Customization Code Wizard Dialog window. You can use the Assembly Reference Manager to view the three assemblies. 6. From the Tools menu, select Assembly Reference Manager. 7. Expand the Custom Assemblies node to view the added assemblies. All added assemblies appear under the Custom Assemblies node. There are two other assembly types that display in this Custom Assembly Reference Manager: •

System Assemblies: required by the Microsoft® backbone

•

Native Assemblies: required by the Epicor product

8. Click OK to close the Custom Assembly Reference Manager window. 9. Close the Customization Tools Dialog window. 10. In the Save Confirmation window, click No. 11. Close Customer Shipment Entry.

Custom Object Explorer Use the Custom Object Explorer to browse for and select a specific code object(s) you can use in the custom code. In essence, Business Objects provide abstracts of the programming structures that run the application. Business Objects often encapsulate all the data, the specific business behaviour and workflows associated with the form or module it represents. Business Objects do not necessarily need to represent objects in an actual business, though they often do. They can represent any object related to the domain for which a developer is creating business logic. The term is used to distinguish between the objects that relate to the domain and all the other object types.

Epicor 9 | 9.04.507

26 | Advanced Embedded Customization Course The Custom Object Explorer displays the Business Objects in three categories: •

UI Objects: UI Objects contain the code that displays the program interface on a monitor.

•

Data Objects: Data Objects contain the code that interacts with a database. It houses the methods used to enter, view, and calculate data for a specific function within an application.

•

Adapters: Adapters are code objects that connect the UI object with a data object. This file makes calls that either retrieve data from or send data to the data object.

Code snippets in the Object Explorer assist in writing VB.NET subroutines necessary to complete customization projects. In general, two types of code samples display. One is the VB.NET code and the second is provided to demonstrate another manner to access the same data.

Epicor Software

The Customization Tool Set | 27

Workshop - Review the Custom Object Explorer Use the Custom Object Explorer to locate the Job Entry screen properties and review the following: •

UI Objects: contain the code that displays program interface components on the screen. It houses the methods used to display various programs. An example of an UI Object is a check box. As you select an object from the tree view on the left, its details display on the right side of the screen. Following are the details that display: •

Return Type: This field displays the data types the method returns, for example, System.Boolean.

•

Property Type: This field displays the data type of the selected property, for example, System.string.

•

Parameters: This field displays the object's main attributes that are passed into the method, for example, System.Object.

•

VB.Net Example: This field displays code snippets that can be used for the selected UI Object, Property, or method. Two code styles can display for a given object.

•

Data Objects: represent the data captured from the application tables of a specific Epicor Object.

•

Adapters: bridges between datasets and datasources for retrieving information.

Access the Custom Object Explorer The workshop assumes the Developer Mode is active and you are logged in with appropriate permissions to generate customizations. Navigate to Job Entry. Menu Path: Production Management > Job Management > General Operations > Job Entry 1. In the Select Customization window, select the Base Only check box and click OK. This check box is a safeguard for creating new customizations. Checking it indicates the new customization is based on the original code requirements of the forms, excluding any personalizations. It also protects the new customization from being deployed to a menu before you complete it. 2. Once Job Entry opens, from the Tools menu, select Customization. 3. In the Customization Tools Dialog window, from the Tools menu, select Object Explorer. The Object Explorer opens to the UI objects tab specific to the Job Entry form.

Review EpiTransaction Objects One of the most frequently used UI objects is the EpiTransaction object. EpiTransaction Object (oTrans) is the layer between the UI and the adapter that binds the data to the UI and provides the application data specific behavior. 1. Expand the Transaction node and the Properties node. 2. From the list, select EpiDataViews. This is a hashtable of all the EpiDataViews in the Transaction object. An EpiDataView displays data from a specific table or form. 3. Under the Transaction node, expand the Methods node. 4. From the list, select Update ().

Epicor 9 | 9.04.507

28 | Advanced Embedded Customization Course The oTrans.Update() method updates an existing piece of data. 5. Select any of the methods that begin with GetNewxxx(). These methods pull new records into a form. 6. Review other Methods and Properties as necessary.

Review Session Objects While the UI object has many properties and methods, one of the most important is the Session Object that contains several useful properties including the current Acerate, Plant, or Company. 1. While in the UI Objects sheet, expand the Session > Properties node. Session items are usually read-only and you can use them to limit access. 2. From the list, select the User ID object and note the VB.Net example. Example When writting a script, you can use the following conditional statement that begin as follows: If (JobEntryForm.Session.UserID = "Jane Doe") Then Or, you can use an If-Then-Else statement that calls out several user ids. When you use multiple IF statements, the final choice must be followed by End IF.

3. Select the PlantID object and view the corresponding code samples in the VB.Net example section that demonstrate how to access each property. The two examples on this screen provide code choices for the Get Property and Set Property methods.

Review the ICustomScriptManager Object Use the ICustom Script Manager to access global variables from the script. It serves as a communicator between the custom assembly and the main client library. Review some useful methods below. 1. While in the UI Objects sheet, expand the ICustomScriptManager > Methods node. 2. From the list, select GetNativeControlReference. Use this method to retrieve a reference to base control on the form. This method requires a string parameter - controlGUID, which is the unique identifier for the specific control. The following line of code demonstrates the general coding convention for use: Dim ctrl As Control = csm.GetNativeControlReference(“5483cdef-3049-4705-b597-28ae93bc7fdf”) The example below shows use of the method when casting to a specific control type: Dim eucSales As EpiUltraCombo = CType(csm.GetNativeControlReference(“5483cdef-3049-4705-b597-28ae93bc7fdf”), EpiUltraCombo 3. From the list, select AddForeignKeyView. Use this method to add an updatable ForeignKeyView to the EpiTransaction object. Once this method is called, the added ForeignKey is available for control binding. This method works in conjunction with business logic adapters. Use of this method requires the following parameters: •

ViewName(string): This is the name of the Foreign Key View and must be unique.

•

dsData(DataSet): This is an empty DataSet of the Foreign Key Views Type.

•

TableName (String): This represents the name of the table that corresponds with the view in the DataSet.

Epicor Software

The Customization Tool Set | 29 The following lines of code demonstrate the use of this method: '// Add Adapters Table to List of Views '// This allows you to bind controls to the custom child view Dim dsData As DataSet = CType(ud01Adapter.UD01Data, DataSet) Dim fkvUD01 As ForeignKeyDataView = csm.AddForeignKeyView(“MyUD01View”, dsData, “UD01”) 4. From the list, select NotifyForeignKeyView. Use this method to update a ForeignKeyView added by the AddForeignKeyView() method. This method notifies controls bound to the Foreign Key View that the data has changed. This method is almost always used in conjunction with business logic adapters. Use of this method requires the same parameters as the AddForeignKeyView method. The following lines of code demonstrate the use of this method: '// notify with updated data csm.NotifyForeignKeyView("UD01", CType(ud06Adapter.UD01Data, DataSet), "UD01")

Review EpiDataView Objects The EpiDataView Object encapsulates a DataView of a particular DataTable that corresponds to a Table in your database. There is usually a direct correlation between a Database Table and an EpiDataView. To investigate the specific EpiDataViews available for a given UI application, see the Object Explorer tool's Data Objects tab. Use the Object Explorer tool's Data Objects sheet to investigate the specific EpiDataViews available for a given UI application. 1. In the Custom Object Explorer window, navigate to the Data Objects sheet. 2. From the list, expand the AutoAttachJobAsmblAttchAssembly > dataView node. 3. Note the first row which shows a reference to the selected EpiDataView object: Dim [edvVarName] As EpiDataView = CType(oTrans.EpiDataViews("AutoAttachJobAsmblAttchAssembly"), EpiDataView) 4. Note the second row which shows how to access or set a value in the EpiDataView: Dim [VarName] As Int32 = [edvVarName].dataView([edvVarName].Row)("AssemblySeq") 5. From the list, expand the JobHead > dataView node. 6. Select the TravelerReadyToPrint field. Pay special attention to the information on the specific field and data type. This field is a Boolean value that is either true or false. It relates to the Mass Print check box indicating its selection on the Job Entry form. 7. Select the CreatedBy field and view the Extended Props section. 8. Select the DueDate field and in the code box, review the code sample. These lines can be copied into the Script Editor for faster coding. It is necessary to call out the variables indicated in the brackets. In the case of the first line of code, a variable name must be supplied to hold the new EpiDataView in code. Think of the EpiDataView as the entire table view for a Customer. The second line of code helps drill further down to field-level data by establishing a second variable based on the value of the field in the EpiDataView. Bracketed text requires the substitution of a variable for the EpiDataView value associated with the Due Date field for the job. In general, the naming convention for EpiDataView variables is edvXXX.

Epicor 9 | 9.04.507

30 | Advanced Embedded Customization Course Code snippets in the Object Explorer assist in writing the VB.NET subroutines necessary to complete customization projects. Below is an example of the InitializeCustomCodeI() method. You can use this method to extend the object properties. The following code extends the JobNum field properties inside the JobHead EpiDataView. The VB.NET code is as follows: Private Sub SetExtendedProps() ‘// Get EpiDataView reference Dim edv As EpiDataView = CType(oTrans.EpiDataViews("JobHead"), EpiDataView) If edv.dataView.Table.Columns.Contains("JobNum") Then edv.dataView.Table.Columns("JobNum").ExtendedProperties("ReadOnly") = True edv.dataView.Table.Columns("JobNum").ExtendedProperties("Enabled") = False ‘// or to make invisible… ‘edv.dataView.Table.Columns("JobNum").ExtendedProperties("IsHidden") = False End if End Sub The C# code is as follows: private static void SetExtendedProps() { // Get EpiDataView reference Dim edv As EpiDataView = CType(oTrans.EpiDataViews("JobHead"), EpiDataView) if (edv.dataView.Table.Columns.Contains("JobNum")) { edv.dataView.Table.Columns["JobNum"].ExtendedProperties["ReadOnly"] = true edv.dataView.Table.Columns["JobNum"].ExtendedProperties["Enabled"] = false // or to make invisible... //edv.dataView.Table.Columns["JobNum"].ExtendedProperties["IsHidden"] = false } } Note The reference to make invisible in the above code demonstrates the manual way to hide a field. There is also an Extended Properties wizard available to manipulate these properties (discussed later in the course).

Review Adapters Data adapters are bridges between datasets and datasources. Without an adapter, a dataset cannot access any kind of data source. The data adapter takes care of all connection details for the dataset, populates it with data, and updates the data source. The methods on the adapters allow you to view the data within the dataset in a variety of ways and also provide methods for the manipulation of the data. This second line of code helps drill further down to field-level data by establishing a second variable based on the value of the field in the EpiDataView. Bracketed text requires the substitution of a variable. 1. In the Custom Object Explorer window, navigate to the Adapters sheet. 2. Click Get Adapters. All Adapters are brought in at one time the first time this button is selected. 3. Expand the Adapters node.

Epicor Software

The Customization Tool Set | 31 4. Select PartAdapter. The adapter must know what assemblies (or .dll programs) are required to find its data. These display in the Assembly Reference section. 5. Expand the PartAdapter > Classes > PartAdapter > Methods node. The method defines how the search locates the unique value for retrieval. 6. Select the GetByID method. On the right, the Custom Object Explorer displays the Return Type of the method, Parameters (if any), and a VB.Net Example that demonstrates how you can use it in a script. In this example, the return type is a Boolean value that takes the parameter that represents the partNum value. The GetByID method in this case assists in writing a script where you must validate data based on the existence of a specific part number. Example To call a specific field from the Part master file from the Engineering Workbench and update the data in that field through the workbench, use GetByID to validate the part number necessary before you access the field data to modify.

7. Review the VB.NET Example. The code examples contain additional import statements necessary to use the adapter in the green text. The first line defines the adapter to use and how to connect to the business object (BO). The next line identifies how to find the information (GetByID). The final line refreshes the code in preparation for the next command. 8. Close the Custom Object Explorer and Customization Tools Dialog. 9. Exit Job Entry.

Options Menu The Options sub-menu contains a command to determine if the Customization Tools Dialog window always remains on top when you customize a form and a command to specify grid settings. These options determine how the Customization Tools Dialog box is used during the current session. Some key grid options can also be defined. Following is a brief explanation of the choices. Top Most: The dialog box, by default, displays on top of the form. You can clear this check box to display it behind the form. Grid Settings: Use the Grid Settings option to specify the grid characteristics used in Customization mode. Grid settings include activating the Snap To Grid functionality and determining the grid size. •

GridSize: Use the Grid Settings option to specify the grid characteristics used in Customization mode.

•

Snap To Grid: Select this option to help position shapes when you are creating customizations on a grid. When this option is selected, the shapes pull, or snap, towards the grid dots.

Epicor 9 | 9.04.507

32 | Advanced Embedded Customization Course

Custom XML Editor The Custom XML Editor displays the XML code of your customization. Use the sheets in this troubleshooting tool to correct any issues that occur within the customization. When open, all the layers of the XML behind the customized form display in a true XML layout. The Custom XML Editor displays three sheets: •

XML View: Use this sheet to display a read-only view of the XML code. It allows you to view the entire XML code for the current form.

•

Custom Controls: Use this sheet to edit the various controls used on the current customization. Both native and custom controls display on this sheet. Control is the term given to any element on the screen. Examples of Controls are text boxes, images, group boxes, fields, and labels. Each control is listed as a separate row on this sheet.

•

Custom Properties: Use this sheet to edit the various properties of the controls set up for the current customization. Both native and custom control properties display on this sheet. A property defines a control. It indicates the control's current state or position within the form. It also defines the value used within the control.

Data Tools Use Tools > Custom Data Dialog to create and edit custom data views. Use this functionality to link related tables together so they display the information you need. The Foreign Key View allows you to create foreign key views for any Query Result or Data View that has a field that enables you to search by its record (GetByID) identifier.You can then create a view based on this field's value. A near unlimited amount of table combinations is available. You can create one view and then link sub-view to that view, another sub-view to the sub-view, and so on. As long as you can establish a logical connection between the Parent and Child columns, you can display data through a combination of views you need. After you create a foreign key view, you can use the features on the Custom Column Like tab to add the Like property to a specific field. You can also customize how the data appears within the grid through Row Rules. You can highlight a column, bold a column's text, make some columns invisible, and so on.

Epicor Software

Custom Code Wizards | 33

Custom Code Wizards You can use several Custom Code Wizards to generate custom code. The Reference Adapter/BL Assemblies wizard adds the references required for the custom code to use a selected adapter. The custom code can then correctly run this adapter. The Modify Extended Properties wizard assists in defining a specific property for a selected DataColumn - which is a field within a selected table. The Simple Search wizard adds a search program and search results fields to your customization. The Add User Defined Table as Child wizard adds a selected user-defined table to your current customization. You can also use this wizard to modify or remove the user-defined table link. The Business Logic Method Call wizard automatically generates a call to any public method within an adapter. You can also use it to map the input parameters required for both the method and the adapter.

Epicor 9 | 9.04.507

34 | Advanced Embedded Customization Course

Workshop - Use the Business Logic Assembly Reference Wizard The Business Logic Assembly Reference wizard adds Assembly References to the custom code Assembly that are necessary to call Business Logic Adapter methods. The workshop assumes the Developer Mode is active and you are logged in with appropriate permissions to generate customizations. Navigate to ABC Code Maintenance. Menu Path: Material Management > Inventory Management > Setup > ABC Code 1. In the Select Customization window, select the Base Only check box and click OK. The ABC Code Maintenance form displays. 2. From the Tools menu, select Customization. If the Clear Confirmation window displays, click Yes. 3. In the Customization Tools Dialog window, select Tools > Wizards > Customization Wizards. 4. In the Customization Code Wizard Dialog window, select Reference Adapter/BL Assemblies and click Launch Wizard to begin the wizard. 5. In the Step 1 of 1 section, click Get Adapters. All available adapters populate. 6. Select the ABCCode Adapter. Once you select the adapter, all three assemblies for that adapter populate. 7. Click Finish. 8. In the Customization Code Wizard Dialog window, click Close. 9. In the Customization Tools Dialog window, select Tools > Assembly Reference Manager. 10. Expand the Custom Assemblies node. The wizard automatically selects all three required assemblies (AD, BO, IF) and populates the Custom Assemblies with the selection. 11. Click OK to close the Assembly Reference Manager window. 12. Close the Customization Tools Dialog window. In the Save Confirmation window, select No. 13. Close ABC Code Maintenance.

Epicor Software

Custom Code Wizards | 35

Workshop - Use the Extended Property Wizard The Extended Property Wizard generates custom code to set the extended properties on a data column. Extended field properties include IsHidden Visible, ReadOnly, Enabled, and format. The workshop assumes the Developer Mode is active and you are logged in with appropriate permissions to generate customizations. Navigate to UOM Class Maintenance. Menu Path: Material Management > Inventory Management > Setup > UOM Class 1. In the Select Customization window, select the Base Only check box and then click OK. The UOM Class Maintenance form displays. 2. From the Tools menu, select Customization. If the Clear Confirmation message displays, click Yes. 3. In the Customization Tools Dialog window, from the Tools menu, select ToolBox. 4. From the Toolbox, select EpiTextBox. 5. In the Select Layer Type window, select Customization. 6. Click OK. 7. To the right of the System Default check box, draw the new text field. 8. Close the Toolbox. 9. Select the new EpiTextBox and navigate to the Customization Tools Dialog > Properties sheet. 10. Locate the EpiBinding property, set your cursor in the field, and open the list. 11. Expand the UOMClass table and double-click the Company field. 12. In the Customization Tools Dialog window, from the Tools menu, select Wizards > Customization Wizards. 13. Select the Modify Extended Properties wizard and click Launch Wizard. 14. In the Extended Property Wizard window, in the DataView field, select UOMClass. 15. In the DataField field, select Company. 16. In the Extended Property field, select Enabled. 17. In the Value field, select True. 18. Click Finish and click Close. 19. Navigate to the Script Editor sheet to see the code written by the wizard just below the private static void SetExtendedProperties() line. 20. On the Standard toolbar, click Save.

Epicor 9 | 9.04.507

36 | Advanced Embedded Customization Course The Customization Save Dialog window displays. 21. In the Name field, enter XXXExtended (where XXX are your initials). 22. In the Description field, enter XXX Extended UOMClassID (where XXX are your initials) and click Save. 23. Leave the Customization Comment window blank and click OK. 24. Close the Customization Tools Dialog and exit UOM Class Maintenance. 25. Reopen UOM Class Maintenance. 26. In the Select Customization window, select XXXExtended and click OK. 27. Select any entry for Class ID to test the new text box. Notice the Company information populates. 28. Exit UOM Class Maintenance.

Epicor Software

Custom Code Wizards | 37

Workshop - Use the Add User Defined Table as Child Wizard This wizard generates code to View/Add/Edit/Delete a UD table as a child DataView to an existing DataView Application. The workshop assumes the Developer Mode is active and you are logged in with appropriate permissions to generate customizations. Navigate to ABC Code Maintenance. Menu Path: Material Management > Inventory Management > Setup > ABC Code 1. In the Select Customization window, select the Base Only check box and click OK. The ABC Code Maintenance form displays. 2. From the Tools menu, select Customization. If the Clear Confirmation message displays, click Yes. 3. In the Customization Tools Dialog window, select Tools > Wizards > Customization Wizards. 4. From the wizard listing, select Add User Defined Table as Child Wizard and click Launch Wizard to begin the wizard. 5. In the Step 1 of 2 section, in the DataViews field, select ABCCode. 6. In the UD Adapters field, select UD01Adapter and click Next. 7. In the Step 2 of 2 section, in the Fields field, select ABCCode. 8. In the UD Key Fields, select Key1 and click Add to accept and populate the mapping field. 9. Click Finish and click Close. You can review the generated code in the Script Editor section. 10. On the Standard toolbar, click Save. The Customization Save Dialog window displays. 11. In the Name field, enter XXXUDTable (where XXX are your initials). 12. In the Description field, enter XXX User Defined Table (where XXX are your initials) and click Save. 13. Leave the Customization Comment window blank and click OK. 14. Close the Customization Tools Dialog and exit ABC Code Maintenance.

Test the User-Defined Wizard 1. Reopen ABC Code Maintenance. 2. Select the XXXUDTable (where XXX are your initials) customization and click OK.

Epicor 9 | 9.04.507

38 | Advanced Embedded Customization Course 3. From the Tools menu, select Customization. 4. If the Clear Confirmation message displays, click Yes. 5. In the Customization Tools Dialog window, from the Tools menu, select ToolBox. 6. From the ToolBox, select EpiTextBox and drag out a new field somewhere on the ABC Code Maintenance form. 7. Close the Toolbox. 8. In the Customization Tools Dialog > Properties sheet, select the EpiBinding field. You should see a listing for the UD01View table as a possible datasource. You could now use it to bind to for additional data on the screen. 9. Close the Customization Tools Dialog window and save your changes. 10. Close ABC Code Maintenance.

Epicor Software

Custom Code Wizards | 39

Workshop - Use the Business Logic Method Call Wizard Use this wizard to automatically generate a call to any public method on an adapter. You can also map the input parameters required for the method and the adapter. The scenario generates an ECO group number based on the company that is a two-digit year plus a sequential number. The basic steps to accomplish this are: 1.

Use the Business Logic Assembly Wizard to add the Company adapter as an assembly and define the method to call.

2.

Create a private function that defines the creation of the new ECO number using the method.

3.

Create the EpiNotificationEvent to tell the application to create the ECO number when the form is called.

Epicor 9 | 9.04.507

40 | Advanced Embedded Customization Course

Workshop - Use the Business Logic Wizard This workshop assumes Developer Mode is active and you are logged in with appropriate permissions to generate customizations. Use a user-defined field on the Company table to create an ECO group number in the Engineering Workbench form. Set the generated group number as the current year followed by a dash and a sequential number. For example, if the current year is 2009 and the last number was 007, the next group ID is 09-008. Navigate to the Engineering Workbench. Menu Path: Production Management > Engineering > General Operations > Engineering Workbench 1. In the Select Customization window, select the Base Only check box and click OK. The Engineering Workbench form displays. 2. From the Tools menu, select Customization. 3. In the Customization Tools Dialog window, navigate to the Script Editor sheet. 4. Select the VB. You must identify the preferred programming language prior to adding any events or code. 5. In the Customization Tools Dialog window, select Tools > Wizards > Customization Wizards. The Customization Code Wizard Dialog displays. 6. From the Wizards listing, select Business Logic Method Call and click Launch Wizard to begin the wizard. The Business Logic Method Call window displays. 7. Click the Get Adapters button. 8. From the resulting list, select CompanyAdapter and click Next. A list of methods displays in the Wizard's window. 9. From the Select Adapter Method listing, select GetByID method. Notice the Return Type field returns a boolean data type and the Parameters field takes a string as a parameter. 10. Select Next to continue the wizard. 11. In the Parameters field, select company : System.String. 12. In the Map Parameters to variables section, select Inside Method. In this case, the method (GetByID) requires a parameter. Some methods require more than one parameter, and some require none. The parameter can be supplied in two ways - passed into the custom method the wizard creates or declared and initialized to the correct value inside the method the wizard creates. If the parameter is to be set inside the wizard generated method, it can set to the value of a field in an EpiDataView or to an arbitrary expression (for example, 5, "Hello", oTrans.Session.UserID, and so on). 13. Select Set to Value/Expression. 14. In the Value field, enter oTrans.Session.CompanyID and then click Add. This value appears in the field below.

Epicor Software

Custom Code Wizards | 41 The Session object contains useful information. If necessary, refer back to the Custom Object Explorer section for more information. In this case, the session value is the company active at the time this code executes. This code is being used as part of the ECO number. 15. Click Finish and click Close. 16. On the Standard toolbar, click Save. The Customization Save dialog displays. 17. In the Name field, enter XXXBLWiz (where XXX are your initials). 18. In the Description field, enter XXX Business Logic Wizard (where XXX are your initials) and click Save. 19. In the Customization Comment window, enter AutoGenerate ECO number and click OK. 20. Navigate to the Script Editor sheet to see that the wizard automatically adds a method called: Private Sub CallCompanyAdapterGetByIDMethod()

Author a Routine Now that the adapter is added, custom code is written to complete the definition of the GetECO() as String call. Add a private function to tell the application what should be done. In this example, the code tells the application how to create the new ECO group number. 1. Navigate to the Script Editor sheet. 2. Locate the Private Sub CallCompanyAdapterGetByIDMethod() section and change the existing code to: Private Function GetNextECO() As String 3. Add the following code just below the Dim result As Boolean = adapterCompany.GetByID(company) entry: Dim nextECO As String = String.Empty If (result) Then nextECO = adapterCompany.CompanyData.Company.Rows(0)("Number02").ToString() adapterCompany.CompanyData.Company.Rows(0).BeginEdit() adapterCompany.CompanyData.Company.Rows(0)("Number02") += 1 adapterCompany.CompanyData.Company.Rows(0).EndEdit() adapterCompany.Update() End If 4. Just below the adapterCompany = Nothing entry, enter the following: Return nextECO End Function 5. Delete the End Sub line. 6. Click Save and enter comments if desired. 7. From the Tools menu, select Test Code. Address any compile errors if they arise.

Epicor 9 | 9.04.507

42 | Advanced Embedded Customization Course

Add an EpiNotificationEvent Trigger an EpiNotificationEvent right after a dataView loads into an application. It signals the data is ready to view or edit. The code below defines the next sequential number by calling the GetNextECO routine. The following code defines the GroupID as a two digit year followed by a dash and the next sequential number. 1. In the Customization Tools Dialog window, navigate to the Wizards > Form Event Wizard sheet. 2. In the Select Event Type field, select EpiViewNotification. 3. In the Select View/Table (and Field) field, select ECOGroup. 4. Click the blue right arrow to record the selection. See the code that appears in the View / Edit Event Handling Code section. 5. Click the Update Selected Event Code button. The application generates the Form Event code and places it inside the Script Editor. 6. Navigate to the Script Editor sheet and locate the Private Sub edvECOGroup_EpiViewNotification section in the code window. 7. Enter the following code after the If (args.Row > -1) Then code line: view.dataView(Args.Row)("GroupID") = Right(Year(view.dataView(args.Row)("CreatedDate")),2) & "-" & GetNextECO view.dataView(args.Row)("ECO") = view.dataView(args.Row)("GroupID") 8. From the Tools menu, select Test Code. Address any compile errors if they arise. 9. Click Save and enter comments if desired. 10. Close the Customization Tools Dialog and exit the Engineering Workbench. 11. Re-open the Engineering Workbench. 12. In the Select Customization window, select the XXXBLWiz customization and click OK. 13. Click New. Note the GroupID that automatically generates. 14. Enter a description of your choice and click Save. 15. Create one more entry to test the function and then close the Engineering Workbench. 16. In the Save Confirmation window, select No.

Epicor Software

Code Examples | 43

Code Examples This section includes several workshops that present custom coding examples using all the customization tools. •

UI-Controls: Each of the items in the embedded customization toolbox represents a user interface control.

•

Modify a Sub Process: A sub process is a routine called from a variety of UI applications. You can customize them only by calling out the specific process. A new Sub Process Menu is then created and attached to the original process, which is called using the new customization

•

Modify an MES button: The Manufacturing Execution System is a separate module designed to have a touch screen available to shop employees for labor and inventory transactions. You can customize this screen to attach items to some of the blank buttons.

UI Controls and Form Events UI Controls refer to elements on a specific UI application, such as the Sales Order Entry screen. Users frequently wish to combine any number of form event triggers and to add custom controls to the UI form. Many UI controls (such as EpiTextBoxes, EpiGrids, and such) can be further enhanced to execute an event based on a specific trigger. For example, the Price Lists button on the Part Entry Maintenance screen opens a new screen to allow you to view existing price lists. Another example is to add a button that opens a web page once you click it. The following example demonstrates the wizard like tool that allows you to embed a specific dashboard in a sheet.

Epicor 9 | 9.04.507

44 | Advanced Embedded Customization Course

Workshop - Work with Embedded Dashboards You can use the Embedded Dashboard Panel wizard to add a dashboard to a new sheet. This wizard allows you to find and select the dashboard you want to place within your new sheet. You can also use this wizard to indicate if the selected dashboard will publish (display) its data within another dashboard or subscribe (update) its data based on another dashboard. This example provides the steps to add a new sheet that displays the Part On Hand Status dashboard directly inside the Part Maintenance UI application.You can test the new, embedded dashboard before you actually deploy it within the Run Mode to ensure it accurately displays the records desired. Any dashboard can be embedded into a specific program's interface though the Sheet Wizard; these include all the dashboards delivered with the application as well as any the user creates. Regardless of the dashboard you select for inclusion into a sheet, the dashboard must have some data connection or relationship with the UI in which it is to be embedded. You can use the Data Dictionary Viewer to assist you in selecting the best columns for subscription when you embed a dashboard or when you are uncertain in your decision.

Add a New Sheet The workshop assumes the Developer Mode is active and you are logged in with appropriate permissions to generate customizations. Navigate to Part Maintenance. Menu Path: Material Management > Inventory Management > Setup > Part 1. In the Select Customization window, select the Base Only check box and click OK. The Part Maintenance form displays. 2. From the Tools menu, select Customization. If the Clear Confirmation message displays, click Yes. 3. In the Customization Tools Dialog window, select Wizards > Sheet Wizard. 4. Click New Custom Sheet. 5. From the Dockable Sheets listing, select mainPanel1. The new sheet positions on the top level of the UI application. Select Docking Sheet if the new sheet can also have sheets attached to it. 6. In the Name, Text, and Tab Text fields, enter PartStatus. 7. Click Add Dashboard. The three-part Embedded Dashboard Panel Wizard displays. 8. Select the Dashboard Panel option. Select the Dashboard Panel to cause the embedded dashboard to bring the dashboard definition directly from the dataset during run time. Use the AppBuilder Panel to cause the embedded dashboard to build the finished dashboard assembly. This selection generally provides better performance as the dashboard is loaded after it is compiled. 9. Click Dashboard ID to search for and select the PartOnHandStatus dashboard.

Epicor Software

Code Examples | 45 10. Select both the Display Dashboard Tool Bar and Display Dashboard Status Bar check boxes. These choices bring in the elements directly from the Dashboard. 11. Click Next to proceed to Step Two of the Wizard.

Define the Publish and Subscribe Options of the Dashboard A Dashboard typically uses Publish and Subscribe to display its properties. You can also use these features in an embedded dashboard. The Dashboard can subscribe or publish to the data in the UI form based on the options defined in the Step 2 of 3 window. 1. From the option listing select Publish data to the UI. Select this option if the dashboard should display data pulled from another query. A brief description of the other choices: •

Subscribe to UI data (auto Retrieve on publication): Select this option to allow the dashboard to automatically retrieve data when the customized program publishes the current value.

•

Subscribe to UI data (include Retrieve button): Select this option if the dashboard should automatically clear data when the customized program publishes the current value. A Retrieve button displays to allow you to manually retrieve the data.

•

Neither Subscribe nor Publish: Use this option to have the dashboard display the data contained within itself.

2. Click Next. The Publish Data to the UI option requires dashboard columns for which the user interface should subscribe to be defined. 3. From the Available Published Columns listing, select Part.Partnum. 4. Click Add Published Column. 5. Click Finish to return to the Customization Tools Dialog window. Note that the PartStatusOnHandTracker now appears within the Add Dashboard field. 6. Click the right blue arrow to move the PartStatus embedded dashboard into the Custom Sheets listing. The dashboard does not embed until it appears under the Custom Sheets. 7. Click Save. The Customization Save Dialog window displays. 8. In the Name field, enter XXXDashboard (where XXX are your initials). 9. In the Description field, enter XXX Embedded Dashboard (where XXX are your initials) and click Save. 10. Leave the Customization Comment window blank and click OK. 11. Close the Customization Tools Dialog window. 12. Return to Part Maintenance, and in the Part field, enter DSS-1000 and press Tab. 13. Select the Part Status sheet to display the Part On Hand Status dashboard.

Epicor 9 | 9.04.507

46 | Advanced Embedded Customization Course 14. Exit Part Maintenance.

Modify Infragistics Components ®

To modify aspects of the form menu, access the Infragistics control properties that form the intrinsic, structural components of the user interface. Application The code that displays below demonstrates the method in which infragistics components that make up the UI structure or frames can be modified. The code that displays is written for ABCCode Maintenance; the general principles can be extrapolated to any UI application and you can insert them before the End Module statement at the end of the automated Script Editor statements. The Delete icon often presents a potential pitfall for users due to its proximity to the Save icon. To ensure users do not inadvertently press the Delete icon when they attempt to save a record, you can hide this icon from the form toolbar. Review the VB.net code below and note how the code uses a Try/Catch block. Try/Catch is one of the most useful ways to deal with exceptions the UI components throw. The UltraToolbarManager is an instance of an Infragistics component. These are not exposed in the system architecture and are not accessible through the Object Explorer. The code example below is strictly for use with the often troublesome Delete icon: Private Sub AbcCodeForm_Load(ByVal sender As Object, ByVal args As EventArgs) 'Add Event Handler Code try If (baseToolbarsManager.Tools.Exists("DeleteTool")) Then '// verify we have the "Standard Tools" toolbar If (baseToolbarsManager.Toolbars.Exists("Standard Tools")) baseToolbarsManager.Toolbars("Standard Tools").Tools("DeleteTool").InstanceProps.Visible = Infragistics.Win.DefaultableBoolean.False baseToolbarsManager.Toolbars("FileMenu").Tools("DeleteTool").InstanceProps.Visible = Infragistics.Win.DefaultableBoolean.False end if end if Catch Ex as Exception ExceptionBox.Show(Ex) End try End Sub

Modifying Sub Processes Use Sub Process Maintenance to create sub process menu IDs for programs you customized and wish to launch or call from within other programs. Menu Path: System Management > Utilities > Sub Process Maintenance Important This program is not available in the Epicor Web Access™ interface.You can launch this program ® from an Epicor Smart Client (Windows ) interface. A sub-process is a small program that is called to execute from an Action menu item or from within the UI itself. They are called from a variety of UI applications.

Epicor Software

Code Examples | 47 Example Memo Comments, Attachments, and CRM Calls are all examples of sub processes called from the Action menu or the toolbar. Using the embedded customization toolset on these sub processes is a three step process. •

Use the customization tools to access the sub process and modify the UI.

•

Use Sub Process Menu Maintenance to identify the menu ID for a custom program. The ID is linked to an assembly (.dll) in order to execute the process from within other programs.

•

Use Process Calling Maintenance to launch, or activate, the sub process program.

Some Action menu subprocesses are not separate assemblies (.dll) but execute at the same time the UI form executes. The only way to customize this type of sub process is to also customize the main UI form it is linked to. For example, the Job Entry UI includes the New Job selection from the New menu. The sub process (New Job) is customized by launching it as part of the Job Entry. A specific customization of Job Entry UI also must also be created with the same name as the sub process. Therefore, when you deploy the customization to a menu item for the main form, the sub form's customization is also applied. You then give the customization of the Job Entry form a name.

Epicor 9 | 9.04.507

48 | Advanced Embedded Customization Course

Workshop - Modify Sub Processes Sub-processes are called from a variety of UI applications. The basic steps required to use the embedded customization toolset on these sub processes are: 1.

Identify the sub process to be customized.

2.

Customize the specific sub process.

3.

Create a new sub process menu.

4.

Attach the menu to the process using the new customization.

The following workshop demonstrates how to customize the Memo Entry sub process when called from a customer record.

Identify the Sub Process The workshop assumes the Developer Mode is active and you are logged in with appropriate permissions to generate customizations. Navigate to Customer Maintenance. Menu Path: Sales Management > Order Management > Setup > Customer 1. In the Select Customization window, select the Base Only check box and click OK. The Customer Maintenance form displays. 2. Navigate to the Customer > Detail sheet. 3. In the Customer field, enter Dalton and press Tab. 4. From the Actions menu, select Memo. A Process Calling window displays the actual key for the process being called. Note the Key and Calling Preferences inside the Process Calling screen. 5. Click OK. 6. In the Select Customization window, select the Base Only check box and click OK. The Memo Entry Detail window displays.

Customize the Memo Window 1. From the Tools menu, select Customization. 2. Extend the group box to allow space for an additional field. 3. In the Customization Tools Dialog window, select Tools > ToolBox. 4. In the Toolbox select the EpiDateTimeEditor. 5. In the Select Layer Type window, select Customization.

Epicor Software

Code Examples | 49 6. Click OK. 7. Place the new field just below the Memo Category field. 8. Navigate to the Customization Tools Dialog > Properties sheet and select the EpiBinding field. 9. Open the list, expand Memo, and select Date01. 10. From the Toolbox, select the EpiLabel tool and create a label to the left of the EpiDateTimeEditor field. 11. In the Customization Tools Dialog window, in the Text field, enter Create Date. 12. Click Save. The Customization Save Dialog displays. 13. In the Name field, enter XXXMemo (where XXX are your initials). 14. In the Description field, enter XXX Memo (where XXX are your initials) and click Save. 15. In the Customization Comment window, enter Added Create Date Field and click OK. 16. Close the ToolBox and the Customization Tools Dialog. 17. Exit Memo Entry and Customer Maintenance and return to the Main menu. The Memo Entry UI has now been customized. The new sub process must be defined.

Create the Sub Process Disable Developer Mode. Navigate to Sub Process Maintenance. Menu Path: System Management > Utilities > Sub Process Maintenance Important This program is not available in the Epicor Web Access™ interface.You can launch this program ® from an Epicor Smart Client (Windows ) interface. 1. Click New. 2. Enter the following information: Field

Data

Process ID

UDMemoXX (where XX are your initials)

Name

XXX Memo with Create Date (where XXX are your initials)

Security ID

SEC018

Order Sequence

100

Program Type

Non Menu Item

Program

Epicor.Mfg.UI.MemoEntry.dll

3. In the Customization field, select your customization.

Epicor 9 | 9.04.507

50 | Advanced Embedded Customization Course 4. Click Save and close Sub Process Menu Maintenance. 5. In the Main menu, select Options > Change User ID. This refreshes the session and makes the new menu item available. 6. Log back into the application. Use the same User name and Password of manager.

Create the Process Calling Process Calling determines what applications or customization is called when an application is called anywhere in the Main menu (including action menus, context menus, and buttons). Navigate to Process Calling Maintenance. Menu Path: System Management > Utilities > Process Calling Maintenance Important This program is not available in the Epicor Web Access™ interface.You can launch this program ® from an Epicor Smart Client (Windows ) interface. 1. Click New. 2. In the Called Process Reference field, enter Epicor.Mfg.UI.MemoEntry without the .dll extension. This is the same program identified in Sub Process Maintenance without the .dll extension. 3. Leave the Called From field blank. If you leave this field blank, the customization form is used any time it is called from within the application. Only enter something here if you want to limit the calling of this particular customization form. 4. In the MENU ID field, select UDMemoXX. 5. Click Save and exit Process Calling Maintenance.

Test the New Sub Process In the Main menu, select Options > Change User ID. Use the same User name and Password of manager. Now that the new sub process is written and called, you must test it. Navigate to Customer Maintenance. Menu Path: Sales Management > Order Management > Setup > Customer 1. In the Customer field, enter Addison and press Tab. 2. From the Actions menu, select Memo. 3. Verify the new customized version of Memo entry is now in place. 4. Exit both Memo Entry and Customer Maintenance.

Epicor Software

Code Examples | 51

Delete Sub Process Navigate to Sub Process Maintenance. Menu Path: System Management > Utilities > Sub Process Maintenance Important This program is not available in the Epicor Web Access™ interface.You can launch this program ® from an Epicor Smart Client (Windows ) interface. 1. On the tree view, expand Processes. 2. On the tree view, select your customization XXX Memo with Create Date. 3. From the standard toolbar, click Delete. 4. To the "Delete this record?" message, click Yes. The customization created in the previous workshop is now removed. 5. Click Save and exit Sub Process Maintenance.

Epicor 9 | 9.04.507

52 | Advanced Embedded Customization Course

Tracing Options The Tracing Options Form window allows you to set up a tracing log that captures all the calls the user interface makes to the server. When you activate this log, any business logic (BL) calls sent to the server are automatically recorded within this log. The tracing log is a tool that has several uses. Web service developers can use this log to see what business logic calls are being made when users launch a specific function, for example, the BL calls made when a user enters a new customer record. Custom programmers can use this log to fine-tune their customized applications. Epicor Support may also ask you to turn on this log to help them track issues. To make this log easier to review, you can enter Mark Text to organize it; all the calls that reference this mark text are then grouped together. You then have the option to display this log either as a text ( .txt) file or as an .xml file. Note that a pre-built .xml stylesheet is included with this functionality. It is recommended that you use the .xml file format, as it organizes these calls in a readable format. Note You can also turn the tracing log on and off within the mfgsys.exe.config file.

Epicor Software

Tracing Options | 53

Workshop - Create the Tracing Log Use the Tracing Options to set up a tracing log that captures all public business object calls. This includes calls initiated from the client as well as calls from one object to another. When you activate this log, any public business calls sent to the server are recorded in the log. You can use the tracing log to track business object calls so you can see how successful operations are performed within the application. You can then map the business logic as needed to a Service Connect workflow. Important Due to the logic of creating and processing the Tracing Log, this workshop can only be performed by one person on a shared database.

Configure and Start a Trace Log 1. In the application's Main menu window, from the Options, select Tracing Options. 2. In the Tracing Options Form window, select the Enable Trace Logging check box. 3. In the Dataset Options section, select the type of information to appear in the trace log file. Only one choice is allowed and the options include: •

Select Write Full DataSet to view the XML datasets passed to and returned from the server.

•

Select Track Changes Only to view only changed columns in the dataset.

4. In the Mark Text field, enter any specific text to organize the tracing log. All the calls that reference this mark text are then grouped together. 5. Click Apply. 6. Exit the System Monitor to reduce the number of trace packets in the log. To exit the System Monitor, right-click the System Monitor icon in the Notification Area (right side of the task bar) and select Exit. You can restart the System Monitor using the following menu path: Menu Path: System Management > Utilities > System Monitor Important This program is not available in the Epicor Web Access™ interface. You can launch this ® program from an Epicor Smart Client (Windows ) interface.

Create an XML Trace Report Click Create XML to begin the trace log. All business object calls from this point forward are entered into the log file shown in the Current Log File field. Click View to view the log file at any time. To clear the log, click Clear Log. The trace file can be saved to an XML file. The application generates an XSL stylesheet so when you open the XML file, it is formatted in a report layout. 1. In the Tracing Options Form window, click the Ellipsis (...) button next to the XML File field. 2. Browse to a location on your computer where you want the file created. 3. Enter a File name.

Epicor 9 | 9.04.507

54 | Advanced Embedded Customization Course 4. Click Save. 5. Click Create XML. To view the XML trace, go to the folder where the XML file was created and double-click the file. Note If you send the XML file to someone else, include the TracePacket_Default.xsl file.

Disable Tracing Disabling the Tracing functionality is important when it is not necessary to run. The Tracing Log can become overwhelmingly large if it is always selected as enabled. 1. In the applications Main Menu, from the Options menu, select Tracing Options. 2. In the Tracing Options Form window, clear the Enable Trace Logging check box. 3. Click the Apply button. 4. Click OK. The Tracing Log is now disabled.

Epicor Software

Customization Maintenance | 55

Customization Maintenance The Customization/Personalization Maintenance is an important tool that allows you to manage all the customizations and personalizations that exist within your application. Its primary feature is the verification functionality that allows you to detect problems within any customization or personalization. Menu Path: System Management > Utilities > Customization Maintenance Important This program is not available in the Epicor Web Access™ interface.You can launch this program ® from an Epicor Smart Client (Windows ) interface. This maintenance program allows you to launch the tools you need to correct issues that occur. Customization/Personalization Maintenance is especially useful when you upgrade the application to a new version, as it can help you make customized and personalized programs compatible with the current version. Customization/Personalization Maintenance has additional functionality that allows you to import and/or export your customizations and personalizations, allowing you to make these programs available throughout your organization.This maintenance tool also allows you to delete any customization or personalization. Use this feature to either remove custom program stages you no longer need or remove personalizations made by employees who are no longer with your company. System Administrators with Security Manager rights can use this program to modify fields and delete any customizations and personalizations created by users. For System Administrators without Security Manager rights, this program appears in a Read-Only format. For more information on security, see the Application Help - Security Overview. Note You cannot access Customization/Personalization Maintenance from the Customization Tools Dialog window. You must select it from the Main menu. Customization/Personalization Maintenance allows you to: •

Review the details on each customization or personalization, including the Product ID, Version, LastUpdated By, Form Name, and Parent Layer.

•

Delete obsolete customization files.

•

Delete all personalizations associated with a specific user.

•

Select a customization as a Work in Progress. This prevents the customization from being used within the application before it is ready.

•

Export a customization that you wish to use elsewhere.

•

Import a customization that you want to incorporate into your manufacturing application. Any customization .xml file from an outside source must be imported to the appropriate program in the application using this utility.

•

Test if your customizations and personalizations work properly. This verification tool can review all the custom fields and code within a selected customization or personalization or a group of customizations and personalizations. It then informs you whether the customization or personalization is valid.

•

Use Run Mode/Developer Mode Access to immediately launch a customization or personalization in both Run Mode and Developer Mode within Customization/Personalization Maintenance. You can use these functions, for example, to discover why a selected personalization or customization does not work properly.

•

Set a Verification Warning for users who attempt to launch a customized or personalized program that is not compatible. An error message displays that prevents the user from launching the program. You can then use Customization/Personalization Maintenance to upgrade the program.

Epicor 9 | 9.04.507

56 | Advanced Embedded Customization Course

Workshop - Use Customization/Personalization Maintenance This workshop introduces you to the fundamental features of Customization/Personalization Maintenance. Use the Detail sheet to select, update, or delete a specific customization or personalization. The Warnings sheet displays any elements (controls or properties) within the customized or personalized program that do not validate. These elements display within the Warnings grid. Use the Compile/Script Errors sheet to review any larger issues within the selected customization or personalization. These are errors the verification process generated. Use this sheet to help discover what you need to do to resolve the error.

Export a Customization Security Manager rights are required to use this program. The workshop should be performed in Run Mode. Navigate to Customization/Personalization Maintenance. Menu Path: System Management > Utilities > Customization Maintenance Important This program is not available in the Epicor Web Access™ interface.You can launch this program ® from an Epicor Smart Client (Windows ) interface. 1. Navigate to the Detail sheet and click Name. 2. Browse for and select the XXXBLWizard (where XXX are your initials) customization created earlier. 3. From the Actions menu, select Export Customization. The Export Customization window displays. 4. In the New Name field, enter BLWizardXXX (no spaces and where XXX are your initials). 5. Click Export Filename and browse to your Desktop. 6. In the File name field, enter XXXExport (where XXX are your initials) and click Save. The exported customization retains the New Name while the export file name is used to identify the new file. 7. In the Export Customization window, click Export. The exported file is used for the remaining workshops.

Import a Customization File 1. On the Standard toolbar, click Clear to clear the Customization/Personalization Maintenance screen. 2. In the Clear Confirmation window, select Yes. 3. From the Actions menu, select Import Customization. 4. Click Import Filename and browse for and select XXXExport (where XXX are your initials). 5. In the New Name field, enter MyBLWizardXXX (no spaces and where XXX are your initials).

Epicor Software

Customization Maintenance | 57 6. Click OK to accept. The Customization Maintenance dialog window now indicates the new customization has been imported successfully.

Review and Verify the Imported Customization File 1. Review the information that displays on the Detail sheet including the information that displays in the Valid For and Status fields. Note Notice the Valid For and Status fields are currently blank.

2. From the Actions menu, select Verify Customization. Note The Actions menu contains two features that allow you to verify code. Verify Customization simply runs the code in the current customization file through a validation sequence in order to find any errors and potential problems with controls referenced by the form. The Verify All option runs this validation against all current customization files for all UI application programs. Verify All can be a long process and should be reserved for times when the least amount of users are currently logged into the application.

3. Note the Valid for field populates with the current application version, and the Status field shows Pass. 4. Navigate to the Compile/Script Errors sheet. If there are any compile errors, they display in the Errors grid. 5. Select the Warnings sheet. The warnings sheet displays errors if they occur that indicate a problem with the customization. The code must compile before an accurate list of warnings displays. 6. From the tree view, select your customization XXXExport. 7. On the standard toolbar, click Delete. 8. To the "Delete this record?" message, click Yes. 9. Close Customization/Personalization Maintenance.

Epicor 9 | 9.04.507

58 | Advanced Embedded Customization Course

Conclusion Congratulations! You have completed the Advanced Embedded Customization course. The customization feature is the best tool to modify the application's interface to meet your company's specific needs. This session highlighted some of the tools available to customize your environment. Although understanding Visual Basic code makes customization easier, it is not a requirement. The following tools are available to help you define code in your customizations: •

Custom Object Explorer: Code snippets in the Object Explorer assist in writing the VB.NET subroutines necessary to complete customization projects. The objects of the explorer are broken into three groups: Data Objects display the EpiDataView object. EpiDataViews encapsulate all the data captured at a specific moment in time from within any application table. UI Objects are objects on the forms that open for a program. Data Adapters are bridges between datasets and data sources. Without an adapter, a dataset cannot access a data source.

•

Assembly Reference Manager: This allows you to quickly locate and add custom assembly references to a customized form. Specifically, assembly references are necessary when calling an adapter from another table in the application.

•

Script Editor: A form's original code displays along with code from any customizations on file. Everything about the form displays within this tool. Use the Script Editor to add additional code to a form for special procedures.

•

Tracing Log: This is a tool that has several uses. Web service developers can use this log to see what business logic calls are being made when users launch a specific function, for example, the BL calls made when a user enters a new customer record. Custom programmers can use this log to fine-tune their customized applications.

Please take a moment to let Epicor know how to serve you better by completing a course evaluation at http://www.keysurvey.com/survey/191084/2e21/ or by clicking the Course Evaluation link below. Your feedback provides the guidelines for the future direction of Epicor education.

Epicor Software