Identifying the Site Name
Overview
From within a script of HTML document, it may be necessary to dynamically identify the current site's identity. There are several ways to accomplish this task, which vary based on the context and location within an Oracle CPQ application.
Determining the identity of the current site is a critical step in creating portable, safe applications that can be copied across different testing, staging, and production instances. Whenever a resource is being referenced, externally or internally, make sure that a migration or site copy will not cause issues.
Some common areas where this occurs:
- Accessing files or images stored in the File Manager
- Connecting to an external integrated service
- Sending a call to CPQ's SOAP Services
- Document Engine XSL Snippets
- Header/Footer images, CSS, and JavaScript
Administration
Relative vs Absolute Links
A relative link doesn't include the hostname, and refers to a resource based on it's starting position.
Examples of a relative path include the following:
-
<a href="/path/to/resource.html"></a>
-
<a href="resource.html"></a>
-
<a href="../resource.html"></a>
There are some instances where using a relative path is enough. The path will automatically point to the appropriate resource, regardless of the environment.
File Manager and Links
The challenge with linking to the File Manager is that the name of the site appears in two locations:
http://*SITENAME*.bigmachines.com/bmfsweb/*SITENAME*/image/
This can make it difficult to find link to the resource without having the site name available. Our strategy for finding the site name will vary based on where we are in CPQ.
In Commerce BML
Use _system_supplier_company_name to identify the current site. This is a variable that stores the hostname of the current site, and is the same name that appears in the relative path to the File Manager.
sitename = lower(_system_supplier_company_name);
filemanager_path = "/bmfsweb/"+sitename+"/image/";
The path to the File Manager is case sensitive. Account for this by using "lower()" in your function.
In Configuration BML
You can use BMQL in combination with the commerce method to expose the site name in configuration. Assuming that the Quote Variable Name of the Commerce Document is quote_process, the script would look like this:
path = "";
records = BMQL("select filemanager_path from commerce.quote_process");
for item in records {
path = get(item, "filemanager_path");
}
return path;
Document Engine XSL Snippets
There are some parameters available in the snippets that provide site-specific information:
$XSL_COMPANYNAME_PARAM: Returns the site name. $XSL_URL_PARAM: Returns the site URL, including the protocol.(http://sitename.bigmachines.com/)
<!-- Example XSL Snippet-->
<xsl:variable name="image_url">
<xsl:value-of select="concat($XSL_URL_PARAM, '/bmfsweb/',$XSL_COMPANYNAME_PARAM, '/image/my_folder/my_image.gif"/>
</xsl:variable>
Display XSL Templates
When modifying the Home Page XSL, Parts Search XSL, or other XSL display templates, the site name is available under the "page_data" element. Here's how to select it in the Home Page.
Notice that it is translated to lower case for the File Manager link.
<xsl:variable name="sitename" select="translate(/home_page/page_data/host_company, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"/>
<xsl:variable name="image_url" select="concat('/bmfsweb/',$sitename,'/image/my_folder/my_image.jpg')"/>
The $BASE_PATH$ Parameter
$BASE_PATH$ is a variable supplied by Oracle CPQ that resolves to the full relative link of the File Manager. If you are adding a file to the header or footer, use the variable like this:
<img src="$BASE_PATH$/my_folder/my_image.jpg">
$BASE_PATH$ is available in the following areas:
- Header
- Footer
- Custom Home Page
- Commerce HTML/Read-Only Attribute
- Configuration HTML/Read-Only Attribute
- Configuration Flow Custom Templates
Home Page Alt JS File
From within the Home Page Alt JS file, you have access to the global variable _BM_HOST_COMPANY, which refers to the current site name.
// outer function to avoid creating global variables
(function() {
var image_url = "/bmfsweb/"+_BM_HOST_COMPANY+"/image/my_folder/my_image.jpg";
}());
From Within the File Manager
Some files that you link to within the File Manager can have references within themselves. CSS files, for instance, may have links to images.
In the case of CSS, you can use relative links within your file to find other files in the File Manager. As long as the folder structure stays consistent, this will work across sites.
For example, assume the following directory structure in the File Manager:
From within style.CSS, you can link to photo.jpg as shown in the following example:
.class-foo {
background-image: url(../images/photo.jpg);
}
Troubleshooting
It can be difficult to recognize that a static reference has been broken, especially where it points to a similar resource on CPQ.
If there is a broken link, or a visible error, then this could be good news: it will point directly to the source of the problem.
- Use a global script search to search for the site name is another quick way to find hard-coded references.
- Check for any calls to an external resource.
- Check for the name of a test, production, or staging instance.
- Try it from a commerce document, from the home page, and from your configurators.
As an extreme measure, Oracle CPQ Ops can bring down a test site for a testing period. During this period a thorough screen should be run over the user side, looking for broken links and errors in functionality.
Notes
Having links that point to unexpected locations is a maintenance liability and a security risk.
Related Topics
See Also
