| Previous Contents Index Next |
| BuyerXpert/SellerXpert 4.1 (BuyerXpert SP3) Administrator's Guide |
Chapter 12 Administering Configuration Files
The types of configuration files discussed in this appendix are:
Master Configuration File
Customization/Localization Files
Codes File
Note The application configuration files are the master.ntv file and the appInfo files.
Master Configuration File
The master configuration file of BuyerXpert/SellerXpert, master.ntv, can be found in the following locations:APPS/com/iplanet/buyer/config
APPS/com/iplanet/buyer/admin/config
Note The name and location of the master.ntv file cannot be changed.
Both framework and application configuration information exists as a set of NTV structures (sections) in the master.ntv file. The sections are called:
Each of these structures is made up of one of several files residing in app-root/AppName/config.
The set of NTV files making up configuration the NTV files is determined by the following syntax in the master configuration file:
NTV {
"repository" StrArr [ "rep_common.ntv", "rep_oms.ntv", "rep_catalog.ntv" ],
"messages" StrArr [ "/ecommerce/arch/config/arch_msg.ntv", "msg.ntv",
"msg_oms.ntv" ],
"codes" Str "codes.ntv",
"appInfo" Str "appInfo.ntv"
}This master file says that the repository is the result of merging of three NTV files, as well as the message NTV file. A file name like rep_common.ntv is relative to the application's configuration directory, which is app-root/appName/config, whereas an absolute path starting with / (slash) is relative to app-root. Since every AppName/config directory can contain multiple subdirectories, one for each supported locale, there should be a master.ntv file in each of them.
Sometimes it is helpful to have more than one configuration for a single application. For example, servlets developed exclusively for testing purposes may require special configuration (such as repository entries) which are not necessary for the real application. This is solved by having multiple master files; master.ntv for the real application configuration and master_test.ntv for testing.
To command the test servlet to use the test configuration, pass an additional URL parameter:
__Cfg=test
Note This value is kept in session data, so it is enough to pass it only once per session.
The extends and defaults attributes allowing you to specify inheritance relationships across NTV entries are supported for all configuration NTVs. Moreover, the semantics of extends is expanded so that cross-level inheritance is now possible. For example, the following NTV structure will be expanded so that Node3 will inherit Attr1 and Node4 will inherit Attr2.
NTV {
"Node1" NTV {
"Attr1" Str "Value1"
},
"Node2" NTV {
"Node3" NTV {
"extends" Str ".Node1" // starts with "." meaning relative to the root
},
"Node4" NTV {
"extends" Str "A.B" // relative to the current level
},
"A" NTV {
"B" NTV {
"Attr2" Str "Value2"
}
}
}
}
When specified together, the extends attribute is processed before defaults. And file mergers (specified by master.ntv) are done before inheritance relationships are processed.In the master.ntv file, the names of the different sections (repository, messages, and so on) cannot be changed. The ordering of the sections is not relevant.
The repository section lists all the DOR (Data Object Repository) files. The DOR files define the mapping between POF objects and Business Objects. The DOR files also act as a repository for UI elements such as text boxes, list boxes, and so on. More information on DOR files follows.
The messages section lists all the files that contain messages that get displayed in the user interface. More information on the messages files follows.
The codes section lists all the codes files. More information on the codes files follows.
The appInfo section lists all the configuration information for the different modules as well as the configuration information for the application itself. The application information is in a file called buyerInfo.ntv, which has to be the last in the list of appInfo files. This is to ensure that the entries in buyerInfo.ntv override any duplicate entries in the module-specific configuration files.
The data model section lists datamodel files. The data model specifies the types of POFs available for use by BuyerXpert/SellerXpert. It also specifies the mapping of the persistent objects to the data source schema.
Application Info Files
The application information (appInfo) files are used by the different components to store configuration information. Most of this information cannot be changed.For example, the order management system stores the criteria for splitting a requisition into purchase orders in the lguConfig.ntv file. The information in this file cannot be changed. However, xdoc stores some information in the following file, which is configurable:
ias/APPS/com/iplanet/buyer/config/xdoc/xdocinfo.ntv
Some of the appInfo files that you will be configuring include:
buyerInfo.ntv
buyerInfo.ntv
The most important appInfo file is buyerInfo.ntv. This file deserves more explanation, because it contains application configuration information with which the administrator has to be familiar.Here is how a sample buyerInfo.ntv looks:
"on_auth_error" Str "NonAuthTemplate.jsp",
"params_for_exceptions" Bool "true", // exception params in log file
"stack_for_exceptions" Bool "true", // stack trace in log file
"stack_top_ignore" StrArr [ "CXDebug.", "CXReporting." ],
"stack_bottom_cut" StrArr [ "BeanLogic.execute", "CXBaseServlet.do" ],
}, // End of default message_type
"active" Bool "false", // disabled for now. will enable later.
"params_for_exceptions" Bool "true", // exception params in log file
"stack_for_exceptions" Bool "true", // stack trace in log file
"stack_top_ignore" StrArr [ "CXDebug.", "CXReporting." ],
"stack_bottom_cut" StrArr [ "BeanLogic.execute", "CXBaseServlet.do" ],
}, // End of default message_type
"data_source" Str "jdbc/default",
"data_source" Str "jdbc/default_tx",
"data_source" Str "pinevalley",
"user_name" Str "cn=Directory Manager",
"attr_server" NTV { // this section is to overwrite the
// default attribute server connection defined
// in /ecommerce/attrsvr/config/appinfo
// uncomment out the following for changes
"data_source" Str "jdbc/rules", // use separate connection for performance
// "data_source" Str "jdbc/default",
"tx_source" Str "attr_server_tx",
"optimizer_max_permutations" Int "1000"
"attr_server_tx" NTV { // this section is to overwrite the
// default attribute server connection defined
// in /ecommerce/attrsvr/config/appinfo
// uncomment out the following for changes
"data_source" Str "jdbc/rules_tx", // use separate connection for performance
// "data_source" Str "jdbc/default",
"attr_server" NTV { // this section is to overwrite the
// default attribute server schema prefix
// in /ecommerce/attrsvr/config/appinfo
// uncomment out the following for changes
"root_dn" Str "o=iplanet.com",
"data_source_access" Str "com.iplanet.ecommerce.membership.util.AuthDataSourceAccess"
Some appInfo entries are reserved for use by the framework:
on_auth_error (String)—A name of the JSP template to be used for displaying an appropriate message when all the user authentication information is lost (this can happen when a user session expires). The value of this attribute could also be an absolute URL of a servlet. In this case, this servlet will be redirected when an authentication problem occurs.
The datasources section lists the data stores that will be used by the application. The RDBMS datasources have to be registered with the Application Server using the resreg utility provided by iAS.log (NTV)—Settings related to logging (the default reporting mechanism, the logging locale and message filters). These settings control the behavior of the CXReporting.report method.
trace (NTV)—Parameters related to tracing (the trace stream definition, message filters and settings defining the volume of information directed to the trace stream). This entry controls the behavior of the CXDebug.trace method.
data_sources (NTV)—Configuration for data sources used by the application.
object_space (NTV)—Additional configuration for data sources used by POF.
data_source_access (Str)—The fully qualified name of the Java class performing application-specific connection management. This class should be derived from com.netscape.ecommerce.arch.CXDataSourceAccess.
attr_server (NTV)—Data needed to instantiate an attribute server. This NTV contains the following values:
The datasource format is as follows:
DataSources := "data_sources" NTV { <DataSourceStanzas> }
DataSourceStanzas := "<name>" NTV {
"type" Str "<DataSourceType>",
"data_source" Str "<dataSourceName>",
[ "user_name" Str "<jdbcUserName>", ]
[ "password" Str "<jdbcPassword>", ]
Details related to the data_sources, object_space and data_source_access entries can be found in the POF documentation.
To avoid name collisions, each functional module is given a subtree in the appInfo NTV, configuration data specific to the module should be placed in this subtree. For example:
Tracing-Related Settings
The attributes mentioned in this section are specified inside the trace entry of the appInfo NTV. All attributes are set on the per message type basis. Namely, the trace entry typically looks like the following:// settings for the "perf_trace" message type
// settings for the "default" message type
The active, reporter and filter attributes have the same syntax and semantics as they have inside the log entry. There are also other attributes defining the volume of information directed to the trace stream:
params_for_exceptions (boolean)—If set to true and an instance of CXException is passed to CXDebug.trace, an NTV containing exception parameters is written to the trace stream.
The filter attribute is mostly the same as inside the log entry. The difference is that it is possible to specify volume settings (except stack_top_ignore and stack_bottom_cut) on the per filter element basis. For example, the following filter element is prescribed to write out exception parameters for all errors of the catalog module:stack_for_exception (boolean)—If set to true and an instance of Throwable is passed to CXDebug.trace, its stack trace is written to the stream.
stack_for_all (boolean)—Like the above, but the stack trace is written for all calls of the trace method (even if the object passed is not the exception. In this case, the stack trace relates to the point at which the method is called).
stack_top_only (boolean)—If set to true, only the first (topmost) line of the stack trace is printed.
stack_top_ignore (StrArr)—This attribute is used to reduce the amount of unnecessary information placed to the trace stream. When a stack trace is printed, its topmost lines containing either element of this array as a substring are suppressed. The usual value is ["CXDebug.", "CXReporting."].
stack_bottom_cut (StrArr)—This attribute serves the same purpose as the one above. If a line of a stack trace contains either element of this array, this line as well as all lines below it are suppressed. The usual value is ["BeanLogic.execute", "CXBaseServlet.do"].
"params_for_exceptions" Bool "true"
Per-element volume settings take precedence over the common ones. If a tracing message meets multiple filter conditions, the message is printed out as if their volume settings were united.
mail.ntv File
The ias/APPS/com/iplanet/ecommerce/workflow/config/mail.ntv file is listed below:"smtphost" Str "sumith.red.iplanet.com",
The sender should contain a valid user ID and smtphost should contain a valid smtp host name. These entries are used to form an email address as follows: sender@smtphost.
This email address is used for sending email notifications.
xdocinfo.ntv File
The ias/APPS/com/iplanet/buyer/config/xdoc/xdocinfo.ntv file is listed below:"xdoc_dir" Str "/u/sridatta/map",
"submit_to_ecx_script_850" Str "submitToECX_850.sh",
"submit_to_ecx_script_860" Str "submitToECX_860.sh",
"submit_timecard_to_ecx_script" Str "/u/akhil/bx40/timecards/ecx/submitTimecardToECX.sh",
"timecard_receiver" Str "legacyTC", //
"timecard_sender" Str "buyerTC", //
"timecard_filetype" Str "timecard",
"timecard_file" Str "timecard.xml",
"xdoc_archive_dir" Str "/tmp",
"smtphost" Str "sunrise.red.iplanet.com",
"subject" Str "Status change in BuyerXpert",
"url" Str "http://jackiel2:8080/NASApp/buyer/"
"cc" Str "jackiel@netscape.com"
"status_message" Str "BuyerXpert status change. Please contact your admin"
"inbound_error_message" Str "Error processing the inbound request. Please contact your
"po_transmission_failure" Str "Transmission of the PO failed. Please contact your
"cancel_transmission_failure" Str "Transmission of the PO cancellation failed. Please
There is a script that configures xdoc for outbound documents. Run the script:
IAS-ROOT/buyer/sample_data/xdoc/scripts/config_xdoc.pl
This script will do the necessary updates to the preceding configuration file.
omsServiceInfo.ntv File
The ias/APPS/com/iplanet/buyer/oms/omsServiceInfo.ntv file is listed below://** com/iplanet/buyer/attachment is a link entry of "/tmp"
directory and should reside at web server docs directory
"file_system_entry" Str "/tmp",
"web_entry_link" Str "com/iplanet/buyer/attachment"
The "file_system_entry" specifies the physical location where attachments for notes reside. This value is configurable.
reportsInfo.ntv File
If you have the Actuate server running on one machine and BuyerXpert/SellerXpert and the Oracle instance running on another machine, you need modify Acutate_Path to point to a running Actuate server.
Go to the IAS_HOME/buyer/buyer/config/reports directory.
Edit the reportsInfo.ntv file by modifying Actuate_Path to point to a running Actuate server. For example:
http://colonial.red.iplanet.com:5050/acweb/colonial
Verify that linkto is pointing to your BuyerXpert/SellerXpert URL.
Log into the machine that is running the Actuate server and add the Oracle instance that the client machine points to in the tnsnames.ora file.
Create a file, such as bx_input.txt, that contains the user name, password, and ORACLE_SID that BuyerXpert/SellerXpert is using on the client machine.
In the reportsInfo.ntv file, enter this file in the actuate_login field.
Restart the iPlanet Application Server:
omsInfo.ntv File
The order management NTV file specifies the number of requisitions and timecards to be displayed per page. For example, on the Track screen.The off-catalog NTV file is for the off catalog screen items. It specifies whether or not the off-catalog screen is optional, the default value, and the validation model.
By setting the ShowCheckoutConfirmation to False, the Confirm Checkout screen is bypassed.
The reqState NTV file specifies the display strings that correspond to the states of a requisition. For example, a requisition state will be displayed at Pending Approval if the status of the requisition is PENDING_APPROVAL.
The ias/APPS/com/iplanet/buyer/oms/omsInfo.ntv file is listed below:
NTV-ASCII {
"NonAuthTemplate" Str "NonAuthTemplate.jsp",
"default_uom" Str "each",
"defReporter" NTV {
"reporter" Str "Printout"
},
"oms" NTV {
"ordersPerPage" Int "5",
"requisitionsPerPage" Int "5",
"timecardsPerPage" Int "2",
},
"offCatalog" NTV {
"defaultUnit" Str "each",
"defaultQty" Dec "1",
},
"NonCatalog" NTV {
"Product Code" NTV {
"optional" Bool "true",
"default" Str "",
},
"Product Description" NTV {
"optional" Bool "false",
"default" Str "",
},
"Commodity Code" NTV {
"optional" Bool "true",
"validation" Bool "false",
"default" Str "",
},
"Supplier" NTV {
"optional" Bool "true",
"validation" Bool "false",
"default" Str "other",
},
"Quantity" NTV {
"optional" Bool "true",
"default" Dec "1",
},
"UOM" NTV {
"validation" Bool "false",
"default" Str "each",
},
},
"HostCompany" Str "Mercury Enterprises",
"UnknownCompany" Str " Unknown Seller Company ",
"MaxLength" Int "20",
"ReqNamePrefix" Str "Req - ",
"CopyString" Str "Copy of ",
"ReorderString" Str "Reorder of ",
"TemplateString" Str "Template - ",
"Req" Str "Requisition",
"Template" Str "Template",
"PO" Str "Purchase Order",
"ANY" Str "Any",
"ALL" Str "All",
"ShowCheckoutConfirmation" Bool "true",
"reqState" NTV {
"-" Str "All",
"CREATED" Str "Created",
"PENDING_APPROVAL" Str "Pending Approval",
"APPROVED" Str "Approved",
"DECLINED" Str "Declined",
"WITHDRAWN" Str "Withdrawn",
"CANCELLATION_TRANSMITTED" Str "Cancel Transmitted",
"PARTIALLY_CANCELLATION_TRANSMITTED" Str "Partially Cancellation Transmitted",
"FAILED_CANCEL_TRANSMISSION" Str "Failed Cancel Transmission",
"PARTIAL_ACKNOWLEDGED" Str "Partially Acknowledged",
"CANCELLED" Str "Cancelled",
"CANCEL_REJECTED" Str "Cancel Rejected",
"ORDER_REQUESTED" Str "Order Requested",
"ORDER_TRANSMITTED" Str "Order Transmitted",
"FAILED_ORDER_TRANSMISSION" Str "Failed Order Transmission",
"PARTIAL_RECEIVED" Str "Partially Received",
"RECEIVED" Str "Received",
"PARTIAL_INVOICED" Str "Partially Invoiced",
"INVOICED" Str "Invoiced",
"PARTIAL_SHIPPED" Str "Partially Shipped",
"SHIPPED" Str "Shipped",
"CLOSED" Str "Closed",
"ORDER_REJECTED" Str "Order Rejected",
"ACKNOWLEDGED" Str "Acknowledged",
"DELIVERED" Str "Delivered",
},
"defaultUnit" Str "each",
}
Data Model Files
This section describes the data/object configuration files, which are dataModel files and DOR (Data Object Repository) files.The configuration that you would have to do in the data model is related to xdoc. When xdoc is configured for non-OBI, then there are some custom properties in the dataModel that determine which attributes of a purchase order are to be written out for sending to the vendor. Here is an example of this custom attribute:
"class_name" Str "order_header",
"attr_name" Str "need_by_date",
"schema_attr" Str "need_by_date"
The above example shows that the order_id attribute of a requisition should not be written out while writing out an outbound purchase order, whereas the "need_by_date" needs to be written out.
The above example shows how attributes of a given object can be selectively written out during xdoc. You can also specify the "PurchaseOrder" custom_property for relationships. This allows us to say "if line_group is written out then line objects associated with line_group also have to be written out." Of course, while writing out the line object, the "PurchaseOrder" custom property for each attribute of the line_group will be examined. Only those attributes which have "PurchaseOrder" = true will be written out.
An example of the custom_prop for a relationship is given below:
"data_object" Str "line_group",
"assoc_rel" Str "line_group_lg_line_assocs",
"access_name" Str "line_groups",
"assoc_rel" Str "line_lg_line_assocs",
The PurchaseOrder custom property is examined while writing out purchase orders sent to the vendor. Similarly, there is another custom property called OrderChange which is used to determine the objects and attributes that are to be sent to a vendor for an "Order Cancellation Request."
DOR Files
The repository is an NTV structure (physically existing as a set of files in app-root/AppName/config) that defines categories of data items that can be input and/or output by the application. Each category is represented by a single entry that looks like the following:...... optional attributes go here ....
"productQuantity" is a data item name (which can be referred to by PC scriptlets).
In general, the roles of "type" and "datatype" can be described as follows:"datatype" is a mandatory attribute defining the domain of valid values and the way of transforming those values from native format to external representation and vice versa.
"Int" means the domain of integer numbers. Native type int and the standard conversions between integers and strings.
"type" is another mandatory attribute, defining how to construct HTML UI controls through which you can enter a value of the data item.
"Text" denotes the HTML input field as a way of entering values.
At page generation time: The datatype is used to convert the default value of a data element from its native format to external representation. The type is used to build HTML UI element(s) so that their initial appearance corresponds to the external representation.
At form submission time: The Web browser, Web server and iAS infrastructure guarantee that the external representation of user input is delivered to the application.The datatype is used to validate the external representation delivered and to convert it back to native format. Another responsibility of the datatype is generating a descriptive error message provided the user input is not valid.
Type and datatype are fully orthogonal. UI elements that are generated based on types deal with external representations only and have nothing to do with the native data formats, which are taken care of by datatypes.
The set of possible types and datatypes is not something hardcoded in the CX framework. Indeed, the CX 4.0 architecture provides a relatively easy way to introduce new types and datatypes.
Business objects are also reflected in the repository (hence its name, Data and Object repository). For a simplified business object user having two attributes (Name and Password), the repository entry looks like the following:
Customization/Localization Files
This section describes the customization/localization configuration files, which are messages files and codes files.
Messages File
A typical messages.ntv file looks similar to the following:"Adjustment:NoAttr" Str "No Attributes received by import for Adjustment.",
"Adjustment:OperationFailed" Str "Ajustment import operation failed.",
As part of any localization effort, the message itself can be customized. The message code (for example, "Adjustment:NoAttr") should not be changed.
Codes File
The codes file allows you to define static lists of data which display in pull-down lists in the user interface. A pull-down list allows users to choose an item from the list rather than typing it in. Typical lists are all states or all countries.The following codes.ntv file lists the states and their abbreviations as well as the countries and their abbreviations.
Note It is important to use the correct state and country abbreviations when mapping for pull-down lists or the Import utility.
"AA" Str "Armed Forces Americas",
"AE" Str "Armed Forces Europe",
"AP" Str "Armed Forces Pacific",
"DC" Str "District Of Columbia",
"MP" Str "Northern Mariana I",
"AE" Str "United Arab Emirates",
"AG" Str "Antigua and Barbuda",
"AN" Str "Netherlands Antilles",
"BA" Str "Bosnia and Herzegovina",
"DO" Str "Dominican Republic",
"FX" Str "Metropolitan France",
"GW" Str "Guinea-Bissau - Guine-Bissau",
"HM" Str "Heard Island and McDonald Islands (Australia)",
"HR" Str "Croatia - Hrvatska",
"HU" Str "Hungary - Magyarorszag",
"IO" Str "Indian Ocean Territory (UK)",
"KH" Str "Cambodia - Kampuchea",
"KN" Str "Saint Kitts and Nevis",
"LB" Str "Lebanon - Lubnaniyah",
"LT" Str "Lithuania - Lietuva",
"MK" Str "Macedonia - Makedonija",
"MN" Str "Mongolia - Mongol Uls",
"MP" Str "Northern Mariana Islands",
"MQ" Str "Martinique (France)",
"MR" Str "Mauritania - Muritaniyah",
"MZ" Str "Mozambique - Mocambique",
"NC" Str "New Caledonia - Nouvelle-Caledonie",
"NF" Str "Norfolk Island (Australia)",
"NL" Str "Netherlands - Nederland",
"PF" Str "Polynesie Francaise",
"PH" Str "Philippines - Pilipinas",
"PM" Str "Saint-Pierre et Miquelon",
"SG" Str "Singapore - Singapura",
"SI" Str "Slovenia - Slovenija",
"SJ" Str "Svalbard og Jan Mayen",
"SK" Str "Slovakia - Slovensko",
"ST" Str "Sao Tome e Principe",
"SU" Str "Soviet Union - Sovietskiy Soyuz",
"TC" Str "Turks and Caicos Islands",
"TF" Str "Southern and Antarctic Lands",
"TJ" Str "Tajikistan - Tojikiston",
"TK" Str "Tokelau (New Zealand)",
"TM" Str "Turkmenistan - Tiurkmenostan",
"TT" Str "Trinidad and Tobago",
"UA" Str "Ukraine - Ukrayina",
"UM" Str "United States Minor Outlying Islands",
"US" Str "United States of America",
"UZ" Str "Uzbekistan - Uzbekiston",
"VC" Str "Saint Vincent and the Grenadines",
"VG" Str "Virgin Islands (UK)",
"VI" Str "Virgin Islands (USA)",
"VN" Str "Vietnam - Viet Nam",
Previous Contents Index Next
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.
Last Updated October 08, 2001