Understanding the Publishing Process
Knowledge Prerequisites
Understanding the end-to-end publishing process is key in producing a successful custom implementation. The skill set needed to achieve this goal typically includes:
• Experience with Arbortext Publishing Engine administration and configuration, including the PTC Server connection to Windchill PDMLink.
• Experience using Arbortext Editor and developing stylesheets using Arbortext Styler.
• Experience developing and deploying specialized document type applications for Arbortext Editor and Publishing Engine, as well as how to use the application directory.
• Experience developing XSL transformation stylesheets.
• Experience using XPath expressions.
• Experience with Windchill PDMLink administration.
• Experience with Windchill Visualization Services (WVS) and Worker Agent administration.
• Experience writing WVS publishing rules.
Publishing Prerequisites
The installation, setup, configuration and operation of the following needs to be working successfully before proceeding with custom implementations:
• Arbortext Publishing Engine must be installed and configured on a supported Windows server.
Instructions for installing and configuring Arbortext Publishing Engine are in the Installing Arbortext Publishing Engine and Configuring Arbortext Publishing Engine guides, part of the Arbortext Publishing Engine Help Center documentation.
• The Windchill WVS connection to the Arbortext Publishing Engine server must be configured in the Windchill file wvssis.properties.
Instructions for setting up the server connection from Windchill are in Configuring Windchill Service Information Manager and Windchill Service Parts, part of the Windchill Service Information Manager documentation available from this Help Center and the PTC Reference Documents site at:
Choose Browse Documentation to access the links.
• The Arbortext Publishing Engine server must have the Service application com.ptc.arbortext.service installed and enabled. By default, it’s located in the Arbortext Publishing Engine application directory. The Service application manages the initial transformation of the input XML document being prepared for publishing.
• The Arbortext Publishing Engine server must have a document type installed and enabled for handling the publishing output. By default, a sample is located in the Arbortext Publishing Engine application directory. The Technical Information DITA document type application com.ptc.arbortext.techinfo is a working sample of such a document type that is distributed with Arbortext Publishing Engine.
• The PTC Server connection to Windchill must be configured on the Arbortext Publishing Engine server to allow the Arbortext Publishing Engine server to retrieve objects from Windchill.
Instructions for setting up the PTC Server connection are in the Arbortext Content Management Guide, part of the Arbortext Publishing Engine documentation.
• A SIS Worker must be configured on Windchill PDMLink so WVS can manage publishing requests sent to Arbortext Publishing Engine from information structures, publication structures, and parts lists.
Instructions for setting up the SIS Worker are in Configuring Windchill Service Information Manager and Windchill Service Parts, part of the Windchill Service Information Manager documentation.
• WVS Publish Rules must be set up on Windchill PDMLink so users can choose a publishing rule and WVS can send the associated publish parameters to Arbortext Publishing Engine. Publishing rules must have a clear name and description to distinguish them to the user.
Instructions for setting up publishing rules are in the Configuring Windchill Service Information Manager and Windchill Service Parts, part of the Windchill Service Information Manager documentation.
• A publication structure, information structure, and, optionally, a parts list should be defined in a service product. General WVS publishing must be operational before using publishing actions.
Publishing actions are documented in this Help Center.
• A published representation in a specified output format can be created using the Publish Representation menu action item, shortcut menu, or toolbar button. The user specifies the publication name, description, and possibly a WVS publishing rule as well. The output type and various publishing parameters are designated by the WVS publishing rule or the user’s choice in the case of parts lists.
• Publish Representation enables publishing a bundle for Arbortext Content Delivery. Bundle publishing produces a file called a bundle that is used as input to Arbortext Content Delivery. The bundle is placed on the Arbortext Publishing Engine server in a destination directory where Arbortext Content Delivery can find it. The bundle publishing process does not return a bundle to Windchill, but it does return information about the bundle publishing operation.
• The WVS publishing rules file must have defined SIS Worker parameters to control the publishing process. The parameters and examples are explained in
Service Worker Parameters.
Service Information Publishing Workflow
The basic workflow of publishing from a service product structure follows this process:
1. When a publishing action is triggered from a publication structure, an information structure, or a parts list, several files are generated, zipped, and sent by WVS in a file called a payload to the Arbortext Publishing Engine server. The number and type of files are specific to the structure, its content, specified output, and publishing specifications for the publishing job being requested.
2. Windchill Service Information Manager creates a generalized XML document from the structure to send to the Arbortext Publishing Engine server.
You need to understand this generalized XML format to successfully transform the input XML document into a format that complies with the structure of your document type. An XSLT transformation stylesheet is provided as part of the Service application processing. This XSLT stylesheet is specified using one of the parameters in the WVS publishing rule.
3. The WVS Publish Rule specifications are converted to a publishing specification file, which is sent to the Arbortext Publishing Engine server in the payload. Its parameters are applied during the publishing process.
4. Objects referenced by the input XML document, such as graphics, are sent to Arbortext Publishing Engine as part of the payload, or they can be retrieved using the PTC Server connection to Windchill PDMLink. The choice is determined by a SIS Worker parameter.
5. The input XML document, publishing specification, and referenced objects (if necessary) are all zipped into a payload file, along with a manifest XML file describing the payload's contents.
The payload is then sent as a POST type of HTTP request to the Arbortext Publishing Engine server for processing, using an f=acl function call that is handled by the Service application.
6. The Service application contains XSLT stylesheets that transform the generalized XML input document into a form that complies, by default, with the sample distributed DITA document type, an illustrated parts list, or a Arbortext Content Delivery bundle.
7. A document type must be installed on the Arbortext Publishing Engine server that can take the interim document from the Service application and produce published output or a bundle.
The Technical Information sample specialized DITA document type is distributed on the Arbortext Publishing Engine server. By default, it processes the content and markup generated by the default Service application and can produce the output according to the publishing specification.
The Technical Information application is designed for writing and publishing information about service operations and parts as a working document type sample. Any customer document type would need to emulate the features and actions built into the Technical Information application.
8. After the payload is received by the Arbortext Publishing Engine server, the request is directed to and then processed by an Arbortext Publishing Engine sub-process.
The publishing specification must specify the XSLT transformation stylesheet that converts the generalized input XML document into markup that complies with the designated document type. The XSLT needs to specify this output document type.
9. The publication structure, information structure, or parts list input XML is transformed to a map structure by the Service application. If the structure references a parts list, the parts list is transformed into a separate XML format called Illustrated Part Definition (IPD). If only a parts list is input, it’s placed in a wrapper publication structure XML file that references the parts list, which is transformed as though it were actually referenced by a publication structure.
10. The Arbortext Publishing Engine sub-process puts the document through pipeline filters specific to the output document type, and then styles and publishes output according to the specified stylesheet (using APP as specified by the Arbortext Styler stylesheet).
11. The Arbortext Publishing Engine server gathers the published output (or an error message if one is generated instead), the composer log (in both XML and HTML formats), and a manifest identifying the output type, the process ID, the transaction ID, and the Arbortext Publishing Engine server name and IP address, and then it zips these files into a response file. The response zip is returned to the SIS Worker. If the output is a bundle, the bundle is not included in the response file, but the information about the path to the bundle is included. The bundle remains on the Arbortext Publishing Engine server in the destination directory awaiting further action by Arbortext Content Delivery.
12. The SIS Worker delivers the returned response zip file to WVS.
13. WVS either provides a link to the zip containing the representation from the Representations tab. If the representation includes a PDF, you can configure a post-publish delegate to extract the PDF and check it in as a representation in Windchill PDMLink.