Table of Contents

CLICK in a Nutshell

CLICK is a tool available to AgGateway members that helps business analysts and developers comprehend and implement AgGateway Open Standards.

Getting Started with CLICK

Download

1. Log in at http://www.aggateway.org.
2. In the menu, select eConnectivity | eConnectivity Tools |CLICK. (This may change in the future as AgGateway improves the structure of its website.)
   
3. Click on the download link.
   

Install

1. Go to your download folder.
2. Right click on the zip file.
3. Choose properties.
   
4. Check the Unblock checkbox if you see one.
5. Click OK.
   
6. Right click on the download file.
7. Choose Extract All.
   
8. Choose a folder to which you would like the files extracted (e.g., Documents folder).
9. Once the files are extracted, go to that folder.

Run

1. Double click on the CLICK folder.
   
2. Double-click on CLICK.exe to launch the application.

Create a Desktop Shortcut (optional)

1. Right click on CLICK.exe.
2. Choose Send To from the pop-up menu.
3. Choose Desktop (create shortcut).
   
4. Go to desktop.
   
5. Double-click the shortcut to launch CLICK.

User Interface Overview

1. In the top-right is CLICK version 3.1.0.0. Your version is likely to be a later version.
2. Next is the standard and version dropdown list.
   
3. CLICK supports AgGateway Open Standards going back to version 4, OAGi Chem eStandards going back to version 4, and AgXML version 4.
4. Next is the Context dropdown list.
   
5. Over the years, AgGateway has collected notes on implementing standards in various contexts, e.g., crop protection for Canada, seed and feed for the United States.
6. Next is the Open New Window button, which will be addressed later in this documentation.
7. In the Search section, you can search by All Elements in the standard, or by Messages Only.
   REPLACE
8. Choose Messages Only.
9. In the search box, type order.
10. Note that the search results include any message with order in its name, which includesOrderChange where Order begins the message name and RetailerOrderSummaryReport where Order occurs in the middle of the name.
    
11. Click on one of the search results and note that the structure is shown in the treeview in the center.
    
12. Next, search All Elements.
13. Search for product.
14. As you may expect, there is a large number of search results. There are so many, that it exceeds the current supported number of search results displayed.
15. You may need to narrow your search to find the results you seek.
    
16. Search ordercreate.
17. As it appears in the search results, click on it so that its structure appears in the main tree view.
    
18. As you click on the disclosure triangles, the structure unfolds.
    
19. As you click on various items, in this case ProductIdentifier, content on the right is filled in for that selected item.
    
20. For ProductIdentifier, we see the definition: The unique code or number for a specific product.
    
21. We see Notes, which includes synonyms.
    
22. We see a list of Parent Elements.
    
23. We see a list of Messages in which ProductIdentifier appears.
    
24. When you click on Agency, there is no information to the right. However, there is a code list which includes AGIIS-ProductID, ANSI, AssignedByBuyer, and others.
    
25. There are a number of visual cues in CLICK.
26. Items that are in bold indicate required, which is supported by the occurrence listed after the item.
27. For example, Header indicates 1..1, which means a header is required. One is required and only one is permitted.
    
28. Moving down to OrderCreateProductLineItem, it indicates 1..*, which indicates that one is required but many may occur.
    
29. There are also icons to the left of the text, that give some indication of whether or not an element has structure, or whether it is just a value and whether or not an item may occur many times.
30. The icon next to OrderCreateProductLineItem is a structure icon with a plus sign on it, which indicates that there can be more than one. That visual cue is complemented supported by the text that follows, 1..*.
31. Consider ShipNotice.
32. Choose the USA | Feed context.
    
33. Choose ShipNoticeStatus.
    
34. Hide Parent Elements and Messages to provide more room and resize the Notes section.
35. You then will see that there is a Context Note.
    
36. The notes indicate that when you implement ShipNotice in the context of a feed related process in the United States, that this note applies.
37. It says, "In this context [USA | Feed] the elements use is conditional [i.e., depends on the situation]. If a ShipNotice is updated, then send Update as the status otherwise would not use this on an original ShipNotice."
38. Notice that when you click on ShipNoticeStatus in the Search Results, which brings ShipNoticeStatus to the top, the context notes go away. This is a very important point because context notes require a drill-down starting at the root of a message.
    
39. Click on ShipNotice in the Messages section to go back to the top.
40. Switch back to OrderCreate.
41. Drill down to ScheduleDateTimeInformation under the OrderCreateProductLineItem.
42. Examine DateTimeInformation. Notice that it is composed of a choice. An implementer would choose DateTime, or DateTimeRange as required.
    
43. CLICK indicates this by having a Choose... item in the treeview with enclosed options.
44. Notice that when you hover the mouse over DateTimeRange, a tool tip appears.
    
45. In this case it says "Structure for ranges of date/time information. All DateTime elements need to conform to ISO 8601."
46. Next, examine ContractProductLineItem.
47. Note that a child of ContractProductLineItem is itself, ContractProductLineItem. If you drill down on that you see another ContractProductLineItem.
    
48. This is recursive. CLICK allows you to keep drilling down as far as you want.
49. As we'll see later, when we produce Excel documentation, that situation is addressed by just including the first occurrence and just adding the word recursive in parenthesis afterwards.
50. Another CLICK feature, is to right-click on an element and choose Hoist from the context menu.
    
51. Doing so hoists the selected element to the top and that makes it the root of the displayed tree.
52. Another handy feature is Open New Window. Click on Open New Window.
    
53. Doing so creates a new window.
54. Set the windows side by side and hide various panels.
    
55. In the left panel, choose AgGateway Open Standards Version 4.0.0.
    
56. Search for Partner Information again.
57. You'll notice that in Version 4, UnloadingPoint and LoadingPoint are just text.
    
58. In Version 5.3, they are structures.
    
59. A final feature to note is that you can navigate by using the arrow keys. Click on an item in the tree view, and the up and down arrow keys go up and down. The right-left arrow keys will expand or collapse structures.

Excel Documentation

1. Launch CLICK.
2. Select a context, for example, USA | Feed.
   
3. Search shipnotice and select it in the search results.
   
4. Click on the ShipNotice node in the treeview.
5. Right click on ShipNotice in the treeview and choose Create Excel Documentation from the context menu.
   
6. You are immediately presented with a message informing you that a file is being created in the background and will be saved on the desktop.
7. There are a couple things to note about the file name. It starts with the name on the element that we right clicked on, in this case ShipNotice. It is followed by a date-time stamp and by the extension xlsm, which indicates a macro-enabled excel file.
   
8. Open the file.
9. The first thing to note is that at the top is a security warning that tells us that the macros have been disabled.
10. Click on Enable Content. You'll see why this is important in a moment.
    
11. The contents on the File_Info worksheet (i.e., tab) have the date the file was produced, the time, what standard is being documented, what its version is, the context for the contextual notes, information about the application itself, and license information.
12. The Legend worksheet explains various visual cues, which should be consistent with CLICK.
    
13. The next worksheet provides a few tips.
    
14. Next is the Schema worksheet. This is the main worksheet.
    
15. Double click on ShipNotice. Doing so should reveal the ShipNotice attributes and child elements, which in this case includes Header and ShipNoticeBody.
16. Consider the various columns that are available. Min..Max in column C, which tells whether attributes are required or optional, and the occurrence of elements. In this case Header, one is required, and only one is permitted, same with ShipNotice Body. You'll notice other numbers as you expand other elements. Next is Description, the Data Type or Code List, which version as a fixed value equal to 5.3, Sample Values, Notes, and xPath. There is no content in them for now, but there will be as you expand them.
17. Drill down to ShipNoticeStatus.
    
18. You'll see that on line 267, ShipNoticeStatus is not bold, indicating that it is not required, which corresponds to column C, which says that it has a minimum occurrence of 0 and a maximum occurrence of 1.
19. Note that ShipNoticeDate right above it on row 264 is required and is bold. (Note that your row number may not be 264, depending on what version you exported to Excel.)
20. Now let's consider Excel behavior. This isn't CLICK specific or specific to this file, it is just how Excel behaves, which may be helpful in terms of how you use the Excel files that are produced.
21. You can see that in column H for ShipNotice, which is the notes, that only some of the content is visible. There are a couple of ways to see more of the content.
22. One way is to double click on the cell itself, which puts Excel in edit mode for that cell, which allows you to see more of the content–all the way down to the context note.
23. We have the context note because we chose USA | Feed as the context and it pulled that information and included it in the notes.
    
24. Press the Esc key on your keyboard to exit edit mode.
25. Note that if you press enter by mistake, just do Ctrl+Z, or click the undo button on the toolbar. 
26. Another approach is to can down on the formula bar to make it bigger.
    
27. As you go to different cells you can see all of the content.
28. Some elements have two plus signs. When you double-click on a cell with two plus signs, it expands all of the descendants. For example, if we double-click on RequestedDocument, it expands all of the descendants.
    
29. If you double-click on the cell with two plus signs again, it will collapse it all.
30. If you double click on the two plus signs to the left of ShipNotice, it expands all of the content.
    
31. Circling back to a comment earlier in this documentation, note the recursive indication for ShipmentPackaging.
    

Other Features

Copy XPath to Clipboard

1. Go to ShipNoticeStatus.
   
2. Right click on it and choose Copy XPath to Clipboard.
3. Past it all into a text editor. (Consider Microsoft's Visual Studio Code. It's free and available for Windows, Mac, and Linux. That's what is shown in the screen-capture images that follow.)
   
4. It includes the XPath all the way from the root.
5. Hoist RoutingInstructions to the top and copy that XPath to clipboard.
   
6. Paste into a text editor.
7. Note that once again it goes from the top of the treeview, while not including Choice and Options.

Create Sample XML

1. Right-click on an element and choose Create Sample XML.
2. When creating sample XML document, just like creating Excel documentation, it produces the file in the background and presents a message indicating that.
3. If you switch to the desktop you will see that the file is present. Open it in a text editor.
   
4. Some sample values are more realistic than others.
5. In some cases there is a choice, where both choices are included.
6. The XML file that CLICK produces is not valid against the corresponding XML schema. Notably, it is missing the XML namespace references.

Create Schema Subset

1. Right-click on an element and select Create Schema Subset. When creating an XML schema subset, it produces the file in the background and saves it to the desktop.
2. Open the file in a text editor.
   
3. The contrast between the CLICK presentation and the text you see in the text editor should emphasize the purpose of CLICK: Hide all of the angle brackets, element declarations, and type definitions; and just present the schema in an intuitive way.

Provide Feedback

1. Select USA | Feed as the context.
2. Right click on ShipNoticeStatus and choose Email Question or Comment.
   
3. Past the content into a text editor (or for real comments, the body of a new email).