Creating a new BOX

From the NetConfig tool, you select threads or destinations to create a BOX. All referenced files are automatically included.

During BOX creation, configurations are defined as parameters that are editable. BOX resources can be edited and thread environment properties can be configured similar to the BOX deployment Wizard. This helps when creating standard interfaces and BOXes for sharing and deploying to other environments.

  1. Select the threads/destinations to include in the BOX.
  2. Right-click and select Create BOX. You can also select File > Create BOX.
    After selecting Create BOX, the system checks if there are any validation errors for the thread configurations of the current NetConfig. If so, then a message opens prompting confirmation to continue. The error message differentiates between included threads and threads not included, so you can make an informed decision.
  3. Selecting Create BOX opens the New BOX wizard.
    On this dialog box you configure the BOX basic information. Existing properties can be modified or new properties added on this dialog box. Similar to the BOX Property dialog box, the Name field is required, and cells on the Metadata table are editable. Version and Create Time are auto-populated.

    The BOX Name supports only letters, digits, underscores, or dots in the middle, and can be up to a length of 100.

    For Location, specify the location or click Browse to open a file browser where you select the location. The top folder is $HCIROOT\box. If the location does not exist, then when you click Finish after configuration a confirmation opens for users who require creating the directory. The generated BOX entry is stored into the specified location.

    Metadata values are saved in a box.ini file located at \integrator\box. This removes the necessity of re-entering common values. For example, Author and Organization are often going to be the same value. Having these values saved in an ini file saves you the time of re-entering those values over again.

    The box.ini file is a template for BOX properties. Values that are defined in this file are used as the default properties for the next BOX creation. Selecting Save As Default saves the current properties and values to box.ini.

    Selecting Restore restores all values to the system default values. This feature does not affect box.ini. When Restore is clicked, the list table is refreshed with the system’s built-in properties, not the properties that are defined in box.ini. This is useful when it is not necessary to use the template properties, to reconfigure from scratch. Values that are saved as default are still loaded when creating a new BOX.

    Properties include:

    • Author: Current user name. In basic/advanced security, it is the log-in user. In Windows, it is the log-in user name when in non-security mode.
    • Create Time: The BOX creation time
    • Organization: Organization name
    • Source Data Type: Data format type
    • Source System: System name
    • Source System Version: System version
    • Tag: BOX with same tag can be searched through the BOX searching function
    • Target Data Type: Data format type
    • Target System: System name
    • Target System Version: System version
    • Version: BOX version, starting from 1.0
  4. Click Next. This opens the Options for References Resources dialog box.
    On this dialog box, you can include or skip referenced resources.
    • Some referenced threads/destinations are not selected on NetConfig.

      For example, there are three threads named "a", "b" and "c." Thread "a" routes to "b" and "b" routes to" c." If only thread "a" and "b" are selected to create a new BOX, then the new BOX is incomplete without thread "c."

      If you do not include that thread, then all the routes leading to that thread are not added into the new BOX; otherwise, all referenced threads are added into the BOX. If these referenced threads also have routes to other threads, then other threads are also added into the new BOX.

    • Some referenced resources are from master site or the Cloverleaf root.

      If you specify package resources from anywhere, then resources from the master site or root level are packaged along with site level resources. When deploying this BOX in the future, there is no distinguishing of the master site level, root level, or site level resources; they are all at the same level.

      In the Master Site or Root Resources section, options are grouped into two categories.

      • Whether to include Master Site or Root level resources for reference finding:

        Ignore non-current site resources: Any resources from a Master Site or Root are not returned when reference processing. They are not displayed on the BOX resource tree in the next step of the Create BOX wizard.

        Include non-current site resources: Master Site or Root level resource files are returned when references processing, and these resources are included in the new BOX.

      • How to package Master Site or Root level resources:

        Replicate and package as current site resources: New BOX resource files are organized as before, where Master Site or Root level resource files are put into site level resource folders.

        Replicate and package as original location: Master Site and Root level resource files are saved separately from site level resource files. In this way, other level resources return to their original folders during BOX deployment.

      • In Thread Route Deployment, when Only keep the routes with destination threads in BOX is selected, the route messages and route replies are deleted when the destination thread is not packaged in the BOX.
  5. Click Next. This opens the Modify Resource Description dialog box. On this dialog box, all required Cloverleaf artifacts which are referenced by previously selected threads are listed on the left-hand side. They are categorized by type as a tree structure.
    The BOX resource tree shows other level resources in other root tree nodes:
    • Site level resources are grouped into a root node named Site.
    • Master Site level resources are grouped into a root node named Master Site.
    • Root level resources are grouped into a root node named Root.

    Depending on the selected option combination from the previous dialog box, this tree only shows site level resources or all level resources.

    The right-hand side text area is for entering further descriptions of any packaged item.

    The IDE auto populates all referencing resources of the selected threads/destinations, and optionally includes those resources located in the master site and root. All included resources in the BOX are the same level regardless of whether they originate from the master site or root.

    For process/thread/destination nodes, the process/thread/destination notes are shown in the text area by default. Modified descriptions for process/thread/destination are not saved in the manifest file, but propagated into the packaged process/thread/destination notes. For other nodes, the description text area is initially blank. Updated descriptions are saved to the manifest file.

    The BOX resource tree is editable. The toolbar’s Add Resource option is used to manually add most types of BOX resources. Clicking the arrow next to Add Resource opens a listing resources. Selecting Add Libraries opens the Add Additional Libraries dialog box.

  6. Because BOX supports to remember a file’s original path, the Java UPoC libraries path is also remembered, similar to the common library files. There is no requirement to distinguish Java UPoC library files from common library files.
    Selecting Add File or Add Folder opens a file chooser, where you can select files/folders under the hci ROOT folder.
    Click OK to add the selected library resource files to the BOX resource tree. This is where library files from other levels are grouped under other tree nodes.
  7. When a file is selected, its name and description display in the Resource Name and Resource Description fields. These can be changed as required. This is useful for users that must rename a thread or process to match production during BOX creation.
    The resource name is validated by the system and prompts an error message if an invalid name is entered.
  8. You can also manually add/delete procs or other files on the tree.
    For example, suppose you have written a TPS procedure called mytps which is included in a new Tcl file test.tcl. This TPS procedures calls another procedure myother of type other which is located in another Tcl file test2.tcl. If you use mytps in a thread and you include this thread in a BOX, then test.tcl is added to the BOX. The test2.tcl file is not added. After deployment, you miss the myother procedure. The BOX tool does not detect the requirement for test2.tcl. This is only detected by parsing the Tcl code. As a user, you should be aware of thetest2.tcl file missing in the BOX. The possibility to add files manually in a BOX solves this issue.
    • Select Add Resources to open the Add Procs dialog box, from which you can manually add procs to a BOX. Adding a selection to the Selected list and then clicking OK adds it to the BOX dialog box.
    • Click the Add Resources arrow to open a list of available resources which you can manually add to a BOX.

    After a selection is made, the appropriate dialog box opens showing the available configurations, scripts, and so on. Adding a selection to the Selected list and then clicking OK adds it to the BOX dialog box.

  9. If a Database Schema resource node is selected, then a Configuration tab displays on the right side of the dialog box.
    Modifications to the configuration fields are saved into the dbconfiguration.ini file of the BOX being created.
  10. Click Next. Set the environment configurations of the BOX being created. This assists in sharing and deploying to other environments when distributors create standard interfaces and BOXes.
    The creator of the BOX knows the configuration values to set, so the receiver of the BOX has no requirement to do any configuration.

    This configuration is the same as the BOX Property dialog box.

  11. Click Finish. A new BOX is created with the given name under the folder $CL_ROOT$/box.