Siebel Business Component Builder
In this topic ...
Dealing with Invalid XML Characters
Related Topics ...
Use this builder to add a "SiebelDataHelper" LJO to your model that can access a Siebel backend system and make calls against a Siebel Business Component. This LJO provides the following utility methods that can be invoked against the chosen Business Component: create, delete, findData, getData, getEmptyDetailRow, saveData.
The builder UI allows you to choose a Siebel Business Component and then choose the fields from that Component that you wish to use in Summary and Detail operations. The builder stores that information in a Schema that is added to the model. The builder also adds a number of schema-typed Variables to the model that are referenced by the utility methods specified above. (See "Objects created by the Siebel Business Component builder" below.
This builder functionality is incorporated into the Siebel View & Form builder.
To communicate successfully, a Siebel server and an external Siebel client (such as WebSphere Portlet Factory), must use the same file encoding scheme. To use Siebel Builders successfully, make sure that your client platform matches the file encoding used by your Siebel server.
How Do I...
Establish a connection with a Siebel server
Use Business Component Field Names
Profile a Siebel Builder
Establish a connection with a Siebel server
1. Specify connection properties - The builder allows you to specify connection information for a Siebel server in two ways. The primary way is by using a connection properties file that can be shared by multiple instances of the builder. A connection properties file must be created in web-inf/config/siebel_config and filled out with the required properties. The file default_connection.properties in web-inf/config/siebel_config shows the properties required. As an alternative to the properties file we can specify connection inputs in the "Connection Override" group of builder inputs. These overrides take precedence over any properties defined in the properties file.
2. Make the SiebelJI * jars available to the Designer and the application server. See the Siebel Getting Started guide available from the Designer documentation menu for details on placement of the three SiebelJI* jar files
Use Business Component Field Names
When displaying Business Component data on a web page it s best to use meaningful labels, and probably the actual Siebel field names.
When data is passed to/from the SiebelDataHelper LJO it is passed in XML Variables with element names that are derived from the field names associated with the Siebel Business Component. For example, a field name of "Email Address" will be mapped to an element name of "Email__Address".
This builder contains a "Generate Label Resources" input that, when enabled, causes the builder to construct a resource bundle that can be used by other builders, such as Data Page, to create presentable web pages. The resource bundle contains the name mappings from the derived element name back to the real Siebel field name. So, to use the Siebel field names on a page created by the Data Page Builder:
1. Check the "Generate Label Resources" input of the builder.
2. Apply the builder input changes. The label resource bundles are written to web-inf/source and web-inf/classes. The name of the resource bundle will be "<model name>_<builder name>_<BusinessComponentName>.properties.
If the files exist already they will not be overwritten and you will need to remove them first. This behaviour allows you to further modify them after they have been created.
3. Open the Data Page Builder that is being used to display the Business Component data. In the Label Translation Settings group select the resource bundle as the value for the Resource Bundle Name input
4. Apply the Data Page changes and run your model. The displayed web page now uses the selected labels instead of the property names to identify Component Interface data.
Profile a Siebel Builder
If you are going to vary the Object, Component, or View Mode, follow this best practice for using profiles with the Business Object, Business Component, and/or View Mode inputs in the Siebel builders. Using this technique eliminates the need to copy the XML representation of the fields associated with the choice of Object, Components, etc. from the Model XML and paste them into the Profile Editor.
If you are going to vary any of the values of these inputs through profiling, the easiest way to accomplish this is to add to the model another Siebel View and Form or Siebel Business Component Builder with the same name as the existing Siebel Builder. Then Profile the "Enable Builder" input of both Siebel Builders. (This input is located in the "Properties" section of the builder editor.)
Specifying Inputs
The Siebel Business Component builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor."
Input Name Description Name Enter a name for this builder call. The Designer displays this name in the Builder Call List. This name will be used as a prefix for the artifacts created by this builder.
Connection Properties File Enter the name of the properties file to be used to establish a connection with the backend Siebel server. Example: my_siebel.properties
This file must be located in the WEB-INF/config/siebel_config directory
Test Connection Button Press this button to test the builder's connection to the Siebel server. If the connection is successful, a connection confirmation dialog is displayed. If the connection is unsuccessful,an error dialog will be displayed with information about why the builder was unable to contact the Siebel server.
The connection properties are taken from the properties file defined for the builder and any overrides you specified in the "Connection Override" advanced group. If you have connection problems remember to review both inputs for correctness.
Runtime Credentials Select the type of credentials to use at runtime to access the Siebel server. We can choose:
- Use same credentials properties for all users To use the user name and password credentials specified in the .properties file regardless of which user is running the Siebel builder.
- Specify execution credentials To specify a user name and password that will be used by this builder at runtime to access the Siebel server.
Execution User Name This input is available when "Specify Execution Credentials" is selected as the Runtime Credentials input. Specify an indirect reference to the location used to store the Siebel user name. This location might be a variable or method result.
Execution Password This input is available when "Specify Execution Credentials" is selected as the Runtime Credentials input. Specify an indirect reference to the location used to store the password.
Business Component Selection Get Business Object and Business Component Names Button Press this button to get a list of Business Objects and Components available on the Siebel server. If successful, the "Business Object" input picker will list the available Business Objects. Interfaces.
If the operation was unsuccessful, an error dialog will be displayed with information about why the builder was unable to get the list of Business Object Interfaces.
If the picker does not list any Business Objects, or you don t see the expected list of names, then the user name provided by the properties file may not have permission to access any Business Objects and Components.
Business Component Select the name of the Siebel Business Component to be accessed by this builder. Once you select a Business Object, the Business Component selection list will be populated with the components available in that Business Object.
View Mode Select a View Mode. These are standard Siebel definitions that control the visibility of fields of a Business Component. The usual choice is "Personal." See your Siebel documentation for more information.
We can choose:
- Sales Rep
- Manager
- Personal
- All
- Organization
- Group
- Catalog
- Sub Organization
Access Info This read-only field will display the delete, insert, and update status/characteristics of the selected Business Component. Enable Schema Caching Use this check box to enable the caching of the schema for the specified Siebel Business Component. When enabled, the Builder s regeneration phase uses a cached version of the Business Componen schema. If a different Business Componen is selected a new version of the schema will be cached. Selecting this option provides two benefits:
- Enhanced Performance - This helps during editing models containing this Builder.
- Enhanced Security - A cached schema avoids exposing model generation time credentials once an initial regen has been performed. To leverage this specify to use separate runtime credentials (see the "Runtime Credentials" input).
Note - If the schema for the data changes on the Siebel server, disable this input, regenerate the model, and enable this input again.
Note - If you have the "Generate Resource Labels" input checked uncheck this input to generate the resource files for the labels. Once the resource bundles are generated we can enable schema caching again, and then disable the "Generate Resource Labels" input.
Field Selection Copy Summary field choices to detail fields Press to copy the currently selected (true) fields in the left hand (summary) column of the Field Choices table to the detail column Copied items will be merged with any other choices already there. You may need to close the builder and reopen it for the widgets to refresh to show the new values.
Clear summary field choices Press to clear all the summary field choices in the Field Choices table, setting all the values to false. You may need to close the builder and reopen it for the widgets to refresh to show the new values
Clear detail field choices Press to clear all the detail field choices in the Field Choices table, setting all the values to false. You may need to close the builder and reopen it for the widgets to refresh to show the new value
Field Choices Use this table to select the fields of the Business Component that you want to have available in Summary and Detail operations on the Business Component. Fields selected will be indicated in the <name>_DetailFieldNames and <name>_SummaryFieldNames Variables that are generated in the Webapp, and will be the fields of the Business Component that are activated and returned in data retrieval and save operations.
Note that fields chosen here, and then fed via the <name>_DetailRow and <name>_SearchResults variables to DataPage builders for display, can be hidden in those displayed pages using other builders such as Data Field Modifier and Data Column Modifier.
Note also that the order of the fields (which is by default alphabetic) can be changed simply by dragging a desired row up or down the table. This action feeds into the generated Schema and the Variables generated and becomes the default order of the fields seen when displayed using Data Page with "Make UI from Schema" selected.
The field name showing in the 3rd column is the Siebel field name. The 4th column (Attributes) shows selected metadata information on that field gathered from Siebel. Values shown, if set, are "required", "calculated" and "readOnly". Typically you would not choose a "calculated" field for a detail view, since the detail view can be used for record creation.
Connection Override Connection String Use this input to override the "ConnectString" property specified in the connection properties file. You might want to do this if we need to use a different Siebel server than the one specified in the properties file or you want to profile the selection of the Siebel server.
Example: 10.10.2.125:2320/siebel_es/SSEObjMgr_enu/wicdemo9
User name Use this input to override the "UserName" property specified in the connection properties file. You might want to do this if we need to use different credentials than the ones specified in the properties file
Password Use this input to override the "Password" property specified in the connection properties file. You might want to do this if we need to use different credentials than the ones specified in the properties file
Resource Bundle Generation Generate Label Resources Enable the check box to have the builder construct a resource bundle that can be used by other builders, such as Data Page, to create presentable web pages. The resource bundle is written to web-inf/source and web-inf/classes when the model is regenerated. The bundle name is created from a combination of the model name, builder name, and Business Component name to ensure uniqueness.
the builder writes the resource bundle only if it does not already exist. This means we can manually customize the content of the bundle if we need to change one or more of the labels for some reason.
You must disable "Enable Schema Caching" in order to generate the resource files for the labels. Once the resource bundles are generated we can enable schema caching again, and then disable the "Generate Resource Labels" input.
Specifying Credentials
You have several options when choosing the credentials used to access the Siebel system at portlet execution time. We can employ the same credentials for all portlet users if you want all users to have the same user name and password. In many cases, it is desirable to have different credentials for each user. Implementing this feature varies greatly between different brands of portal server, therefore, it is best to refer to the specific portal server's documentation to learn how to implement user-specific credentials.
Dealing with Invalid XML Characters
In some cases, illegal XML characters will be returned from a Siebel database as part of a field name. The Factory provides a mechanism to define substitutions for characters in Siebel field names that would otherwise cause invalid XML element names. Substitutions are controlled by the "siebel_builder.properties file, located in your project under "WEB-INF/config/siebel_config" directory.
We can examine the Siebel properties file to view known problem characters. We can add a character substitution to this file with the "replace.char." prefix.
Objects Created by the Siebel Business Component Builder
The "SiebelDataHelper" LJO, providesa Schema holding all the field information for the chosen Business Component, and a number of Variables that are used by the LJO methods to communicate with the application.
SiebelDataHelper LJO Methods
In the following table <name> represents the name given to the builder, which is used as a prefix on the LJO and Variables that the builder adds to the model. See table for Variable data formats
Name Args Action create none Takes name/value pairs from the <name>_DetailRow Variable and uses them to create a new record. Fields specified in the <name>_DetailFieldNames Variable are activated when the newly created record is returned in the <name>_DetailRow Variable.
delete none Uses the name/value pairs in the <name>_DetailRow Variable to identify and delete a specific record. findData none Takes name/value pairs from the <name>_SummaryRow Variable and uses them as search keys to find all matching records. The fields activated in the records retrieved are those specified in <name>_SummaryFields, and the result set is returned in the <name>_SearchResults Variable.
getData none Takes name/value pairs from the <name>_DetailRow Variable and uses them as search keys to find a matching record. The search keys are expected to be specific enough to return only one record. Fields activated in the records retrieved are those specified in <name>_DetailFields, and the result is returned in the <name>_DetailRow Variable.
getEmptyDetailRow none Utility method to return an "empty" <name>_DetailRow object that can then be added to. name/value pairs can then be added to that object prior to a call to "getData". getSiebelAccess none Returns a com.bowstreet.builders.webapp.siebel.SiebelAccess object on which low level calls can be made to return information on Business Objects and Business Components in the Siebel repository. Used by the Siebel Business Component builder. Not generally expected to be used by model developers, but more information is provided below. saveData none When a "getData" call is made the underlying API saves a copy of the result handed back. When "saveData" is called all of the values in that original copy are used to retrieve that original record, then the values in <name>_DetailRow are applied to it and the record is saved.
SiebelAccess Object
It's not generally necessary to use this object, but it allows lower level access to the Siebel API. Remember to call "release()" to free up resources:
public static void main(String[] args)
{
SiebelAccess sa = null;
try
{
Properties p = new Properties();
p.put(SiebelAccess.PropertyNames.CONNECT_STRING,
"siebel://10.10.2.125:2320/siebel_es/SSEObjMgr_enu/wicdemo9");
p.put(SiebelAccess.PropertyNames.USERNAME, "sadmin");
p.put(SiebelAccess.PropertyNames.PASSWD, "sadmin");
sa = new SiebelAccess(p);
System.out.println(sa.getBusinessObjectNames());
System.out.println(sa.getBusinessComponentNames("Account"));
BusinessComponent bc = sa.getBusinessComponent("Account Person Admin", "Account
(Delegated Admin)", SiebelAccess.ViewMode.PERSONAL);
System.out.println(bc.getMetadata());
sa.release();
}
catch (Exception e)
{}
}
Variable Information and Content Formats
Variable Name Variable Contents and Format Examples <name>_DetailRow Specifies the name/value pairs to be used a "getData" call and holds the retrieved detail record. The element names are the "morphed" names that are constructed from the Siebel Component field names and used in the Schema. Example:
<DetailRow><Active__Status>Y</Active__Status><Alias></Alias> <Created__By__Name>SADMIN</Created__By__Name> <Email__Address>amoore@lemus.com</Email__Address> <Full__Name>Moor Antonio</Full__Name> <Home__Phone____p></Home__Phone____p> <Personal__Contact>N</Personal__Contact> <Primary__State></Primary__State><Role></Role> <Spouse__Name></Spouse__Name> <Start__Date></Start__Date> <Work__Phone____p>4078863394</Work__Phone____p> </DetailRow>
<name>_DetailFieldNames Fields to be activated in "getData" calls and also holds the mapping between the element names used in the Schema and page tags and the actual Siebel field names used in Component operations Example:
<DetailFields>
<field name="Active__Status" siebelFieldName="Active Status" />
<field name="Alias" siebelFieldName="Alias" />
<field name="Created__By__Name" siebelFieldName="Created By Name" />
<field name="Email__Address" siebelFieldName="Email Address" />
<field name="Full__Name" siebelFieldName="Full Name" />
<field name="Home__Phone____p" siebelFieldName="Home Phone #" />
<field name="Personal__Contact" siebelFieldName="Personal Contact" />
<field name="Primary__Account__Name" siebelFieldName="Primary Account Name" />
<field name="Primary__State" siebelFieldName="Primary State" />
<field name="Role" siebelFieldName="Role" />
<field name="Spouse__Name" siebelFieldName="Spouse Name" />
<field name="Start__Date" siebelFieldName="Start Date" />
<field name="Work__Phone____p" siebelFieldName="Work Phone #" />
</DetailFields>
<name>_SummaryRow Specifies the name/value pairs to be used in a "findData" call. Empty elements are disregarded. In the following example records with a Personal Title of "Mr." will be retrieved. Example:
<SummaryRow><Email__Address></Email__Address>
<Full__Name></Full__Name>
<Last__Name></Last__Name>
<Personal__Title>Mr.</Personal__Title>
<Work__Phone____p></Work__Phone____p>
</SummaryRow>
<name>_SummaryFieldNames Fields to be activated in "findData" calls and also holds the mapping between the element names used in the Schema and page tags and the actual Siebel field names used in Component operations. Example:
<SummaryFields><field name="Email__Address" siebelFieldName="Email Address" /> <field name="Full__Name" siebelFieldName="Full Name" />
<field name="Last__Name" siebelFieldName="Last Name" />
<field name="Personal__Title" siebelFieldName="Personal Title" />
<field name="Work__Phone____p" siebelFieldName="Work Phone #" />
</SummaryFields>
<name>_SearchResults Holds the result of a "findData" call. Example:
<SearchResults><SummaryRow><Email__Address>abrahadennis@alliedhealth.com</Email__Address>
<Full__Name>Dennis Abraham</Full__Name>
<Last__Name>Abraham</Last__Name>
<Personal__Title>Mr.</Personal__Title>
<Work__Phone____p>4073334005</Work__Phone____p>
</SummaryRow> <SummaryRow><Email__Address>heinzw@wvf.com</Email__Address>
<Full__Name>Heinz Weiss</Full__Name>
<Last__Name>Weiss</Last__Name>
<Personal__Title>Mr.</Personal__Title>
<Work__Phone____p>6504855771</Work__Phone____p>
</SummaryRow>
</SearchResults>
Files
- <modelname>_<buildername>_<ciname>.properties - Resource bundle containing mappings from generated element tag names back to Siebel filed names. (if "Generate Label Resources" is enabled in builder UI)
Siebel Session Pooling
The Siebel builders support pooling of sessions to your backend Siebel servers. By default session pooling is disabled which is a reasonable configuration for a Designer environment. However, on the server you may want to enable pooling to minimize the number of sessions created and improve overall builder runtime performance. See the Siebel Getting Started Guide for information about the properties available to control session pooling
The Siebel builders use the standard open source Apache Commons pooling implementation. See the Commons documentation for the GenericKeyedObjectPool class on the Apache web site for detailed information on the meanings of these properties.