44 Alternate Publishing Methods

In addition to Realtime publishing, you can use On Demand publishing where the delivery system is a database or an external system running an application other than WebCenter Sites, Export to Disk publishing where the delivery system is a web server, Mirror to Server publishing where the delivery system is a WebCenter Sites system, and Exporting Assets to XML where the delivery system is a database or an external system running an application other than WebCenter Sites.

Topics:

44.1 About Alternate Publishing Methods

This section describes the publishing methods that WebCenter Sites supports. The following three figures summarizes the publishing methods.

For Export to Disk publishing, the delivery system is a web server. Approved assets in the CM system database are rendered by templates into HTML files. The files are saved to a file system and subsequently published to the web server by an administrator using a transfer protocol, such as FTP. When published content is requested by site visitors, the HTML files are served as pages to the browser.

Figure 44-1 Export to Disk Publishing

Description of Figure 44-1 follows
Description of "Figure 44-1 Export to Disk Publishing"

For Mirror to Server publishing, the delivery system is a WebCenter Sites system. Approved assets and their database tables are mirrored from the CM system database to the delivery system database. Throughout the publishing session, the publishing system communicates with the CacheManager on the delivery system. The CacheManager is a WebCenter Sites servlet that manages a system's page cache. CacheManager ensures caching of the pagelets or pages that refer to the mirrored assets. After the publishing session concludes, CacheManager generates those pages again to display the updated content, and caches the new pages and pagelets.

When published content is requested by site visitors, it is provided on-the-fly. The content is drawn from the delivery system database by templates and served to the browser, where it is finally rendered as pages.

Figure 44-2 Mirror to Server Publishing

Description of Figure 44-2 follows
Description of "Figure 44-2 Mirror to Server Publishing"

For Export Assets to XML, the delivery system is a database or an external system running an application other than WebCenter Sites. The publishing method is a data transformation method that outputs XML files. Rather than creating pages that are ready to be displayed by a web server, this publishing method uses the Export API to create one XML file for each approved asset.

When published content is requested by site visitors, it is provided on-the-fly. The content is drawn from the delivery system database by templates and served to the browser, where it is finally rendered as pages.

Figure 44-3 Export to XML Publishing

Description of Figure 44-3 follows
Description of "Figure 44-3 Export to XML Publishing"

44.2 Using On-Demand Publishing

When you publish, you can immediately and selectively publish any of the assets on the approved assets list. This is known as publishing assets on-demand.

As with scheduled RealTime publishing, an asset is published with all its dependent assets. Therefore, the dependent assets are also placed in the On-Demand Queue.

The list of approved assets is searchable, making it easier to find the assets you have to publish. After the selected assets are published, they are removed from the approved assets list for the next publishing session.

Note:

On Demand publishing can be either complete or delayed.

To select approved assets for immediate publication:

  1. Open the Publish Console by clicking Publishing on the button bar.

  2. From the Publish Destination drop-down list:

    1. Select the RealTime publishing destination to which you will publish the assets.

    2. Click Select Destination.

  3. On the Publish Destination form, click the x assets are ready for publish link.

    Figure 44-4 Publish Destination Form

    Description of Figure 44-4 follows
    Description of "Figure 44-4 Publish Destination Form"

    The On Demand Queue tab opens. The Approved Assets tab lists all assets approved for the upcoming publishing session.

  4. (Optional) Search through the approved assets.

    1. Enter a search term in the Search text box.

      • Search runs across asset names and descriptions.

      • You cannot use wildcard and Boolean operators.

    2. Click Search.

      The Search Results tab opens, displaying the results of your search.

  5. Add assets to the On-Demand Queue.

    Note:

    On-Demand supports immediate publication. Selections that you place into the On-Demand queue remain there only throughout the current WebCenter Sites session. When you log out (or the system logs you out), the On-Demand queue is cleared.

    On either the Approved Assets tab or the Search Results tab, select the assets you wish to add to the On-Demand Queue, then click Add to On-Demand Queue.

    A message opens while the dependencies are calculated. The selected assets are removed from the Approved Assets tab (and Search Results tab, if open). The On-Demand Queue is updated with the selected assets and their dependent assets.

  6. Publish the On-Demand Queue. Complete either:

    • If you are sure that the assets you selected can be published, click Publish On-Demand Queue (on the Approved Assets tab).

    • If you wish to review the assets before you publish them, switch to the On-Demand Queue by clicking the On Demand Queue tab.

    • To view an asset's dependencies, click the plus mark at the far left of the asset's row.

    • If you decide not to publish assets after you place them in the On-Demand Queue, select them and click Remove from On-Demand Queue. The assets are removed from the On-Demand Queue and placed back in the Approved Assets list. (A dialog box prompts you to confirm your action.)

  7. Click OK.

    The Publish Console opens showing the publishing session in process.

  8. For instructions on observing the publishing session, see Using RealTime Publishing.

44.3 Unapproving Selected Assets from a Publishing Session

If you change your mind about publishing approved assets, you can selectively remove them from the approved assets list.

To unapprove assets:

  1. Open the Publish Console by clicking Publishing on the button bar.

  2. From the Publish Destination drop-down list:

    1. Select the RealTime publishing destination you wish to publish assets to.

    2. Click Select Destination.

  3. On the Publish Destination form, click the link x assets ready for publish.

    The On Demand Publishing form opens. This form displays the Approved Assets tab and the On-Demand Queue. The Approved Assets tab lists all assets approved for the upcoming publishing session.

  4. (Optional) Search through the approved assets.

    1. Enter a search term in the Search text box.

      • Search runs across asset names only.

      • You cannot use wildcard and Boolean operators.

    2. Click Search.

      The Search Results tab opens, displaying the results of your search.

  5. On either the Approved Assets tab or the Search Results tab, select assets to unapprove. Click Unapprove.

    The assets you selected are removed from the Approved Assets list. If the asset you unapprove has a dependent asset that is approved for this publishing session, it is placed into a hold queue.

  6. (Optional) Approve assets held from publishing:

    1. Click Back to return to the Publish Destination form. There are now two text links. One lists the assets held for publishing, the other the assets ready for publishing. Click the x assets are held for publish link.

      Figure 44-6 Publish Destination

      Description of Figure 44-6 follows
      Description of "Figure 44-6 Publish Destination"

      The held queue opens.

      Figure 44-7 Assets in Held Queue

      Description of Figure 44-7 follows
      Description of "Figure 44-7 Assets in Held Queue"
    2. Click the Held link for the asset you wish to approve for the publishing session.

      The Assets Preventing Asset From Being Published to Destination form opens.

      • If the asset has no dependencies, a message opens stating that the asset is approved.

      • If the asset has dependencies, a list of those dependent assets is shown.

        Figure 44-8 Assets Preventing Site From Being Published Form

        Description of Figure 44-8 follows
        Description of "Figure 44-8 Assets Preventing Site From Being Published Form"

        After reviewing the list of dependent assets, select all of the assets on the list by selecting the check box in the header row of the table. Then click Approve.

        The following occurs: A message indicates that the assets are approved and are ready for publishing, the asset and its dependent assets are placed in the approved assets queue, and you are returned to the held queue.

    3. (Optional) Repeat step b to approve another held asset.

44.4 Learning Export to Disk Publishing Terminology

Compared to mirror publishing, where dependencies in both the approval and publishing stages are determined by the asset model, Export to Disk publishing is an entirely template-driven process. If the approval template and publishing templates differ with respect to the dependencies they specify—a condition we do not recommend—the likelihood of publishing unapproved content increases.

Coding templates is the responsibility of the developer. However, the administrator (and any users who publish) must understand which templates to call and what outcome to expect to prevent adverse effects on publishing sessions.

Note:

The terminology presented here refers only to Export to Disk publishing. Terms such as publish key, dependencies, and references have completely different meanings in mirror publishing.

This section covers the following topics:

44.4.1 Page

In the Export to Disk publishing context, a page is typically an HTML file that is exported to a disk. (The file is not to be confused with a Page asset type.) Each exported page is represented by a page.

44.4.2 Publish Key

A publish key (or pubkey) is strictly a publish-time term. A pubkey represents an atomic publishing unit, which in the case of Export to Disk publishing is an exported file, equivalent to a page, not to be confused with a Page asset type).

A pubkey is defined by two constructs: an asset, and a publish-time template (not to be confused with an approval template).

The initial pubkeys in Export to Disk publishing are the starting points defined by the user who initiates the publishing session. All other pubkeys are discovered and logged during publishing.

44.4.3 Publish Queue

A publish queue is a list of pubkeys awaiting publication. For a pubkey to be added to the publish queue, its primary asset must be approved.

44.4.4 Primary Asset

The primary asset participates in the definition of a pubkey. In layman's terms, its ID and type become the cid and c parameters for the template. A primary asset must be approved before its page or pages can be exported.

Note:

If it is determined that a page's primary asset is not approved, the page is not exported. This can lead to the creation of a broken link on the publishing destination, depending on which approval and publishing templates were used.

It is the developer's responsibility to code approval templates such that they can validate the dependencies that are expected to exist on the target destination.

44.5 Using Approvals and Export to Disk Publishing

Exporting a page first requires approval of the page's primary asset. Approval of the primary asset is contingent on the approval states of its dependent assets, which are dictated by the primary asset's approval template. The dependent assets' dependencies are further dictated by their own approval templates.

Note:

Because the approval template is not necessarily the one used to render the asset, it is possible to publish assets without passing them through the approval system. This implication and others are discussed and illustrated in Investigating Publishing Behavior and Functionality and Understanding the Approval and Publish-Time Templates: What Happens When They Differ?

Also note that compositional dependencies (involving non-primary assets of a page, as explained on Working with Export to Disk Publishing) do not require approval to appear on an exported page (to filter out unapproved assets, see the <render:filter> tag in the Tag Reference for Oracle WebCenter Sites Reference for more information).

This section covers the following topics:

44.5.1 Using the Approval Template

Approval in Export to Disk publishing allows the developer to define dependencies that ensure the correct content is published and that it is published intact.

Compared to mirror publishing, in which asset dependencies in both the approval stage and publishing stage are determined by the asset model, Export to Disk publishing is entirely template-oriented. As a result, approval behavior (and publish-time behavior) is defined by the developer who writes the approval templates (and the publish-time templates). WebCenter Sites then uses the approval template to discover an asset's dependencies. If an asset is published against the approval template, its approval dependencies are likely to be the same as its compositional dependencies. For more information, see Working with Compositional Dependencies.

Approval templates are assigned by use of the Set Default Templates feature in the Publishing Destination form.

  • If a default template is not explicitly chosen, the approval system will choose the asset's default template.

  • If neither the approval nor default template is specified, the asset will be approved without an approval template (that is, it will have no approval dependencies).

If the approval template is shared among sites, the approval system will choose the site entry corresponding to the current site.

44.5.2 Using the Approval Queue

The approval queue handles asset modification events to keep approval tables up to date. For example, if an asset is approved for publication, but you then change it, the approval queue will handle this by unapproving the asset—rejecting it from the publish queue.

You never work directly with the approval queue. The queue runs every five minutes by default. However, if you call a feature that uses approval functionality (such as the Publishing tab), the approval queue is forced to run before it is rendered to keep approval information up to date.

44.5.3 Using Approval Dependencies

When you approve an asset, its approval template (see Using the Approval Template) is used to determine its approval dependencies. The following tags create approval dependencies:

  • <asset:load>

  • <asset:loadall>

  • <assetset:setasset>

  • <assetset:setlistedassets>

  • <render:logdep>

  • <render:getpageurl>

  • <render:gettemplateurl>

  • <render:gettemplateurlparameters>

If you approve asset A whose template (or any element called by the template) references asset B using a tag listed above, an approval dependency is created from A to B. This typically means that when you want to approve A, you must also approve B.

Types of Approval Dependencies

Approval dependencies are created and used at approval-time, not to be confused with publish-time dependencies (even though they can be the same). Approval for Export to Disk publishing involves two types of approval dependencies:

  • Template dependencies

  • Reference dependencies

Template dependencies are created when an asset's approval template uses another asset to define the content. For example, if asset A's approval template loads asset B, then A has a template dependency on B. In more practical terms, if you have an approval template for a Page asset that shows an Article asset, the Article asset is used on the Page, so the dependency is of a template kind. The following tags generate template dependencies:

  • <asset:load>

  • <asset:loadall>

  • <assetset:setasset>

  • <assetset:setlistedassets>

  • <render:logdep>

Reference dependencies are generated when a link is created from one page to another. They are registered as reference dependencies between the primary assets of the two pages. For example, if we create a link from the approval template of asset A to a page where asset B is the primary asset, the approval system will register this as asset A's reference dependency on B. Tags that generate this kind of dependency are:

  • <render:getpageurl>

  • <render:gettemplateurl>

  • <render:gettemplateurlparameters>

Template dependencies (in Export to Disk publishing) are by default exact dependencies — to approve A, you must approve B if B has been changed. Reference dependencies are always exists dependencies—if you approved and published B one time, you are not required to approve it again to re-publish A.

The exception is when you set deptype="none" on any of the tags. In that case, no approval dependency at all is created by that tag. This means no record is created for it during approval; in all other contexts, such as Export to Disk publishing and live sites, the deptype attribute is ignored.

44.6 Working with Export to Disk Publishing

Three main components play a role in the Export to Disk publishing process:

44.6.1 Working with the Publish-Time Template

The purpose of the publish-time template is to render content as files. Typically, publish-time templates are identical to the approval templates. When they differ, content can be published without first being approved. Bypassing the approval system requires the developer to provide a means for publishable content to be validated.

44.6.2 Working with Starting Points

The starting point is the pubkey (or pubkeys) where export begins, which is at publish-time. Typically, starting points are selected to link to most if not all the pages on your site. (The page is not necessarily the home page. For example, it could be a sidebar with many links.) The Export to Disk publishing system crawls your site, beginning with the starting points, and logs new pubkeys as it discovers them.

44.6.3 Working with Compositional Dependencies

Compositional dependencies are the dependencies of a generated page on the assets that were used to generate that page. They are determined by the logic in that page's Working with the Publish-Time Template. Compositional dependencies dictate what is rendered on the exported page as prescribed by the template, completely ignoring any deptype attributes. The same tags that created template and reference dependencies in the approval template also create compositional dependencies at publish-time. The tags are listed in Using Approval Dependencies.

44.7 Frequently Asked Questions About the Export to Disk Publishing Process

How Do I Select an Approval Template?

The approval template (if specified) is the only template ever used by the approval system to validate a given asset. This template is not necessarily used at publish-time, depending on what the starting point is set to. The best advice is to set approval templates that most closely represent the asset's intended dependencies.

What if the template that contains the most representative set of dependencies is not the template to publish the asset with? Set it as the approval template for assets of that type, and use any template(s) as starting point(s).

Are Data Model Dependencies Accounted For in Any Way?

Associations, attributes, and so on, are not used in Export to Disk publishing. The only dependencies that matter are those established by templates.

Why Do We Track Publish-Time Compositional Dependencies?

After you export a page, its content is frozen. However, the assets used to generate that page may evolve, making the affected pages obsolete.

Because it records dependencies, is able to remind you which pages require updating, assuming you will want to republish those pages. gives you two republishing options: automatic refresh and manual refresh.

  • With automatic refresh, pages are queued automatically for the next publishing session, without your having to approving compositional dependencies that have changed.

    If you choose this option, the modified assets do not have to be approved in order for the page to be queued for publishing; in other words, the article page is republished as soon as you change the image asset. To set up automatic refresh, specify exists or no dependencies between the article and the image; this disables the approval system from prompting you to approve the assets.

  • With manual refresh, you review the updated pages before publishing them.

    If you choose this option, the affected pages will be Held until approved; in other words, you must reapprove the article page every time the image changes. For this to work, you have to set up exact dependencies.

44.8 Investigating Publishing Behavior and Functionality

Following is a compilation of simple scenarios which demonstrate Export to Disk publishing behavior:

The participating asset types are Page and HelloArticle (from HelloAssetWorld). The templates are Ttemplate, RTemplate, and dummyTemplate.

For clarity, the asset IDs have been hard-coded into the templates. Normally, assets would be loaded somehow instead of being hard-coded, so developers would have to leverage the deptype='none' attribute in their tags if they do not wish to set up additional dependencies. For the template code, see Working with Sample Templates.

44.8.1 Investigating Template Dependencies

Setup: Page P asset uses Ttemplate for both approval and publishing. Ttemplate loads HelloArticle A, therefore establishing a template dependency.

Starting Point: P+Ttemplate

Pubkeys (exported files): P+Ttemplate

Approval Dependencies: Page P has template dependencies on Ttemplate because of <render:logdep>, and on HelloArticle A because of <asset:load>. Because Ttemplate does not create any links, there are no reference dependencies.

Publish Dependencies: Starting Point is the only pubkey; therefore only one file is exported.

Note that the exported page does not have any publish-time compositional dependencies because it is never actually used by the template. There is only reason why P had to be approved—P is the exported page's primary asset. So, the only compositional dependencies determined at publish-time are the exported page's dependencies on A and Ttemplate.

Table 44-1 Template Dependencies

Action Approval Status Publish Status Comments

Initial

Approved:P, A, Ttemplate

Published:A and Ttemplate

P was not published because it was not referenced by the template.

Edit P

P status becomes Changed

Not affected by change.

Since there are no compositional dependencies on P, the change had no effect.

Edit A

P status becomes Held.

A status becomes Changed – have to approve P again.

After approval, page is published again

Template dependency on A causes P to be held, and subsequent approval makes the page publishable again.

44.8.2 Investigating Reference Dependencies

Setup: Page P asset uses Rtemplate for both approval and publishing. Rtemplate references HelloArticle A, which is in turn rendered by dummyTemplate.

Starting Point: P+Rtemplate

Pubkeys (exported files): P+Rtemplate, A+dummyTemplate

Approval Dependencies: Page P has the routine <render:logdep> template dependency on its Rtemplate. In addition, it establishes a reference dependency on A because of <render:getpageurl> (but not on dummyTemplate, because dependencies between pages are logged only between their primary assets). Note that dummyTemplate does not participate in an approval dependency because it is not referenced by any tags.

Publish Dependencies: The relevant tags are <render:logdep> and <render:getpageurl>. These dictate the publish-time compositional dependencies as Rtemplate and A. As before, note that Page P does not have a compositional dependency because it is not used by any of the templates. When export encounters <render:getpageurl>, it detects that another page is involved, so it creates the A+dummyTemplate pubkey on-the-fly, and runs dummyTemplate to generate its contents. Note that dummyTemplate does not officially have a compositional dependency because it is not used by any tags—it participates only as a pubkey member; so, if dummyTemplate is changed, the approval/publishing cycle will not recognize the change. For this reason, we advise not altering <render:logdep>, which opens on every newly created template.

Table 44-2 Reference Dependencies

Action Approval Status Publish Status Comments

Initial

Approved: P, A, Rtemplate

Published:A, Rtemplate

P was not published because it was not referenced by any template. The result is two HTML files: P+Ttemplate and A+dummyTemplate

Edit P

P status becomes Changed – approve it to go back to status quo

Not affected by change.

Since there are no compositional dependencies on P, the change had no effect.

Edit A

A status becomes Changed; P is still Approved, not Held because it has only an exists dependency on A (no reason to hold P).

P+Rtemplate was automatically queued for re-publishing because <render:getpageurl> generated a compositional dependency. (If you are not sure as to why, keep reading);

A+dummyTemplate was not affected because it does not use A.

A+dummyTemplate was not affected because it does not have tags that use A.

44.9 Understanding the Approval and Publish-Time Templates: What Happens When They Differ?

Generally, using the same template for approval and for publishing does not create problems, because approval dependencies match compositional dependencies. Problems start to occur when you use a different template for approval than for publishing. This can happen in several situations. For template code, see Working with Sample Templates.

This section covers the following topics:

44.9.1 Differing Templates: Example 1

Asset A uses T1 for approval. T1 does not reference any assets. Asset A uses T2 for publishing. T2 references asset B using <asset:load>. T2 loads asset B, which was never approved, but B will nevertheless be on the exported A+T2 page.

Does this mean you can publish assets that were never approved?

Yes! Some users prefer this, only to avoid approving assets before publishing. Approval can be a taxing operation because exact dependencies cause primary assets to be given Held status if the dependent assets change. As a result, pages of those primary assets cannot be exported. However, a better way to handle such situations is to make good use of the deptype attribute with exists or none values to avoid unwanted approval dependencies.

Now, what happens after asset B is published and then we change B? In this case, there is no approval dependency between asset A and asset B, but there is a compositional dependency. Whenever asset B is changed, the affected pages are automatically re-published. (Because there are no dependencies, the automatic refresh option is chosen). So, A+T2 are placed in the publish queue automatically as soon as asset B is saved—not approved. For information about republication options, see Frequently Asked Questions About the Export to Disk Publishing Process.

44.9.2 Differing Templates: Example 2

Asset A uses T1 for approval. T1 references asset B using <asset:load> under an exact dependency. Asset A uses T2 for publishing. T2 does not reference asset B.

In this case, there is an approval dependency between asset A and asset B, but there is no compositional dependency. Whenever asset B is changed, asset B has to be approved before asset A can be approved, even though the published page does not make any use of asset B.

44.9.3 Differing Templates: Example 3

Asset A uses T1 for approval. T1 does not reference any assets. Asset A uses T2 for publishing. T2 references asset B using <asset:getpageurl>.

In this case, there are no approval dependencies, so A is the only approved asset. During publishing of A+T2, we realize there is another page to be created, with B as the primary asset. Now, remember that primary assets must be approved before their page is exported. However, B is not approved, so its page is not exported. A+T2 is exported, but has a broken link.

Unknown dependencies and Export to Disk publishing. Situations become complicated when you start using <render:unknowndeps>. This tag removes compositional dependencies, and it records unknown dependencies to the pubkey. Assets thus remain in the publish queue permanently (meaning they are refreshed with every publish cycle). This behavior is expected, because if unknown dependencies exist (that is, dependencies may change at any moment, such as query results), the system cannot determine which assets a given asset depends on. To be on the safe side, the system always republishes the assets.

Many exact dependencies. While this is not always avoidable, keep in mind that when a primary asset has exact dependencies on other assets, a change to any of the dependent assets will cause the approval system to change the primary asset's status to Held. The primary asset's page is not publishable unless approved again. If the modified asset is used by many pages, they will all require re-approval. Consider setting the deptype to exists, and make the dependent pages automatically publishable—but the modified asset must be ready when the publishing session begins.

Note:

The preferred way to customize export URLs (without using simplename) is to use PREFERREDFILE and PREFERREDDIR as parameters to <render:getbloburl> and <render:getpageurl> to specify arbitrary names. For example:

<render:getbloburl blobtable='MungoBlobs' 
   blobcol='urldata' blobkey='id' 
   blobwhere='1088466917821'  outstr='pagelogoURL' 
   csblobid='1088466917821'>

<render:argument name='PREFERREDFILE' 
   value='myBlob.out'/>
<render:argument name='PREFERREDDIR' value='myDir'/>
</render:getbloburl>

This code exports the blob with 1088466917821 to myDir/myBlob.out.

44.10 Working with Sample Templates

This section lists the template implementations used in the examples in Investigating Publishing Behavior and Functionality and Understanding the Approval and Publish-Time Templates: What Happens When They Differ? Taglib and import definitions have been skipped.

Ttemplate:

<%-- Record dependencies for the Template --%>
<ics:if 
 condition='<%=ics.GetVar("tid")!=null%>'><ics:then><render:logdep 
 cid='<%=ics.GetVar("tid")%>' c="Template"/></ics:then></ics:if>
<asset:load name='myArticle' type='HelloArticle' 
 objectid='1156878442427'/>

Rtemplate:

<%-- Record dependencies for the Template --%>
<ics:if 
 condition='<%=ics.GetVar("tid")!=null%>'><ics:then><render:logdep 
 cid='<%=ics.GetVar("tid")%>' c="Template"/></ics:then></ics:if>
<render:getpageurl outstr="myURL" pagename='HelloAssetWorld/
 dummyTemplate' cid='1156878442427' c='HelloArticle'/>
 Got URL: <a href='<%=ics.GetVar("myURL")%>'> Click here</a><br/>

dummyTemplate:

completely blank, no logDep.

44.11 Rendering Export to Disk Pages

In basic terms, renders a Export to Disk page as follows:

  • A page name is submitted by the client browser to (through HTTP or another protocol).

  • locates the page in the SiteCatalog table, calls the root element, and renders the page to an HTML file.

  • You publish the file (either through FTP or another file transfer protocol) to the web server that is hosting your online site.

    Typically, administrative users of the Export to Disk publishing method set up a quality assurance process to test the rendered files before moving them to the web server of the delivery system. This rendering is illustrated in the following figure.

    Figure 44-9 Export to Disk Rendering

    Description of Figure 44-9 follows
    Description of "Figure 44-9 Export to Disk Rendering"

Note:

Export to Disk publishing is not recommended. Instead, use the Site Capture application of WebCenter Sites.

44.12 Understanding Export to Disk Publishing

When content is published using Export to Disk, the approval system, the publishing schedule, and your destination configurations all contribute to the export of your approved assets into static HTML files.

When an Export to Disk publishing session runs, this is what happens:

  1. The publishing system notifies the CacheManager servlet that a session is starting for a specific destination. CacheManager clears all the pages that were previously exported to this destination from the page cache on the source system.

    During a publishing session, exported files are cached to the page cache. If publishing sessions occur more frequently than the cache is configured to clear (expiration time), there could be exported pages in the cache that have the same names as the newly exported pages. To prevent this, the CacheManager servlet clears the page cache before a new publishing session starts.

  2. WebCenter Sites creates an export queue and adds all references that can be published to it. A reference that can be published is:

    • A pubkey that has been designated as an export starting point. See Working with Export Starting Points.

      There must be a starting point for the site and its asset must be approved, or the export session cannot begin. Every site that is exported must have at least one export starting point designated.

    • Any previously exported page or pagelet (reference) whose assets have changed and been approved again since the last publishing session to this destination. (After a site has been published, the publishing system knows which references have been published. It reads the data in the PublishedAssets table and then adds any references whose assets have been changed and approved again for this destination to the export queue.)

    • Any asset whose template uses RENDER.UNKNOWNDEPS tag.

      This tag alerts the approval system that the dependencies for the asset rendered by the template cannot be calculated because they are unknown. It is typically used for queries. When the dependencies are unknown, the system cannot determine if changed dependents would require publishing the asset. The presence of this tag means that the asset must be published every session.

    • Any page or pagelet (reference) that has not yet been published and is connected to another page or pagelet through a RENDER.GETPAGEURL tag. (That is, it is referenced from another page and has not yet been published.)

    • Any page or pagelet (reference) identified by a RENDER.SATELLITEPAGE or satellite.page tag.

  3. For the first export starting point, WebCenter Sites determines whether its asset has been approved:

    • If the asset has not been approved, the publishing session ends.

    • If the asset is approved, WebCenter Sites determines the page name of the template assigned to the asset.

  4. WebCenter Sites renders the export starting point by passing the following information to WebCenter Sites:

    • The page name of the template for the starting point.

    • The rendermode variable set to export[destinationID].

    • The name and location of the export directory where the rendered files should be saved.

  5. WebCenter Sites calls the root element of the page name, and begins rendering every approved asset that is connected to that export starting point as a reference. WebCenter Sites writes the resulting rendered pages to files rather than posting them to the browser.

  6. After each file is rendered, WebCenter Sites writes a message about that reference to the publish log for the session.

  7. If there are multiple export starting points, the process cycles back to step 3 in this description.

  8. When the publishing session is successful, WebCenter Sites concludes the session by writing information about the published references to the PubKey and PublishedAssets tables.

  9. WebCenter Sites also writes information about the assets that were published to the ApprovedAssets and ApprovedAssetDeps tables. It logs the date from the assets' updated field at the time that the assets were published so the approval system can calculate dependencies correctly the next time an asset is approved.

44.13 Working with the Path Naming Convention

How WebCenter Sites names paths to exported files depends on the type of asset that is published and path information that could have been set for the asset. The export path can be as simple as a single directory or it can be a path of several directories, limited only by the number of characters that are supported by the operating system.

The export path naming convention is:

<cs.pgexportfolder>/<DIR>/<file_dir>

where <cs.pgexportfolder> is a required directory. The subdirectories are conditional. Whether <file_dir> is used depends on a publishing argument named SIMPLEDIR.

Before summarizing the possible export paths, we define the export path variables and the SIMPLEDIR publishing argument.

This section covers the following topics:

44.13.1 Working with Export Path Variables and SIMPLEDIR

Export path variables are defined as follows:

  • <cs.pgexportfolder> defines the root directory for all exported files. <cs.pgexportfolder> is the value of the cs.pgexportfolder property in the wcs_properties.json file. It is a required value and applies to all Export to Disk publishing destinations.

    Typically, <cs.pgexportfolder> names a testing location (a file system where the exported files are verified) rather than a location directly on the delivery system.

  • <DIR> is the value of the publishing argument DIR, which is used to create subdirectories of the root directory (specified by cs.pageportfolder). When <DIR> is specified, WebCenter Sites creates <cs.pgexportfolder>/<DIR>.

    Note:

    The DIR publishing argument is available to administrators as the Base Directory field in the Add New Destination form (see Configuring an Export Destination). Throughout this section, we use <DIR> to mean Base Directory.

    This argument is typically used to organize the contents of the root export directory when multiple export destinations exist for your sites.

    Note:

    The directory specified by <cs.pgexportfolder> or <cs.pgexportfolder>/<DIR> is called the destination directory.

  • <file_dir> takes a value listed below, depending on whether the exported asset is a page asset and whether path information is available. <file_dir> is determined hierarchically, as WebCenter Sites looks for the values listed below, in the order shown. It is assumed that SIMPLEDIR=false.

    Table 44-3 Possible File_Dir values

    Possible <file_dir> Values Description

    <ForDestination:Path>

    Value of the For Destination: Path field (the field is shown in the Specify Path/Filename for Destination form for a specific destination).

    Setting a value in the ForDestination: Path field forces the asset to take the specified path when the asset is exported to the specified destination.

    If <ForDestination:Path> is not set, WebCenter Sites uses <parent_page's_path>.

    <parent_page's_path>

    Value of the Path field for the exported asset's parent page.

    Note for Page Assets: When exported, a page asset takes the path that is set for its parent page, not the one set for itself. (As a rule, a page asset's Path is applied only to child assets.)

    If <parent_page's_path> is not set, WebCenter Sites uses <ID_of_parent_page>.

    <asset's_path>

    Value of the exported asset's Path field.

    Note: <asset's_path> is used only for assets that are not page assets. If <asset's_path> is not set, WebCenter Sites uses <ID_of_parent_page> as the value of <file_dir>. If both <parent_page's_path> and <asset's_path> are not set, WebCenter Sites uses <ID_of_parent_page>.

    <ID_of_parent_page>

    ID of the asset's parent page. This value is used if <parent_page's_path> and <asset's_path> are unknown.

  • SIMPLEDIR. Although this publishing argument is not explicitly part of the export path, it determines whether <file_dir> is used when path information is unavailable. That is:

    • If SIMPLEDIR is set to true and path information is unavailable, <file_dir> is omitted from the export path. Setting a path overrides SIMPLEDIR.

    • If SIMPLEDIR is set to false and path information is unavailable, <file_dir> takes <ID_of_parent_page> as its valuė.

      Note:

      The SIMPLEDIR publishing argument is available to administrators as the Use simple directory naming check box in the Add New Destination form (see Configuring an Export Destination).

44.13.2 Working with Export Path Construction

This section summarizes the export paths that WebCenter Sites can construct using the convention:

<cs.pgexportfolder>/<DIR>/<file_dir>

Note that only <file_dir> varies in all the examples below

This section covers the following topics:.

44.13.2.1 Using a Forced Export Path

When <ForDestination:Path> (defined in Working with Export Path Variables and SIMPLEDIR) is specified, the asset being published to the named destination is forced to take the specified path, even if other path information is set. The asset's full export path is:

<cs.pgexportfolder>/<DIR>/<ForDestination:Path> 
44.13.2.2 Using an Export Path for Page Assets

If <ForDestination:Path> is not set, constructs the export path as shown below (for examples, see alternate-publishing-methods1.html#GUID-D4D39637-FCD5-4455-A78A-E534C17C8D8C__BEIEIADI).

  • When <parent_page's_path> is specified, the page asset's export path is:

    <cs.pgexportfolder>/<DIR>/<parent_page's_path>
    

    (even if <asset's_path> is specified).

    Note:

    When exported, a page asset takes the path that is set for its parent page, not the one set for itself (that is, <file_dir> takes the value <parent_page's_path>).

    As a rule, a page asset's Path information is applied only to child assets.

  • When <parent_page's_path> is not specified:

    • If SIMPLEDIR=false, uses <ID_of_parent_page>:

    <cs.pgexportfolder>/<DIR>/<ID_of_parent_page>
    
    • If SIMPLEDIR=true, omits <file_dir>:

    <cs.pgexportfolder>/<DIR>
    
44.13.2.3 Using an Export Path for Assets Other than Page

For an asset that is not a page, constructs an export path depending on which information is available (For examples, see alternate-publishing-methods1.html#GUID-D4D39637-FCD5-4455-A78A-E534C17C8D8C__BEIDHICI).

  • When <asset's_path> is specified, the export path is:

    <cs.pgexportfolder>/<DIR>/<asset's_path>
    
  • When <asset's_path> is not specified, uses <parent_page's_path>:

    <cs.pgexportfolder>/<DIR>/<parent_page's_path>
    
  • When both <asset's_path> and <parent_page's_path> are unspecified:

    • If SIMPLEDIR=false, uses <ID_of_parent_page>:

    <cs.pgexportfolder>/<DIR>/<ID_of_parent_page>
    
    • If SIMPLEDIR=true, omits <file_dir>:

    <cs.pgexportfolder>/<DIR>
    
44.13.2.4 Using Sample Export Paths

The following tables describe the sample export paths for assets.

Table 44-4 Sample Export Paths for Page Assets when SIMPLEDIR=false

Page Asset cs.pgexportfolder DIR file_dir (value 1) file_dir (value 2) file_dir (value 3) Export path

N/A

N/A

N/A

asset's_path

parent_page's_path

ID_of_parent_page

N/A

Home

/export

N/A

/abstracts

N/A

N/A

/export

Home

/export

/Japan

/abstracts

N/A

N/A

/export/Japan

World News

/export

/Japan

/abstracts

/news/

998877665

/export/Japan/news

World News

/export

N/A

/abstracts

/news/

998877665

/export/news

World News

/export

/Japan

/abstracts

N/A

998877665

/export/Japan/998877665

World News

/export

N/A

/abstracts

N/A

998877665

/export/998877665

Table 44-5 Sample Export Paths for Assets Other Than Page when SIMPLEDIR=false

Not Page Asset cs.pgexportfolder DIR file_dir (value 1) file_dir (value 2) file_dir (value 3) Export path

N/A

N/A

N/A

asset's_path

parent_page's_path

ID_of_parent_page

N/A

Oil Price

/export

/Japan

/energy

N/A

997766554

/export/Japan/energy

Oil Price

/export

/Japan

/energy

/news/

997766554

/export/Japan/energy

Oil Price

/export

N/A

/energy

/news/

997766554

/export/energy

Oil Price

/export

/Japan

N/A

/news/

997766554

/export/Japan/news

Oil Price

/export

/Japan

N/A

N/A

997766554

/export/Japan/997766554

Oil Price

/export

N/A

N/A

N/A

997766554

/export/997766554

44.13.3 Working with Paths for Links Within Exported Files

URLs in links for HREFs within the exported files do not include the values that specify the destination directory (<cs.pgexportfolder>/<DIR>). Instead, they begin within the destination directory and are relative to that directory.

The URL Prefix field on the Destination Configuration form is used to resolve URLs by specifying the location of those files on the delivery system. That is, URLs for links within the exported files are created like this:

<URLPREFIX>/<path_of_parent_page>

The value for URL Prefix must match the value of the web alias that identifies the directory where the files are found. If you are using only cs.pgexportfolder to create the destination directory, the web alias that the URL Prefix represents must point to that location. And if you have set the Base Directory field on the Destination Configuration form to add a subdirectory to the root directory specified by cs.pgexportfolder, be sure that the web root or the web alias represented by URL Prefix points to this directory.

44.13.4 Working with File Naming Conventions

How WebCenter Sites names an exported file depends on whether a file name is provided by the asset (in the Inspect form) and whether Use Simple File Naming is selected on the Destination Configuration form. For more information about this setting, see Configuring Your System for Export to Disk Publishing. Possible file names are shown in the following table. The naming convention is explained after the table.

Table 44-6 File Naming Conventions

File Name Description

<pagename>_ <packedargs(if any)>_ <filename>.<SUFFIX>

Used for assets with a populated Filename field and Use Simple File Naming is not selected.

<packedargs(if any)>_ <filename>.<SUFFIX>

Used for assets with a populated Filename field and Use Simple File Naming is selected.

<pagename>_ <packedargs(if any)>_ <assetID>.<SUFFIX>

Used for assets with an empty Filename field and Use Simple File Naming is not selected.

<packedargs(if any)>_ <assetID>.<SUFFIX>

Used for assets with an empty Filename field and Use Simple File Naming is selected.

Note:

When export files are named, these syntax changes are made:

  • Slash characters (/) in page names are converted to hyphens (-) in file names.

  • Equal signs (=) in packed arguments are converted to hyphens (-) in file names.

  • Ampersand characters (&) in packed arguments are converted to underscores (_) in file names.

  • <pagename> is the name of the SiteCatalog page entry of the template that is used to render the asset. (All template assets have SiteCatalog page entries.)

    Note:

    <pagename> is dropped when the Use Simple File Naming parameter is selected in the Destination Configuration form. Use the Use Simple File Naming option selectively. If your assets are rendered by multiple templates, do not select Use Simple File Naming.

  • <packedargs(if any)> are passed in from the page entry's root element. If any packed arguments are passed in from the root element of the asset's rendering template, the values of those arguments are also included in the name of the file generated for the asset.

    For information about packed arguments and how they relate to URLs, see Using the referURL Variable in the Developing with Oracle WebCenter Sites.

  • <filename> is the value of the asset's Filename field. If the Filename field is empty, WebCenter Sites uses the asset_ID specified in the asset.

    Note:

    A file name set for an asset for a specific destination in the Specify Path/Filename for Destination form supersedes the file name provided in the Filename field on the asset's New or Edit form when the asset is exported to that destination.

  • <asset_ID> is the ID that is specified in the asset. <asset_ID> is used if the asset's Filename field is empty or if the following note applies.

    Note:

    WebCenter Sites requires both the asset's ID and type to determine whether a file name is provided for the asset. If the identity of the asset's type is not provided, the file name cannot be used. In such a case, WebCenter Sites uses the asset's object ID in place of its file name.

  • <SUFFIX> is a destination configuration option that specifies the extension of the file name..

The following table provides examples of how file names are created during Export to Disk publishing. In the examples given, Use Simple File Names is not selected in the destination configuration.

Table 44-7 Export File Naming Conventions

Asset Name SiteCatalogPagename packedargs filename asset_ID SUFFIX Exported File Name

Home

BF/Page/Home

cid=123

c=Page

123

BF-Page-Home_123.html

Home

BF/Page/Home

cid=123

c=Page

123

.htm

BF-Page-Home_123.htm

Home

BF/Page/Home

cid=123

c=Page

home.html

123

BF-Page-Home_home.html

Home

BF/Page/Home

cid=123

c=Page

home.html

123

.htm

BF-Page-Home_home.html

Home

BF/Page/Home

cid=123

c=Page

PACKEDARGS="topicword=oil"

home.html

123

BF-Page-Home_topicword_ oil_home.htm

44.13.5 Working with Export Starting Points

The Export to Disk publishing method cannot begin rendering files unless it knows where to start. You tell it where to start by designating at least one starting point: that is, a page asset and the template that should be used to render it. calls the root element of the template's page name, and begins rendering every approved asset that is connected to that export starting point  — assets connected through an association, a link, a navigation bar, a query, and so on.

Note:

There must be at least one export starting point for an exported site. Typically it is your home page. However, depending on how your online site is designed, you may have to designate multiple export starting points. This is because if there is a section on your site that isn't connected to the rest of the site, it is not rendered. For example:

  • If your online site has multiple top-level page assets, you require an export starting point for each one.

  • If your site uses a combination of static pages and dynamic pages and there is a hard-coded static URL in an HREF on a dynamically-generated page, the asset that the URL points to should be designated as an export starting point.

44.14 Configuring Your System for Export to Disk Publishing

The main steps when configuring a system for Export to Disk publishing are these:

44.14.1 Creating the Batch User Account For Export Publishing (If One Does Not Exist)

This procedure must be performed only one time on each source system, regardless of the number and types of publishing destinations you are configuring.

If you have not done so, create the batch user account. For instructions, see Creating the Batch User Account (If One Does Not Exist).

If an account exists for your installation, skip to Specifying the Root Export Directory.

The purpose of creating a batch user account is two-fold:

  • Configure a batch user account for the publishing system on the source to use.

  • Specify where the publish logs should be stored.

The procedures in this section require you to set several properties in the wcs_properties.json file. Additional properties are also available to you for fine-tuning your system configuration. For a complete list of properties, see Oracle WebCenter Sites JSON Property File in the Property Files Reference for Oracle WebCenter Sites.

44.14.2 Specifying the Root Export Directory

As mentioned previously in this chapter, the directory that WebCenter Sites exports files to is determined by the cs.pgexportfolder property in the wcs_properties.json file. (If you wish to add subdirectories to this directory, you enter a value in the Base Directory field in the Destination Configuration form.)

Note:

Before you run an export publishing session, ensure this root export directory exists and that it has enough space for the HTML pages that will be created there.

To set the root directory for the exported files:

  1. In the Admin interface, open the Property Management Tool. (For instructions on accessing the Property Management Tool, see Overview of the Property Management Tool in the Property Files Reference for Oracle WebCenter Sites.)
  2. In the Name field, enter cs.pgexportfolder.
  3. Click Search.
  4. In the Properties section of the form, select the name of the property. Set the value to the file directory (location) to which all files should be exported.

    This is a global setting for the system. If you have multiple destinations and want the files published to those destinations to be stored in separate subdirectories within this directory, enter a value in the Base Directory field when you configure those destinations (in Configuring an Export Destination).

    For more information about export directories, see Working with the Path Naming Convention.

  5. Click Save.
  6. Restart the application server.

44.14.3 Configuring an Export Destination

To create an export destination:

  1. Log in to the Admin interface on the source WebCenter Sites system.
  2. In the General Admin tree, expand the Admin node, expand the Publishing node, expand the Destinations node, and then double-click Add New.

    The Add New Destination form opens.

  3. Fill in the fields on the Add New Destination form as follows:
    • In the Name field, enter a unique name for the destination.

      Note:

      The following characters are not allowed in the Name field: single quote ('), double quote ("), semicolon (;), colon (:), less-than sign (<), greater-than sign (>), percent (%), and question mark (?). Additionally, the name cannot end with a backslash (\).

    • In the Delivery Type drop-down list, select Export to Disk: Export Web Files to Disk. The available fields on the form will change slightly.

    • Base Directory: Enter a subdirectory name for the files published to this export destination. The base directory is created as a child directory of the root directory that is specified by the cs.pgexportfolder property.

      When you enter a value in this field, the export path for the publishing destination is as follows:

      <cs.pgexportfolder>/<DIR>
      

      where <DIR> is the base directory.

      Note:

      URLs that are contained in exported files do not include this destination directory path in the URL. Exported files have URLs that begin below this level, inside the destination directory. Therefore, if you enter a value in this field and you enter a value in the URL Prefix field as well, be sure that the web root or the web alias represented by the URL Prefix field points to this directory.

      This parameter is typically used to organize the contents of the root export directory when there are multiple export destinations for your sites.

    • URL Prefix: Enter the prefix that the export process will add to the beginning of the URLs that are used as links (HREFs) within the exported files. The names of the generated files do not include this prefix , only the links within the files use it.

      Specify the web server alias of your delivery system in the URLs so that the links in the HTML files can be resolved when the files are moved to that system. If you leave this field blank, URLs are relative.

      Be sure that the name of the web alias on the testing system is the same as the name of the web alias on the delivery system.

    • Suffix: In this text box, specify the file suffix to use for the generated files when the Filename field for the asset is not used or it does not specify a suffix. The default is html.

    • Use simple file naming: If this parameter is selected, WebCenter Sites overrides the normal file-naming conventions by ignoring the SiteCatalog page entry of the template that is used to render the asset and uses only the value entered in the asset's Filename field as the file name. If the asset does not have a filename, WebCenter Sites uses the asset's ID, instead. See Working with File Naming Conventions.

      There is one exception to this rule: assets with upload fields (assets that are blobs) will always receive a standard (long) file name, even when this value is set to true.

      Caution:

      The Use simple file naming parameter must be used with caution. If your site is designed such that individual assets are rendered by multiple templates, you must not use this parameter. Without the SiteCatalog page entries used in the file name, file names cannot be guaranteed to be unique when an asset is rendered by multiple templates.

    • Use simple directory naming: When selected, this parameter overrides the normal directory-naming convention. See Working with the Path Naming Convention.

      When Use simple directory naming is selected, WebCenter Sites puts the rendered HTML file directly into the default export directory when there is no path information available from the parent asset. (Normally, WebCenter Sites uses the page asset's ID when there is no path information.) If there is a value in the Path parameter of the asset's parent page asset, this selection is ignored.

    • Old Template: Select this parameter to use the rendering methodology that was standard in 3.5 and earlier versions of the product.

      Note:

      If the online site that you present on your delivery system was designed for the rendering model used in WebCenter Sites versions before 3.6 and it has not yet been redesigned for the 3.6 rendering model, you must select this parameter.

      If you select this parameter, do not set an export starting point for your site. The export starting point is determined by the templates themselves.

    • Send Email on Failure: If publishing fails and email notices to that effect are required, select this option. Additional fields appear.

      • Email Addresses: Enter the recipient's email address, and click Add. (This field is shown only when Send Email on Failure is selected). All email addresses that will receive an email on failure are shown.

    • Verbose Output: Activates detailed error logging during the publishing process. When selected, messages in addition to error messages are written to the PubMessage table. Because additional information lengthens the publishing process, be sure to select this option only for troubleshooting.

    • More Arguments: No additional arguments can be specified at this time.

    • Sites: Select the sites whose assets can be approved for and published to this destination.

    • Roles (Approve for Publish): Select the roles to which you are assigning approval privileges. All users assigned these roles can approve assets.

  4. Click Add New Destination.

    The Publish Destination form opens. The new destination is shown on the form.

    Figure 44-10 Publish Destination Form

    Description of Figure 44-10 follows
    Description of "Figure 44-10 Publish Destination Form"
  5. Repeat steps 2–4 for each additional export destination.

44.14.4 Mapping a URL Prefix for Your Web Server

To make your exported content available to the public at its final destination (your delivery system), you must configure your web server to map a URL path prefix to the place where the files will reside so that URLs can resolve.

See the vendor documentation for your web server for information about the appropriate procedure for mapping URL prefixes on your web server. Remember that the name you specify for this prefix must match the name that you specified with the URL Prefix destination configuration parameter for the destination. If you enter a URL Prefix, be sure that the web root or alias includes the directory you entered.

44.14.5 Creating the Export Starting Points

To create an export starting point:

  1. Using the Admin interface on the source system, find the asset to specify as an export starting point.

  2. Open the asset in its Status form and scroll to the Publishing Destination section.

  3. Complete either:

    • If the asset is not yet approved for the destination you are currently configuring, select Approve for Publish from the toolbar (The green check mark icon) and go to step 4.

    • If this asset is approved for the destination you are currently configuring, go to step 6.

  4. In the Publishing Approval form, select the destination for which you are approving the asset and click Approve.

    calculates dependencies for all the assets linked to this asset and shows the results.

  5. When the approval results are shown, click the Status icon (a clock face with a green check mark) from the toolbar.

  6. Scroll down to the section of the Status form that shows the selected destination.

  7. In the File/Path field, click Specify Path/Filename, Start points.

    The File and Path fields are made available on the Content Attribute form.

    Figure 44-11 Content Attribute Form

    Description of Figure 44-11 follows
    Description of "Figure 44-11 Content Attribute Form"

    Figure 44-12 Content Attribute Form

    Description of Figure 44-12 follows
    Description of "Figure 44-12 Content Attribute Form"

    Note:

    If the starting point selected is a page, no templates are found, and then clicking Save results in the error "To make this asset a publish starting point, you must select a template," the enableAssetForms property must be set to true.

    From the Property Management Tool, set advancedUI.enableAssetForms=true then set the page as the starting point in the Content Attribute form.

  8. In the Content Attribute form, fill in the fields:

    1. (Optional) For Destination section:

      Path: To specify unique path information for the asset being published to this destination (the path information is not provided elsewhere for this asset), enter the path in the Path field.

      Filename: To specify file name information that is different for this destination, enter it in the Filename field. A file name entered in this form for this destination overrides any file name information provided elsewhere for the asset.

    2. Select Yes for Is this asset an export starting point?

    3. (Optional) Using Templates section:

      Select a template.

      Select a wrapper page.

      Select Force specified path if you would like to force this asset to be exported to the path that is named in the For Destination section.

      Select Force specified filename if you would like to force the use of the file name that is specified in the For Destination section.

  9. Click Save.

  10. Repeat steps 1–9 for each top-level page asset in the site.

44.14.6 Approving Your Assets for Export to Disk Publishing

To perform a simple test of your configuration, select the export starting point with the fewest number of dependent assets and approve each of those assets.

To complete a test publish of your entire site, approve all the assets for the site. See Approving Multiple Assets.

44.14.7 Publishing and Testing the Results

When the assets you want to publish to the selected destination are approved, run a test publishing session:

  1. In the Admin interface on the source system, click Publishing in the button bar.
  2. In the Publish Console, select your destination from the drop-down list and click Select Destination.

    shows information about the assets that are ready to be published to this destination. (If you have not yet created an export starting point for this destination, the form states this fact. You must create at least one export starting point before the publishing session can begin.)

  3. Click Publish.

    A confirmation message opens. Click Yes to proceed with publishing.

    The publishing system exports all the approved assets for this destination into files.

  4. In the Publish Console Active tab you can observe that the session is running.
  5. When the session completes, click the History tab to view the session summary for this session.

    Mouse over the session information to view summary information;

  6. In the Publish Console History tab, select the link to the publishing destination.

    A session summary shows a list of all the files that were created during the export process.

  7. Click the Preview (binoculars) icon next to the file representing the top-level page in your site.

    The page opens in a new browser window.

  8. Scan the page for errors and test all the links. Make sure to test links to all of the other files that were generated.
  9. Test the results by directly entering the URL of the rendered home page into your browser and navigating the entire site. To do this, you must first set up a web server root on the management system that points to the export directory.
  10. If you decide that the files are ready for delivery, copy them to your delivery system.

44.14.8 Setting Up the Schedule

After you have ensured that:

  • Your destination is configured correctly,

  • The file names and directory names are created according to your requirements, and

  • Your web server is delivering the files correctly,

you can finish configuring your publishing system by completing the following steps on the source system:

  1. Create scheduled publish events for the destination. For help with this step, see Scheduling a Publish Event.
  2. Plan how you will copy the generated files to your web servers, for both the testing area and the delivery system. For example, you can set up a script that automatically copies the files by FTP to a testing area after a publishing session completes.

44.15 Understanding Mirror to Server Publishing

The Mirror to Server publishing method gathers information from the approval system, the publishing schedule, and the destination configurations, copies data to the destination, unpacks that data on the destination system, and then calls the CacheManager servlet to refresh any pages that should be regenerated to take advantage of the new content.

Figure 44-13 Mirror to Server Publishing

Description of Figure 44-13 follows
Description of "Figure 44-13 Mirror to Server Publishing"

Note:

Export to Disk publishing is not recommended. Instead, use the Site Capture application of WebCenter Sites.

Whether your WebCenter Sites delivery system delivers content dynamically, you probably use the Mirror to Server publishing method to move data from your development systems to your management system. For information about that process, see Troubleshooting.

When a Mirror to Server publishing session runs, the followingfigure illustrates what occurs.

Figure 44-14 Mirror to Publishing Process

Description of Figure 44-14 follows
Description of "Figure 44-14 Mirror to Publishing Process"
  1. On the source system, Mirror to Server publishing uses the list of approved assets that the publishing system passed to it to create a mirror queue for the destination.

    Mirror Queue for Basic Assets

    For basic assets, the following information is added to the queue:

    • The asset's main table row. For example, for page assets, the asset's row in the Page table.

    • The appropriate rows in the AssetPublication table. These rows list sites and which assets belong to them.

    • Rows in the AssetRelationTree table that refer to any assets that are associated with the asset being published.

    • The associated assets referenced by those rows in the AssetRelationTree table. The asset table rows, AssetPublication rows, and associated assets of any dependent assets are also mirrored, if they are approved and have not yet been published.

    Mirror Queue for Flex and Complex Assets

    For flex asset types and the other multi-table asset types like template and CSElement, the information from the appropriate rows from all of their tables are serialized into an object and stored in the _Publish table for that asset type.

    For example, when a template is to be published, the appropriate rows from the Template, SiteCatalog, and ElementCatalog tables are serialized into an object and stored in the Template_Publish table.

    Each item in a _Publish table is added to the mirror queue.

  2. WebCenter Sites uses the AssetPublishList table to create a list of all the assets that are in the mirror queue.

  3. The mirror operation starts.

    First, the AssetPublishList is mirrored from the source to the destination.

  4. The mirror queue is delivered and the publishing system unpacks the assets in the queue.

    For flex assets, Mirror to Server publishing de-serializes objects in the _Publish tables, and inserts the results in the appropriate tables.

    For basic assets, each row in the queue is copied.

  5. When the items in the mirror queue are unpacked, the publishing system sends messages that the mirror publish concluded successfully. The destination system responds as follows:

    • The newly published assets are marked as changed on the destination system, which means that before they can be published from that system to another destination, they must be approved. Note that this feature is enabled by default. You can turn it off if you must. For details, see Turning Off Asset Invalidation on the Delivery System.

    • The CacheManager servlet on the destination regenerates the appropriate pages in the cache so that all pages that refer to the assets that were just published are updated. It also rebuilds any pages that have unknown compositional dependencies.

    • CacheManager then communicates a message about which pages must be refreshed to each Satellite Server identified by the satellite.ini file on the destination system. It communicates with the co-resident version and any remote instances that are identified as belonging to this WebCenter Sites system. The Satellite Server applications then use that information to refresh the Satellite Server page caches.

    • The AssetPublishList table is cleared, making it ready for the next publishing session.

  6. On the source system, the publishing system updates the publish log file. Unlike the Export to Disk publishing method, which writes to the publish log after each asset is exported, Mirror to Server publishing waits until the entire mirror queue has been successfully mirrored before writing the results to the publish log.

  7. When the publishing session is successful, WebCenter Sites concludes the session by writing information about the published references to the PubKey and PublishedAssets tables and by clearing the AssetPublishList table on the source system.

  8. WebCenter Sites also writes information about the assets that were published to the ApprovedAssets and ApprovedAssetDeps tables so the approval system can calculate dependencies correctly the next time an asset is approved.

44.16 Pre-Configuring Mirror to Server Publishing

Before you configure the Mirror to Server publishing process, take into the consideration the topics that are presented in this section. Prior knowledge of the information you provide will help to ensure a smooth configuration process.

44.16.1 Working with Users and Mirror to Server Publishing

In addition to the batch user account on the source system that a publish event uses to process a publishing session, the Mirror to Server publishing method requires another user account: the mirror user account, which is located on the destination server. This is the user account that the publishing system uses to unpack the mirror queue on the destination system.

When you set up a Mirror to Server publishing destination, you must create the mirror user account on the destination system that the destination represents.

44.16.2 Working with CacheManager

The CacheManager is a servlet that maintains the page cache on any dynamic system, including the management system.

CacheManager is important because it locks the appropriate assets on the destination during a mirror publishing session and ensures the integrity of the page cache both before and after a mirror publishing session.

See About the CacheManager in Developing with Oracle WebCenter Sites.

44.16.3 Configuring a Mirror Destination

The Mirror to Server publishing method copies information for approved assets from one database to another. This information must be configured for the mirror destination. Configuring a mirror destination involves two steps: initializing the destination, and configuring the data for the destination.

Whenever you create a new mirror destination, you must initialize it before you can publish to it. To initialize a mirror destination, you specify the following information:

  • The sites. Based on the sites that you select, the appropriate rows from the Publication, SitePlanTree, and PublicationTree tables are mirrored to the destination.

  • Any custom table that supports or is directly related to your asset types. In other words, a table for assets that was not created by either AssetMaker or Flex Family Maker. Examples of these are Source and Mimetype. These tables are called auxiliary tables.

Mirror destination configuration is the process of indicating which data (for example, assets types, associations, and start menu items) is mirrored to the target destination. Mirror destination configuration moves configuration data and rows from auxiliary tables—which are non-asset database tables that are used for the dynamic display of the assets—from one database to another.

44.16.4 Determining When to Use Mirror Destination Configuration

You use Mirror Destination Configuration in several situations:

  • To set up a new mirror destination.

  • To move configuration items that support asset types (start menu items, associations, and so on) from a development system to a management system or to a delivery system.

  • To move workflow configuration data from a development system to a management system.

  • If you or your developers add any additional sites, asset types, or auxiliary tables to your system.

  • If you or your developers add any additional categories or subtypes for existing asset types.

  • When you must troubleshoot your configuration. If you can successfully initialize a mirror destination, that means that the source and the destination systems are communicating.

44.17 Configuring Your System for Mirror to Server Publishing

The main steps when configuring a system for Mirror to Server publishing are as follows:

44.17.1 Creating the Batch User Account for Mirror Publishing (If One Does Not Exist)

This procedure must be performed only one time on each source system, regardless of the number and types of publishing destinations you are configuring.

If you have not done so, create the batch user account. For instructions, see Creating the Batch User Account (If One Does Not Exist).

If a batch user account exists on your source system, skip to Setting Up the Destination System.

44.17.2 Setting Up the Destination System

To mirror publish assets from one WebCenter Sites system to another, you must ensure that the sites and asset types are the same on both the source and the destination system. You must also create an additional user on the destination system, called the mirror user (as opposed to the batch user, which exists on the source). This user completes the mirror publish database transactions on the destination system.

Note:

Database properties on the source and destination systems, if not an exact match, must be compatible, particularly database schema options (set from the Property Management Tool). Be sure to restart the application server if you make changes to database properties.

To set up your destination system:

  1. If you have any custom support tables—a lookup table for a field in an asset type, for example— create those tables on the destination system.
  2. On the destination system, create the mirror user.

    Note:

    The mirror user has the same privileges as the RealTime user configured for RealTime publishing. If a RealTime user is configured for RealTime publishing, the same user may serve as the mirror user.

    • This user must have the following ACLs:

      • Browser

      • ElementEditor

      • PageEditor

      • TableEditor

      • Visitor

      • VisitorAdmin

      • xceladmin

      • xceleditor

    • Because the mirror user account is used by the CacheManager to regenerate the page cache after a publishing session, the mirror user must have sufficient privileges to regenerate all the pages in the cache. Therefore, the mirror user account must be given to all ACLs which are assigned to page entries in the SiteCatalog table or database tables that are holding data to be rendered.

      Note:

      If any of the sample sites are installed on the destination system, a user named mirroruser exists. For security, if you decide to keep this user as your mirror user, be sure to change the password for this user; or if you decide to create a different mirror user, be sure to delete the sample site mirroruser.

    • If you require help with creating the mirror user, see Creating a User in the Admin Interface.

44.17.3 Identifying the Mirror User to the Source System

Next, you identify the name and password of the mirror user on the destination system to the source system by setting property values in the wcs_properties.json file on the source system.

Note:

Because the proxy server is used by both Mirror to Server and RealTime publishing, it may have been set up for RealTime publishing. In such a case, review the properties in the procedure steps to ensure they are set correctly.

To identify the mirror user to the source system:

  1. In the Admin interface, open the Property Management Tool. (For instructions on accessing the Property Management Tool, see Accessing the Property Management Tool in the Property Files Reference for Oracle WebCenter Sites.)
  2. In the Category drop-down menu, select Publish.
  3. Click Search.
  4. Set values for and save the following properties:
    • cs.mirroruser

      Set this property to the name of the user that you created on the destination system in the preceding procedure.

    • cs.mirrorpassword

      Set this property to the password of the user that you created on the destination system in the preceding procedure.

  5. Complete either:

44.17.4 Identifying the Local Proxy Server to the Source System (If One Exists)

Note:

This procedure must be performed only one time on each source system, regardless of the number and types of publishing destinations you are configuring. Skip to Creating a Mirror Destination if the local proxy has been identified to your source system, or a proxy server is not used.

To identify the local proxy to the source system:

  1. In the Admin interface, open the Property Management Tool. (For instructions on accessing the Property Management Tool, see Accessing the Property Management Tool in the Property Files Reference for Oracle WebCenter Sites.
  2. In the Category drop-down menu, select Publish.
  3. Click Search.
  4. Set values for and save the following properties:
    • cs.mirrorproxyserver

      Set this property to either the name or the IP address of the local proxy server.

    • cs.mirrorproxyserverport

      Set this property to the port number of the local proxy server.

  5. Restart the application server.

44.17.5 Creating a Mirror Destination

A mirror destination must be configured, just as any other part of the process of publishing.

To create a mirror destination:

  1. Log in to the Admin interface on the source WebCenter Sites system.
  2. In the General Admin tree, expand the Admin node, expand the Publishing node, and then expand the Destinations node.
  3. Under the Destinations node, double-click Add New.

    The Add New Destination form opens.

    Figure 44-15 Add New Destination Form

    Description of Figure 44-15 follows
    Description of "Figure 44-15 Add New Destination Form"
  4. Configure the fields on this form as follows:
    • Name: Enter a unique name for the destination.

      Note:

      The following characters are not allowed in the Name field: single quote ('), double quote ("), semicolon (;), colon (:), less-than sign (<), greater-than sign (>), percent (%), and question mark (?). Additionally, the name cannot end with a backslash (\).

    • Delivery Type: Select Mirror to Server: Copy database rows to remote server.

    • Destination Address: Enter the URL of the remote server in the format shown. For <targetserver:port>, enter the host name or IP address of the target system and the port to be used by the destination. A slash is required after the URL because this URL is appended dynamically.

    • Remote User: Enter the name of the mirror user created in Setting Up the Destination System. This user is called by the publishing system to unpack the mirror queue on the target system.

    • Remote Password: Enter the password of the mirror user.

    • Send Email on Failure: If publishing fails and email notices to that effect are required, select the check box.

      • Email Addresses: Enter the recipient's email address. (This field is available only when Send Email on Failure is selected.)

    • Verbose Output: Select this option to activate detailed error logging during the publishing process. When selected, messages in addition to error messages are written to the PubMessage table. Because additional information lengthens the publishing process, select this parameter only for troubleshooting.

    • More Arguments: This parameter is reserved for future use; no additional arguments can be specified at this time.

    • Sites: Select the sites whose assets can be approved for and published to this destination.

    • Roles (Approve for Publish): Select the roles to which you are assigning approval privileges. All users who are assigned these roles are allowed to approve assets.

    • Roles (Publish): Select the roles to which you are assigning publish privileges. All users assigned these roles can publish.

  5. Click Add New Destination.

    WebCenter Sites opens the Publish Destination form.

    Figure 44-16 Publish Destination Form

    Description of Figure 44-16 follows
    Description of "Figure 44-16 Publish Destination Form"
  6. If you are ready to initialize this destination system (you must initialize the destination system before you can publish to it), click the Initialize Mirror Destination button in the Publish Destination form, then proceed to Initializing the Destination for detailed instructions (begin at step 4 of that procedure).

    If you must create more mirror destinations, repeat steps 1 through 5 for each additional mirror destination that you must create for your source system.

44.17.6 Initializing the Destination

You must initialize the destination system before you can publish to it. This creates the basic site information about the destination system. Specifically, the Publication and PublicationTree tables are updated with the site names and asset types published to the target.

To initialize the destination system:

  1. In the General Admin tree, expand the Admin node, expand the Publishing node, and then expand the Destinations node.

  2. Under the Destinations node, double-click the destination you want to initialize.

  3. In the Publish Destination form, click Initialize Mirror Destination.

    The Initialize Mirror Destination form opens.

  4. Select the sites whose assets you want to publish to this destination.

  5. In the Auxiliary tables fields, enter the names of the following tables:

    • Source, if you are using the source feature for any of your asset types

    • Mimetype, if you are using flex filter assets, the ImageFile asset type, or if you are using this table for any of your custom asset types.

    • Filters, if you are using flex filters on your site. (The Filters table lists the classes that are used by the flex filters. You must copy jar files and classes manually.)

    • Any other auxiliary tables (such as lookup tables) for your asset types.

      Note:

      Only five fields are provided for table names. If you have to enter more than five table names, complete this procedure through step 6 for the first five tables, then repeat steps 3 through 6 for the remaining tables.

  6. Click Mirror.

    If the initialization is successful, displays a confirmation message; otherwise, an error message opens.

    Based on the sites that you selected in step 4, the corresponding rows from the Publication, SitePlanTree, and AssetType tables are copied to the destination.

    Additionally, all the rows in the tables that you specified as auxiliary tables are copied to the destination.

    Note:

    You can also initialize the target destination from the Publish Console. In the button bar, click Publishing.

    1. In the Publish Console, select your mirror destination from the drop-down list and then click Select Destination.

    2. Click the Create Site on Target button. When the confirmation form opens, click Yes. This creates the basic site information about the destination system.

44.17.7 Configuring the Mirror Destination

Now you must configure the data that will be on your target destination. This configuration will vary depending on the purpose of the target destination. For example, if the target destination is strictly a delivery computer, it makes sense to only include asset types when mirroring. Before proceeding with configuring the destination, you may find it helpful to see Migrating a Site from One System to Another.

Note:

If Revision Tracking is turned on at the publishing target destination for either ElementCatalog or SiteCatalog, then the publishing of template will fail and the template may become corrupted.

It is not recommended to enable Revision Tracking on the target destination.

  1. In the General Admin tree, expand the Admin node, expand the Sites node, and then double-click the site whose data you want to publish on the target destination.
  2. In the Publish Destinations field (near the bottom of the form), click Mirror site configuration for destination (dynamic), where destination is the target destination.

    The Mirror Site Configuration form opens.

    Figure 44-17 Mirror Site Configuration Form

    Description of Figure 44-17 follows
    Description of "Figure 44-17 Mirror Site Configuration Form"

    Select the data you wish to make available on the target destination:

    • Asset Types: Select the asset types to make available on the target destination.

      If your asset types have subtypes and categories, choose the appropriate options from the list in the Asset Types section and select the corresponding check boxes. For example, the AssocNamed table contains information about associations for asset types. The table is mirrored only if you select Asset associations for selected asset types and then the relevant asset types.

    • Start Menu Items: Select any start menu items that you or the developers designed for your content providers to use.

    • Workflow Processes: If there are workflow processes for your asset types, select these processes and the appropriate workflow items.

    • Workflow Groups: Select any workflow groups that you or the developers designed for your content providers to use.

    • Tree Tabs: Select the tree tabs to make available on the target destination.

      Note:

      If any of the following tree tabs exist on the target destination, mirroring the tree tabs will fail and potentially corrupt the tree tabs on the destination: Site Plan, Admin, Site Admin, Workflow, Bookmarks.

      It is not recommended to mirror tree tabs that exist on the target destination.

    • Saved Searches: Select any saved searches that you or the developers designed for your content providers to use.

    • Roles: Select the roles you want to exist on the target destination.

  3. Click Mirror.

    Based on which asset type configuration options you selected in step 1, appropriate rows from the AssocNamed, AssocNamed_Subtypes, and Category tables are copied to the destination.

    If you selected Start Menu Items or Saved Searches, appropriate rows from the tables that implement those features are copied to the destination.

    Based on which workflow configuration options you selected in step 1, appropriate rows from the workflow tables are copied to the destination.

  4. Repeat steps 1 through 3 for each site whose assets you want to publish on the target destination.

44.17.8 Approving Your Assets

To test your published site, you must approve and publish all the assets for the site. See Approving Multiple Assets for help with approving many assets at one time.

To perform a simple test of your configuration, temporarily create a home page asset with only a few dependents.

44.17.9 Publishing the Assets

After you have approved assets that can be published to your destination, you can run a test publishing session:

  1. On the source system, click Publishing in the button bar.
  2. In the Publish Console, select your mirror destination from the list and click Select Destination.

    WebCenter Sites displays information about the assets that are ready to be published to this destination.

  3. If for some reason the target destination has not yet been initialized, it must be initialized now or the publishing session will fail. To initialize the destination, click Create Site on Target in the Publish Console. This creates the basic site information about the destination system.
  4. Click Publish.

    A confirmation message opens. Click Yes to proceed with the publish.

    The publishing system mirrors all the approved assets for this destination to the WebCenter Sites database on the destination system.

  5. In the Publish Console Active tab you can observe that the session is running.
  6. When the session completes, click the History tab to view the session summary for this session.

    Mouse over the session information to view summary information; click View Log to view the session log files. For information about configuring the logs to view destination information, see Retrieving Logs From Delivery WebCenter Sites Systems.

44.17.10 Testing the Results

To test the results, point your browser to the home page asset on the destination system and examine the site.

If you have not done so, you must determine the asset's URL. A URL is constructed by concatenating the following values:

  • The host name or IP address (and sometimes the port number) of the destination system.

  • The CGI path, which the system obtains from the ft.cgipath property in the wcs_properties.json file. For example, for WebLogic and other application servers with servlet architectures, this default path is /servlet/.

  • The string ContentServer?pagename=

  • A page name from a SiteCatalog entry.

  • Additional information that is passed in with the page criteria variables, c, cid, tid, and p. (For information about these variables, see Template, CSElement, and SiteEntry Assets in the Developing with Oracle WebCenter Sites.)

Complete the following steps to determine the URL of your home page and test the site:

  1. In the Admin interface, open the Property Management Tool. (For instructions on accessing the Property Management Tool, see Accessing the Property Management Tool in the Property Files Reference for Oracle WebCenter Sites.)
  2. In the Category drop-down menu, select Core.
  3. Click Search.
  4. Write down the values of the following properties:
    • ft.cgipath

    • ft.approot

  5. Open a text editor. Enter the server name, a slash (/), and then the cgipath. Precede the server name with the proper protocol—http:// or https://—as in the following example:

    Example for Oracle WebLogic Server and IBM WebSphere:

    http://bigfatsun.example.com:8080/servlet/

  6. After the string, type a slash, and then add the following text:
    ContentServer?pagename=your_home_page
    

    Now the URL should look similar to the following examples:

    Example for Oracle WebLogic Server and IBM WebSphere:

    http://bigfatsun.example.com:8080/servlet/
       ContentServer?pagename=ExampleSite/Page/Home
    
  7. Point your browser to the URL you assembled.
  8. Scan the page for errors and test all links to ensure they work.

    Note:

    It is recommended that you conduct a complete test of the system under peak load conditions after you have mirrored the entire site for the first time, and at regular points thereafter.

44.17.11 Setting Up the Schedule

After you have ensured that your destination is configured correctly, you can finish configuring your publishing system by completing the following steps on the source system:

  1. Create scheduled publish events for the destination. For help with this step, see Troubleshooting.
  2. If you are using images that are not assets in the design of your site — that is, your site designers want to store all images on the web server rather than manage them as assets — plan how you will move the image files from the web server for the management system to the web server for the delivery system. For example, you can set up a regular FTP transfer.
  3. If you are using elements and SiteCatalog page entries that are not CSElement and SiteEntry assets, you must use the CatalogMover tool to mirror them to the destination system. For help with CatalogMover, see CatalogMover in Developing with Oracle WebCenter Sites.

44.17.12 Turning Off Asset Invalidation on the Delivery System

By default, the publishing system is configured to select an asset as changed on the destination system when you publish an asset from one system to another (source to destination). Then, the newly published asset must be approved on the destination system before it can be published to another destination.

The default configuration is appropriate for development and management systems. However, when you are publishing to the delivery system, it is not necessary for the publishing system to take the time to mark the change—assets are published to the delivery system but not from it.

Therefore, on the delivery system, turn off this publishing feature by completing the following steps:

  1. In the Admin interface, open the Property Management Tool. (For instructions about accessing the Property Management Tool, see the Accessing the Property Management Tool in the Property Files Reference for Oracle WebCenter Sites.)
  2. In the Name field, enter xcelerate.publishinvalidate.
  3. Click Search.
  4. Select the name of the property. In the Value field, set its value to false.
  5. Click Save.

44.18 Retrieving Logs From Delivery WebCenter Sites Systems

provides a way to retrieve publishing-related logging information from the delivery system and display it in the Publishing console. To achieve this, inserts the publishing session ID into each relevant log entry. The management interface has the ability to retrieve the relevant entries for a publishing session and display them in the Log form for that session.

To enable remote publishing logging:

  1. Activate the logger by setting the following property in commons-logging.properties on both source and target:
    org.apache.commons.logging.LogFactory=com.fatwire.cs.core.logging.ContextAwareLogFactory 
    
  2. Add the following lines to your web.xml on the target system:
    <filter> 
       <filter-name>ContextHeaderFilter</filter-name> 
       <filter-class>
         com.fatwire.cs.core.logging.context.filter.ContextHeaderFilter
       </filter-class> 
    </filter> 
    <filter-mapping> 
       <filter-name>ContextHeaderFilter</filter-name> 
       <servlet-name>ContentServer</servlet-name> 
    </filter-mapping>
    
  3. On the target system, set the following property (located under the config folder):
    log.file.location=<path to Sites log file>
    

44.19 Exporting Assets to XML Publishing Method

The Export Assets to XML publishing method is a hybrid between the Export to Disk and dynamic publishing methods. Assets are rendered into files, but this publishing method uses the dynamic dependency calculation method rather than the method of Export to Disk publishing.

The Export Assets to XML publishing method differs from the other two in that it is really a data transformation method. While Export to Disk publishing creates one HTML file per page, which could mean that several assets are rendered into one file, Export Assets to XML creates one XML file for each asset that is approved to a destination configured to use this publishing method.

Export to Disk publishing creates Export to Disk files that are to be delivered from a Export to Disk WebCenter Sites delivery system. In contrast, Export Assets to XML creates XML files for delivery to a database or non-WebCenter Sites system.

When an Export Assets to XML publishing session runs, this is what happens:

  • On the source system, the approval system provides a list of the assets approved for this destination to Export Assets to XML.

  • Export Assets to XML renders each asset in the list to an XML file. The output file describes the asset, stating all the values for all of the asset's fields.

When you use the Export Assets to XML publishing method, typically you set up a quality assurance process to test the generated files before you move them to the external (non-WebCenter Sites) system.

The following topics provide information about exporting assets to XML:

44.19.1 Understanding the XML Output

The output from Export Assets to XML is well-formed XML that describes an asset object in terms of its field values. Fields are described as attributes.

For each of the asset's fields, there is a name/value pair. The statement of the value includes the data type of the field. For example, the Name field holds characters. So the name/value pair for an asset's Name field would appear as follows in the output:

<attribute name="Name">
   <string value="nameOfAsset"/>
</attribute>

Flex attributes serve as the fields for flex assets. In the output XML for a flex asset, the flex attribute values are prepended with Attribute_. Here's an example of an attribute value for the price of a sample site product asset:

<attribute name="Attribute_price">
   <decimal value="5.9"/>
</attribute>

Note that the XML output uses the column names rather than the field name of each field/attribute and that column names and field names can be different.

The following is a description of the XML file created by this publishing method, presented as a pseudo-dtd file:

<!-- ASSET:
-- ASSET defines an asset object
-- an asset is made up of attributes
-->
<!ELEMENT ASSET (ATTRIBUTE)*>
<!ATTLIST ASSET TYPE CDATA #REQUIRED>
<!ATTLIST ASSET ID CDATA #IMPLIED>
<!ATTLIST ASSET SUBTYPE CDATA #IMPLIED>

<!ELEMENT ATTRIBUTE (STRING | DATE | INTEGER | DECIMAL | BINARY | FILE | ASSETREFERENCE | ARRAY | STRUCT | LIST)>
<!ATTLIST ATTRIBUTE NAME CDATA #REQUIRED>

<!ELEMENT STRING>
<!ATTLIST STRING VALUE CDATA #REQUIRED>

<!ELEMENT DATE>
<!ATTLIST DATE VALUE CDATA #REQUIRED>

<!ELEMENT INTEGER>
<!ATTLIST INTEGER VALUE CDATA #REQUIRED>

<!ELEMENT DECIMAL>
<!ATTLIST DECIMAL VALUE CDATA #REQUIRED>

<!ELEMENT BINARY>
<!ATTLIST BINARY VALUE CDATA #REQUIRED>

<!ELEMENT FILE (CDATA) >
<!ATTLIST FILE NAME CDATA #REQUIRED>

<!ELEMENT FILE>
<!ATTLIST FILE NAME CDATA #REQUIRED>

<!ELEMENT ASSETREFERENCE>
<!ATTLIST ASSETREFERENCE TYPE CDATA #REQUIRED>
<!ATTLIST ASSETREFERENCE VALUE CDATA #REQUIRED>

<!ELEMENT ARRAY (STRING | DATE | INTEGER | DECIMAL | BINARY | FILE | ASSETREFERENCE | ARRAY | STRUCT | LIST)+>

<!ELEMENT STRUCT (FIELD)+>

<!ELEMENT FIELD (STRING | DATE | INTEGER | DECIMAL | BINARY | FILE | ASSETREFERENCE | ARRAY | STRUCT | LIST)+>
<!ATTLIST FIELD NAME CDATA #REQUIRED>

<!ELEMENT LIST (ROW)+>

<!ELEMENT ROW (COLUMN)+>

<!ELEMENT COLUMN ( STRING | INTEGER | DECIMAL | DATE | ASSETREFERNCE)>
<!ATTLIST COLUMN NAME CDATA #REQUIRED>

44.19.2 Understanding File Naming Conventions for Export Assets to XML

Exported XML files are named according to the following convention:

assetID.xml

For example, if the asset ID is 3344556677, the file name for the asset's XML file is:

3344556677.xml

The Export Assets to XML publishing method does not use any information that is entered in an asset's Path or Filename field.

44.20 Configuring Your System for Export Assets to XML

The main steps when configuring for the Export Assets to XML delivery type are as follows:

44.20.1 Creating the Batch User Account for XML Publishing (If One Does Not Exist)

Creating a batch user account is required before any type of publishing can take place. This procedure must be performed only one time, regardless of the number and types of publishing destinations you are creating.

If you have not done so, create the batch user account. For instructions, see Creating the Batch User Account (If One Does Not Exist).

If a batch user account exists for your installation, skip to Specifying the Root Export Directory.

44.20.2 Specifying the Root Export Directory

As mentioned earlier in this chapter, the directory to which exports files is determined by the cs.pgexportfolder property in the wcs_properties.json file.

To set the root directory for exported files:

  1. In the Admin interface, open the Property Management Tool. (For instructions, see Accessing the Property Management Tool in the Property Files Reference for Oracle WebCenter Sites.)
  2. In the Name field, enter cs.pgexportfolder.
  3. Click Search.
  4. Select the name of the property. In the Value field, set its value to the full path of the directory to which files should be exported. This is a global setting for the system.
  5. Click Save.
  6. Restart the application server.

    Note:

    Before you run an Export to XML publishing session, ensure this destination directory exists and that it has enough space for the XML files that will be created there.

44.20.3 Configuring an Export Assets to XML Destination

Next, create the Export to XML destination by completing the following steps:

  1. In the General Admin tree, expand the Admin node, expand the Publishingnode, and then expand the Destinations node.
  2. Double-click Add New.

    The Add New Destination form opens.

    Fill in the fields as described:

    • Name: Enter a unique name for the destination.

      Note:

      The following characters are not allowed in the Name field: single quote ('), double quote ("), semicolon (;), colon (:), less-than sign (<), greater-than sign (>), percent (%), and question mark (?). Additionally, the name cannot end with a backslash (\).

    • Delivery Type: Select Export Assets to XML: Export XML file for each asset.

    • Sites: Select the sites whose assets can be approved for and published to this destination.

    • Roles (Approve for Publish): Select the roles to which you are assigning asset approval privileges. All users who are assigned these roles can approve assets.

    • Roles (Publish): Select the roles to which you are assigning publish privileges. All users assigned these roles can publish.

  3. Repeat step 1 for each additional export destination that you must configure for your source system.

44.20.4 Approving Your Assets for XML Publishing

To perform a simple test of your configuration, select an asset and approve it and any of its dependent assets.

To complete a test publish of your entire site, approve all the assets for the site. See Approving Multiple Assets for help with approving many assets at one time.

44.20.5 Publishing and Testing the Results

After you have approved assets that can be published to your destination, you can run a test publishing session:

  1. On the source system, click Publishing in the button bar.
  2. In the Publish Console, select your destination from the drop-down list and then click Select Destination.

    displays information about the assets that are ready to be published to this destination.

  3. Click Publish.

    A confirmation message opens. Click Yes to proceed with the publish.

    exports all assets approved for this destination to files. The files are stored in the directory you specified earlier.

  4. In the Publish Console Active tab you can observe that the session is running.
  5. When the session completes, click the History tab to view the session summary for this session.

    Mouse over the session information to view summary information; click Log to view the session log files.

  6. The log file displays a list of all the resulting XML files; verify that the files are correct.

44.20.6 Setting Up the Schedule

After you have ensured that your destination is configured correctly, that the directory names are created according to your requirements, you can finish configuring your publishing system by completing the following steps on the source system:

  1. Create scheduled publish events for the destination. For help with this step, see Troubleshooting.
  2. Plan how you will move the generated files to your external, non-WebCenter Sites systems. For example, you can set up a regular FTP transfer that automatically moves files to a testing area after a publishing session completes.

44.21 Migrating a Site from One System to Another

During the development phase for your sites, your site designers and developers develop sites and asset types with the sites' supporting configuration (subtypes, associations, start menu items, and so on), code templates. They also assist the administrators in customizing the user interface, when necessary, by writing elements for workflow and so on. This work is done on the development system.

When the site is ready for the content providers, you can use the Mirror Destination Configuration feature to migrate it to both the management and the delivery systems.

This section covers the following topics:

44.21.1 Moving a Site from a Development System to a Management System

The first part of moving a site from development to management requires setting up the support tables, the users, and if used, managing the flex family on the management system. This portion of the process of moving should only be done once.

Complete the following procedure only one time:

  1. Log in to the Admin interface on the management (destination) system as the fwadmin user.
  2. If you have any custom support tables—a lookup table for a field in an asset type, for example—create those tables on the management (destination) system.
  3. On the management system, create all the users.
  4. On the source system, log in to the WebCenter Sites interface.
  5. Create a Publishing Destination for the destination system that uses the RealTime publishing method.

    For help with this step and the following two steps, see Configuring Your System for RealTime Publishing.

  6. Initialize the publishing destination.
  7. Configure the publishing destination.
  8. On the destination (management) system, configure the users for the site. For help with this step, see Granting Users Access to a Site (Assigning Roles to Users).
  9. If you created a flex family, log back in to the source system. Approve and then publish all of the data structure flex assets to the management (destination) system.

    You can either approve each asset individually or use the Approve Multiple Assets feature on the Admin tab. For information about this feature, see Approving Multiple Assets.

  10. Approve and then publish all of the rest of the appropriate assets for the destination system: template, page, collection, query, CSElement, and SiteEntry assets, and so on.
  11. If there are any elements or page entries in the SiteCatalog table that are not CSElement or SiteEntry assets, use CatalogMover to mirror those items to the management system. For help with CatalogMover, see CatalogMover in Developing with Oracle WebCenter Sites.

44.21.2 Moving a Site to a Delivery System

When you move a site to a delivery system, it is not necessary to mirror start menu items, workflow, saved searches, and so on.

To move a site to a delivery system:

  1. Log in to the Admin interface on the delivery (destination) system as the fwadmin user.
  2. If you have any custom support tables—a lookup table for a field in an asset type, for example—create those tables on the delivery (destination) system.
  3. On the source system, log in to the WebCenter Sites interface.
  4. Create a Publishing Destination for the destination system that uses the Mirror to Server publishing method.

    For help with this step, see Creating a Mirror Destination.

  5. Initialize the mirror destination.

    For help with this step, see Initializing the Destination.

  6. Configure the mirror destination.

    For help with this step, see Configuring the Mirror Destination.

    Do not select start menu items, saved searches, or any of the workflow options.

  7. If you created a flex family, log back in to the source system. Approve and then publish all of the data structure flex assets to the management (destination) system.

    You can either approve each asset individually or use the Approve Multiple Assets feature in the General Admin tree. For information about this feature, see Approving Multiple Assets.

  8. Approve and then publish all of the rest of the appropriate assets to the destination (delivery) system: template, page, collection, query, CSElement, and SiteEntry assets, and so on.
  9. If there are any elements or page entries in the SiteCatalog table that are not CSElement or SiteEntry assets, use CatalogMover to mirror those items to the management system. For help with CatalogMover, see CatalogMover in Developing with Oracle WebCenter Sites.
  10. If there are any images in the online site that are not assets, be sure to copy them to the delivery system.

44.22 Approving Multiple Assets

Each publishing destination has an option to Approve Multiple Assets. It is especially useful for upgrades and for the first publishing session to a destination.

Note that the Approve Multiple Assets feature is not the BulkApprover utility. The BulkApprover utility approves only those assets that have been imported into the WebCenter Sites database with the BulkLoader utility. Both BulkLoader and BulkApprover are described in About the BulkLoader Utility and Approving Flex Assets with the BulkApprover Utility in Developing with Oracle WebCenter Sites.

To approve a group of assets:

  1. In the General Admin tree, expand the Admin node, expand the Publishing node, expand the Destinations node, and then expand the destination to approve assets for.
  2. Under that destination, double-click the Approve Multiple Assets option.

    The Approve Assets form opens.

    Figure 44-18 Approve Assets for Publish to Destination Form

    Description of Figure 44-18 follows
    Description of "Figure 44-18 Approve Assets for Publish to Destination Form"
  3. In the Asset Types section, from the list on the left, select the asset types to approve.
  4. From the Sample Queries list on the right, select a query. If the exact query that you require is not present, select the query that is most like the one wanted.

    WebCenter Sites creates a SQL query based on the items that you selected and displays it in the Query box.

  5. (Optional) If necessary, edit the SQL query.
  6. Click in the Approve in Batches of field and enter a numeric value. The default is set to 500.

    Note:

    When you click the Approve for Publish button, the approval system approves batches of assets. The number of assets in each batch is determined by value in the Approve in Batches of field. Because the approval process is not a background process, it is possible that the browser session could time out while the batch is being approved.

    When using the Approve Multiple Assets feature, to ensure that the session does not time out, adjust the following settings:

    • The cs.timeout property in the wcs_properties.json file, which sets the browser session timeout value. Start by setting this value to 1800 (which means 30 minutes). (See Properties in the Core Category in the Property Files Reference for Oracle WebCenter Sites.)

    • The value you specify in the Approve in Batches of field. Start by using the default of 500 and lower it if necessary.

  7. Specify the Approve Previously Approved Assets option as follows:
    • If you want WebCenter Sites to ignore all previous approvals and re-approve all selected assets, select Yes. This is the option to use if previous approvals have become invalid for some change such as a change in default templates for that destination.

    • If you want WebCenter Sites to approve only the assets that have not yet been approved, select No. This is the correct choice when you are sure that previously approved assets are still valid.

  8. Click Approve for Publish.

44.23 Creating Destinations

The procedures for creating destinations are described in the previous section. For information about creating new destinations, use a procedure in the following list, as appropriate:

44.24 Editing Destinations

In some cases, after a publishing destination is created, it will need to be modified. The basic procedure for editing all types of publishing destinations is covered here.

To edit a destination:

  1. In the General Admin tree, expand the Admin node, expand the Publishing node, and then expand the Destinations node.
  2. Double-click the destination to edit.

    The Publish Destination form opens for the selected destination.

  3. Click the Edit icon, and then make the appropriate changes.

    For information about the values that can be entered in the fields in this form, see the delivery-type specific procedures in the previous sections:

44.25 Deleting Destinations

Destinations are easily deleted once they are no longer required for publication.

To delete a destination:

  1. In the General Admin tree, expand the Admin node, expand the Publishing node, and then expand the Destinations node.
  2. Double-click the destination to delete.
  3. Click the Delete icon.

    displays a verification message.

  4. Click Delete Destination.

44.26 Creating Export Starting Points

Export starting points are defined in Working with Export Starting Points. For information about creating them, see Creating the Export Starting Points.