Applicability in Publishing
Overview
XML topics can contain logical expressions to determine whether to include content at the element level. The markup that defines the options and choices that apply to some content is called inline applicability. The decision to include or exclude content is determined by evaluating this logical expression against the choices selected by the applicability filter at the time of publishing (or by the rootApplicabilityExpression parameter, if it is set in a publishing rule).
An applicability expression represents a subset of a product’s options and choices, which is used to annotate the content. The expression associates the content with a specific product or products, and it can then be used to filter it. Simple expressions can be combined using logical operators.
In the service structure user interface, you can set filtering for both the service structure and inline applicability for dynamic documents using the Filter action set on the toolbar of the Structure tab. Publishing applies the Option Filter to the publication structure and to its dynamic documents. If the publishing rule parameter rootApplicabilityExpression is set, it will overwrite the filtering expression defined using the Filter action set.
Inline applicability filtering is supported only for PDF and using XSL output types. In the case of bundle output, no filtering is applied during publishing as filtering is applied by a Servigistics InService user.
Applicability expressions need a parser that can decipher the options and choices expressions specified with intersecting and disjunctive operators such as AND, OR, and NOT.
About APEX
Windchill uses the ATO syntax to represent applicability expressions. When a bundle is published, depending on the publishing rule, applicability expressions are published in APEX format, that is usable by Servigistics InService. For more information on publishing rules, see the section Applicability Expressions in Bundles.
APEX is a syntax that is based on LISP programming language. The value of LogicalExpression property is the APEX applicability expression that is applied to a Windchill object. This property is available in the DMPmap.xml and hierarchy.xml file for a service structure and service product hierarchy respectively in a published bundle.
Use the following table to get a better understanding of the APEX expression grammar.
|
APEX Grammar Symbol
|
APEX expression grammar
|
|
expression
|
"(" expression-body ")" | constant
|
|
expression-body
|
polyadic-body | choice-body | function-body
|
|
polyadic-body
|
polyadic-op s expression expression-list
|
|
choice-body
|
"IS" s quote string-list
|
|
function-body
|
name string-list
|
|
expression-list
|
empty | s expression s expression-list
|
|
string-list
|
empty | s quote s string-list
|
|
S
|
" " | " " s
|
|
polyadic-op
|
"AND" | "OR" | "NOT"
|
|
constant
|
"TRUE" | "FALSE" | "UNKNOWN"
|
|
quote
|
' string '
|
Examples
|
|
You must define an assigned expression inside a parenthesis since the AND operator denoted by + takes precedence over the OR operator denoted by /.
|
Example 1:
An object in Windchill is assigned an expression where the Tire option is 155 or 145 and the Colour option is Black or Red. The ATO format is:
("155"/"145") + (Black/Red)
The corresponding APEX format is:
(AND (IS 'Tire' '155' '145') (IS 'Colour' 'Black' 'Red')
Example 2:
An object in Windchill is assigned an expression where the release option is X-24 or X-26. For release X-24, the maintenance option can be M022 or M023. Then the ATO format is:
(“X-24” + (“M022”/”M023”) ) / ”X-26”
The corresponding APEX format is:
(OR (AND (IS 'release' 'X-24') (IS 'maintenance' 'M022' 'M023')) (IS 'release' 'X-26'))
Example 3:
A Windchill object is assigned an expression with a service effectivity as follows:
The family option is assigned X96 with context as K95 or K96 models. The service effectivity type is serial number with range set between 12000 to 13000. The APEX format for the above expression and service effectivity is:
(AND (IS 'family' 'X96') (IS 'model' 'K95' 'K96') (IS 'serialNo' '12000' '13000'))
Setting Up Stylesheets
If you want inline applicability expressions in the root service structure document Identfier.xml sent in the payload, you need to modify your pubstructXsl stylesheet so it copies applicability expressions from the Identfier.xml to the correct location in your output DITA map (such as topicref and topic elements).
Setting Up Publishing Rules
When creating publishing rules for PDF and XSL output, you should consider which publishing rule parameters to apply during publishing on the Arbortext Publishing Engine server. You can use the basic applicability publishing rule parameters to apply to both structures and inline content in dynamic documents. The following are preceded by com.ptc.arbortext.pe/:
• applicabilitySyntax
Specify the name of applicability syntax used for applicability expressions in the payload. Specify the name that was registered on the Arbortext Publishing Engine server using the applic::registerSyntax() ACL method. There is no default.
If a bundle is being published for use with Servigistics InService, and both the structures and their topics use ATO and the same source syntax, applicabilitySyntax is the only parameter needed for publishing bundles.
• rootApplicabilityExpression
Specify an applicability expression to apply to the entire service structure and its content during publishing. The expression syntax must match the syntax found in both the service structure and its XML textual content.
Applicability for inline dynamic documents is enabled or disabled using disableInlineApplicFiltering. Specify true (the default) to disable inline applicability, or specify false to enable it.
For more information on publishing rule parameters, see
Service Worker Parameters.
Implementing a Syntax Parser
Applicability syntax can take a basic form using labels from the Option Set, assuming the labels are unique choice names. Applicability expressions use operators to combine or discard choices. A parser is needed to evaluate the expression using a registered syntax.
To implement a new syntax parser, you need to use the following Java packages found on the Arbortext Publishing Engine server in lib\classes\applicability.jar:
• com.ptc.arbortext.applicability.expression
A Java package that contains interfaces to support applicability expression objects for filtering content with Options and Choices data. Options elements have a Name, Description, and a set of Choice elements. The Option and the Choice elements have a label attribute which is used in the user interface and in applicability expressions. The labels are expected to be unique within each Option Set.
• com.ptc.arbortext.applicability.representation
A Java package that contains interfaces to support applicability markup for elements, attributes, content, and processing instructions.
In the payload, the options and choices are included in the OptionsDefinition.xml file.
Registering the Applicability Syntax
You need to register your applicability syntax on the Arbortext Publishing Engine server using an ACL function before it can be used during publishing. Use the following registration function:
applic::registerSyntax(NAME, TEST_XPATH, EXPR_XPATH, PARSER_CLASS)
• NAME is the name of the applicability syntax.
• TEST_XPATH is an XPath boolean expression to check if there is an applicability expression for an element.
• EXPR_XPATH is an XPath expression that retrieves the applicability for a particular element.
• PARSER_CLASS is the class name of the parser for the applicability syntax.
An ATO parser is available on the server by default, registered as follows (ignore the line breaks):
applic::registerSyntax("ATO", "boolean(@*[namespace-uri() =
'http://arbortext.ptc.com/namespace/ATO'
and local-name() = 'applic'])",
"@*[namespace-uri() = 'http://arbortext.ptc.com/namespace/ATO'
and local-name() = 'applic']",
"com.ptc.arbortext.applicability.representation.ATOParser")
Applicability Expressions in Bundles
Applicability filtering is not performed during bundle publishing. Instead applicability expressions are converted into a format that can be applied in Servigistics InService.
Publication structure applicability is in the LogicalExpressionmetadata property. Applicability from topics is copied into the {http://arbortext.ptc.com/namespace/ATO}applic attribute and then converted.
The following inline applicability parameters apply to structures published to bundles:
• com.ptc.arbortext.pe.service/structureSourceApplicSyntax
Specify the name of the applicability syntax used for applicability expressions in the service structure. Specify the name registered by applic::registerSyntax on the Arbortext Publishing Engine server. If not specified, the value of applicabilitySyntax is used. If applicabilitySyntax is not specified, the default is ATO.
• com.ptc.arbortext.pe.service/structureTargetApplicSyntax
Specify the name of the applicability syntax used for applicability expressions after the service subsystem is finished processing. Specify the name registered by applic::registerSyntax on the Arbortext Publishing Engine server. If not specified, the value of applicabilitySyntax is used. If applicabilitySyntax is not specified, the default is ATO.
• disableStructureApplicabilityConverter
Specify whether to find and convert applicability expressions in a structure. Specify false, the default for bundles, to enable it. Specify true to disable. By default, it is disabled for PDF.
The following inline applicability parameters apply to topics published in bundles:
• com.ptc.arbortext.pe.service/topicCcfParam.sourceApplicabilitySyntax
Specify the name of the applicability syntax used for applicability expressions inside topics in the bundle. Specify the name registered on the Arbortext Publishing Engine server. If not specified, the value of applicabilitySyntax is used. If applicabilitySyntax is not specified, the default is ATO.
• com.ptc.arbortext.pe.service/topicCcfParam.targetApplicabilitySyntax
Specify the name of the applicability syntax used for applicability expressions inside topics after the service subsystem has finished processing. Specify the name registered on the Arbortext Publishing Engine server. If not specified, the value of applicabilitySyntax is used. If applicabilitySyntax is not specified, the default is APEX.
• com.ptc.arbortext.pe.service/topicCcfParam.disableApplicabilityConverter
Specify whether to find and convert applicability expressions in a topic. Specify false, the default, to enable it. Specify true to disable it.
Profiling Applicability Expressions
Information elements can have profiling that was applied when being authored. The profiling markup can be converted to an applicability expression using an applicability syntax. The profiling conversion is controlled by the boolean publishing parameter com.ptc.arbortext.pe.service/topicCcfParam.disableProfilingConverter.
For example, the following markup could be found in an XML document, where os and userlevel specify profiling:
<chapter os="Windows Vista;Unix" userlevel="Novice">
A publishing request that specified the APEX syntax as the applicability expression would convert the profiling information to the following markup:
<book xmlns:prf=http://arbortext.ptc.com/namespace/
applicability/profiling prf:syntax="APEX"
prf:optionSet="axdocbook">
<chapter prf:applic="(AND (IS 'os' 'Windows Vista' 'Unix')
(IS 'userlevel' 'Novice'))">
</chapter>
</book>
The namespace URI for prf at the top level specifies a profiling configuration. The namespace profiling attribute is specified by the com.ptc.arbortext.pe.service/topicCcfParam.profilingAttribute publishing parameter.
The prf:syntax attribute specifies the syntax of the expression. The prf:optionSet attribute specifies the document type for the profiling configuration file being used.
The prf:applic attribute is placed on the element containing the profiling markup and assigned the converted expression.
The original profiling attributes can be removed from information elements when publishing to a bundle using the com.ptc.arbortext.pe.service/topicCcfParam.removeProfilingMarkup publishing parameter.
In the publishing payload, the OptionsDefinition.xml file contains the list of profiling configuration option sets. For the previous example, the option set might look like the following:
<OptionSet container="axdocbook.pcf" token="_oset_axdocbook_pcf"
label="Operating System, User Level, Output Type, Security Level Options">
<Option label="os" token="_opt_axdocbook_os"><Name>Operating System</Name>
<Choice label="Windows XP" token="_ch_axdocbook_pcf_os_windows_xp">
<Name>Windows XP</Name></Choice>
<Choice label="Windows Vista" token="_ch_axdocbook_pcf_os_windows_vista">
<Name>Windows Vista</Name></Choice>
<Choice label="Windows 7" token="_ch_axdocbook__pcf_os_windows_7">
<Name>Windows 7</Name></Choice>
<Choice label="Unix" token="_ch_axdocbook_pcf_os_unix">
<Name>Unix</Name></Choice>
</Option>
<Option label="userlevel" token="_opt_axdocbook_pcf_userlevel">
<Name>User Level</Name>
<Choice label="Novice" token="_ch_axdocbook_pcf_userlevel_novice">
<Name>Novice</Name></Choice>
<Choice label="Typical" token="_ch_axdocbook_pcf_userlevel_typical">
<Name>Typical</Name></Choice>
<Choice label="Expert" token="_ch_axdocbook_pcf_userlevel_expert">
<Name>Expert</Name></Choice>
</Option>
</OptionSet>
For more information on the profiling publishing parameters, see
Service Worker Parameters.
