User Portal Developer's Guide

Transcription

1 User Portal Developer's Guide

2

3 User Portal Developer's Guide

4 NOTICE This material is for informational purposes only. Navision a/s disclaims all warranties and conditions with regard to use of the material for other purposes. Navision a/s shall not, at any time, be liable for any special, direct, indirect or consequential damages, whether in an action of contract, negligence or other action arising out of or in connection with the use or performance of the material. This material is subject to change without notice. According to Danish copyright legislation it is against the law to reproduce any part of this material in any form or by any means without the permission of Navision a/s. The software described is supplied under license and must be used and copied in accordance with the enclosed license terms and conditions. COPYRIGHT NOTICE Copyright 2002 Navision a/s, Frydenlunds Allé 6, 2950 Vedbaek, Denmark. All rights reserved. TRADEMARKS The trademarks referenced herein and marked with either TM or are either trademarks or registered trademarks of Navision a/s or Navision Development a/s. However, the trademarks Microsoft, Windows, Windows NT, SQL Server and BackOffice are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Any rights not expressly granted herein are reserved. The trademarks of Navision a/s and Navision Development a/s are listed on this Web site: The Arial font was used. Published by Navision a/s. Published in Denmark DocID: AT-360-DVG-006-v01.00-W1W1

5 TABLE OF CONTENTS CHAPTER 1. INTRODUCTION About User Portal Developer s Guide User Portal Overview Folder Structure 1-10 CHAPTER 2. DESIGN AND DEVELOPMENT WORKFLOW Designing the Web User Experience A User-Centered Design Process Discovering and Understanding the Roles Interpreting Findings Vision Changing Work Practices Organizing Work Activities Interface Prototyping Design Walk-Through Designing and Developing 2-12 CHAPTER 3. USER INTERFACE The General Layout Navigation 3-7

6 TABLE OF CONTENTS 3.3 Business Object Views Task Views 3-20 CHAPTER 4. USER PORTAL APPLICATION SERVER Overview User Portal Features in the Object Designer Creating User Portal Dataports Exporting and Importing Data Issues Regarding Web Enablement 4-22 CHAPTER 5. FROM QUERY TO USER INTERFACE Introduction Web Part Framework Web Part Handlers User Portal Business Object XML Documents Search Handlers 5-17 CHAPTER 6. WORKING WITH USER PORTAL Enabling Search and Lookup Updating the Recently Visited Menu 6-5

7 CHAPTER 7. EXERCISES Overview Preparing a New Activity Center Developing a New Dataport for User Portal Enabling Search and Lookup Developing a Web Part Handler Developing the Job Overview Web Part Developing the Job Create Web Part Developing Support for Comments 7-48 APPENDIX A. DEBUGGING USER PORTAL A-I APPENDIX B. USER PORTAL BASIC TERMINOLOGY LIST B-I APPENDIX C. META USER INTERFACE REFERENCE GUIDE C-I APPENDIX D. REFERENCES D-I

8

9 PREFACE This course is a independent course in the Navision Attain curriculum and is designed for students who have passed the Navision Attain Overview Test and want to learn more about User Portal for Navision Attain. The following diagram shows all the courses in the Navision Attain training curriculum:

10

11 Chapter 1. Introduction This chapter is an introduction to User Portal and the User Portal Developer s Guide. You will learn about the overall structure of the User Portal Developer s Guide, the basic concepts of User Portal, and a description of the folder structure that is necessary in order to use User Portal. The chapter contains the following sections: About User Portal Developer s Guide User Portal Overview Folder Structure

12 1-2 User Portal Developer's Guide 1.1 ABOUT USER PORTAL DEVELOPER S GUIDE The User Portal Developer s Guide describes and teaches how to develop User Portal solutions for Navision Attain. It can be used as an instructorled course, and as self-paced study for consultants and developers with experience in web technology, C/SIDE and C/AL. Course Organization The course consists of the following chapters: Chapter 1: Introduction Business Analyst Part Chapter 2: Design & Development Workflow Chapter 3: User Interface Developer Part Chapter 4: User Portal Application Server Chapter 5: From Query to User Interface Chapter 6: Working with User Portal Chapter 7: Exercises The chapters consist of instructional text that describes different aspects of User Portal and provides examples about how it works. The last chapter consists of exercises that allow you to practice. In addition to the chapters, a number of appendices offer you additional guidance and information: Appendix A: Debugging User Portal Appendix B: User Portal Basic Terminology List Appendix C: Meta User Interface Reference Guide Appendix D: References

13 Introduction 1-3 Target Audience This course is intended for people in Navision Solution Centers who will work as User Portal consultants. The course is developed for two target audiences. The first part of the course is targeted at Business Analysts, and the latter part is targeted at developers. Course Prerequisites All participants must have passed the Navision Attain Overview Test. Developers must be experienced with C/AL, C/SIDE and dataports. Developers must be familiar with the concepts and terminology behind Microsoft Digital Dashboard, Microsoft Windows 2000, Microsoft Internet Information Services, VBScript, JavaScript, XML and XSL. Course Objectives The course is designed to build product knowledge required for you to work as a User Portal consultant, a business analyst or as a developer. Course Overview Before you begin this course, you must have installed User Portal for Navision Attain and User Portal Application Server as described in the User Portal Installation Guide. Business Analyst Part Chapter 1, Introduction, provides an introduction to the key concepts in User Portal Developer's Guide and to the basic architecture of User Portal. Chapter 2, Design & Development Workflow, gives you an overview of the phases you go through as a business analyst, from the first visits at the customer site to the completion of the design through development completion. Chapter 3, User Interface, gives you an overview of the elements that form the user interface.

14 1-4 User Portal Developer's Guide Developer Part Chapter 4, User Portal Application Server, teaches you how User Portal Application Server uses dataports to import and export data. Chapter 5, From Query to User Interface, describes the processes involved in retrieving data from Navision Attain and presenting it in the user interface. You learn how to use and create Web part handlers and the Web part framework. Chapter 6, Working with User Portal, provides you with an overview of how to perform common tasks as a User Portal developer. Chapter 7, Exercises, contains exercises allowing you to practice developing User Portal solutions. Course Duration The course can be conducted in one day. We recommend that course participants receive the User Portal Developer s Guide prior to the class. The User Portal Developer s Guide can serve as self-paced training for skilled developers. Dates The dates in the course material are in the American format. In order to avoid confusion when reading the material and following the exercises, it is a good idea to change the date format in your operating system before starting the training session. In Navision Attain, the working date is set to be 01/25/01 (January 25, 2001). It is important that this date is used when doing the activities. Demonstration Data All exercises refer to a fictitious company, CRONUS International Ltd., based on the demonstration data available in the demo database installed with Navision Attain (W1). License Information To run the development exercises in this course, you need a developer s license.

15 Introduction USER PORTAL OVERVIEW User Portal is a Web solution that gives users a single point of entry to personal, team, corporate and external information. User Portal enables users to access Navision Attain data from a Web browser, utilizing the latest Navision technology and functionality from Microsoft Digital Dashboard. User Portal is part of the e-business strategy of Navision a/s to Web-enable Navision products. User Portal makes it easy for users to access data in Navision Attain, no matter where they are working. Remote users, such as traveling sales representatives, can immediately access their personal activity pages. User Portal delivers all the critical information users need to their own activity page, helping them become more productive. All that is needed is access to a browser (Microsoft Internet Explorer 5.o or later). With User Portal, users can have access to all information that supports the roles they play in their organization. They can initiate searches for relevant role-based information from any source. For example, when a sales representative needs information on customer accounts and sales history, he can easily access the relevant and up-to-date information from Navision Attain. User Portal enables users to tailor their personal home page to fit their needs. They can select from available Web parts, such as stock tickers, recent business news and Navision Attain Web parts. Navision Attain Web parts can also be personalized so that, for example, a user can see both the standard Item Sales Top 10 and the personalized My Item Sales Top 10. Digital Dashboard User Portal is based on the Microsoft Digital Dashboard framework. A digital dashboard is a powerful tool that knowledge workers can use to view their daily activities, collaborate with coworkers and gain insight into the performance of the company. It ensures that knowledge workers have the information they need to properly assess and act upon business opportunities. The digital dashboard concept is derived from the dashboards found in real life. For example, cars and airplanes have dashboards that aid users in driving a car or flying a plane safely. When you are in the role of a driver, you need to be able to monitor speed, gas level, and engine temperature whereas pilots also need to monitor the altitude, for example. So the

16 1-6 User Portal Developer's Guide dashboards are equipped with carefully designed gauges and controls that aid the user in performing the tasks relevant to their role. Before the gauge is designed and physically placed on the dashboard, the relevant roles are analyzed thoroughly in order to gain knowledge about the workflow and tasks involved in each role. This information is also used to decide how to group the different gauges on the dashboard. Also digital dashboards are designed to support a role. The available gauges are called Web parts and instead of monitoring speed and altitude, they monitor business data, specific tasks and other relevant information. As with physical dashboards, you need to go through a predesign analysis identifying the roles and their workflows when you are developing digital dashboards. In User Portal, digital dashboards are used to create activity centers. Activity Center An activity center contains all the links and views a user needs when acting in a certain role. All users have the same Home activity center. In addition to that, you have one activity center for each role you are assigned to. This way you are only presented with tasks relevant for the role you are currently in. An activity center contains an assortment of Web parts organized in views, and will typically contain the user's predefined application role menu called My Frequent Tasks. This menu provides links to other views and tasks such as My Customer Sales Top 10 and Search. As an administrator, you can both add activity centers to a user and remove activity centers. For more information, see the manual User Portal Installation Guide. Web Parts The Web parts are the gauges on the dashboards. In other words, activity centers are made up of Web parts. Once a Web part has been designed, it can be reused in different activity centers. Web parts are components that contain any kind of Web-based technology. As described earlier, they are Microsoft Digital Dashboard s way of modeling gauges from a real-world dashboard. For example, a speedometer would be considered one Web part.

17 Introduction 1-7 Web parts are used to add functionality to the activity centers. Some web parts are used to add the functionality needed to navigate between the activity centers. Others add general or specialized functionality to an activity center, such as My Frequent Tasks, Recently Visited and Search. These Web parts add general functionality to an activity center and are similar to those you find on most Web sites. Other Web parts are highly specialized for one activity center and produce specific business object views. Definition of Business Objects and Views A business object is an object in the program that is defined in terms of the business domain it relates to and not from the programming perspective. For example, a sales order is a single business object that is made up of two different table objects (the Sales Header table and the Sales Line table). A view is an area that contains data related to a single business object. The types of views that reflect the level of detail are: Overview view, Details view and Related views. Using Views Some of the business object views in User Portal for Navision Attain are listed below: Contact Customer Item Purchase Order Sales Quote Sales Order Vendor The views are used to build the basis for the activity centers. They all communicate with Navision Attain and administer how the data is presented to the user. To some extend, you can think of these views as the Web equivalent of a card form in Navision Attain, with the exception that

18 1-8 User Portal Developer's Guide the view includes only the fields needed to perform a specific task. Other Business Object views can to some extend be thought of as reports and are used to display lists of filtered and sorted data, for example My Recent Contacts and My Customer Sales Top 10. Web parts can also contain information from other sources, for example, stock tickers, Microsoft Outlook, Microsoft NetMeeting and Web sites with recent business news. System Architecture User Portal uses the Dataport feature in Navision Attain as a gateway for inbound and outbound data. In order to facilitate this, User Portal Application Server acts as a middletier data server for the Web server application responding to requests for data and processing updates. Data and updates are exchanged as XML formatted messages. The figure below outlines the system architecture for User Portal: Client Microsoft Internet Information Server (IIS) Microsoft Digital Dashboard Database Server XSL DDB VBScript User Portal Application Server Microsoft Internet Explorer 5.5 XML DWP JavaScript Navision Attain As a developer, you will be creating dataports in User Portal Application Server in order to import and export data in XML format. You will also be creating Web part handlers in XML format and XSL style sheets that together will form the basis for displaying the data in a browser. As a business analyst, you will observe and analyze how the user works in order to determine which data to present when.

19 Introduction 1-9 Data Flow The following diagram shows how a request from the user interface (a browser) is converted into a query and how the data is returned to the user interface. Chapter 5 describes this scenario in greater detail.

20 1-10 User Portal Developer's Guide 1.3 FOLDER STRUCTURE On the Web server, there are some folders that are particularly relevant for developers. This section highlights the most important folders for User Portal development. For a detailed description of the folder structure, refer to Microsoft Digital Dashboard documentation. Important You must use the naming conventions described in the following section to make it easy to maintain and administer your User Portal solutions. This means that you must not change the default folder names when you install Microsoft Digital Dashboard. NSWebParts The NSWebParts folder is used to store all the Web part handlers and definitions of views. They are all stored in the root level of the folder. You should refer to this folder when you add a Web part from the Microsoft Digital Dashboard administration. Factory The Factory folder is used to store files used internally by User Portal and Microsoft Digital Dashboard to generate the portal. Most of the files relate to the digital dashboard. For example, the Factory folder stores the Business Object Processor which controls communication between Navision Attain and User Portal, the Renderer that renders XML and meta UI into HTML pages, cascading style sheets and image files that are used to create the overall layout of User Portal. You will rarely need to access this folder. Dashboards The Dashboards folder is used to store definitions of digital dashboards. You will not usually need to access this folder and its subfolders. Most of the files in this folder structure are empty files, but they have properties that are visible to Microsoft Digital Dashboard. The folders and

21 Introduction 1-11 their contents can be created from the digital dashboard administration but not from Windows Explorer, for example. Users The Users folder contains a folder for each user. In each user s personal folder, there is a folder for each activity center that the user has access to. Forms The Forms folder contains definitions for the views that form the basis for User Portal. Each folder relates to a specific view that can be displayed in the digital dashboard. The contents of this folder correspond to the Web parts that make up the view. The views are configured during installation but they can be changed later from the Digital Dashboard administration. Parts The Parts folder is used to generate the Web part catalog. The user can access the Web part catalog from the Personalize menu in order to add Web parts to their activity pages. Welcome The Welcome folder contains the standard Digital Dashboard Welcome dashboard and an Administration dashboard that can be used to administer digital dashboards and Web parts.

22

23 Chapter 2. Design and Development Workflow This chapter contains an introduction to the User Portal design process and to the user-centered design principles upon which the process is based. The chapter contains the following sections: Designing the Web User Experience A User-Centered Design Process Discovering and Understanding the Roles Interpreting Findings Vision Changing Work Practices Organizing Work Activities Interface Prototyping Design Walk-Through Designing and Developing

24 2-2 User Portal Developer's Guide 2.1 DESIGNING THE WEB USER EXPERIENCE Introduction The User Portal design and development workflow is in many ways different from the way Navision Attain is traditionally designed and developed. Not only has the technology changed from software application to Web-enabling an existing application, but the user groups have also changed. This presents you with many new challenges, such as the following: Designing for the Web, as opposed to a Windows application. Designing for different roles, tasks and goals, as opposed to designing just forms and tables. Designing for a new target group. Designing for walk-up usage. These key issues are outlined in the following section. Web Design The Web enablement of Navision Attain opens up many new opportunities within the design and development area. You face the challenge of creating a Web user experience that is different from the present Windows-based graphical user interface guide. You can find this guide on the Navision Attain product CD (NAGUIGuide.exe). Furthermore, the current Windows functionality does not differentiate between roles, whereas User Portal allows a high degree of personalization. Using the Web as a communication device will also affect the way in which the end-user will use and perceive the product in the future. High usability and effective design are therefore essential when designing for the Web. Roles, Tasks and Goals User Portal is role and task based, which means that it is focused on the tasks and goals defined for the different roles in order to achieve their daily work. The underlying design idea is that a user portal should be perceived as a tunnel. This means that the user initially has several tasks to choose from, but when he chooses one task, the possibilities narrow down to a

25 Design and Development Workflow 2-3 limited number of functionalities that are specifically related to that role. The tunnel metaphor allows users to perform one task at a time with each click reducing the possibilities and leaving only the core functionalities. If we want to support the user s task performance and goal achievement, it is crucial to involve the users early in the project cycle and keep them involved throughout the process to ensure that the new user portal supports the role s daily workflow efficiently. The new design challenge is to move the attention away from forms, windows and tables and move it towards user roles, tasks and goals. New Target Group User Portal addresses a new target group not previously focused on by to Navision Attain. These are novice or casual users that may have limited or no experience using Navision Attain, who would benefit from having (remote) access to limited functionalities. Walk-Up Usage Another challenge is to deliver walk-up usability for the Web interface where the user is not required to have previous training in the user interface. Basically, the aim is to provide intuitive navigation based on the typical user s prior Web experiences and work skills that allow the user to immediately access and understand the logic of the system. Note that the links and headings are more descriptive and carry more information than traditional applications in order to ensure good performance in a welldesigned task environment. Conclusion One of the primary concerns is to meet the user s expectation of a usable and useful product that enriches the final user experience. The design activities outlined in the following storyboard can assist you in identifying the focus areas and activities needed in each design phase. The storyboard is not a methodology for general analysis and design, but a specialized version tailored for User Portal.

26 2-4 User Portal Developer's Guide 2.2 A USER-CENTERED DESIGN PROCESS Storyboard 1. Discovering and understanding the roles. See section Interpreting findings. See section Vision - changing work practices. See section Organizing work activities. See section Interface prototyping. See section Design walk-through. See section Designing and developing. See section 2.9.

27 Design and Development Workflow DISCOVERING AND UNDERSTANDING THE ROLES Introduction Products influence and change users work performance. In order to design a usable and useful user portal, you need to understand what the users are doing today. This includes their goals, tasks, breakdowns in their workflow and their workarounds. This will allow you to improve their work practice and support their overall goals. Why? The goals of this step in the design process are: To understand what matters to the user today. To identify what the most important aspects of the work are and what duties are considered peripheral. This information is important in order to be able to identify the main business objects and core functionalities later on in the design process. To provide a reason why and how a new product is relevant to the user. How? You should conduct contextual inquiries with different users performing the same role. A contextual inquiry is a site visit, which is a method inspired by ethnographical fieldwork. It combines observation and interviewing techniques to gather user data for the design process while the user is working in his or her usual work environment. When you gather user data, it is crucial not to make any prejudgments or interpretations. We recommend one to two hours of contextual inquiry per user. Observe, listen, take notes and ask the users questions while they work within their own context to see how they perform their job and to identify the complexity of their different roles. By observing and listening to the user, you will be able to identify and understand the user s current work practice and have a thorough understanding of what the user is doing, how they do it and the obstacles they may face. Before finishing the inquiry, sum up your findings so the user may correct any misunderstanding or expand on an unresolved issue. It is from these inquiries that you receive the raw user data that is of so much value

28 2-6 User Portal Developer's Guide throughout the design phase. Suggested Focus Areas The following areas are of special interest: Different tasks and goals What matters to the user role? Communication and coordination strategies Workflow breakdowns Problem solving strategies Resources Cultural issues Working environment Business rules and values User s own perception What did the user say and do, any conflicts? Critical Success Factor User involvement.

29 Design and Development Workflow INTERPRETING FINDINGS Introduction When you have conducted a contextual inquiry, it is important to translate and interpret the data collected during the contextual inquiry into design issues and considerations. Take care to distinguish between observations from the field and your own interpretations. By examining the different users' profiles, you will gain a broader knowledge of the different user roles. Why? The goals of this step in the design process are: To gain an overall picture of what matters to a cross-section of users. To identify the most critical work and design issues. How? There are no prescribed ways of interpreting the findings. We recommend representing the interpretations visually, for example using models. Ideally, you should interpret the data on the day of the inquiry based on the interviewer s memory and hand written notes to make sure that you will not forget details of the user s work situation. This way, the findings will be easy to share with others and this will save you time. You might find it necessary to refocus business goals and gather more detailed role data. Methods The following are tools that you can use at this step of the process: You can write the user s overall goal and the tasks needed to accomplish it, including the different workflow breakdowns. You can try to visualize the flow of information and coordination needed to accomplish a workflow between different users. You can portray the necessary resources and how they are organized. You can try to find patterns for a cross-section of users within the same role. Here you gather the many open issues on small note cards and organize them in a diagram revealing common issues and themes across multiple user roles. The hierarchy is built on a bottom-up structure.

30 2-8 User Portal Developer's Guide 2.5 VISION CHANGING WORK PRACTICES Introduction Now it is time to be innovative and visionary based on the previous interpretation and consolidation phase. This is not a contradiction in terms because we do not reproduce the user s current work practice. Rather, we use the user s present situation as a gateway to gain access to the overall patterns and goals. In other words, the purpose is to ensure that the new system matches the user s logic to the extent of allowing the user to make the necessary transition. The technical solution does not form part of the vision yet, because the purpose of the vision phase is to come to a common agreement on how we want the user s current work practice to be changed. Be creative! In order to be innovative, it is important to get far-fetched ideas, some of which may not be realistic to implement. But these unrealistic ideas might generate other valuable ideas. The final goal is to arrive at a shared vision of how to redesign work practice. How? The visions are gathered as a traditional brainstorm of ideal usage scenarios. Basically, the designer, or team, generates multiple visions that are evaluated for their positive and negative aspects and then consolidated into one shared vision containing all the positive aspects gained from the different ideas. The final vision is then made more concrete through a storyboard illustrating how the vision is going to influence the user s routine life practice showing how it relates to the user s working environment and not only the system. Avoid too many detailed interface screen shots at this early stage. Methods The following are tools that you can use at this step of the process: Develop and write a vision Set up a storyboard

31 Design and Development Workflow ORGANIZING WORK ACTIVITIES Introduction Having drawn the vision on a storyboard, it is now time to organize and structure the Web site to support the different work activities found. If the goal is to provide intuitive navigation, we must complete this phase before designing the actual screen shots. The phase focuses on obtaining an overview of the different work areas at a conceptual level. Why? The goals of this step in the design process are: To be able to provide intuitive navigation. To get an overview at a conceptual level of the site structure. To show the focus areas and functions necessary to do the work. How? Architects need to have the overall picture of a house before designing, for example, a front door. In the same way, you want to map out the work activities from the vision into a high-level architecture, categorizing the sites by their focus areas and not the actual page title. In this way, you are able to get a quick overview of the focus areas, the inherent goals and functions supported early in the design process. Method Outline a high-level plan of the architecture.

32 2-10 User Portal Developer's Guide 2.7 INTERFACE PROTOTYPING Introduction You are now ready to draw rough sketches on paper of the interface and come up with some interface prototypes that you can show and test with users in their own environment. The key issues in this step of the process are: Proof of concept Challenge the underlying logic and structure. Does it correspond to user tasks and goals? Is it intuitive? Will the user be able to use it right away? Is the user able to use it in their daily workflow? What are the most critical aspects of the current design? What do the users expect at each action? Method Use low-tech material, such as paper interface prototypes, to sketch potential interface prototypes. Critical Success Factor User feedback based on rough paper prototypes, screen shots or tests of the system are critical for success. The users can tell you if you have reached your goal. Test the paper prototype in the user s own environment to see if it helps daily work.

33 Design and Development Workflow DESIGN WALK-THROUGH Introduction Having designed the screen shots, it is once again time to look at the big picture to see if the new work practice corresponds to the site structure, the business object views and task pages. How? Map out a flow chart using the screen shots. This provides you with an overall view of the navigation, structure and tasks. Invite colleagues to a walk-through of the flow chart. It is a good idea to attach comments, changes or other suggestions on Post-It notes on each screen shot for further improvement. Challenge the design by testing prototypes (drawing on paper, screen shots or on the system) with users. You may want to let the user go through the different tasks and see whether they suit the user s expectations. Methods Tools that can help you at this step in the design process are: Low-tech material such as paper drawings and Post-It notes Design walk-through Flow chart Critical Success Factors It is critical that you demonstrate the walk-through for persons not directly involved in the design process. You should invite at least one colleague to a walk-through of the flow chart. User involvement is recommended, but not a requirement. The critical success factor is that someone other than the designer takes part.

34 2-12 User Portal Developer's Guide 2.9 DESIGNING AND DEVELOPING Introduction You are now ready to develop a user portal for each role that you have identified. The rest of the User Portal Developer s Guide will help you through this process. If you have any doubts about anything related to a role s workflow or the navigation structure, it is still a good idea to get user feedback, go through earlier user data or to some degree develop and design in collaboration with the user through Joint Application Sessions. Method Read the User Portal Developer s Guide and use it to understand the process. Critical Success Factors Design and development iteration Reality check though user feedback

35 Chapter 3. User Interface In this chapter, you learn about the design of the user interface. First, a description of the general layout of the user interface provides you with an overall understanding of the layout. Secondly, we describe the layout and use of the different navigation areas to give you an understanding of how these areas are used. Finally, you can see a description of the layout and use of the views used to display the actual data. You can use these design guidelines early in the design phase, for example, when you interpret your observations at the user site, or when you make prototypes. The guidelines are also helpful during the final design phase. The chapter contains the following sections: The General Layout Navigation Business Object Views Task Views

36 3-2 User Portal Developer's Guide 3.1 THE GENERAL LAYOUT The layout of the User Portal pages is rigidly structured. All pages have four areas in common: logo area, global navigation area, title area, content area and local navigation area. The following diagram shows the layout of a typical page: Global Navigation Area Title Area Local Navigation Area Content Area Logo Area Global Navigation Area The global navigation area is placed at the top of the screen and contains links to the activity centers that this user has access to. The content of this area is always the same for a user. In the example above, the global navigation area contains links to Product Design and Sales. The activity center Product Design has the highest

37 User Interface 3-3 priority for this user, so it is listed as the first activity center from the left. Sales has second priority and is placed to the right of the primary activity center. Title Area The title area contains the title for what is currently shown in the content area. The title area is placed at the top of the browser window, just below the global navigation area. In the example, the title area displays the ID of Customer 1000, The Cannon Group PLC:

38 3-4 User Portal Developer's Guide Content Area The content area contains the various Web parts that constitute the page. In the example, the content area displays the overview of a sales order:

39 User Interface 3-5 Logo Area The logo area is used for placing your customer s logo and links to other related information. The logo is placed on the lower left-hand corner of the screen and is always displayed no matter which activity page is open. In the example, the logo area displays the logo for CRONUS International Ltd.:

40 3-6 User Portal Developer's Guide Local Navigation Area The local navigation area is placed in the left-hand side of the screen and contains a Search function and menus with links to other pages. The Search function and menus depend on the Web parts that make up the content area. In the example, the local navigation area displays Search and three different local navigation menu groups: These menus and Search are explained further in section 3.2.

41 User Interface NAVIGATION The users navigate User Portal by following links from their activity centers and from the global and local navigation areas. The global navigation area was described in the previous section. Activity Centers A user portal consists of one or more activity centers. Each activity center relates to a particular role and incorporates the activities related to that role. A role can have more than one activity center. In the following example, the user has access to two activity centers, Product Design and Sales, as shown in the global navigation area: The content area of an activity center consists of Web parts and the user can personalize the content and the layout of each activity center. The Web parts can come from different sources, for example Navision Attain and Microsoft Outlook or from information providers on the Internet. User Portal comes with three generic Web parts: My Frequent Tasks Web Part Folders Recently Visited

42 3-8 User Portal Developer's Guide My Frequent Tasks The My Frequent Tasks Web part contains links to the most frequent tasks that the user performs within an activity center. The user can add a task to the list by clicking the Add This Task to My Frequent Tasks link that is added to the Personalize menu whenever a task is shown. Web Part Folders A Web part folder is a Web part that displays a group of tasks. In the example above, Product Design Categories and Product Design Tasks are Web part folders. They are set up in Navision Attain as described in the manual User Portal Installation Guide. Recently Visited The Recently Visited list is updated automatically and provides a history of data items that you have accessed most recently. In User Portal Application Server, you can set up the maximum number of links that will shown in this list. The default value is 5. The Local Navigation Area The local navigation area currently consists of the following components: Search Browse [Business Object] See Also Common Tasks Other Tasks Note A business object is a logical grouping of Navision Attain objects, so that User Portal refers to business domains rather than to programming objects. For example, a sales order is a single business object that consists of two different table objects (the Sales Header table and the Sales Line table).

43 User Interface 3-9 For more information about how to create the menu groups in the local navigation area, see section C.6 in Appendix C. Search [Area] The Search function is context sensitive which means that the search is scoped to search the relevant area within the user portal. For example, if the user is currently working on a sales order, then Search will operate within the scope of that business object. In the example above, the user is working in the Sales activity center, so Search would operate within the Sales area. All pages should have the Search function enabled. However, there are certain task views where Search is not relevant. The scope of the search must be indicated in the title of the Search function, for example Search Sales Orders, Search Customers or, as in the example below, Search Items: The user cannot change the scope of Search. Browse [Business Object] The Browse menu group is used to change the view of the current business object. When a business object is displayed, there must be a Browse menu group allowing alternative views of the business object.

44 3-10 User Portal Developer's Guide The following example shows the Browse Order menu group: The Browse [Business Object] menu group is context sensitive, so the number of links in the menu group depends on what is in shown in the content area. Links that refer to another business object and not to another view of the current business object, are placed under the heading See Also.

45 User Interface 3-11 Common Tasks The Common Tasks menu group offers links to the tasks that the user will perform most often with the current business object. On task pages, use the Common Tasks menu group to provide the user with links to tasks that could be necessary in order to complete the current task. Do not provide access to tasks that are not related to the current task. Other Tasks The Other Tasks menu group contains links to less typical tasks that can be performed by the user with the business object currently displayed. On task pages, use the Other Tasks menu group to provide the user with the ability to perform tasks that could be necessary in order to complete the current task. Do not provide access to tasks that are not related to the current task.

46 3-12 User Portal Developer's Guide See Also Use the See Also menu group to display links to other business objects related to the current business object. Place the link in the Browse [Business Object] menu group if the link refers to another view of the current business object and not to another business object.

47 User Interface BUSINESS OBJECT VIEWS Information is presented and data entered in views that consist of a number of interface elements presented together on the screen. These elements include fields, labels, groups of fields and lists of related information. Views can be divided into two main groups: Business Object Views for presenting information Task Views for creating or editing business objects Task views are described in section 3.4. Definition of Business Object Views Information about business objects such as customers and sales orders is displayed in business object views. A business object view defines how the elements that comprise the view are arranged and viewed together. Four view modes are currently defined for business object views: Business Object View Mode Overview Details View Related Details View Report View Description Shows just the overview details about a business object Shows the relevant details about a business object Shows the related details about a business object Shows report information related to the current business object The following sections describe how a business object view is presented in each view mode.

48 3-14 User Portal Developer's Guide Overview View Mode The Overview view mode shows the primary details (the ContentBlock element of the XML document, as described in Appendix C) of a business object in a single section. It resembles the General tab of a card form in Navision Attain. Title The title is displayed in the title area and browser title bar according to the following template: Format [Type] [No.] [Description] Example Item 1000 Bicycle Global Navigation Area Contains links to the activity centers that the user has access to.

49 User Interface 3-15 Local Navigation Area In Overview mode, the local navigation area can contain the following functions and menu groups in the order described in the following table: Element Search [Area] Browse [Business Object] Common Tasks Other Tasks See Also Specification The default scope of the search function is the category of the displayed business object. Always display this function. This menu group contains links to selected detail information about the business object. Always display this menu group. This menu group contains links to the most frequent tasks related to the current business object. Always display this menu. This menu group contains links to less frequent tasks related to the current business object. This menu group contains links to information about other business objects related to the current business object. Do not place links to information that is directly related to the current business object in this menu group. Content Area Display the most basic information about the business object in one Web part in the content area. Display the Web part without frames and give the information the heading Overview. Details View Mode The details view shows the detail elements (multiple ContentBlock elements of the XML document as described in Appendix C), one below the other. This is like placing all the tabs of a Navision Attain card form on one page.

50 3-16 User Portal Developer's Guide You should only display the information that is relevant to the user in the given context, not all available information about a business object. Title The title is displayed in the title area and browser title bar according to the following template: Format [Type] [No.] [Description] Example Item 1000 Bicycle Global Navigation Area The specifications are the same as for Overview. Local Navigation Area The specifications are the same as for Overview. Content Area Display all the detail information about the business object except reports. Give the information the heading Details. Each ContentBlock element (except the first one, containing the basic information) is given a heading that describes the content. If a ContentBlock element is empty, display the heading and the following text: There are no [type] for this [business object]. Display the Web part without frames.

51 User Interface 3-17 Related Details View Mode In the related details mode, the user selects to view a related details list from the local navigation area. The related details list can be a list of orders for that customer, as shown in the following example: At the top of a Related Details view, you must have a summary based on the Summary element in the XML document as described in Appendix C. This summary is a header that identifies the list contents. The list is based on the ContentList element in the XML document and contains a list of related rows. Place links to related details in the Browse menu group. Remember that the Browse menu group relates to the current business object and See Also relates to other business objects. Title The title is displayed in the title area and browser title bar according to the following template: Format [Type] [No.] [Description] Example Customer The Cannon Group PLC Global Navigation Area The specifications are the same as for Overview.

52 3-18 User Portal Developer's Guide Local Navigation Area The specifications are the same as for Overview. Content Area Give the content area a heading that describes the information, for example, Orders, Comments or Ledger Entries. Display basic information about the business object, for example customer number, name and phone number, as a header for the information. Display the lines of information in a table below the header. Do not provide a caption for the table. Report View Mode Use a report page to display a Navision Attain report. Links to reports are placed in the Common Tasks menu group and Other Tasks menu group.

53 User Interface 3-19 Title The title is displayed in the title area and browser title bar according to the following template: Format [Name of report] Example Customer Sales Top 10 Global Navigation Area The specifications are the same as for Overview. Local Navigation Area The specifications are the same as for Overview. Content Area Displays the pages of the report. When there are more pages to display, navigation buttons are automatically added to the page.

54 3-20 User Portal Developer's Guide 3.4 TASK VIEWS As described in section 3.3, Business Object Views are used for presenting information, while Task Views are used for creating or editing business objects Definition of Task Views Task views allow the user to create new business objects or to modify or delete existing business objects. Action buttons that allow the user to complete or cancel the task are automatically added at the bottom of the content area. Task views have the following view modes: Task View Mode Description Create [Business Object] View object Task View Mode Create [Business Object] View Edit View Delete View Search Results View Allows the user to create a business Description Allows the user to create a business object Allows the user to edit a business object Allows the user to delete a business object Displays the result of a search in the current business object.

55 User Interface 3-21 Create [Business Object] View Mode Use a Create view to let the user create a new business object or part of a business object. Title The title is displayed in the title area and browser title bar according to the following template: Format [Action] [Type] Example Create Customer Global Navigation Area The specifications are the same as for Overview. Local Navigation Area The local navigation area can contain the following function: Element Personalize Specification Default link: Add this task to My Frequent Tasks.

56 3-22 User Portal Developer's Guide Content Area Display the Web parts without frames. If the business object consists of a header part and a table part, display the header part in edit mode and the empty table part in display mode. The user can only edit the header part. A Create and a Cancel button are automatically placed at the bottom of the page. Edit View Mode Use Edit views to let the user change information about business objects. Title The title is displayed in the title area and browser title bar according to the following template: Format [Type] [No.] [Description] Example Customer The Cannon Group PLC Global Navigation Area The specifications are the same as for Overview.

57 User Interface 3-23 Local Navigation Area The specifications are the same as for Overview. Content Area Display the web part without frames. If the business object consists of a header part and a table part, display the header part in read-only mode and the line part in edit mode. The user can edit or delete a line by clicking the edit or the delete option for the line. The user can create a new line by clicking the Create [Type] Line in the Common Tasks menu group in the local navigation area. A Change Now and a Cancel button are added automatically to the page. Delete View Mode If a user clicks Delete, a message box with the following content is displayed: Delete [Type]? Ok, Cancel

58 3-24 User Portal Developer's Guide Search Results View Mode Search results are displayed in a standardized list as shown here: Title The title is displayed in the title area according to the following template: Format Example Search Results for [search string]. Search Results for Chain Global Navigation Area The specifications are the same as for Overview. Local Navigation Area The local navigation area can contain the following function: Element Search [Area] Specification The scope of the search function is the same as for the original search, that is, the same business object. Always display this function. Content Area Displays the search result. Navigation buttons are added when needed.

59 Chapter 4. User Portal Application Server User Portal Application Server is a middle-tier server that exports data from and imports data into Navision Attain so that you can access Navision Attain from a Web browser. User Portal Application Server uses dataports to handle the transformation of XML data into Navision Attain data and vice versa. This chapter contains the following sections: Overview User Portal Features in the Object Designer Creating User Portal Dataports Exporting and Importing Data Issues Regarding Web Enablement

60 4-2 User Portal Developer's Guide 4.1 OVERVIEW User Portal Application Server is the link between Navision Attain and User Portal. It uses dataports to transform XML data into Navision Attain data and transform Navision Attain data into XML data. User Portal Application Server is installed as a client on the computer that stores your Microsoft Internet Information Server, and it is given the runasupas program property to convert the client into User Portal Application Server. You access the application server user interface by clicking Start, Programs, Navision Attain, Navision Attain or Microsoft SQL Server Option for Navision Attain, unless you have renamed the shortcut as described in the manual User Portal Installation Guide. This means that you will not see a service or program called User Portal Application Server on your server computer. You will see a Navision Attain client, but when you start this client with the runasupas program property, the client is converted into a User Portal Application Server. However, you will still see it listed as Navision Attain in the registry and elsewhere. You can send a query in XML format from a user portal to the dataport in User Portal Application Server, which then returns XML formatted data to the portal. You can also send an update request (Insert, Modify or Delete) to the dataport that will then return an XML formatted response. Error messages are returned in separate XML responses. For more information about XML, see Chapter 5 and Appendix C.

61 User Portal Application Server USER PORTAL FEATURES IN THE OBJECT DESIGNER User Portal Application Server acts as a client towards the database server and as a server towards a user portal. To do that, User Portal Application Server uses special features in the following areas of the Object Designer: Dataport properties Dataport data item properties Dataport field properties C/AL functions The following subsections describe those Navision Attain features that User Portal Application Server uses in more detail. Dataport Designer In Navision Attain, the Dataport Designer is set up so that you can design User Portal dataports. This means that you can indent data items so that whenever the data item on the first level is executed, the data item on the second level is also executed. The buttons used to indent or unindent a data item are always visible in the Dataport Designer, but only dataports where the file format is set to UPXML can be compiled with indented data items. Dataport Properties The FileFormat property now has a UPXML option. To allow the dataport to import data from User Portal and export data to User Portal in XML format, set the file format to UPXML. When the file format is set to UPXML, a new property is added to the Dataport Designer: XMLIncludeTextConst.

62 4-4 User Portal Developer's Guide The following picture shows the properties that are available in the Dataport Designer for a User Portal dataport with the file format set to UPXML: XMLIncludeTextConst The XMLIncludeTextConst property is specific to User Portal and it is only visible when the file format is set to UPXML. You use this property to include the texts constants in the exported XML data. The property accepts the values Yes and No. If you set the XMLIncludeTextConst property to Yes, all text constants will be appended to the XML output when data is exported. Data Item Properties The following four data item properties are only supported for data items in dataports where the file format is set to UPXML: DataItemIndent DataItemLinkReference DataItemLink XMLDataItemName DataItemIndent The DataItemIndent property makes it possible to indent data items the

63 User Portal Application Server 4-5 way you can in the Report Designer. DataItemLinkReference Use this property to specify the data item on a higher level to which an indented data item is linked. When you have set a DataItemLinkReference property, you must use the DataItemLink property to specify a field from each data item to base the link on. DataItemLink Use this property to specify the corresponding fields from two data items that are linked by the DataItemLinkReference property. The link is defined as a property of the indented data item. XMLDataItemName You use the XMLDataItemName to specify the name to be used in the XML data for the data item. An underscore character ( _ ) replaces special characters not supported by XML. The default value of this property is the value of the DataItemTable property. The following picture shows the data item properties for the data item Customer in the Customer dataport:

64 4-6 User Portal Developer's Guide Field Properties The following properties are of special interest for fields in User Portal dataports: XMLFieldName Caption CaptionML AutoCalcField CallFieldValidate XMLFieldName The XMLFieldName property is used to specify the field name to be used in the XML data. An underscore character ( _ ) replaces special characters not supported by XML. The default value is the value of the SourceExpr. property. Caption The Caption property known from other Navision Attain objects is also supported for the dataport fields. The caption is included in the XML data as an attribute to the field. CaptionML The CaptionML property is also supported for the dataport fields. The CaptionML property is used the same way here as in other Navision Attain objects. For more information, see the manual Application Designer's Guide. AutoCalcField The AutoCalcField property has a default setting of Yes. This property also influences dataports that are not User Portal related, so since the default setting is Yes, you may see changes in existing dataport functionality. When it is set to Yes, all FlowFields are calculated before the data is exported.

65 User Portal Application Server 4-7 CallFieldValidate The CallFieldValidate property determines if the OnValidate trigger for the field will be executed when a field is imported. The default setting is No, but when the file format for the dataport is set to UPXML, this property is changed to Yes. In the following picture, you can see the properties of the No. field: C/AL Functions User Portal Application Server has added two C/AL functions and modified an existing function. For more information about the changes in C/AL, see section 4.5. GUIAllowed You can use the GUIALLOWED function in the code to test whether User Portal Application Server activates some code. SaveAsXML This function is similar to the SaveAsHTML function, but it saves the report as an XML file. CreateTempFile You can use this function to get the name of the temporary file that User Portal Application Server uses to generate, for example, reports. As an example, we will now create a new codeunit that executes this function. 1 In the Object Designer, click Codeunit and click New. The C/AL Editor window appears.

66 4-8 User Portal Developer's Guide 2 Click View, C/AL Globals. The C/AL Globals window appears. 3 In the C/AL Globals window, on the Variables tab, create two new variables with the following properties: Variable 1 Variable 2 Name MyTempFile FileName Data Type File Text Length Close the C/AL Globals window. 5 In the C/AL Editor window, in the first line of the OnRun() trigger, enter the following lines of code: MyTempFile.CREATETEMPFILE; FileName := MyTempFile.NAME; MESSAGE ('File is %1 ', FileName); MyTempFile.CLOSE; Using the f.close function means that the temporary file is deleted immediately after you have entered the message in it. 6 Close the C/AL Editor window. When prompted, save the codeunit with the following properties: Field Value ID Name TempTest Compiled x 7 In the Object Designer window, select the codeunit that you just created and click Run. When the codeunit is run the system will tell you the unique name and path for the temporary file, for example C:\Documents and Settings\UserName\Local Settings\Temporary Files\ TEMP.09C. You can also use the C/AL Symbol Menu window to insert your variables into the C/AL Editor. In that window, the CreateTempFile function is listed as a function for your variable, MyTempFile.

67 User Portal Application Server 4-9 For more information, see the online Help C/SIDE Reference Guide. Invalid Functions The following C/AL functions cannot be used in connection with User Portal Application Server: C/AL function CONFIRM C/AL function STRMENU C/AL function d.input (DIALOG)

68 4-10 User Portal Developer's Guide 4.3 CREATING USER PORTAL DATAPORTS One of the main purposes of User Portal Application Server is to make sure that queries in XML format from a User Portal client are returned with data in XML format from Navision Attain. User Portal dataports are designed for both exporting XML data, and importing and processing Update and Init requests. To help you create a User Portal dataport on your own, we will now set up a dataport in User Portal Application Server using the already existing Customer dataport as an example. Dataport First, we create a new dataport in the Object Designer and save it with the name Customer and the ID Dataport Properties The FileFormat property is set to UPXML. This allows you to set the XMLIncludeTextConst property to Yes as shown in the following picture:

69 User Portal Application Server 4-11 Data Items We then add three data items to the dataport as shown in the following picture: Data Item Properties The following picture shows the default property settings for the data item Customer: In most cases, you can leave the default settings for these properties. Dataport Fields For each data item, add the relevant fields. To add dataport fields, follow this procedure: 1 In the Dataport Designer, select the first data item, in this example Customer.

70 4-12 User Portal Developer's Guide 2 Click View, Dataport Fields. The Customer Field Designer window opens. 3 Click View, Field Menu. The Field Menu window opens. 4 In the Field Menu window, select the fields that you want to add to this dataport. 5 Click the Customer Field Designer window. When you are asked if you want to append the fields that are selected in the field menu, click Yes. The dataport fields are now added to the Customer Field Designer window. 6 In the Customer Field Designer window, make sure that all fields are enabled. The following picture shows the dataport fields for the data item Customer: You must now repeat steps 1-6 for all other data items in this dataport. For more information about dataport fields, see Chapter 17 in the manual Application Designer's Guide. Field Properties The values for XMLFieldName and Caption are auto-generated based on the values in SourceExpr.

71 User Portal Application Server 4-13 Special characters, that is, those not supported by XML, in the SourceExpr value are replaced by an underscore ( _ ) as shown in the following picture: The AutoCalcField property is set to Yes by default. You must specify the captions for the languages you support in the CaptionML property in order to use the multilanguage functionality of Navision Attain. Text Constants User Portal uses text constants in the same way as for the rest of Navision Attain. You can use the text constants in the C/AL Globals window to specify language sensitive texts to include in the exported XML data. From the XSL style sheet, you can refer to the text constants and retrieve the values. This method eases maintenance and ensures consistency in the GUI. Text constants replace static text strings that are hardcoded in the views, such as titles, captions, messages and so on. Field captions are generally contained in the data part of the XML document, however.

72 4-14 User Portal Developer's Guide In the following picture, you can see the text constants specified in the Customer dataport:

73 User Portal Application Server 4-15 C/AL Export Triggers If you need to fill in special values for a field, for example, this can be done in the OnBeforeExportRecord()trigger as shown in the following example: In this example, the Line No. values are used to determine that it is an Init request rather than a general Export request and then initialize the data with a default value (working date). This trigger is also used to update the Recently Visited menu. You do this by inserting C/AL code that can include updated information in the XML document as shown in the following picture: For more information, see Chapter 6.

74 4-16 User Portal Developer's Guide 4.4 EXPORTING AND IMPORTING DATA As mentioned earlier, User Portal Application Server uses dataports to import and export data in XML format. The connection between the application server and User Portal is a Named Pipe Connector. This connection does not require maintenance from you, but you need to know that the connector has three ports: Dataports Reports Functions The ports are used for different kinds of requests. The Dataports port is used for most XML documents, namely Export, Init and Import requests. The Reports port is used for reports. The Functions port is a generic port through which you can send all types of XML documents to Codeunit 1 Function 98. This function can then process the XML document and return an XML document. The syntax for error messages is described in Appendix C. PostXML With the PostXML tool, you can test the system to see how requests are handled. You find this tool in the Uptools folder on the Navision Attain product CD. Decimals When you export data using User Portal dataports and the data contains numbers with decimals, such as a price in dollars and cents, User Portal Application Server uses the settings for decimal places set up in the fin.stx file. This is usually two decimal places. XML Formats for Dataports The XML data must follow the guidelines described in the following sections in order to be accepted by User Portal Application Server.

75 User Portal Application Server 4-17 Remember that Navision Attain messages are captured and automatically added to the XML document. Error messages are sent as separate XML documents and replace the expected response. The asterisks (*) indicate that the XML document can have several such elements. Italics indicate input from you or the system. The complete structure for these XML documents is described in Chapter 5. The elements are defined in Appendix C. Exporting XML Data User Portal Application Server generates XML output from a dataport when the dataport FileFormat property is set to UPXML. Request To request data you send an XML document to User Portal Application Server with the following structure: <Dataport ID="[Dataport ID]" Name="[Dataport Name]" Direction="[Direction]"> *<Request Data Item XML Name="[Data Item XML Name]" Data Item Var Name="[Data Item Var Name]" Data Item Index="[Data Item Index]"> <Init/> *<Filter Field="[Field Name]">[Field Value] </Filter> <Key>[Key Field List] </Key> <Sorting>[Sorting] </Sorting> <RequestForm> *<Control ID="[Control ID]" Name="[Control Name]"> [Control Value] </Control> </RequestForm> </Request> </Dataport> This syntax is valid for both Export requests and Init requests. You will see that the information part of the syntax looks like the tabs on a request form, for example when you want to print a test report in the rest of Navision Attain.

76 4-18 User Portal Developer's Guide In Navision Attain, you start by specifying filters on fields, keys and sorting order like on the first tab of a request form. You then go to the second tab, the Options tab, and enter check marks and other information in various fields to specify what the request is for. Dataport Element You must enter either ID or Name to identify the dataport. Remember to enter a value for Direction, either Export or Init. Request Element You only have to use one attribute to identify the data item, that is, either DataItemXMLName or DataItemVarName or DataItemIndex. Control Element You only have to use one attribute to identify the control, that is, either ID or Name. The following example is taken from an XML document querying the Customer dataport: <Dataport Name="Customer" Direction="Export"> <Request DataItemXMLName="Customer"> <Filter Field="No.">10000</Filter> <Key>Search Description</Key> <Sorting>Ascending</Sorting> </Request> <RequestForm> <Control Name="Posting Date">010101</Control> </RequestForm> </Dataport> User Portal Application Server queries the database based on the values of the different elements and returns the found data as an XML document. In the example above, the Customer dataport and the Customer data item are queried. The scope of the query is for those entries where the posting date is January , the results are filtered using the No. field with the value 10000, and they are sorted in ascending order.

77 User Portal Application Server 4-19 Response The application server formats the response according to the following structure: <[Dataport Name]> *<[Data Item XML Name] Version="[Version ID]"> *<[Field XML Name] Caption="[Field Caption]" FieldLength="[Field Length]" OptionCaption="[Option Caption]" Option="[Option Value]" CompanyName="[Company Name]" TableID="[Table ID]" FieldNo="[Field No]"> [Field Value] </[Field XML Name]> *<[Data Item XML Name]/> </[Data Item XML Name]> <TextConstants> *<[Text Constant Name]> [Text Constant Value] </[Text Constant Name]> </TextConstants> <Messages> *<Message>[Message] </Message> </Messages> </[Dataport Name]> For Customer No , the returned data structure is like shown below, assuming that Customer has two comments: <Customer> <Customer Version="23"> <No_ Caption="No." FieldLength="55"> </No_> </Customer> <Comment_Line>First comment</comment_line> <Comment_Line>Second comment</comment_line> <TextConstants> <Caption>Customer</Caption> </TextConstants> </Customer> The first two elements are based on the data items specified in the dataport, Customer and Comment Line. One element is created for each record returned. The third element, TextConstants, is created when the dataport property XMLIncludeTextConst is set to Yes. Importing XML Data User Portal Application Server accepts XML input to a dataport when the dataport FileFormat property is set to UPXML.

78 4-20 User Portal Developer's Guide The input must be formatted according to the following structure: <Dataport ID="[Dataport ID]" Name="[Dataport Name]" Direction="[Import]"> *<Update Type=[Update Type]"> *<[Data Item XML Name]> <[Field XML Name]> [Field Value] </[Field XML Name]> *<[Data Item XML Name]/> </[Data Item XML Name]> </Update> </Dataport> Note In the Dataport element, you only have to enter either ID or Name to identify the dataport. Remember to enter Import as the value for Direction. The update is processed by the dataport as an Import and executes the OnAfterImportRecord () trigger for each row that is imported. In the example below, the DPCustomers dataport is used to change the customer name for customer 1000 to New Customer Name. <Dataport Name="DPCustomer" Direction="Import"> <Update Type="Modify"> <Customer> <No_>1000</No_> <Name>New Customer Name</Name> </Customer> </Update> </Dataport>

79 User Portal Application Server 4-21 XML Formats for Reports The request XML format for reports is very similar to the XML format for dataports. Request <Report ID="[Report ID]" Name="[Report Name]"> *<Request DataItemXMLName="[Data Item XML Name]" DataItemVarName="[Data Item Var Name]" DataItemIndex="[Data Item Index]"> *<Filter Field="[Field Name]">[Field Value] </Filter> <Key>[Key Field List]</Key> <Sorting>[Sorting]</Sorting> <RequestForm> *<Control ID="[Control ID]" Name="[Control Name]"> [Control Value] </Control> </RequestForm> </Request> </Report> In the following example, we request a report based on the chart of accounts: <Report Name="Chart of Accounts"> <Request DataItemVarName="G/L Account"> <Filter Field="No."> </Filter> </Request> </Report> Response The response from the server is a document for each page of the report. The information is HTML formatted, so the Web part handler just has to let the meta UI direct the raw data into the right places in the view. The data will not be rendered into HTML since it already is HTML. <Report> <Title>[Report Title]</Title> <HTMLHead> <![CDATA[ [HTML Header] ]]> </HTMLHead> *<Page PageNo="[Page Number]"> <![CDATA[ [HTML for Page] ]]> </Page> <HTMLFoot> <![CDATA[ [HTML Footer] ]]> </HTMLFoot> </Report>

80 4-22 User Portal Developer's Guide 4.5 ISSUES REGARDING WEB ENABLEMENT The overall purpose of User Portal is to make it possible to access Navision Attain over the Internet. However, not all objects and C/AL functions can be transferred directly to the Web. The following is a list of the objects and functions you can not Web enable: Navision Attain forms C/AL function CONFIRM C/AL function STRMENU C/AL function d.input (Dialog.Input) If you try to use these objects and functions in an XML document, you will get an error message. In order for you to locate the functions d.input, CONFIRM and STRMENU in your application, you can use a tool, Findconf.exe. You find this tool in the Uptools folder on the Navision Attain product CD. To find the functions d.input, CONFIRM and STRMENU that will cause problems, follow this procedure: 1 Export all objects to a text file. 2 Run the tool from your Command Prompt using the following parameters: [Command] [Name of source file] [Name of target file] For example: C:\Findconf.exe ExportedObjects.txt Result.txt 3 The resulting target file is a tab delimited text file that can be imported into Microsoft Excel for further investigation. If code containing functions d.input, CONFIRM and STRMENU is activated through User Portal Application Server, the code needs to be changed. You can use the function GUIALLOWED in the C/AL code to test whether User Portal Application Server activates some code. You can then replace this code with MESSAGE functions.

81 Chapter 5. From Query to User Interface Chapter 1 provided an overview of the way data flows through the system when a user activates a link in User Portal. In this chapter, we will go through the steps in more detail and describe the processes involved in retrieving data from Navision Attain and presenting it in the user interface. You learn how the different meta UIs are applied and how to use and create Web part handlers. The chapter contains the following sections: Introduction Web Part Framework Web Part Handlers User Portal Business Object XML Documents Search Handlers

82 5-2 User Portal Developer's Guide 5.1 INTRODUCTION As described in Chapter 1, a User Portal solution consists of a number of Web parts that use the Microsoft Digital Dashboard server components to provide an application framework. As you can see from the following picture, the Web parts contain specific tasks that relate to a role: User Portal User Activity Center Activity Center Activity Center Role Web part Web part Web part Web part Web part Web part Tasks Web part Web part Web part In this context, a Web part consists of data taken from Navision Attain and presented to the user in HTML format. User Portal Application Server extracts Navision Attain data in XML format and forwards it to the user portal. Web part handlers then provide different views of the same XML data depending on which XSL style sheet is attached to the XML data. For more information about XSL and meta UI, see Appendix C. Sending Query and Retrieving Data When the user browses to a page in his user portal, a series of events take place in order to retrieve data from Navision Attain and show the user the view they have requested. In Microsoft Digital Dashboard, a Web part handler transforms the user action into a query and sends it as an XML document to User Portal Application Server. The server generates the requested data and sends it back to the digital dashboard as an XML document. When he browsed to the page, the user selected a view for the result of the query, and the Navision Attain data now has to be transformed into the requested view. The Business Object Processor (BO Processor) in User Portal does this by applying a XSL style sheet, as determined by the Web part handler, to the XML document. The style sheet contains information about the meta user interface so that the data can be presented in the way

83 From Query to User Interface 5-3 specified by the view. Finally, the XML data and the meta UI style is rendered into an HTML page and shown on the screen. In other words, there are four steps to this process: 1 BO Processor processes the query by passing it on to User Portal Application Server and verifying the result. 2 A view is selected based on the original request, defined by the Web part handler. 3 Based on Step 2, meta UI is applied to the data in the shape of an XSL style sheet for this view. 4 The meta UI and XML data is rendered into HTML and presented to the user. We introduced this flow of data from user interface to Navision Attain and back in Chapter 1: Note that the BO Processor controls all four steps. The tools used in this process are described in the sections below.

84 5-4 User Portal Developer's Guide 5.2 WEB PART FRAMEWORK In the process described on page 5-3, we mentioned four new concepts: Query, XML data, meta UI and Web part handlers. In this section, we will take a look at the Web part framework that plays an important part in allowing data to be transformed from Navision Attain data into XML and HTML and back again. Note The Web part handlers are described in section 5.3. The meta user interface, or meta UI, and the XSL style sheets are described in detail in Appendix C. All User Portal XML and XSL documents are well-formed and valid XML documents. This means that they are based on defined templates such as the Web part framework. The Web part framework is the template for all XSL style sheets and Web part handlers used by User Portal and Microsoft Digital Dashboard. It ensures that data is transformed correctly to and from XML and that it is presented correctly in the user interface. Each view that we looked at in Chapter 3 is described in an XSL style sheet, which is stored in the NSWebParts folder on the Web server. It ensures that the data is presented on the screen in a user friendly and consistent way.

85 From Query to User Interface 5-5 Overview of the Web Part Framework In each of the Web part handlers described in section 5.3 and 5.4, the Web part framework provides the structure for describing the contents of the view. The framework contains a combination of elements to describe the title, contents, local menus, permissions and custom search handler for this view. The Web part framework consists of the following elements: <WebpartFramework> <BaseURL>[Base URL]</BaseURL> <Permissions>[Permissions]</Permissions> <PageTitle>[Page Title]</PageTitle> <Summary>[Summary]</Summary> <ContentBlock>[Content Block]</ContentBlock> <LinkBlock>[Link Block]</LinkBlock> <Links>[Links]</Links> <SearchHandler>[Search Handler]</SearchHandler> <Messages>[Messages to be displayed]</messages> <HTML>[HTML]</HTML> </WebPartFramework> Each of the elements is described in detail in Appendix C. For now, we must note that the Web part framework is what ties the entire process together and makes it possible to use Navision Attain from a browser interface. Since all XML documents that are exchanged between Navision Attain and Microsoft Digital Dashboard are built so that their data fits into this framework, the actual transformation from query to user interface is straightforward, relatively speaking.

86 5-6 User Portal Developer's Guide 5.3 WEB PART HANDLERS User Portal uses the Microsoft Digital Dashboard server components to provide an application framework for the individual user portal. As described in the previous section, each view has an associated Web part handler and one or more XSL style sheets with meta UI definitions. In other words, Web part handlers provide different views of the same XML data depending on which XSL style sheet it attaches to the XML data. As a rule of thumb, remember that Web part handlers determine what is displayed and the meta UI in the associated XSL style sheet determines how it is displayed. Web part handlers are themselves XML documents that are written for a specific extract from a business object. This chapter contains descriptions of how to create a Web part handler with XML based on the User Portal Business Object XML structure developed for this purpose. This structure, or template, is based on the Web part framework in the sense that the two structures have the same names of elements. Tasks for a Web Part Handler In the process described in section 5.1, a typical Web part handler will perform the following tasks: 1 Request URL. 2 Get query. 3 Select view. 4 Get view. 5 Transform the XML meta UI for this view with the Render.xsl style sheet to generate HTML. As far as Digital Dashboard is concerned, there are two kinds of Web part handlers: XML Web part handlers and VBScript Web part handlers. XML Web part handlers are described in the section below. They are processed by the Business Object processor (BOProcessor.js), which controls the steps outlined above. A Web part handler can also be created using VBScript, but this course

87 From Query to User Interface 5-7 does not cover VBScript Web part handlers. As a general rule, you should write Web part handlers in VBScript when there is a need to process the extracted data or the formatting applied to the data, or when data is extracted from a third party. XML Web Part Handlers User Portal primarily uses XML Web part handlers that are based on the User Portal Business Object XML document structure described in section 5.4. These Web part handlers are processed by the Business Object processor (BOProcessor.js), which controls the steps outlined above. XML Web part handlers are stored as XML documents along with their associated XSL style sheets in the NSWebParts folder on the server running Internet Information Services. Once the XML Web part handler is included in an activity center, Microsoft Digital Dashboard will invoke the BO processor when needed. The Web part handler s tasks are divided into two main areas: They specify which data is requested from User Portal Application Server. They specify how the content is formatted before it is sent back to the user. The first set of tasks is carried out by the URLParameters element and the Queries element. The second set of tasks is carried out by the Views element. The following section describes the individual elements of a User Portal Business Object XML document so that you can generate your own Web part handlers. However, when you create your own Web part handlers, you may prefer to base it on an already existing Web part handler in order to ensure that you do not leave out any essential elements. Already existing Web part handlers and XSL style sheets are very useful templates in your own work. Note Exercise 5 in Chapter 7 guides you through the process of creating a new Web part handler.

88 5-8 User Portal Developer's Guide 5.4 USER PORTAL BUSINESS OBJECT XML DOCUMENTS The complete structure of the User Portal Business Object XML document as used in Web part handlers developed for User Portal is as follows: <UserPortalBusinessObject Version="3.1" Name="[Name]"> <URLParameters> <URLParam Name="[Name of URL parameter]"/> </URLParameters> <Queries> <Query Version="3.1"> <Dataport Name="[Dataport]" Direction="[Export or Import]"> <Request XMLDataItemName="[XMLDataItemName]"> <Filter Field="[Field name]">[filter] </Filter> </Request> <Request DataItemVarName="[DataItemVarName]"> <Filter Field="[Field name]">[filter] </Filter> </Request> <Request DataItemIndex="[DataItemIndex]"> <Filter Field="[Field name]">[filter] </Filter> </Request> </Dataport> </Query> <Query> <Report ID="[Report ID]" Name="[Report Name]"> <Request DataItemXMLName="[Data Item XML Name]" DataItemVarName="[Data Item Var Name]" DataItemIndex="[Data Item Index]"> <Filter Field="[Field Name]">[Field Value] </Filter> <Key>[Key Field List]</Key> <Sorting>[Sorting]</Sorting> <RequestForm> <Control ID="[Control ID]" Name="[Control Name]"> [Control Value] </Control> </RequestForm> </Request> </Report> </Query> <Query> <Function> </Function> </Query> </Queries> <Views> <View> <Source Type="xsl"> [Name of XSL style sheet] </Source> </View> </Views> </UserPortalBusinessObject>

89 From Query to User Interface 5-9 Each of the elements is described in detail below. UserPortalBusinessObject Element The UserPortalBusinessObject element is the root element of a User Portal Business Object XML document. Digital Dashboard will only process an XML document as a User Portal Business Object XML document if it has this element as the root element. The Version attribute is mandatory. New documents developed for Navision Attain 3.10 or later versions should have the Version attribute set to 3.1, but documents that have not changed from version 2.60 can keep the value 2.6. The Name attribute is optional. URLParameters Element The URLParameters element contains the definitions of the parameters in the URL that are relevant for the Web part that this XML document handles. The URLParameters element is optional and is only processed if the document contains one or more Queries elements. <URLParameters> <URLParam Name="[Parameter name]"> [Default value] </URLParam> </URLParameters> The URLParameters element may contain any number of URLParam sub elements, each defining the name and default value of a parameter. The Name attribute is mandatory. In the example below, the URLParameters element is used to define two parameters in the Web part handler for the business object Customer (Customer.xml). They are named Customer and DocType and neither have a default value. <URLParameters> <URLParam Name="Customer"> </URLParam> <URLParam Name="DocType"> </URLParam> </URLParameters>

90 5-10 User Portal Developer's Guide This URLParameter could then be shown in the following way in the browser address bar: DashboardURL/Forms/Customer&Customer=10000&View=Overview Queries Element The Queries element contains all the Query elements. Within the Queries element you define one or more queries for User Portal Application Server using the Query element. <Queries> <Query Version="3.1"> <[Data Source]>[Data source] <[/Data Source]> </Query> <Query> </Query> </Queries> Query Element The Query element specifies the request sent to User Portal Application Server. <Query Version="3.1"> <[Data Source]>[Data source request] <[/Data Source]> </Query> The Version attribute is mandatory. New documents developed for Navision Attain 3.10 or later versions should have the Version attribute set to 3.1, but documents that have not changed from version 2.60 can keep the value 2.6. The Data Source element is the actual request sent to User Portal Application Server. As described in section 4.4, the following data sources are supported: Dataport <Query Version="3.1> <Dataport> </Dataport> </Query>

91 From Query to User Interface 5-11 Report <Query Version="3.1> <Report> </Report> </Query> Function <Query Version="3.1> <Function> </Function> </Query> In the data source content, you can specify name that will insert the value that this parameter has in the URL: <URLParameters> <URLParam Name="Customer"></URLParam> <URLParam Name="DocType"></URLParam> </URLParameters> <Queries> <Query Version="3.1"> <Dataport Name="Customer" Direction="Export"> <Request DataItemXMLName="Customer"> <Filter <!-- No. --> </Request> <Request DataItemXMLName="Sales Header"> <Filter <!-- Document Type --> </Request> </Dataport> </Query> </Queries> Data Source: Dataport When the data source is a dataport, you use the Name attribute to specify the dataport to communicate with. You should then use the Direction attribute to specify whether to Export, Import or Init data. Export is used to request data. The dataport returns data in a structured XML format. Import is used to send data to the dataport. The dataport validates the data before accepting the entry. The validation follows the rules used in the Navision Attain client. Init is used to initialize a new record. The dataport returns fields that could be initialized for the new record. The initialization follows the

92 5-12 User Portal Developer's Guide rules used in the Navision Attain client. For more information about the XML format for these requests, see section 4.4. The example below illustrates how the Dataport element is used in the Web part handler Customer.xml. The code shown is fragments of the entire code used in Customer.xml. First we define two URL parameters: Customer and DocType. <URLParameters> <URLParam Name="Customer"></URLParam> <URLParam Name="DocType"></URLParam> </URLParameters> Secondly, we specify the query: <Queries> <Query Version="3.1"> <Dataport Name="Customer" Direction="Export"> <Request DataItemXMLName="Customer"> <Filter </Filter> <!-- No. --> </Request> <Request DataItemXMLName="Sales Header"> <Filter </Filter> <!-- Document Type --> </Request> <Request DataItemXMLName="Comment Line"/> </Dataport> </Query> </Queries> In the query, we first specify the name of the dataport and the direction of the data. In the example, the Web part handler uses the Customer dataport to export data from Navision Attain. Thirdly, we specify three requests: 1 A request for data from the Customer data item and filters the output by matching the value of the URL parameter Customer to the Field1 field. 2 A request for data from the Sales Header data item and filters the output by matching the value of the URL parameter DocType to the Field1 field. 3 A request for data from the Comment Line data item. This query does

93 From Query to User Interface 5-13 not set a filter because if it is a Create request, BO Processor will modify the query by adding <Init/> elements to the request element that belongs to the type you want to create. Using the following URL: DashboardURL/Forms/Customer&Customer=10000&View=Overview generates this request for User Portal Application Server: <Dataport Name="Customer" Direction="Export"> <Request DataItemXMLName="Customer"> <Filter Field="Field1">10000 </Filter> <!-- No. --> </Request> </Request> <Request DataItemXMLName="Sales Header"> <Filter Field="Field1" /> <!-- Document Type --> </Request> <Request DataItemXMLName="Comment Line"/> </Dataport> If you have selected Debug mode as described in Appendix A, the request is stored in the file XMLQueryFinal1.xml where 1 is the number of the request. You can see the returned data in the WebPartData1.xml file. Data Source: Report The example used to illustrate the Report data source is based on the Web part handler SalesOrderReport.xml. First two parameters are defined: No This parameter specifies the number of the sales order that will be displayed by inserting its value in the Filter element, which sets Field3. Report This parameter specifies the report that must be run. This is done by inserting its value in the Report element s ID attribute. The Views element contains references to the Report.xsl which is a generic template used to format all reports. You should always use the same style sheet to display a report, as this ensures consistency throughout the solution.

94 5-14 User Portal Developer's Guide <UserPortalBusinessObject name="salesheaderorderreport > <URLParameters> <URLParam Name="No"></URLParam> <URLParam Name="Report"></URLParam> </URLParameters> <Queries> <Query Version="2.6"> <Report <Request DataItemIndex="0"> <!-- Sales Header --> <Filter Field="Field1">1</Filter> <!-- Document Type --> <Filter </Filter> <!-- No. --> </Request> </Report> </Query> </Queries> <Views> <View ID=""> <Source Type="xsl">Report.xsl</Source> </View> <View ID="Order"> <Source Type="xsl">Report.xsl</Source> </View> </Views> </UserPortalBusinessObject> Using the following URL: DashboardURL/Forms/SalesOrderReport&No=101016&Report=205 generates this request for the User Portal Application Server: <Report ID="205"> <Request DataItemIndex="0"> <!-- Sales Header --> <Filter Field="Field1">1</Filter> <!-- Document Type --> <Filter Field="Field3">101016</Filter> <!-- No. --> </Request> </Report> If you have selected Debug mode, the request is stored in the file XMLQueryFinal1.xml where 1 is the number of the request. You can see the returned data in the WebPartData1.xml file. Data Source: Function The Function data source sends requests to Codeunit 1 Function 98. You can use this data source to send any kind of XML document to the codeunit. For more information, see section 4.4.

95 From Query to User Interface 5-15 Views Element The Views element contains a list of the XSL files that are used to present the data retrieved from the request. <Views> <View ID="[View ID]"> <Source Type="[type]">[Name of style sheet] </Source> </View> </Views> The Views element is mandatory when the document has a Query element. The Views element must contain at least one View element. View Element You use the View element to refer to one of the XSL files specify how to format the content. Below is the structure of a View element: <View ID="[View ID]"> <Source Type="[type]">[Name of style sheet]</source> </View> You use the ID attribute to specify an ID for this view. For example, in the Web part handler Customer.xml, we have specified the following view IDs: Overview, Create, Comments, SalesQuotes and SalesOrders. The ID can be used in the View parameter in the URL for this Web part handler. When one of these values are set in the View parameter in the URL, the XSL file specified in the Source element is used to format the data. In the following URL, the value of the View parameter is Overview: DashboardURL/Forms/Customer&Customer=10000&View=Overview When Digital Dashboard is processing a User Portal business object, it will look for the View parameter in the URL and try to match its value with an ID attribute in one of the View elements in the Web part handler. Based on the URL above, Digital Dashboard will locate this View element: <View ID="Overview"> <Source Type="xsl">Customer.xsl</Source> </View> As a result, Digital Dashboard applies the Customer.xsl style sheet to the XML document to create meta UI.

96 5-16 User Portal Developer's Guide If the View parameter is not found in the URL, Digital Dashboard will use the first View element in the Views element. The ID attribute must be unique within the XML document. Source Element The Source element specifies the file type and path of the XSL file that will be applied to the content. User Portal only supports one type, namely XSL. If you use the URL for the Customer example: DashboardURL/Forms/Customer&Customer=10000&View=Overview the Customer.xsl style sheet is applied to the content because this is the style sheet specified in the Source element for this view ID: <View ID="Overview"> <Source Type="xsl">Customer.xsl</Source> </View> We need not write a path for the XSL style sheets because they must be stored in the NSWebParts folder. The following example shows the entire Views element in the Web part handler Customer.xml: <Views> <View ID="Overview"> <Source Type="xsl">Customer.xsl</Source> </View> <View ID="Create"> <Source Type="xsl">CustomerCreate.xsl</Source> </View> <View ID="Comments"> <Source Type="xsl">CustomerComments.xsl</Source> </View> <View ID="SalesQuotes"> <Source Type="xsl">CustomerSalesQuotes.xsl</Source> </View> <View ID="SalesOrders"> <Source Type="xsl">CustomerSalesOrders.xsl</Source> </View> </Views> In this example, five different style sheets can be applied to the XML documents from User Portal Application Server. If the URL does not have a View parameter, the content will be formatted using the Customer.xsl since this is the style sheet for the first view in the list.

97 From Query to User Interface SEARCH HANDLERS Searches are handled through a generic search handler (Search.xml). This handler is used when you create context sensitive Search handlers. The search handler passes the parameters from the URL to the Search dataport. The parameters are parsed within the C/AL procedures of the dataport that invokes the search within Navision Attain. Generic Search Handler <UserPortalBusinessObject Name="Search"> <URLParameters> <URLParam Name="Title"></URLParam> <URLParam Name="Query"></URLParam> <URLParam Name="Start">0</URLParam> <URLParam Name="Area"></URLParam> <URLParam Name="TableID">0</URLParam> <URLParam Name="SubID">-1</URLParam> </URLParameters> <Queries> <Query Version="2.6"> <Dataport Name="Search" Direction="Export"> <RequestForm> <Control Name="Title">@Title</Control> </RequestForm> <RequestForm> <Control Name="Query">@Query</Control> </RequestForm> <RequestForm> <Control Name="Start">@Start</Control> </RequestForm> <RequestForm> <Control Name="Area">@Area</Control> </RequestForm> <RequestForm> <Control Name="TableID">@TableID</Control> </RequestForm> <RequestForm> <Control Name="SubID">@SubID</Control> </RequestForm> </Dataport> </Query> </Queries> <Views> <View> <Source Type="xsl">Search.xsl</Source> </View> <View ID="Lookup"> <Source Type="xsl">Lookup.xsl</Source> </View> </Views> </UserPortalBusinessObject>

98 5-18 User Portal Developer's Guide Context sensitive search handlers, which make use of the generic search handler, are defined in the style sheet for a given Web part: <SearchHandler> <Title>[Search title]</title> <URL>Search&[ScopeKeyword=ScopeValue& SubScopeKeyword=SubScopeValue] </URL> </SearchHandler> The use and origin of the parameters in the generic search handler are described below. Title The Title is displayed in the bar above the search field. The title is specified in the Title element in the SearchHandler element in the style sheet. Query The Query is the actual text that the user types in the search field. This value is taken from the search field when the user presses the Search button. Start The Start keyword is used to indicate the length of the list of search results. The use of this keyword is handled by the Search dataport. Area and TableID The Area and TableID keywords both relate to the scope of the search. The keyword and the corresponding value are specified in the URL element in the SearchHandler element in the style sheet. Each of the keywords can act as the ScopeKeyword in the style sheet fragment above. The TableID keyword specifies a scope at single table level. TableID is language independent. The Area keyword can be used to specify a scope at multiple table level. The Search dataport must be set up to handle the keyword value appropriately. If the scope keyword is not specified, the search will cover all the search areas that are specified in the Search dataport.

99 From Query to User Interface 5-19 SubID The SubID keyword is used to specify a narrower scope within the scope defined by the use of Area or TableID as keyword. As above, the keyword is specified in the URL element in the SearchHandler element in the style sheet. The sub scope keyword is optional. Example The following example is taken from the Customer.xsl style sheet: <SearchHandler> <Title> <xsl:value-of select="/customer/ TextConstants/SearchCustomers"/> </Title> <URL>Search&TableID=18</URL> </SearchHandler> As you can see, the title is derived from a text constant. The scope of the search is determined by <URL>Search&TableID=18</URL> where TableID=18 specifies that the search has to take place in Table 18.

100

101 Chapter 6. Working with User Portal This chapter contains examples of how to perform common tasks with User Portal. The chapter contains the following sections: Enabling Search and Lookup Updating the Recently Visited Menu

102 6-2 User Portal Developer's Guide 6.1 ENABLING SEARCH AND LOOKUP When you have created a new dataport to view and update information from a table, you need to modify the Search dataport in User Portal Application Server to enable search and lookup from the User Portal solution. To enable search and lookup for a table, you need to create two new functions, and add calls to these in the FindGlobalResultSet function in the Search dataport. The following sections describe how to enable search and lookup for Customer. First, add two new functions to the C/AL Globals window: 1 In the Object Designer, select Dataport 6704 and click Design. 2 Click Edit, Select Object, and then click View, C/AL Globals. 3 In the C/AL Globals window, click the Functions tab and add the two new functions, SetCust and FindCust. 4 Click View, C/AL Code. The C/AL Editor window opens 5 In the C/AL Editor window, enter the C/AL code described below. SetCust SetCust(VAR Cust : Record Customer) WITH Cust DO BEGIN SetData('Customer&Customer=%2&View=Overview', TABLECAPTION,"No.",Name,''); SetLookupID("No."); END;

103 Working with User Portal 6-3 FindCust FindCust(Category : Boolean;SearchString : Text[250]) WITH Cust DO BEGIN IF NOT READPERMISSION THEN EXIT; SetCategory(TABLECAPTION,DATABASE::Customer,-1); IF CheckSearchField(MAXSTRLEN("No.")) THEN BEGIN SETFILTER("No.",'%1',SearchString); IF NOT ResultSetFull THEN IF FIND('-') THEN BEGIN IF Category THEN BEGIN AddToCategoryResultSet; EXIT; END; REPEAT SetCust(Cust); AddToResultSet; UNTIL (NEXT = 0) OR ResultSetFull; END; SETRANGE("No."); END; IF CheckSearchField(MAXSTRLEN("Search Name")) THEN BEGIN SETCURRENTKEY("Search Name"); SETFILTER("Search Name",'%1',SearchString); IF NOT ResultSetFull THEN IF FIND('-') THEN BEGIN IF Category THEN BEGIN AddToCategoryResultSet; EXIT; END; REPEAT SetCust(Cust); AddToResultSet; UNTIL (NEXT = 0) OR ResultSetFull; END; SETRANGE("Search Name"); END; END; The FindCust function is called from the FindGlobalResultSet function.

104 6-4 User Portal Developer's Guide Adding Customer to the Global Search To include Customer in the global Navision Attain search, a call to FindCust is inserted in the CASE statement where TableID is tested to be 0 (zero). FindGlobalResultSet(Category : Boolean;SearchString : Text[250]) CASE TableID OF 0: BEGIN FindCust(Category,SearchString); END; DATABASE::Customer: FindCust(Category,SearchString); ELSE BEGIN Object.GET(Object.Type::Table,'',TableID); ERROR(NoSearchAvailable,Object.Name); END; END; To enable context sensitive search and lookup for customer add an entry in the CASE statement for Customer: FindGlobalResultSet(Category : Boolean;SearchString : Text[250]) CASE TableID OF 0 BEGIN FindCust(Category,SearchString); END; DATABASE::Customer: FindCust(Category,SearchString); ELSE BEGIN Object.GET(Object.Type::Table,'',TableID); ERROR(NoSearchAvailable,Object.Name); END; END; Now the Search dataport is enabled to handle Customer.

105 Working with User Portal UPDATING THE RECENTLY VISITED MENU A user s home activity center has a Web part containing a list of the most recently visited views. Each time the user visits business objects, this information is stored as a record in Table All dataports that export XML documents based on User Portal business objects must contain the following lines of C/AL code in the OnBeforeExportRecord() trigger: IF Get("Document Type"::[Business Object type],"[field name]") THEN BEGIN NewVisit."User ID":= USERID; NewVisit.Description := '[Business Object name]' + "[Field name]"; NewVisit.Link := '[XML identifier]=' + "[Business object or Field name]" + '[View identifier]'; NewVisit.TableID := DATABASE::"[Table name]": NewVisit.INSERT(TRUE); The elements are as follows: Element "User ID" Description Link TableID Description Ensures that the update is linked to a specific user. Mandatory. The text used in the hyperlink. In this example, the link in Recently Visited would say "Sales Quote 1001", if this were the most recently visited sales quote, because the description consists of the name of the business object and the contents of the No. field. Consists of XML identifier, business object identifier and view identifier. Identifies the table that forms the basis for the business object. In the example, the Sales Header table is the basis for the Sales Quote business object. You can use this TableID to set table filters. Note Set the INSERT function to True in order to make the business object update the Recently Visited menu.

106 6-6 User Portal Developer's Guide Example The following example is from the Sales Header data item in the SalesQuote dataport: This could then create a link in the Recently Visited menu as shown in the following picture: Because we have set a table filter in the file SalesRecentlyVisited.xml, the Recently Visited menu in the Sales activity center is only updated by visits to business objects that are based on the tables in the filter. You can use any Navision Attain table filter, for example the one used in the file SalesRecentlyVisited.xml as shown in the following example: <UserPortalBusinessObject Version="2.6"> <Queries> <Query Version="2.6"> <Dataport Name="Recently Visited" Direction="Export"> <Request DataItemVarName="Recently Visited"> <Filter Field="Field7"> </Filter> <!-- Table ID --> </Request> </Dataport> </Query> </Queries> </UserPortalBusinessObject>

107 Chapter 7. Exercises These exercises guide you through the development of a User Portal solution. The chapter contains the following sections: Overview Preparing a New Activity Center Developing a New Dataport for User Portal Enabling Search and Lookup Developing a Web Part Handler Developing the Job Overview Web Part Developing the Job Create Web Part Developing Support for Comments

108 7-2 User Portal Developer's Guide 7.1 OVERVIEW During the design phase, you have gained good insight in the users needs and their daily workflow. You have walked users through the prototype of the design to ensure that your design supports their workflow. Now it is time to develop the required dataports, Web parts and Web part handlers to enable the user to work more efficiently. All exercises are based on the following scenario: Summary of the Time Registration Solution A consultancy company has requested a solution that enables their consultants and project managers to access Navision Attain, when they are working in the field. Currently the consultants fax their time sheets to the company on a weekly basis. Clerks then enter the number of hours that consultants have spent on the project into Navision Attain. The project managers can only monitor the progress of the project when they are in-house. Your task is to create a Time Registration solution for User Portal. The solution enables consultants working in the field to enter the hours spend on a project directly into Navision Attain through User Portal, at any time they wish to do so. The project managers can monitor the progress of a project even when they are working in the field. Navision Attain already contains the tables and business logic required to create the Time Registration solution. If this were not the case, you would first have to implement tables and business logic for the solution. In the following exercises, parts of the solution described above have already been implemented. This should provide you the insight you need to develop the rest of the solution on your own. In the course of the exercises, you will create Web parts to work with the Jobs table. You will Web enable the Jobs table and thereby allow the user to view, edit, create and delete records in the Jobs table from their browser.

109 Exercises 7-3 Development Phases The following list contains the phases you must go through when developing a solution for User Portal. We begin our work in User Portal Application Server. Prepare the New Activity Center: Create a new activity center in User Portal Application Server. Add standard Web parts to it. Assign the activity center to a user (yourself). Register the Web Parts in Digital Dashboard: Create new DWP files for the Web parts. Add Web part references to the InstallStructure.xml file. Execute the InstallDashBoard.js script. Set Up the Dataport: Create a new dataport containing the required data items. Set the dataport properties FileFormat (UPXML) and XMLIncludeTextConst (Yes). Add the required dataport fields for each data item (table). Set the properties for the each field. Add the required text constants to the dataport. Enable the Search dataport to handle the dataport: Modify the Search dataport (Dataport 6704) to include your new dataport and data items so that they can be searched in. We then leave User Portal Application Server in order to create a Web part handler and two Web parts.

110 7-4 User Portal Developer's Guide Write the Web Part Handler: Add the URL parameters in the URLParameters element. Write the queries to the dataport including the needed filters in the Queries element. Prepare the Web part handler for the Web parts that it is going to handle by writing a View element for each Web part that will be used. Write Each Web Part: You must set up basic information for each Web part: Set up the BaseURL. Add reference to the text constant containing the PageTitle. Then you need to build the Content area: Set up the ModificationOption. Set up UpdateInfo and/or RowUpdateInfo. Add reference to the text constant containing the content area Title. Include the elements needed to display the data in the Content Area. Next you set up the local navigation area: Add context sensitive Search. Setup the required Personalization permissions. Include the elements needed to build the Browse menu group. Include the elements needed to build the Common Tasks menu group. Include the elements needed to build the See Also menu group. The last step in creating the Web part is to include the information needed to update the Recently Visited menu.

111 Exercises 7-5 Add Category and Tasks Web Part to Your Activity Center s Title Page: Use Digital Dashboard to add the Category and Tasks Web parts to the new activity center. Add Links to the Category and Task Web Parts: In User Portal Application Server, define and add links to the Category and Tasks Web parts. Those were the steps that you go through when you develop a User Portal solution. In the following exercises, you are guided through each step. Tables, Fields, Text Constants and Files This section contains lists of the tables, fields, text constants and files you will be using and creating in the exercises. Tables The table below lists the tables used in the solution. Table Name Table No. Job 167 Comment Line 97 Fields The Job Card (Form 88) is used to determine which fields are good candidates for the Overview View for Job: Fields in Form 88 No. Address 2 Status Description Post Code Blocked Bill-to Customer No. City Last Date Modified Name Address Contact Search Description In the Comment Line table, all fields are used.

112 7-6 User Portal Developer's Guide Text Constants for Job Dataport The following table contains the text constants used to create the headings and prompts. Text Constant CreateJobTitle Caption SearchJobs BrowseJob CreateJob EditJob DeleteJob DeleteJobPrompt DeleteCommentLine Comments CreateComment CommonTasks RelatedInfo Overview Details NoComments Value Create New Job Job Search Jobs Browse Job Create New Job Edit Job Delete Job Delete Job? Delete Comment? Comments Create New Comment Common Tasks See Also Overview Details There are no comments for this Job

113 Exercises 7-7 Files In the table below is a list of the files you create during these examples. Filename Folder Description Job.xml NSWebParts Web part handler Job.xsl NSWebParts View and Edit Job JobCreate.xsl NSWebParts Create Job JobComments.xsl NSWebParts Comment for Job Job.DDB NSWebParts/Dashboards Digital Dashboard configuration Job.XML.DWP NSWebParts/Dashboards Job Web part

114 7-8 User Portal Developer's Guide 7.2 PREPARING A NEW ACTIVITY CENTER In this exercise, you prepare the new activity center, Employee. First, you create a new activity center in your User Portal Application Server. You then add the standard Web parts: My Frequent Tasks Search Recently Visited Finally, you assign the activity center to yourself so you can access it with your browser. By the end of the exercise, you will have set up the Employee activity center that allows you to monitor your progress as you develop the specialized Web parts. Adding Users to User Portal You must begin by adding users to User Portal; at least you must set up yourself as a user. To add a user to User Portal, follow this procedure: 1 Open the user interface to User Portal Application Server. This is installed as a special Navision Attain client on your middle-tier server. 2 In General Ledger, click Setup, User Portal Setup, User Setup. The User Portal User Setup window appears: 3 In the User Portal User Setup window, in the User ID field, click the

115 Exercises 7-9 AssistButton p and select your own ID from the list in the Logins window. The Logins window contains the user IDs of all the logins that have been created in the current database; both the database logins and the Windows logins. However, if you have created a login for a Windows group, the Logins window will only display the name of the group and not the names of the individual members of the group. User Portal Application Server only supports Windows logins. Creating an Activity Center To create an activity center, follow this procedure: 1 In User Portal Application Server, in General Ledger, click Setup, User Portal Setup, Activity Centers. 2 In the Activity Centers window, enter the new values for the Code, Name and Order fields for the Employee activity center as shown in the following picture: The number in the Order field determines the order in which the activity centers are displayed in the Global Navigation Area. The activity centers are displayed from left to right with the lowest numbers first. 3 In the Activity Centers window, click Center, Web Parts. The Activity Center Web Parts window for this new activity center appears. It should be empty now. 4 In the Activity Center Web Parts window, click the AssistButton p to open the Web Parts window. 5 In the Web Parts window, select the generic Web part My Frequent

116 7-10 User Portal Developer's Guide Tasks and click OK. The Web part will now be added to the Activity Center Web Parts window. 6 Repeat this process for the other two generic Web parts Recently Visited and Search to add them to the Employee activity center. You have now created a new activity center, Employee, that contains the three generic Web parts My Frequent Tasks, Recently Visited and Search.

117 Exercises 7-11 Setting Up the Default User You must now specify which of the users that you have set up in the user portal will be the default user. The default user is the identity that will be given to anybody who accesses your user portal without having been set up as a user in the user portal, so it should be someone with generic permissions to the database objects. To specify the default user, follow this procedure: 1 Open the General Ledger menu, and click Setup, User Portal Setup, Setup and the User Portal Setup window appears: 2 Select the General tab. 3 In the Default User Setup field, click the AssistButton p and the User Portal User Setup window appears listing all the users that have been set up for this user portal. 4 Select the user that you want to be the default user and click OK. This user s ID will now be displayed in the Default User Setup field. You have now defined the default user.

118 7-12 User Portal Developer's Guide Assigning an Activity Center In order to see the activity center in a browser, you must assign the activity center to yourself in the User Activity Centers window. To assign an activity center to yourself as a user, follow this procedure: 1 In General Ledger, click Setup, User Portal Setup, User Setup. 2 In the User Portal User Setup window, select the user you want to assign an activity center to, in this case yourself. 3 Click User, Activity Centers to open the User Activity Centers window. The User Activity Centers window lists the activity centers that have been assigned to this user. It should be empty now. 4 In the Activity Center Code field, click the AssistButton p, and in the Activity Centers window, select the Employee activity center and click OK to assign the activity center to yourself as a user. When you have completed these steps, the activity center Employee will be available the next time you access your User Portal solution. If your browser is already open, you need to close it and open it again in order for the activity center to be initialized.

119 Exercises 7-13 The Employee activity center will now look like this when you access it through your browser: Disabling Activity Center Since the Employee activity center contains access to sensitive information, you already know that you may want to prevent a user from accessing this data. You do that by granting yourself the right to remove Web parts. To prepare to remove Web parts and activity centers, follow this procedure: 1 In the C:\Inetpub\WWWroot\Factory folder, open the Dashboard_Const.inc file in any editor, for example Notepad. 2 In the stadmincanremovewebparts variable, set the property to 1. 3 Save the file. This allows you as an administrator to delete Web parts. To remove an activity centers from a user, follow the same procedure as for assigning an activity center but delete it rather than assigning it. Enabling Debug Mode Finally, you enable Debug mode for User Portal. Debug mode allows you to

120 7-14 User Portal Developer's Guide see the XML files created by the dataport when sending requests and getting responses from Navision Attain. When you design your own XSL files, you will find it helpful to see the actual XML documents because they will provide you with a good overview of the document structure, element names and attributes. To enable Debug mode, follow this procedure: 1 In the *\wwwroot\factory\ folder, open the file BOProcessor.js in an editor and set bdebugmode = true. Save the file. 2 Open the file NSUpdate.asp in an editor and set bdebugmode = true. Save the file. When you run User Portal next, the system will create a folder named C:\tmp, unless you changed the name and path in the Dashboard_Const.inc file as described in the manual User Portal Installation Guide. This folder will hold the XML content files that are created when you send a request or get a response from dataports in Navision Attain. Remember to disable Debug mode when you have completed developing the solution. For more information on debugging User Portal, see Appendix A.

121 Exercises DEVELOPING A NEW DATAPORT FOR USER PORTAL In this exercise, you will create the Job dataport (Dataport 99000) and add the data items Job (Table 167) and Comment Line (Table 97) to it. Then you will add the fields listed in the Field Name table on page 7-5 and set their properties. Finally you will add the text constants listed in the table on page 7-6. Creating a Dataport To create a dataport, follow this procedure: 1 Open the Object Designer (SHIFT+F12) in User Portal Application Server. 2 Select Dataport and click New to open the Dataport Designer window. 3 Click CTRL+S to save the dataport with the following properties: Field Name Name Value Job No Click OK to save and compile. Modifying a Dataport To modify a dataport so that it will handle XML documents, follow this procedure: 1 In the Object Designer, select the dataport that you created in the previous procedure and click View, Properties. 2 In the Properties window, select the FileFormat property and change its value to UPXML. 3 Select the XMLIncludeTextConst property and change its value to Yes.

122 7-16 User Portal Developer's Guide The following picture shows the Properties window for the Job dataport: Adding Data Items To add the relevant data items to the Job dataport, follow this procedure: 1 In the Object Designer, select the Job dataport that you created earlier and click Design. 2 Add the following data items by clicking the AssistButton p and selecting them from the Table list: Table No. Table Name 167 Job 97 Comment Line 3 Select the data item Comment Line and click View, Properties.

123 Exercises In the Properties window for the data item Comment Line, select the DataItemTableView property and enter the value WHERE(Table Name=CONST(Job)). This will ensure that you only get the comments that relate to Job records. Adding Fields You must now add the fields listed in the Field Name table on page 7-5 to the Job data item and add all available fields to the Comment Line data item. To add fields to a data item, follow this procedure: 1 In the Object Designer, select the Job dataport, click Design and then select the Job data item. 2 Click View, Dataport Fields to open the Field designer.

124 7-18 User Portal Developer's Guide 3 Add the fields listed on page 7-5 as shown in the following picture: 4 Select the Comment Line data item and add all available fields as shown in the following picture: Note For each field where the name contains spaces or dots, you must check the XMLFieldName, Caption and CaptionML properties in order to remove any extra underscores. For example, _No must be changed to No_ in the Table Name, No. and Line No. fields. 5 Save your dataport by pressing CTRL+S. Adding C/AL Code to the Line No. Field In the Comment Line data item, in the Line No. field, you must add C/AL code in the function OnBeforeEvaluateField to generate line numbers

125 Exercises 7-19 stored in the field. 1 Open the Field Designer for the Comment Line data item if you closed it. 2 Select the Line No. line and press F9 to open the C/AL Editor. 3 Click View, C/AL Locals. 4 In the C/AL Locals window, on the Variables tab, create a new variable with the following values: Variable Name Data Type Subtype CommentLine2 Record Comment Line 5 Close the C/AL Locals window. 6 In the C/AL Editor, enter the following lines of code: EVALUATE("Line No.",Text); IF "Line No." = 0 THEN BEGIN LineInserted := TRUE; CommentLine2.LOCKTABLE; CommentLine2.SETRANGE("Table Name","Table Name"); CommentLine2.SETRANGE("No.","No."); IF CommentLine2.FIND('+') THEN; "Line No." := CommentLine2."Line No." ; Text := FORMAT("Line No."); END; 7 Save your dataport by pressing CTRL+S. Adding Text Constants Now we will add the text constants that will be used in the graphic user interface. 1 Click View, C/AL Globals. 2 In the C/AL Globals window, select the Text Constants tab.

126 7-20 User Portal Developer's Guide 3 Enter the text constants listed in the Text Constants table on page 7-6 as shown in the following picture: Remember that text constants are stored in your current application language unless you use the Multilanguage Editor. For more information about languages in Navision Attain, see the manual Application Designer's Guide. 4 Save the dataport by pressing CTRL+S, and close the Dataport Designer. Copy and Paste from Another Dataport Since the GUI design is the same in Views, you can often copy and paste the text constants from a similar dataport. You will then just have to insert references to Job. But be careful not to introduce "Copy and Paste" errors, as they are very misleading to the user.

127 Exercises 7-21 Updating Recently Visited List When our users work with the Employee activity center, we want the Recently Visited menu in their activity center to be updated. In order to do that, you must modify the Job dataport in the following way: 1 In the Dataport Designer window, select the Job data item and click F9 to open the C/AL Editor. 2 In the OnBeforeExportRecord() trigger, enter the following lines of code: IF Get("Document Type"::Job,"No.") THEN BEGIN NewVisit."User ID":= USERID; NewVisit.Description := 'Job' + "No."; NewVisit.Link := 'Job&Job=' + " No." + '&View=Overview'; NewVisit.TableID := DATABASE::"Job": NewVisit.INSERT(TRUE); 3 Compile the dataport. You have now created and modified the Job dataport. The dataport is now ready to import and export data in XML format. The data exported from the dataport is stored in the file c:/tmp/webpartdata1.xml in your debug folder. The next step is to enable global search in Navision Attain and context sensitive search. To do this, you must modify the Search dataport as described in the next exercise.

128 7-22 User Portal Developer's Guide 7.4 ENABLING SEARCH AND LOOKUP To enable search and lookup, you must modify the Search dataport (Dataport 6704). First you add two functions FindJob and SetJob to enable search and lookup for Job. Next you enable lookup for Resource, since you need to be able to lookup Person Responsible in the Resource table. Finally you make changes to the function FindGlobalResultSet to include two calls to FindJob and two calls to FindResource. Modifying Dataport 6704 Search 1 In User Portal Application Server, open the Object Designer. 2 Select Dataport and then open Dataport 6704 Search in Design mode by selecting it and then clicking Design. 3 Click View, C/AL Globals, and in the C/AL Globals window, select the Functions tab. Adding the FindJob Function 1 On the Functions tab and enter FindJob in an available Name field to create a new function. 2 Select the new function and click Locals. 3 In the FindJob C/AL Locals window, on the Parameter tab, create the following parameters: Parameter Name Category Data Type Boolean SearchString Text (250) 4 On the Variables tab, create a new variable with the following values: Variable Name Data Type Subtype Job Record Job

129 Exercises Open the C/AL Editor and enter the following code in the FindJob function: WITH JOB DO BEGIN IF (TableID = 0) AND NOT READPERMISSION THEN EXIT; SetCategory(TABLECAPTION,DATABASE::Job,-1); IF CheckSearchField(MAXSTRLEN("No.")) THEN BEGIN SETFILTER("No.",'%1',SearchString); IF NOT ResultSetFull THEN IF FIND('-') THEN BEGIN IF Category THEN BEGIN AddToCategoryResultSet; EXIT; END; REPEAT SetJob(Job); AddToResultSet; UNTIL (NEXT = 0) OR ResultSetFull; END; SETRANGE("No."); END; IF CheckSearchField(MAXSTRLEN("Search Description")) THEN BEGIN SETCURRENTKEY("Search Description"); SETFILTER("Search Description",'%1',SearchString); IF NOT ResultSetFull THEN IF FIND('-') THEN BEGIN IF Category THEN BEGIN AddToCategoryResultSet; EXIT; END; REPEAT SetJob(Job); AddToResultSet; UNTIL (NEXT = 0) OR ResultSetFull; END; SETRANGE("Search Description"); END; END;

130 7-24 User Portal Developer's Guide Adding the SetJob Function 1 Select the Functions tab and enter SetJob in an available Name field to create a new function. 2 Select the new function and click Locals. 3 In the SetJob C/AL Locals window, on the Parameter tab, create the following parameters: Var Parameter Name Data Type Yes Job Record 4 In the C/AL Editor, enter the following lines of code in the SetJob function: WITH Job DO BEGIN SetData('Job&Job=%2&View=Overview', TABLECAPTION,"No.",Description,''); SetLookupID("No."); END; Adding the FindResource Function 1 Select the Functions tab and enter FindResource in an available Name field to create a new function. 2 Select the new function and click Locals. 3 In the FindResource C/AL Locals window, on the Parameter tab, create the following parameters: Parameter Name Category Data Type Boolean SearchString Text (250) 4 On the Variables tab, create a new variable with the following values: Variable Name Data Type Subtype Resource Record Resource

131 Exercises In the C/AL Editor, enter the following lines of code in the FindResource function: WITH Resource DO BEGIN IF (TableID = 0) AND NOT READPERMISSION THEN EXIT; SetCategory(TABLECAPTION,DATABASE::Resource,-1); IF CheckSearchField(MAXSTRLEN("No.")) THEN BEGIN SETFILTER("No.",'%1',SearchString); IF NOT ResultSetFull THEN IF FIND('-') THEN BEGIN IF Category THEN BEGIN AddToCategoryResultSet; EXIT; END; REPEAT SetResource(RESOURCE); AddToResultSet; UNTIL (NEXT = 0) OR ResultSetFull; END; SETRANGE("No."); END; IF CheckSearchField(MAXSTRLEN("Search Name")) THEN BEGIN SETCURRENTKEY("Search Name"); SETFILTER("Search Name",'%1',SearchString); IF NOT ResultSetFull THEN IF FIND('-') THEN BEGIN IF Category THEN BEGIN AddToCategoryResultSet; EXIT; END; REPEAT SetResource(Resource); AddToResultSet; UNTIL (NEXT = 0) OR ResultSetFull; END; SETRANGE("Search Name"); END; END;

132 7-26 User Portal Developer's Guide Adding the SetResource Function 1 Select the Functions tab and enter SetResource in an available Name field to create a new function. 2 Select the new function and click Locals. 3 In the SetResource C/AL Locals window, on the Parameter tab, create the following parameters: Var Parameter Name Data Type Yes Resource Record 4 In the C/AL Editor window, enter the following lines of code in the SetJob function: WITH Resource DO BEGIN SetData('Resource&Resource=%2&View=Overview', TABLECAPTION,"No.",Name,''); SetLookupID("No."); END;

133 Exercises 7-27 Modifying the FindGlobalResultSet Function All you need now is to add two calls to FindJob in the function FindGlobalResultSet. The first call is used for global search in Navision Attain and the second is used for search in just the Job table. Insert the calls as shown with bold in the code below. Note that not all the code for FindGlobalResultSet is shown in the example below. CASE TableID OF 0: BEGIN FindJob(Category,SearchString); FindResource(Category,SearchString); FindCust(Category,SearchString); FindProspect(Category,SearchString); FindVendor(Category,SearchString); FindItem(Category,SearchString); DATABASE::Job: FindJob(Category,SearchString); DATABASE::Resource: FindResource(Category,SearchString); DATABASE::Customer: FindCust(Category,SearchString); DATABASE::Prospect: FindProspect(Category,SearchString); Save the dataport. This completes the modifications you needed to do to enable search and lookup. The next step is to create the Web part handler.

134 7-28 User Portal Developer's Guide 7.5 DEVELOPING A WEB PART HANDLER You can write your Web part handler in any editor you prefer. Visual InterDev is just as suited for the task as Notepad. First you define the URL parameters, then you create the needed queries, and finally you specify which style sheets to use to transform the XML file into a meta UI XML document. When the Web part handler has been developed, you must install it in Digital Dashboard. Note Web part handlers are based on the Web part framework. The elements of the framework are discussed in Appendix C. XML is case-sensitive, so you must be very careful how you spell the names of elements and data. For brevity, special characters such as & (ampersand) are written in plain text in this chapter. But in XML documents, you must write such characters as &, for example. For more information, see XML documentation. Start by creating a new document in your editor and save it as Job.xml in the NSWebParts folder. Creating Document Root Start by writing the required documents root element: <UserPortalBusinessObject Version="3.1"> Remember that the Version attribute is mandatory. Create URLParameters Element The next step is to declare the URL parameter to be used with Job to pass the contents of the Job No. field to the dataport. In this exercise, you need one URLParam element, Job. The name of the URLParameter is used in the SetJob function in the Search dataport. <URLParameters> <URLParam Name="Job"></URLParam> </URLParameters>

135 Exercises 7-29 Create Queries Element In the Queries element, you specify how to request data from the dataport. You must specify 3.1 as the Version attribute for each Query element. You identify the dataport using the Name attribute, and set the direction to Export. <Queries> <Query Version="3.1"> <Dataport Name="Job" Direction="Export"> Next you send the request to the Job data item that you specified in the Dataport in a previous exercise. <Request DataItemXMLName="Job"> We set a filter on Field1 with the current value of the URLParam Job. (@Job) <Filter Field="Field1">@Job</Filter> </Request> <Request DataItemXMLName="Comment Line"/> </Dataport> </Query> </Queries> Make sure you include end tags for all elements. Create Views Element In the final part of the Web part handler, you specify which XSL style sheets you want to use to transform the XML data. Usually you have this information from you design charts and posters. As described in the Files table on page 7-7, you have three style sheets: Job.xsl JobCreate.xsl JobComment.xsl You can choose any identifier for the style sheets, but we recommend that you use an ID that clearly identifies the style sheet and the task that it is used for.

136 7-30 User Portal Developer's Guide In our exercise, we use the following identifiers: Overview Create Comments The Views element must be similar to the following in order to complete your Web part handler: <Views> <View ID="Overview"> <Source Type="xsl">Job.xsl</Source> </View> <View ID="Create"> <Source Type="xsl">JobCreate.xsl</Source> </View> <View ID="Comments"> <Source Type="xsl">JobComments.xsl</Source> </View> </Views> </UserPortalBusinessObject> Save the Job.xml Web part handler. Installing a Web Part Handler in Digital Dashboard Before you can use your Web part handler, you must install it in Digital Dashboard. To install a Web part, you can use the Administration in Digital Dashboard as described in Microsoft Digital Dashboard documentation. In this exercise, you will use a different approach. We modify the files that Digital Dashboard uses to store information about the organization of Web parts. To install a Web part, you create a DDB file and a DWP file. Next you modify the InstallStructure.xml file and finally you run the InstallDashboard.js to make Digital Dashboard aware of your modifications. Modifying the DDB File 1 In the NSWebParts/Dashboards folder, open the file Item.DDB in any editor. 2 Change the value of the Title element to Job.

137 Exercises Save the file as Job.DDB. Modifying the DWP File. 1 In the NSWebParts/Dashboards folder, open the file Item.XML.DWP in any editor. 2 Change the value of the Title element to Job. 3 Change the value of the ContentLink element to 4 Save the file as Job.XML.DWP. Modifying InstallStructure.xml In the InstallStructure.xml file, you must make two new entries to register the Job dashboard and Job Web part. 1 In the NSWebParts/Dashboards folder, open the file InstallStructure.xml in any editor. 2 In the element <Dashboard name="parts"> section, add a new Web part element: <Web part name="job.xml"/> 3 In the element <Dashboard name="forms"> section, add a new Dashboard element containing the following Web part element: <Dashboard name="job"> <Web part name="job.xml"/> </Dashboard> 4 Save the file. Running InstallDashboard.js In the Factory folder, locate the InstallDashboard.js file and doubleclick it to run the installation. When the script is finished, your new Job dashboard is properly installed.

138 7-32 User Portal Developer's Guide 7.6 DEVELOPING THE JOB OVERVIEW WEB PART The Job Overview Web part will serve as both a read-only and editable view of Jobs. The style sheet will be stored in the NSWebParts folder as Job.xsl. When you start developing a Web part, it helps to have the Debug file C:/tmp/WebPartData1.xml file open in another browser window. This way you can see the correct structure and the correct field names. Since the WebPartData1.xml file is used for all data exported from User Portal Application Server, you need to make sure that the last exported data was a Job record. To ensure this you can enter the following a URL:..Dashboards/Forms/Job. This will export data from the Job table using the dataport and Web part handler you have just created. So even though you have not created a style sheet to format the data for display, it is still stored in the C:/tmp/WebPartData1.xml file. You can then view the structure by opening the WebPartData1.xml file in the browser. Creating Style Sheet First you must write the standard definition and specification for the style sheet. Save the file as Job.xsl in the NSWebParts folder. <xsl:stylesheet xmlns:xsl=" <xsl:template> <xsl:apply-templates/> </xsl:template> <xsl:template match="/"> <WebPartFramework> [The elements described below go here.] </WebPartFramework> </xsl:template> </xsl:stylesheet>

139 Exercises 7-33 Preparing to Receive Messages First add the structure to handle messages captured by User Portal Application Server. <Messages> <xsl:for-each select="/job/messages/message"> <Prompt> <Title><xsl:value-of select="."/> </Title> </Prompt> </xsl:for-each> </Messages> Using this element causes a message box with the message captured in User Portal Application Server. Setting Up BaseURL Next you must set up the BaseURL element. The URL specified here is used as default if no other URL is available. <BaseURL> Job&Job=<xsl:value-of select="/job/job/no_"/> &View=Overview </BaseURL> This BaseURL shows the current Job in Overview view, when no other URL is available. Building the Title Area The Title area of a view consists of three parts: A caption (Job) taken from a text constant and placed in the Caption element. A job number placed in the DataCaption element. A job description placed in the DataCaption element.

140 7-34 User Portal Developer's Guide They are separated with a single space (<xsl:eval>" "</xsl:eval>). <PageTitle> <Caption> <xsl:value-of select="/job/textconstants/caption"/> </Caption> <DataCaption> <xsl:value-of select="/job/job/no_"/> <xsl:eval>" "</xsl:eval> <xsl:value-of select="/job/job/description"/> </DataCaption> </PageTitle> Building the Local Menu In the following subsections, you will build the local navigation area. You build the menu from the top down, starting by adding the context sensitive search, and then you set the Personalization permissions. Finally, you use the Links element to create the menu groups Browse Job, See Also and Common Tasks. Adding Context Sensitive Search The SearchHandler element is used to build the search functionality. The element consists of two main sections: A reference to the text constant containing the title for the Search field (SearchJobs). An URL element where you specify in which table to search. In this case you want to search in the Job table, Table 167. <SearchHandler> <Title> <xsl:value-of select= "/Job/TextConstants/SearchJobs"/> </Title> <URL>Search&TableID=167</URL> </SearchHandler Building the Menu Group Browse Job In the Browse Job group, we add two menu items, Overview and Comments. They are added as Link elements that have LocalMenu as the LinkBlockID attribute, each with a set of Heading, Title and URL subelements. Add the first menu item with the title Overview, or rather the Title element refers to a text constant, Overview. Set the Order attribute to 1, since the

141 Exercises 7-35 Overview menu item is always displayed in the top of a Browse group The Heading element must refer to the BrowseJob text constant with an Order attribute set to 1, since the Browse Job group must be the first menu group in the local navigation area. In the URL element, you specify the URL to this view: <Links> <Link LinkBlockID="LocalMenu"> <Heading Order="1"> <xsl:value-of select= "/Job/TextConstants/BrowseJob"/> </Heading> <Title Order="1"> <xsl:value-of select= "/Job/TextConstants/Overview"/> </Title> <URL> Job&Job=<xsl:value-of select= "/Job/Job/No_"/>&View=Overview </URL> </Link> </Links> You must now add the Comments menu item after the Link element containing the first menu item, Overview. Place it where the three dots,, are in the example above. In the Title element, change the Order attribute to 2 since Comments menu items are always at the bottom of a Browse menu group. Use the Comments text constant to create the text for the menu item. Finally, create the URL using the Comments View parameter. This will load the JobComments.xsl style sheet as specified in the Job Web part handler. <Link LinkBlockID="LocalMenu"> <Heading Order="1"> <xsl:value-of select= "/Job/TextConstants/BrowseJob"/> </Heading> <Title Order="2"> <xsl:value-of select= "/Job/TextConstants/Comments"/> </Title> <URL> Job&Job=<xsl:value-of select= "/Job/Job/No_"/>&View=Comments </URL> </Link>

142 7-36 User Portal Developer's Guide Building the Menu Group See Also In this small example, there are no candidates for the menu group See Also. But if you create another activity center, such as Resource, this could be used for a See Also menu group. When you use the See Also menu group, the Order attribute in the Heading element must be 2. You have already defined text constants containing the menu title. Building the Menu Group Common Tasks In the Common Tasks group, we add four menu items in the following order: Create New Comment Edit Job Delete Job Create New Job Again the text constants provide the heading and menu item texts. In each Link element, in the Heading elements, the Order attribute is set to 3. In the Title elements, the Order attribute is set to 1, 2, 3 and 4 to reflect the order of the menu items. Three of the menu items (1,2 and 4) are very similar; the only difference is the URL (and of course the Title elements and Order attributes). The Create New Comment menu item uses the URL parameters to load the JobComments.xsl with an initialized Comment line: &View=Comments&CreateLine The Edit Job menu item uses the URL parameters to load the Job.xsl in Edit View mode: &View=Overview&Edit The Create New Job menu item uses the URL parameters to load the JobCreate.xsl with an initialized Job record: &View=Create

143 Exercises 7-37 The third menu item, Delete Job, is different from the others. It uses a Prompt element to allow the user to delete the job. <Link LinkBlockID="LocalMenu"> <Heading Order="3"> <xsl:value-of select= "/Job/TextConstants/CommonTasks"/> </Heading> <Title Order="3"> <xsl:value-of select= "/Job/TextConstants/DeleteJob"/> </Title> <Prompt Type="Delete"> <Title><xsl:value-of select= "/Job/TextConstants/DeleteJobPrompt"/> </Title> <URL> Job&Job=<xsl:value-of select= "/Job/Job/No_"/>&View=Overview </URL> </Prompt> </Link> When a user clicks this menu item, a prompt is displayed with the text Delete Job? The Title element in the Prompt element contains the message that you want to display, in this case a text constant. The URL element contains the view to display after the record is deleted. Note that the Browse Job and See Also menu groups must be placed after the Links start tag and before the first Link element in the following example.

144 7-38 User Portal Developer's Guide To build the Common Tasks menu group, enter the following code: <Links> <Link LinkBlockID="LocalMenu"> <Heading Order="3"> <xsl:value-of select= "/Job/TextConstants/CommonTasks"/> </Heading> <Title Order="1"> <xsl:value-of select= "/Job/TextConstants/CreateComment"/> </Title> <URL> Job&Job=<xsl:value-of select= "/Job/Job/No_"/>&View=Comments&CreateLine </URL> </Link> <Link LinkBlockID="LocalMenu"> <Heading Order="3"> <xsl:value-of select= "/Job/TextConstants/CommonTasks"/> </Heading> <Title Order="2"> <xsl:value-of select= "/Job/TextConstants/EditJob"/> </Title> <URL> Job&Job=<xsl:value-of select= "/Job/Job/No_"/>&View=Overview&Edit </URL> </Link> <Link LinkBlockID="LocalMenu"> <Heading Order="3"> <xsl:value-of select= "/Job/TextConstants/CommonTasks"/> </Heading> <Title Order="3"> <xsl:value-of select= "/Job/TextConstants/DeleteJob"/> </Title> <Prompt Type="Delete"> <Title><xsl:value-of select= "/Job/TextConstants/DeleteJobPrompt"/> </Title> <URL> Job&Job=<xsl:value-of select= "/Job/Job/No_"/>&View=Overview </URL> </Prompt> </Link> <Link LinkBlockID="LocalMenu"> <Heading Order="3"> <xsl:value-of select= "/Job/TextConstants/CommonTasks"/> </Heading> <Title Order="4"> <xsl:value-of select= "/Job/TextConstants/CreateJob"/> </Title> <URL>Job&View=Create</URL> </Link> </Links>

145 Exercises 7-39 Setting Permissions Create a Permissions element so that the user can add the Job task to My Frequent Tasks but not have access to other settings. <Permissions> <Personalization> <Content>No</Content> <Layout>No</Layout> <Settings>No</Settings> <AddToFrequentTasks>Yes</AddToFrequentTasks> </Personalization> </Permissions> Creating the Content Area Now it is time to build the Content Area. The Job.xsl style sheet is used for Overview and Edit, so you use the ContentBlock element to present the fields from the dataport. First you set the content area title. Then you use the UpdateInfo element to specify dataport, data item and the redirection URL. Next you use the ModificationOptions element to specify which URL parameters to use to switch modes. Finally you create two columns to hold the fields. Setting the Content Area Title We start by building the actual ContentBlock element and its title stored as a text constant: <ContentBlock> <Title> <xsl:value-of select= "/Job/TextConstants/Overview"/> </Title> </ContentBlock> The following elements are added within the start and end tags of this ContentBlock element.

146 7-40 User Portal Developer's Guide Specifying UpdateInfo The UpdateInfo element is added before the Title element. In the UpdateInfo element, you specify the Job dataport and the Job table in the Dataport and DataItem elements. You must use the same names here as when you created the dataport in Exercise 7.3. <UpdateInfo> <Dataport>Job</Dataport> <DataItem>Job</DataItem> <RedirectionURL>Job&View=Overview&Job =RETURNEDVALUE[/Job/Job/No_] </RedirectionURL> </UpdateInfo> The redirection URL is set to open the same view with the same data once the view has been updated. This way the view is always updated with the data from Navision Attain. If you do not use the redirection URL, the user will not see changes made automatically but have to press Refresh to update the view. Specifying ModificationOptions The ModificationOptions element is the first sub-element in the ContentBlock element. With ModificationOptions you specify which URL parameters to append to the View parameter. Using the specified switches to the mode indicated by the element in which it is declared. This template is only used for Overview and Edit views and only if the Edit element is used. <ModificationOptions> <Edit URLParam="Edit"/> </ModificationOptions> Inserting the Fields We now get to the actual contents of the ContentBlock, the fields that contain the actual data. They are inserted after the Title element. The fields are inserted in two columns. The fields are given properties as if they were only to be used in Edit mode. These properties will only take effect when the view is in Edit mode. The fields are read-only when they are not in Edit mode.

147 Exercises 7-41 The table below outlines which fields are in which column, so you should read it as if it were a layout for the view: Job Field Name No. Description Bill-to Customer No. Name Address Contact Search Description Status Blocked Last Date Modified Address 2 Post Code City Most of the fields are straightforward text box fields. The No_ field is the primary key for the Job table and must not be editable. The Bill_To_Customer_No_ and Person_Responsible fields are Lookup fields and the Status field is an option field. All field captions are stored in the Caption attribute in the element representing the field value. We start by indicating the first column with a Column element: <Column> </Column> Then we fill in the space between the two tags with Field elements. No. Field Set Type="Textbox", Name="No_". Add the attribute Editable="No" to ensure the field is not edited: <Field Type="TextBox" Name="No_" Editable="No"> <Caption> <xsl:value-of select="/job/job/no_/@caption"/> </Caption> <Value> <xsl:value-of select="/job/job/no_"/> </Value> </Field>

148 7-42 User Portal Developer's Guide Description Field Set Type="Textbox", Name="Description": <Field Type="TextBox" Name="Description"> <Caption> <xsl:value-of select= </Caption> <Value> <xsl:value-of select="/job/job/description"/> </Value> </Field> Bill-to Customer No. Field This is a lookup field. Set Type="Textbox", Name="Bill_to_Customer_No_". Add the element Relation of type Lookup to lookup in the Customer table (Table 18). In the URL, you take advantage of the Customer Web part that is already created and use that to display the Customer information. <Field Type="TextBox" Name="Bill_to_Customer_No_"> <Caption> <xsl:value-of select= "/Job/Job/Bill_to_Customer_No_/@Caption"/> </Caption> <Value> <xsl:value-of select="/job/job/bill_to_customer_no_"/> </Value> <Relation Type="Lookup">TableID=18</Relation> <URL> Customer&View =Overview&Customer=<xsl:value-of select ="/Job/Job/Bill_to_Customer_No_"/> </URL> </Field> Name Field Set Type="Textbox", Name=" Name" <Field Type="TextBox" Name="Name"> <Caption> <xsl:value-of select="/job/job/name/@caption"/> </Caption> <Value> <xsl:value-of select="/job/job/name"/> </Value> </Field>

149 Exercises 7-43 Address Field Set Type="Textbox", Name="Address" <Field Type="TextBox" Name="Address"> <Caption> <xsl:value-of </Caption> <Value> <xsl:value-of select="/job/job/address"/> </Value> </Field> Address 2 Field Set Type="Textbox", Name="Address 2" <Field Type="TextBox" Name="Address 2"> <Caption> <xsl:value-of select="/job/job/ Address 2/@Caption"/> </Caption> <Value> <xsl:value-of select="/job/job/address 2"/> </Value> </Field> Post Code Field Set Type="Textbox", Name="Post Code" <Field Type="TextBox" Name= Post Code > <Caption> <xsl:value-of select="/job/job/ Post Code/@Caption"/> </Caption> <Value> <xsl:value-of select="/job/job/post Code"/> </Value> </Field> City Field Set Type="Textbox", Name="City" <Field Type="TextBox" Name= City > <Caption> <xsl:value-of select= "/Job/Job/City/@Caption"/> </Caption> <Value> <xsl:value-of select="/job/job/city"/> </Value> </Field>

150 7-44 User Portal Developer's Guide This was the last field in the first column. Remember to close the column with the end tag: </Column> You follow the same principles to create the fields for the second column. The only special field in that column is the Status field, an Option field. Look in the C:/tmp/WebPartData1.xml for the Status field. Here you see that it has three attributes: Caption, OptionCaption and OptionNo. Caption contains the Caption property of the field. OptionCaption contains the options to display in the Option control when in edit mode. OptionNo contains the number in the selection list of current value. In an Option control, numbering starts at 0 (zero). You do not use this attribute; it is set by the application. Enter the following code to create the Status field as an Option field: <Field Type="TextBox" Name="Status"> <Caption> <xsl:value-of select="/job/job/status/@caption"/> </Caption> <Value> <xsl:value-of select="/job/job/status"/> </Value> <Relation Type="Option"> <xsl:value-of select= "/Job/Job/Status/@OptionCaption"/> </Relation> </Field> Add the remaining four fields and save the style sheet. Now you have created a Web part allowing you to view, edit and delete Job records from the Job table using your browser. Furthermore, you have created a lookup field to look up Customer information, and you have created an Option field allowing you to change the job status. You can also search the Job table from your browser. Finally, you can add the Job to your Frequent Tasks menu.

151 Exercises 7-45 You should now access the activity page in your browser to make sure that it looks right: In addition to that, you have prepared the local navigation area for some more options. In the Browse Job menu group, the Comments menu item will display any comments attached to the Job. And in the Common Tasks menu group, the Create New Comment and Create New Job menu items will open an initialized record to enter new information.

152 7-46 User Portal Developer's Guide 7.7 DEVELOPING THE JOB CREATE WEB PART Once you have created the Job Overview Web part, most of the hard work is done. To develop a Web part that allows you to enter a new Job record is fairly simple compared to the previous exercise. Since the fields you display in the Overview Web part are the same as the ones you want to use to enter data in a Create Web part you can reuse much of the Overview Web part. Open the Job.xsl in your editor and save it as JobCreate.xsl in the NSWebParts folder. Deleted Elements You must delete the following elements and their content: Links SearchHandler These elements are not useful in a Web part that contains a Create task. Unchanged Elements The following elements are not changed: Messages Permissions Changes to BaseURL In the BaseURL element, set the View parameter to Create rather than Overview. Changes to PageTitle In the PageTitle element, refer to the CreateJobTitle text constant rather than the Caption. Delete the DataCaption element.

153 Exercises 7-47 Changes to UpdateInfo Add the attribute Mode to the UpdateInfo element, and set it to Create. <UpdateInfo Mode= Create > Changes to ModificationOptions Add the Create element and set the URLParam attribute to Create. <Create URLParam= Create /> Changes to No_ Field Remove the Editable attribute or set the value to Yes. You have now developed the Create New Job functionality for the menu item in the Common Tasks menu group, and you can open the new page in your browser: In the next exercise, you add the Comments functionality.

154 7-48 User Portal Developer's Guide 7.8 DEVELOPING SUPPORT FOR COMMENTS In the Job dataport, you have specified which table the Comment Line filters for. So all you need now is to add the Comments Line fields. You may not be surprised to hear that all you need to do is to copy and modify the Comments solution for one of the other Web parts. You replace the Local Menu description so it matches the design for the Job Web parts. Open the CustomerComments.xsl style sheet in your editor. 1 Use a Search and Replace tool to find all occurrences of Customer and replace it with Job. 2 Replace the Links and SearchHandler sections with the ones you set up in the Job.xsl document. And now you have support for Comments so that you can view, edit, create and delete Comments to Jobs. This completes the exercises for User Portal.

155 Appendix A. Debugging User Portal In this appendix, you learn how to set up User Portal for debugging and some basic tips about debugging User Portal. This appendix contains the following sections: Debugging User Portal Debugging Output Files Debugging VBScripts Debugging InstallDashboards.js Debugging Errors in Showing Pictures

156 A-II Debugging User Portal A.1 DEBUGGING USER PORTAL The implementation of User Portal allows the user to easily extract debugging information from the system when using User Portal Business Object XML documents as input for a form or Web part. This means that the format and content of the communication between Digital Dashboard, User Portal Application Server and the sequence of transformations that convert XML data into HTML can be monitored. This appendix describes how to make User Portal generate debugging information and what the various output debug files contain. It also describes a debugging technique, which can be used when making Web parts in VBScript. To help troubleshooting, error messages are printed in the content area of the current view, if the view is based on User Portal Business Object XML documents, regardless of whether or not User Portal is running in debug mode. Making User Portal Run in Debug Mode To make User Portal run in debug mode, you must make the Business Object Processor (BOProcessor) and the update handler generate output files. You should also make sure that the debug folder is set up correctly. 1 In the Factory folder, open the files BOProcessor.js and NSUpdate.asp in an editor and assign the value true to the variable bdebugmode in both files. 2 In the Factory folder, open the file Dashboard_const.inc. Make sure that the folder referred to by the constant stdebugdir is placed locally on this computer.

157 Debugging User Portal A-III A.2 DEBUGGING OUTPUT FILES This section lists the debug files that may be generated by User Portal, the conditions under which they are generated and their content. XMLQueryBase.xml This file is generated when the User Portal Business Object XML document contains a valid Query element. It contains the query that was extracted from the document. XMLQueryFinal.xml This file is generated when the User Portal Business Object XML document contains a valid Query element and an applicable View element. It is identical to the previous file, except that all substitutions in the query have been performed. WebPartData.xml This file is generated when the User Portal Business Object XML document contains a valid Query element and an applicable View element. It contains the data that was returned from User Portal Application Server. WebPartMetaUI.xml This file is generated when the User Portal Business Object XML document contains a valid Query element and an applicable View element. It contains the meta UI XML for the XSL transformation of the XML data with the applicable XSL style sheet. WebPartMetaUIExt.xml This file is generated when the User Portal Business Object XML document contains an applicable View element. It contains the XML meta UI with the modifications that caused if you have added elements to the Permissions block. SaveRequest.xml This file is generated when the user accepts an update action. It contains the update request that will be sent to User Portal Application Server.

158 A-IV Debugging User Portal SaveResponse.xml This file is generated when the user accepts an update action. It contains the response from User Portal Application Server, after the previously mentioned update request was processed by it.

159 Debugging User Portal A-V A.3 DEBUGGING VBSCRIPTS When building Web parts in VBScript, the debug files generated by the Business Object Processor will not be generated. But the debug files from the update handler (SaveRequest.xml and SaveResponse.xml) will still be generated. Most of the other debug files can be generated from the VBScript. However, general error messages are not shown in User Portal when using VBScript, which can make development cumbersome. A common technique used to extract debugging information from a VBScript when something is malfunctioning, is to exit the function with some descriptive string that describes how far the processing has come. Moving such an exit statement around in the script can help to locate the instruction that generates an error. Running this script will print the text Put together XML query in the Content Area of the digital dashboard. Moving the getcontent = and exit function instructions around will leave the content area blank. So the error must be somewhere in between the two positions.

160 A-VI Debugging User Portal A.4 DEBUGGING INSTALLDASHBOARDS.JS When you create new Web parts as described in Chapter 5, you must register them in Digital Dashboard using the InstallDashboards.js file. If this file does not in fact install your new Web parts and the script does not even report any errors, follow this procedure: 1 In Windows Explorer, make a copy of the InstallDashboards.js file. 2 Open the InstallDashboards.js file in an editor, for example Notepad. 3 Delete the keyword try. 4 Delete the block beginning with catch. 5 Save the file and run the script again to get a proper error message.

161 Debugging User Portal A-VII A.5 DEBUGGING ERRORS IN SHOWING PICTURES Pictures can be inserted into any view, for example in the Item Overview. This does not usually cause any problems, but your users could see the following icon rather than the real picture:: The first thing you should do is to check the settings in the dashboard_const.inc file, which you find in the Factory folder. For more information about these settings, see the manual User Portal Installation Guide. When you are sure that the settings are correct, you can proceed with the real debugging. To debug missing pictures in User Portal views, follow this procedure: 1 Right-click the icon for the missing picture and select Properties. 2 In the Properties window, select the URL for the missing picture. Identifier First two lines of the URL address. Click and drag to select all of the URL. 3 Place the cursor at the beginning of the Address field and drag the mouse down to select all of the URL, which is typically three lines. When you have selected the URL, press CTRL+C to copy the URL to the clipboard.

162 A-VIII Debugging User Portal 4 Paste the URL into the Address field in your browser and press ENTER. The browser will display an error message that you can use to debug the problem.

163 Appendix B. User Portal Basic Terminology List This appendix contains the terminology list for User Portal.

164 B-II User Portal Developer's Guide activity center A special type of digital dashboard that relates to a particular role and that incorporates the activities related to that role. A role can have more than one activity center. A user portal consists of a number of activity centers. Home is not an activity center but a user portal. area The term to describe the sections that the screen (browser page) is divided into, for example, logo area, global navigation area, local navigation area, title area and content area. Each of these areas is defined. block The technical term to describe the smaller components that make up the content of a Web part defined in a meta UI. A block can contain subblocks. business object An object in the program that is defined in terms of the business domain it relates to and not from the programming perspective. For example, a sales order is a single business object that is made up of two different table objects (a Header table and a Line table). content area The area that contains the different Web parts that constitute the page. dashboard A dashboard is a single page in the framework of Microsoft Digital Dashboard. Digital Dashboard A Microsoft framework that User Portal uses as the foundation. global navigation area The navigation area that is placed on the top of the screen, and contains links to the activity centers that a certain user has access to. This is always

165 User Portal Basic Terminology List B-III the same for a user. local navigation area The navigation area that is placed on the left part of the screen, and contains links to other pages. The links are dependent on the Web parts that make up the content area. logo area The area used for placing the customer s logo, and links to other related information. It is placed on the upper left corner of the screen, and is always the same. meta UI Meta UI is an abstract definition of the user interface. The meta UI contains all the necessary information that defines the user interface, but not the display information. Meta UI is built of a number of blocks. The renderer handles the display information. navigation area The area used for navigating purposes within the user portal; this can either be within an activity center or between the different activity centers. renderer The tool that transforms the content of a Web part (defined in meta UI) to the user interface thereby making it visible to the user. role In User Portal, a role reflects the type of tasks a user works on. The role defines the types of activity centers that a user has access to. Users can have several roles and each role can have more than one activity center. title area The area that contains the title for the current content displayed in the content area. It is placed on top of the screen just below the global navigation area.

166 B-IV User Portal Developer's Guide User Portal The name of the solution, and the term that describes the customizable entry site (Home) on the Web that is made up of a number of activity centers, which gives users a single point of access to the information and the applications (for example, Navision Attain) that they need to carry out their tasks. User Portal Application Server User Portal Application Server is a middle tier server that exports data from and imports data into Navision Attain so that you can access Navision Attain from a Web browser. view An area that contains data related to a single business object. The types of views that reflect the level of detail are: overview view, details view and related views. Web parts One or more components that make up the content area of a dashboard. Web parts contain the information that we want to display in the dashboard. A Web part is a Microsoft term related to Digital Dashboard. Note Navision capitalizes this differently from Microsoft.

167 Appendix C. Meta User Interface Reference Guide Meta user interface is a description of how data is to be presented on the user s screen. All of the user interface elements, described in Chapter 3, are represented as one or more structured XML elements. The meta UI XML is generated by an XSL processor acting on a XSL templates and the XML data extracted by the User Portal dataport. This appendix contains the following sections: Introduction BaseURL Element PageTitle Element Permissions Element LinkBlock Element Links Element SearchHandler Element Summary Element ContentList Element ContentBlock Element Field Element Messages Element XML Syntax

168 C-II User Portal Developer's Guide C.1 INTRODUCTION The Web part framework was described in the context of queries in chapter 5. As a reminder, here is the complete outline of the Web part framework: <WebPartFramework> <BaseURL>[Base URL]</BaseURL> <Permissions>[Permissions]</Permissions> <PageTitle>[Page Title]</PageTitle> <Summary>[Summary]</Summary> <ContentBlock>[Content Block]</ContentBlock> <ContentList>[Content List]</ContentList> <LinkBlock>[Link Block]</LinkBlock> <Links>[Links]</Links> <SearchHandler>[Search Handler]</SearchHandler> <Messages>[Messages to be displayed]</messages> <HTML>[HTML]</HTML> <Report>[Report]</Report> <Lookup>[Lookup]</Lookup> <SearchResultBlock>[SearchResult]</SearchResultBlock> </WebPartFramework> Note The Web part framework is based on the Extensible Markup Language, XML. XML is case sensitive, so you must be very careful how you spell the names of elements in each XML document and XSL style sheet. This appendix contains a description of those framework elements that are most frequently used in the current version of User Portal. The last section of this chapter, section C.13, describes the XML syntax for requests and response documents. Meta UI and Views XSL style sheets provide XML data with meta UI elements that guide the data towards a particular kind of view. The actual components displayed on the page will depend on the layout of the view. User Portal defines three kinds of view: Overview Details Related View

169 Meta User Interface Reference Guide C-III The following three sections describe the layout and Web part framework elements of each kind of view. The individual elements are then described further in the sections C.2-C.12. Overview A view in Overview mode contains an overview of a business object presented in a single ContentBlock element. <WebPartFramework> <PageTitle> </PageTitle> <ContentBlock> </ContentBlock> <Links> </Links> <SearchHandler> </SearchHandler> </WebPartFramework> The PageTitle element contains the title of the view, such as the number and name of a customer. You can compare the ContentBlock element to a tab on a card form in Navision Attain, and it contains the most important information about this business object. The content in a ContentBlock element is displayed in the content area of the screen, as described in Chapter 3. The Links element contains links to other views and tasks, which are displayed in the local navigation area. The SearchHandler element handles the search function that is also displayed in the local navigation area. The Overview layout is outlined in the following picture: Global Navigation Area PageTitle Local Navigation Area ContentBlock 1 Links Company Logo SearchHandler

170 C-IV User Portal Developer's Guide Details In the Details view mode, a view may have one or more ContentBlock elements in order to display all relevant information about the business object. <WebPartFramework> <PageTitle> </PageTitle> *<ContentBlock> </ContentBlock> <Links> </Links> <SearchHandler> </SearchHandler> </WebPartFramework> The elements contain the same information as described for the Overview mode, but the Details view mode can contain several ContentBlock elements. The Details view layout is outlined in the following table: Global Navigation Area PageTitle Local Navigation Area ContentBlock 1 ContentBlock n Links SearchHandler Company Logo Related View A view in a Related view mode contains a summary of the current business object and a list of related objects. These are displayed in the content area. <WebPartFramework> <PageTitle> </PageTitle> <Summary> </Summary> <ContentList> </ContentList> <Links> </Links> <SearchHandler> </SearchHandler> </WebPartFramework>

171 Meta User Interface Reference Guide C-V The Related view layout is outlined in the following picture: Global Navigation Area PageTitle Local Navigation Area Summary ContentList Links Company Logo SearchHandler Meta UI The sections from C.2 to C.12 describe the elements in the meta UI style sheets that are attached to XML documents to guide the data towards views. Important In XML, the character & (ampersand) and a number of other special characters have special meaning. For brevity, these characters are written in plain text in this appendix. However, in XML documents, you must write such characters as &, for example. For more information about XML and special characters, see XML documentation.

172 C-VI User Portal Developer's Guide C.2 BASEURL ELEMENT The BaseURL contains a link to an empty view for a business object. This empty view is displayed to the user when an item has been deleted, for example. Example When you have deleted a customer, you are shown an empty view where you can create a new customer because the BaseURL element looks like this: <BaseURL> Customer&Customer=10000&View=Overview </BaseURL> As a result, the following view is displayed:

173 Meta User Interface Reference Guide C-VII C.3 PAGETITLE ELEMENT The PageTitle element describes the displayed title. This element contains definitions of both a caption and a data caption. The caption typically indicates the current view, and the data caption identifies the data. <PageTitle> <Caption>[This is the page title]</caption> <DataCaption>[The data caption]</datacaption> </PageTitle> The following example shows the PageTitle element used to create the title Customer The Cannon Group PLC shown in the picture below. The values can be generated dynamically by selecting text constants in User Portal Application Server. <PageTitle> <Caption>Customer</Caption> <DataCaption>10000 The Cannon Group PLC</DataCaption> </PageTitle> This is rendered into the page title in the following picture:

174 C-VIII User Portal Developer's Guide C.4 PERMISSIONS ELEMENT The Permissions element controls permissions to certain system functionalities. If there is no Permissions element, these functionalities are displayed as menu items in the Personalize menu group in the local navigation area as Add this page to My Frequent Tasks, Web Parts, Layout and Settings: You can use the Permissions element to restrict the user's access to these functionalities by setting the value to No. In User Portal, you are allowed to personalize activity centers but not forms, so the Permissions element is used to restrict access to the personalization functionalities in certain views. When you take away permission to a specific functionality, the menu item is no longer shown in the Personalize menu. The syntax for the Permissions element makes it possible to add other permissions groups automatically in future versions of User Portal: <Permissions> <[Permissions group]> <[permission 1]>[Value]</[permission 1]> <[permission n]>[value]</[permission n]> </[Permissions group]> </Permissions> The following example takes away access to Settings and Web Parts: <Permissions> <Personalization> <Settings>No</Settings> <Content>No</Content> <Layout>Yes</Layout> <AddToFrequentTasks>Yes</AddToFrequentTasks> </Personalization> </Permissions> As a result, the menu items are not shown either:

175 Meta User Interface Reference Guide C-IX C.5 LINKBLOCK ELEMENT The LinkBlock element is a building block for creating Web Part Folders, which you can read about in section 3.2. Once you have defined a Web part folder using the LinkBlock element, you can add menu items to it using the Links element described in section C.6. <LinkBlock> <ID>[Identification]</ID> <Title>[Title to be displayed]</title> </LinkBlock> ID Element The ID element is a unique identification for the menu. The ID is referenced by the LinkBlockID attribute in the Link element. Title Element The Title element contains the title to display for the menu. User Portal has two predefined menus, the Local Navigation Area (ID LocalMenu) and My Frequent Tasks (ID MyFrequentTasks), and there are two predefined Web part folders, Sales Tasks (ID SalesTasks) and Sales Information (ID SalesInformation). Example The My Frequent Tasks menu is defined in the meta UI style sheet MyFrequentTasks.xsl in the NSWebParts folder. In that document, the placeholder is defined with a LinkBlock element: <LinkBlock> <ID>MyFrequentTasks</ID> <Title>My Frequent Tasks</Title> </LinkBlock> The menu items in the My Frequent Tasks menu are defined by a Links element.

176 C-X User Portal Developer's Guide C.6 LINKS ELEMENT The Links element is used to add menu items to a predefined menu such as My Frequent Tasks and the local navigation area. In most cases you use the Links element to add the appropriate menu items in the local navigation area for the view you are creating. The Links element contains one or more Link elements, depending on how many menu items you want to add. For each menu item you want to display, you add one Link element to the Links element. <Links> <Link>[Menu item 1]</Link> <Link>[Menu item n]</link> </Links> Example The examples in this section are taken from the style sheet Customer.xsl in the NSWebParts folder. The following picture shows the part of a local navigation area that is defined by a Links element: This menu controls views related to the Customer business object, and the menu items are sorted into two menu groups: Browse Customer and Common Tasks. In each menu group, the menu items are defined by Link elements.

177 Meta User Interface Reference Guide C-XI Link Element Each Link element defines a link with a description of URL, title, menu group and any associated prompt. To build the menu in the example above, you need 10 Link elements, one for each menu item. The structure of a Link element is as follows: <Link LinkBlockID="[Menu Name]"> <Heading Order="1">[Menu Group Caption]</Heading> <Title Order="1">[Menu Item Caption]</Title> <URL Current= [Yes or No] Type= [Http or Mail] > [ViewName& Identifier1=keyvalue1& Identifier2=keyvalue2&] View=[Type of view] </URL> <Prompt Type= [Delete or Confirm] > <Title>[Messages to display]</title> <URL>[URL to go to after a Cancel]</URL> </Prompt> </Link> LinkBlockID The LinkBlockID attribute specifies which LinkBlock, or menu group, the menu item belongs to. To add a menu item to the local navigation area described above, enter the following: <Link LinkBlockID="LocalMenu"> To add a menu item to the My Frequent Tasks list, enter the following: <Link LinkBlockID="MyFrequentTasks"> To add a menu item to a custom menu such as a Web part folder, enter the following: <Link LinkBlockID="[the ID specified in LinkBlock]"> Heading The Heading element specifies the heading for a group of menu items, such as Browse Customer. If a preceding Link element has specified the same heading, then the link is placed in this group. Otherwise a new group is created. With the Order attribute, you can specify where the menu group is placed in the menu in relation to the other menu groups in this Links element. If you

178 C-XII User Portal Developer's Guide use the Heading Order attribute, you must follow these design guidelines: Group Browse [Business Object] For example Browse Customer See Also Common Tasks Heading Order <Heading Order="1"> <Heading Order="2"> <Heading Order="3"> These rules ensure consistency across the User Portal solution making it more transparent to the user. Title The Title element specifies the hyperlink text. The Order attribute specifies the order in which the menu items will be displayed within their menu groups. The Overview menu item must always be placed as the first menu item. This ensured by setting the Order attribute to 1: <Title Order="1">Overview</Title> The Comments menu item must always be placed as the last menu item. You can make sure of this by setting the Order attribute to the number of menu items in this menu group. The Browse Customer group has four menu items, so the order attribute for Comments is set to 4. <Title Order="4">Comments</Title> URL The URL element can contain the URL to a view, an external web page or an . The URL values beginning with HTTP are assumed to be global Internet URLs. The syntax for an URL referencing to a view is: Name of Web part handler &data item= [data item key] &View= [view mode] The following example is a reference to the Overview view for Customer 10000: <URL> Customer&Customer= &View= Overview </URL>

179 Meta User Interface Reference Guide C-XIII The URL element has two optional attributes, Current and Type. Current Attribute in the URL Element When Current is set to Yes, the menu item refers to the view currently displayed. Setting the attribute to Yes disables the menu item, and the Title text is colored red, but this feature is not used in the current version of User Portal. Type Attribute in the URL Element You use the Type attribute when the URL is a reference to an , external web page, internal reference to User Portal, a file, an FTP site or Navision Attain. In the current version of User Portal, the attribute two values are used, Http and Mail. The Type value Http creates a link to an external web page: <URL Type= Http > </URL> The Type value Mail creates a standard HTML Mailto link: <URL Type= Mail> JR@Cronus.com </URL> In addition to these, the URL element can contain neither type, in which case the URL is to an internal User Portal view as shown in the following example: <URL> Customer&Customer= &View= Overview </URL> Prompt The Prompt element in a Link element creates a message box with two buttons, OK and Cancel. The message box is displayed when the user clicks the link.

180 C-XIV User Portal Developer's Guide <Prompt Type= [Confirm or Delete] > <Title></Title> <URL Type= [Html or Mail] ></URL> </Prompt> In the Title element you specify the message you want to display in the message box. The URL element is used when the Type attribute is set to Delete. The URL is executed when the user clicks OK. Link Example The following example show the Link elements used to build the menu groups in the view Customer Overview of Customer 1000 based on Customer.xsl. In this example, we only show some of the Link elements.

181 Meta User Interface Reference Guide C-XV Browse Customer <Link LinkBlockID="LocalMenu"> <Heading Order="1">Browse Costumer</Heading> <Title Order="1">Overview</Title> <URL Current= Yes > Customer&Customer=10000&View=Overview </URL> </Link> <Link LinkBlockID="LocalMenu"> <Heading Order="1">Browse Costumer</Heading> <Title Order="2">Sales Quotes</Title> <URL> Customer&Customer=10000&View=SalesQuotes&DocType=0 </URL> </Link> <Link LinkBlockID="LocalMenu"> <Heading Order="1">Browse Costumer</Heading> <Title Order="3">Sales Order</Title> <URL> Customer&Customer=10000&View=SalesOrders&DocType=1 </URL> </Link> Common Tasks <Link LinkBlockID="LocalMenu"> <Heading Order="3">Common Tasks</Heading> <Title Order="4">Edit Customer</Title> <URL> Customer&Customer=10000&View=Overview&Edit </URL> </Link> <Link LinkBlockID="LocalMenu"> <Heading Order="3"> Common Tasks</Heading> <Title Order="5">Delete Customer</Title> <Prompt Type="Delete"> <Title>Delete Customer?</Title> <URL> Customer&Customer=10000&View=Overview </URL> </Prompt> </Link> If customer.xsl had contained a See Also menu group, the view would have been based on the following : <Link LinkBlockID="LocalMenu"> <Heading Order="2">See Also</Heading> <Title Order="1">Contact</Title> <URL> Contact&Customer=10000&View=Overview </URL> </Link> You can see an example of how to use the See Also menu group in the document SalesOrder.xsl.

182 C-XVI User Portal Developer's Guide Setting Up Menu Groups Menu items are group in menu groups that are formed based on the contents of the Heading element. The order of the groups is determined by the Order attribute, and the name of a groups is determined by the value of the Heading element. In the example above, the first three menu items are placed in the first menu group, Browse Customer: <Heading Order="1">Browse Costumer</Heading> Links to other business objects are placed in the menu group See Also: <Heading Order="2">See Also</Heading> The last two menu items are placed in the third menu group, Common Tasks: <Heading Order="3">Common Tasks</Heading> A menu group is created the first time it is mentioned by a Link element. For example, when the first Link element is the example above names Browse Customer as the heading, a group called Browse Customer is created. The next two Link elements are added to that group because they have the same Heading element: <Heading Order="1">Browse Costumer</Heading> The last two Link elements are added to a new group, Common Tasks, which was created earlier by a Link element not shown in this example. Order Within Submenus The menu items are ordered within the submenus as specified by the Order attribute to the Title element within the Link element: <Title Order="1">Overview</Title> <Title Order="2">Sales Quotes</Title> <Title Order="3">Sales Order</Title> <Title Order="4">Edit Customer</Title> <Title Order="5">Delete Customer</Title>

183 Meta User Interface Reference Guide C-XVII URL in Link Element When the user clicks on a menu item, the URL specified in the URL element of that Link element is executed. The menu items in the section Link Example above have URLs that give the results listed in the following sections. Sales Quotes Customer&Customer=10000&View=SalesQuotes&DocType=0 This URL element links to a page with the sales quotes for customer In this example, there are five quotes for customer

184 C-XVIII User Portal Developer's Guide Sales Order Customer&Customer=10000&View=SalesOrders&DocType=1 This URL element links to a page with the sales orders for customer Contact Contact&Customer=10000&View=Overview&Contact=CT This URL element links to a page with contact no. CT000001:

185 Meta User Interface Reference Guide C-XIX Edit Customer Customer&Customer=10000&View=Overview&Edit This URL element links to an overview page for customer where the values can be edited. The buttons Change Now and Cancel are added to the page. The Delete Customer menu item contains a Prompt element with the type Delete, so when the user clicks Delete, a message box appears asking the user to confirm the action. The URL specified in the Prompt element s URL element is executed when the user clicks OK in that message box: <URL> Customer&Customer=10000&View=Overview </URL> In this case, the URL is a reference to the page just deleted, so User Portal displays a blank page where you can create a new customer or use the Search function. This is the same URL as is used in the BaseURL element.

186 C-XX User Portal Developer's Guide C.7 SEARCHHANDLER ELEMENT The SearchHandler element must be included in all views in order to provide a context-sensitive search: <SearchHandler> <Title>{Search Caption]</Title> <URL>[Search&TableID=ID]</URL> </SearchHandler> The values in the Title element and the URL element are used to build the Search Area, for example the one used in the Customer views: Title Element The Title element is used to specify which text to show in the title. URL Element The URL element is used to specify which action to take when the user clicks Search. In User Portal, a special Web part handler, Search.xml, is provided to manage the search. The Web part handler Search.xml accepts six URL parameters: Title Query Start Area TableID SubID For a detailed description of these parameters, see Chapter 5.

187 Meta User Interface Reference Guide C-XXI C.8 SUMMARY ELEMENT The Summary element defines a simple collection of fields that are displayed together. The Summary element is usually used as a header for a list or a search results element. Data displayed using the Summary element cannot be edited. The Summary element contains a Column element that contains Field elements. The structure of the Summary element is outlined below. <Summary> <Column> <Field> </Field> <Field> </Field> </Column> </Summary> The Summary element is a simplified version of the ContentBlock element that is described in section C.11. Example In the following picture, you can see the result of a Summary element containing one column and two fields. The element displays the customer number and name for customer Also notice that the Personalize menu is displayed because the view does not have a Permissions element.

188 C-XXII User Portal Developer's Guide The page shown above is based on the following Summary element: <WebPartFramework> <Summary> <Column> <Field> <Caption>No.</Caption> <Value>10000</Value> </Field> <Field> <Caption>Name</Caption> <Value>The Cannon Group PLC</Value> </Field> </Column> </Summary> </WebPartFramework> Note The summary page is used here as an example of how to use the Summary element. User Portal does not contain such a summary page.

189 Meta User Interface Reference Guide C-XXIII C.9 CONTENTLIST ELEMENT The ContentList element describes how to display a single table of data. The ContentList element is used specifically to display a list of related details such as comments. The structure of the ContentList element is outlined below: <ContentList> <ModificationOptions> <Edit URLParam= Edit /> <Create URLParam= Create /> <Delete URLParam= Delete > <PromptTitle></PromptTitle> </Delete> </ModificationOptions> <EmptyListText></EmptyListText> <Title>[This is the content list title]</title> <Headings> <Heading>[Column 1 Heading]</Heading> </Headings> <Rows> <RowUpdateInfo Mode="Edit"> <Dataport>[The Dataport Name]</Dataport> <DataItem>[The Dataport Item]</DataItem> <DataItemIdentifier> </DataItemIdentifier> </RowUpdateInfo> <Row> <Field></Field> </Row> <Row> <Field></Field> </Row> </Rows> </ContentList>

190 C-XXIV User Portal Developer's Guide The following picture contains the Comments page for Customer 10000: Each row contains one comment. In this example, there are three comments. The table consists of two columns. The first column consists of three row headings, and two rows with three fields. The three fields contain data from Navision Attain. The second column, Actions, shows the options you have for each comment line, in this case Edit and Delete. The table is created by the ContentList element. The summary above the table is created by a Summary element. ModificationOptions Element Each row in a content list can be modified by what is described in a ModificationOptions element. You use this element to make it possible to edit, create and delete a single row in the table created by the ContentList element. The ModificationOptions element can contain the following elements: Edit Delete Create The Actions column is added to the table if either the Edit or the Delete element (or both) is used. If the only ModificationOptions element is Create,

191 Meta User Interface Reference Guide C-XXV the Actions column is only added to the table if the URLParam is used in the URL. Each element has a mandatory attribute, the URLParam: <ModificationOptions> <Edit URLParam="[parameter]"/> <Delete URLParam="[parameter name]"> <PromptTitle>[Message] </PromptTitle> </Delete> <Create URLParam="[parameter name]"/> </ModificationOptions> Edit The Edit element allows the user to edit an existing row. The mandatory attribute URLParam is used to specify the name of the parameter used to enter Edit mode for a row. The value of this parameter is the part of the primary key that differentiates one row from another. For example: /Customer&Customer=10000&View=Overview&EditLine=20000 The links in the Actions column are Edit and Delete. When the user clicks Edit, the link opens the row in Edit mode and the Edit link is replaced by the link Change Now. In the picture below, you can see this in the second row of the Comments table. Delete Element If you use the Delete element, you can allow the user to delete an existing row. The mandatory attribute URLParam is used to specify the name of the parameter used to enter Delete mode for a row. The value of this parameter is the part of the primary key that differentiates one row from another. The PromptTitle element is mandatory for the Delete element. You use the PromptTitle element to specify the message displayed in the message box. The Delete link is added to the Actions column when the Delete element is present. Clicking Delete opens a message box containing the messages and an OK and a Cancel button. Clicking OK deletes the selected row.

192 C-XXVI User Portal Developer's Guide In the following picture, a message box is displayed because the user has just clicked Delete (in the Actions column) in the third row of the table: The other possible action for this row is Edit. In the second row, the user has clicked Edit and the row is displayed in an editable form. The links in the Actions column have changed from Edit and Delete to Change Now and Cancel. Create Element You use the Create element to allow the user to create a new line. The Create element has a mandatory attribute, URLParam. Unlike the two other elements, you have to use the URLParam in the URL to enter Create mode. For example, you can create a menu item in the local navigation area where you attach the URLParam.

193 Meta User Interface Reference Guide C-XXVII In the following picture, you can see the menu item Create New Comment in the Common Tasks menu group. When you click this menu item, a new editable row is added to the table allowing you to create a new comment line. Note the links Create and Cancel. The menu item Create New Customer uses the following URL: /Customer&Customer=10000&View=Comments&CreateLine The example below illustrates how you can use the ModificationOptions element. <ModificationOptions> <Edit URLParam="EditLine"/> <Delete URLParam="DeleteLine"> <PromptTitle> Delete Comment? </PromptTitle> </Delete> <Create URLParam="CreateLine"/> </ModificationOptions> The following examples of URLs refer to the same style sheet, but they have different URLParams appended to the view parameter. Default view /Customer&Customer=10000&View=Comments

194 C-XXVIII User Portal Developer's Guide This produces a read-only list of all comments for Customer No with both the Edit and the Delete links are available in the Actions column. Using EditLine /Customer&Customer=10000&View=Overview&EditLine=20000 This produces a list of all comments for Customer No The row identified by the EditLine value (Line No ) is in Edit mode. In the Actions column for this row, the links Change Now and Cancel are available. For the other rows, the Edit and the Delete links are available in the Actions column. Using CreateLine /Customer&View=Overview&CreateLine This produces a list of all comments for Customer No plus a new editable row. In the Actions field for this row, the links Create and Cancel are available. For the other rows, the Edit and the Delete links are available in the Actions column. Using DeleteLine /Customer&Customer=10000&View=Overview&DeleteLine=20000 This produces a read-only list of all comments for Customer No with both the Edit and the Delete links available in the Actions column. Using this URL will not delete the line. The line is not deleted until the user clicks Delete and then clicks OK in the message box. EmptyListText Element The EmptyListText element is used to specify the text to display when the list is empty. The value can be generated dynamically if you use references to text constants. The following example is for the Customer Sales Quotes list: <EmptyListText> There are no quotes for this customer. </EmptyListText>

195 Meta User Interface Reference Guide C-XXIX Title Element The Title element is used to specify the title to display in the page. For example: <Title>Quotes</Title> Headings Element The Headings element is a container for Heading elements. Heading Element The Heading element is used to specify a single row heading. Note You must have the same number of Heading elements as the number of Field elements in the Row elements. Rows Element The Rows element contains the Row elements used to specify rows in the table, and the RowUpdateInfo element in the Rows element specifies how an update is handled and which view mode the data is displayed in. <Rows> <RowUpdateInfo> <Dataport>The Dataport Name</Dataport> <DataItem>The Dataport Item</DataItem> <DataItemIdentifier></DataItemIdentifier> </RowUpdateInfo> <Row> <Field></Field> <Field></Field> </Row> </Rows> RowUpdateInfo Element The RowUpdateInfo element specifies information that the system uses when updating the data in a row. The system adds Mode attributes. Dataport Element You use the Dataport element to specify which dataport to use.

196 C-XXX User Portal Developer's Guide DataItem Element You use the DataItem element to specify which data item to use in the dataport for the rows. DataItemIdentifier Element You use the DataItemIdentifier element to specify which Request element in the XML Web part handler is used to create a new record. Note The Type attribute must match the type specified in the Request element and the value must match the value set in attribute in the Request element. Row Element Each row defines a number of Field elements. One field is defined for each column displayed. This means that the number of fields equals the number of headings in the preceding Headings element. <Row> <Field> </Field> <Field> </Field> </Row>

197 Meta User Interface Reference Guide C-XXXI C.10 CONTENTBLOCK ELEMENT A ContentBlock element defines one or more columns that contain a number of fields. A ContentBlock element would normally have just one or two columns. The ContentBlock element is similar to a tab on a card form in Navision Attain. The structure of a ContentBlock is outlined below: <ContentBlock> <ModificationOptions> <Edit URLParam= Edit /> <Create URLParam= Create /> </ModificationOptions> <UpdateInfo> <Dataport>[The Dataport Name]</Dataport> <ReDirectionURL>[Link]<ReDirectionURL> <DataItem>[The Data Item]</DataItem> </UpdateInfo> <Title>[This is the content title]</title> <Column> </Column> <Column> </Column> </ContentBlock> The following picture shows a page where a ContentBlock defines the content area with two columns:

198 C-XXXII User Portal Developer's Guide ModificationOptions Element The ModificationOptions element allows you to use the same style sheet to create Read-Only, Create, and Edit views. A view is by default always readonly unless URLParam values have been appended to the URL. You use the elements Edit and Create to specify the modes that the view can be in. In each element, the attribute URLParam is used to specify the parameter to be appended to the URL. The elements contain no values. The example below illustrates how you can set a style sheet to be read-only, and enable edit and create. <ModificationOptions> <Edit URLParam= Edit /> <Create URLParam= Create /> </ModificationOptions> To invoke one of the modes you append the value of the attribute URLParam to the View parameter in the referring URL. The following URLs refer to the same style sheet but with different URLParams appended to the view parameter. In this URL, the View parameter has no URLParam values appended to it: /Customer&Customer=10000&View=Overview The result is an overview of Customer No , presented as read-only.

199 Meta User Interface Reference Guide C-XXXIII In the following URL, the URLParam Edit has been added to the View parameter: /Customer&Customer=10000&View=Overview&Edit The result is an overview of Customer No presented in an editable form, where changed values are submitted when you click Change Now:

200 C-XXXIV User Portal Developer's Guide In the following URL, the URLParam Create has been added to the View parameter: /Customer&Customer=10000View=Overview&Create The result is a view where you can enter data for a new customer. The new values are submitted when you click Create: As a rule, you do not want to use the same style sheet for both edit and create. In Edit mode, you want to make sure that the values used to identify the record are not changed. This means that in Edit mode you must make those fields read-only, but in Create mode you do want them to write enabled, for example in tasks where the navigation options must be limited. In that case, you need to use different style sheets. Column Element The Column element defines one or more fields displayed in a column on the page. <Column> <Field> </Field> <Field> </Field> </Column>

201 Meta User Interface Reference Guide C-XXXV UpdateInfo Element The UpdateInfo element specifies information that the system uses when updating the business object. The dataport and data item specify through which dataport and data item the update is processed. <UpdateInfo> <Dataport>[The Dataport Name]</Dataport> <ReDirectionURL>[Link]<ReDirectionURL> <DataItem>[The Dataport Item]</DataItem> </UpdateInfo> ReDirectionURL Element This element is used to specify where to go after an Update event has taken place. For example, it can be used when the Update is a Create, Edit or Delete. So when the user clicks Create Now, Change Now or Delete Now to confirm, the ReDirectionURL is executed. In other words, when the user has created a new item, the ReDirectionURL element ensures that the user is presented with the result of his work, that is, an Overview view of the new item. The function RETURNEDVALUE returns the value of the field specified. The syntax is as follows: RETURNEDVALUE[/dataport/dataitem/XMLFieldName] This function is used to specify a value from the returned document when issuing an update. Also after a user has created a new record, the data can be displayed for the user. The following example shows how it can be accomplished: <UpdateInfo> <Dataport>ProductionBOMHeaderUpdate</Dataport> <ReDirectionURL> ProductionBOMHeaderUpdate&View =ProductionBOMLineList&BOM =RETURNEDVALUE[/ProductionBOMHeaderUpdate /Production_BOM_Header/No_] <ReDirectionURL> <DataItem>Production_BOM_Header</DataItem> </UpdateInfo>

202 C-XXXVI User Portal Developer's Guide C.11 FIELD ELEMENT The Field elements are used in the Summary element, ContentList element and ContentBlock element. You use one Field element for each field used in a view. The Field element contains attributes to specify the formatting, and elements to specify caption, value and relation. The following example shows the elements used in the Field element to specify the caption, value and relationships to other tables. <Field [attributes]> <Caption>[Field Caption]</Caption> <Value>[Field Value]</Value> <Relation Type="[Relation Type]">[Type]</Relation> <FieldLength>[Link to database]</fieldlength> <URL>[URL]</URL> </Field> The following sub sections contain descriptions of the elements and attributes available when the Field element is used within a Summary element, ContentList element or ContentBlock element. Attributes for the Field Element The table below contains the valid attributes to the Field element. The two columns to the left list the name and accepted values of each attribute. In the three columns to the right, you can see if the attribute can be used in each element that contains the Field element. Attributes in the Field element Apply when used in these elements Name Value Summary Content List Content Block Type Textbox, Image, Spacer Yes Yes Yes Name Unique within view Yes Yes Yes Visible Yes, No Yes Yes Yes KeepOldValue Yes, No No Yes Yes Editable Yes, No No Yes Yes Align Left, Center, Right No Yes No AutoValidate Yes, No No Yes Yes

203 Meta User Interface Reference Guide C-XXXVII Type Attribute The Type attribute is used to specify which type the field is. The following three types are available: Field Type Textbox Image Spacer Description Any text or number represented as text A URL to the image that is displayed Adds an empty line The type Spacer is only available for the fields used in a ContentBlock. Name Attribute The Name attribute is used internally to identify updates to the fields when they are in Edit mode. The name must be unique within the same view. Visible Attribute The Visible attribute is used to hide fields from the user. Some fields are needed to identify the primary key but do not need to be displayed for the user. Visible="No" hides the field. Editable Attribute The Editable attribute is used to make a field not editable when the mode for the whole view is Edit or Create. This is useful for example in Edit mode, where you want to prevent the user from editing values that make up the primary key. KeepOldValue Attribute Field values that are not changed in an Edit view are by default not sent back to User Portal Application Server. Setting the KeepOldValue attribute to No forces the value to be sent back to User Portal Application Server, even though it was not changed.

204 C-XXXVIII User Portal Developer's Guide AutoValidate Attribute In some fields, when the user edits this field, the validate code for that field initializes other fields on the form with values. For example, if the user enters the number of an item in the No. field, the system fills in the Description field. If the AutoValidate attribute is set to Yes, this will happen automatically. If the attribute is set to No, the validate code will not be called until the record is saved. Caption Element The Caption element is displayed as a label for the control on the page. Value Element The Value element is displayed as the value on the page. Relation Element Fields with relationships to other tables may include a Relation element: <Relation Type="[Relation Type]">[Value]</Relation> The table lists the different Relation types available. The first column lists the values available for the Type attribute. The second column specifies what the value in the element is used for. A description is provided in the last column. Relation Type Value Description Option List of option values Displays the AssistButton f. The DropDown menu contains the values specified in the list of option values. DropDown Dataport that must return the values for the dropdown Displays the AssistButton f. The DropDown menu contains the values from the dataport.

205 Meta User Interface Reference Guide C-XXXIX Relation Type Value Description Lookup TableID=[the number of the table to look up in]". Displays the AssistButton p. When the user clicks the AssistButton, the system looks up the specified table and displays it on a separate page. On this page, the user selects a value and is returned to the Edit view. ConditionalLookup Conditions Displays the AssistButton p in the same way as Lookup, but a ConditionalLookup depends on what has been specified in another field. For example, in an order line, the Lookup in the No. field is conditioned by the contents of the Type field for that line (G/L Account, Item or Resource). The following example shows how the conditional lookup could be used: <Field Type="TextBox" Name="No_"> <Value>1000</Value> <Relation Type="ConditionalLookup" ConditionRelationType="Option" ConditionRelation="Type"> <Condition ID="1">TableID=15</Condition> <Condition ID="2">TableID=27</Condition> <Condition ID="3">TableID=156</Condition> </Relation> <URL>Item&View=Overview&Item=1000</URL> </Field> The Type attribute is ConditionalLookup, which then requires the attributes and elements below. The ConditionRelationType attribute can only have the value Option, which means that the condition is controlled by an Option field. The ConditionRelation attribute contains the XML name of the field that controls the relation. This field must be of type Option. The Condition element identifies the tables that set the conditions for this field. The ID attribute is based on the numerical values of the OptionString property for the field that the relationship is linked to.

206 C-XL User Portal Developer's Guide In the example, the No. field has a conditional lookup relationship with the Type field. Numerical Value in Type Field Lookup from No. Field 0 No lookup 1 Table 15 2 Table 27 3 Table 156 FieldLength Element This element is used to define the length of the field. You can hardcode the length in millimeters, but we recommend that you reuse the information returned from the database, for example: <FieldLength> <xsl:value-of select="/salesorder/ Sales_Header/Document_Type/@FieldLength"/> </FieldLength> URL Element The URL element behaves the same way as the URL element described in the Link element (see section C.6 Links Element).

207 Meta User Interface Reference Guide C-XLI C.12 MESSAGES ELEMENT You use the Messages element to display a message box. The message element is outline below. You refer to the message text in the Title element. The structure is outlined below. A messages box is displayed after the View is loaded. <Messages> <Prompt> <Title>[Message to display]</title> </Prompt> </Messages> Static Messages If you enter the message text directly in the style sheet the message is displayed each time the View is loaded, for example: <Messages> <Prompt> <Title>Hello World</Title> </Prompt> </Messages> The following message box will then be displayed each time the view is loaded: Capture Messages from Navision Attain User Portal Application Server captures messages in the Navision Attain client and returns them with the XML data. For example, a confirmation message triggered by converting a sales quote to a sales order is return in the XML data. By referring to the Message elements in the XML data, you ensure that a message box is only displayed when needed.

208 C-XLII User Portal Developer's Guide The Messages element below checks the returned XML data for messages to display so that only messages captured from the client are shown in the browser: <Messages> <xsl:for-each select="/customer/messages/message"> <Prompt> <Title><xsl:value-of select="."/></title> </Prompt> </xsl:for-each> </Messages>

209 Meta User Interface Reference Guide C-XLIII C.13 XML SYNTAX As mentioned in Chapter 4, User Portal Application Server handles requests to and responses from Navision Attain. The application server uses dataports to import and export XML data, and the XML documents that contain this data must follow the syntax described in the following sections. The asterisks (*) indicate that the XML document can have several such elements. Italics indicate that you or the system has to enter information here. Each element and term is explained in the last subsections on page C- XLV. Export and Init Requests to Dataports Export requests and Init requests follow the same syntax: <Dataport ID="[Dataport ID]" Name="[Dataport Name]" Direction="[Direction]"> *<Request DataItemXMLName="[DataItem XML Name]" DataItemVarName="[DataItem Var Name]" DataItemIndex="[DataItem Index]"> <Init/> *<Filter Field="[Field Name]">[FieldValue] </Filter> <Key>[Key Field List] </Key> <Sorting>[Sorting] </Sorting> <RequestForm> *<Control ID="[Control ID]" Name="[ControlName]"> [Control Value] </Control> </RequestForm> </Request> </Dataport> Import Requests to Dataport Import requests follow this syntax: <Dataport ID="[Dataport ID]" Name="[Dataport Name]" Direction="[Import]"> *<Update Type=[Update Type]"> *<[DataItem XML Name]> <[Field XML Name]> [Field Value] </[Field XML Name]> *<[DataItem XML Name]/> </[DataItem XML Name]> </Update> </Dataport>

210 C-XLIV User Portal Developer's Guide Export, Init and Import Responses from Dataport All responses except errors follow the same syntax: <[Dataport Name]> *<[DataItem XML Name] Version="[Version ID]"> *<[Field XML Name] Caption="[Field Caption]" FieldLength="[Field Length]" OptionCaption="[Option Caption]" Option="[Option Value]" CompanyName="[Company Name]" TableID="[TableID]" FieldNo="[FieldNo]"> [Field Value] </[Field XML Name]> *<[DataItem XML Name]/> </[DataItem XML Name]> <TextConstants> *<[Text Constant Name]> [Text Constant Value] </[Text Constant Name]> </TextConstants> <Messages> *<Message>[Message] </Message> </Messages> </[Dataport Name]> Reports The request XML format for reports is very similar to the XML format for dataports: <Report ID="[Report ID]" Name="[Report Name]"> *<Request DataItemXMLName="[DataItem XML Name]" DataItemVarName="[DataItem Var Name]" DataItemIndex="[DataItem Index]"> *<Filter Field="[Field Name]">[Field Value] </Filter> <Key>[Key Field List]</Key> <Sorting>[Sorting]</Sorting> <RequestForm> *<Control ID="[Control ID]" Name="[Control Name]"> [Control Value] </Control> </RequestForm> </Request> </Report>

211 Meta User Interface Reference Guide C-XLV But the response document contains embedded HTML: <Report> <Title>[Report Title]</Title> <HTMLHead> <![CDATA[ [HTML Header] ]]> </HTMLHead> *<Page PageNo="[Page Number]"> <![CDATA[ [HTML for Page] ]]> </Page> <HTMLFoot> <![CDATA[ [HTML Footer] ]]> </HTMLFoot> </Report> Error Messages If an Export, Init or Import request generates an error, the normal response document is cancelled and a new document is sent with the following syntax: <Errors> <Error> [Error] </Error> </Errors> Elements in Dataport Documents In the following table you can see an explanation of the elements and other terms used in the patterns above: Term Dataport ID Dataport Name Direction DataItem XML Name DataItem Var Name DataItem Index Field Name Definition The ID of a dataport object. The Name property of a dataport object. The Direction of the dataport. Values: Import, Export, and Init. Default value is Import. The XML name of a data item (XMLDataItemName property). The name of the variable of the data item (DataItemVarName property). The index number of the data item. The index of the first data item is 0 (zero). A field name in the data item. Field names can be specified as "Field3" or "#3".

212 C-XLVI User Portal Developer's Guide Term Field Value Key Field List Sorting Control ID Control Name Control Value Update Type Field XML Name Version ID Field Caption Field Length Option Caption Option Value Company Name Table ID Field No Text Constant Name Text Constant Value Message Error Definition The value (contents) of the field. List of fields in a Key. Field names are comma delimited. The sort order of the table specified in the data item. Values are Descending and Ascending with Descending as default. ID of a control on the dataport s request options form. Name of a control on the dataport s request options form. The value (contents) of the control. The type of update requested. Values are Read, Insert, Modify, Delete, ValidateInsert and ValidateModify with Read as default. XML name of a dataport field (XMLFieldName property). The version of the record. The Caption property of a field for multilanguage use. The length of the field in millimeters, calculated from the data type and data length. The value of the OptionCaptionML property of the field. Only for fields of type Option and Boolean. The Option Value property value of the option for multilanguage use. Only for fields of type Option and Boolean. The name of the current application company. Only for fields of type BLOB. The ID of the table that the field belongs to. Only for fields of type BLOB. The number of the field. Only for fields of type BLOB. The name of a text constant. The value of a text constant. The text specified in a MESSAGE function. The error text.

213 Meta User Interface Reference Guide C-XLVII Elements in Report Documents In the following table you can see an explanation of the elements and other terms used in the patterns above: Term Report ID Report Name DataItem XML Name DataItem Var Name DataItem Index Field Name Field Value Key Field List Sorting Control ID Control Name Control Value Report Title HTML Header HTML for Page Page Number HTML Footer Error Definition The ID of a report in Navision Attain. The Name property of a report in Navision Attain. The XML name of a data item (XMLDataItemName property). The name of the variable of the data item (DataItemVarName property). The index number of the data item. The index of the first data item is 0 (zero). A field name in the data item. Field names can be specified as "Field3" or "#3". The value (contents) of the field. List of fields in a Key element. Field names are comma separated. The sort order of the table specified in the data item. Values are Descending and Ascending with Descending as default. ID of a control on the report s request form. Name of a control on the report s request form. The value (contents) of the control. The title of the report. HTML code for starting the <HTML> and <HEAD> elements. HTML code for one page of the report. The number of the page. HTML code for ending the <HTML> and <HEAD> elements. The error text.

214

215 Appendix D. References In this appendix you find references to extra information. The references are sorted in the following categories: User Portal Digital Dashboard Usability XML and XSL