Skip Navigation
Expand
Property Formatting Tutorial
Answer ID 8454   |   Last Review Date 10/14/2018

How do I use Formatting for string properties?

Environment:

Oracle Field Service (OFS), All versions

Resolution:

This document contains a short tutorial on how to use Property Formatting feature in Oracle Field Service.

The basic idea of formatted properties is:

If a checkbox "Formatting" is checked on property description page then:

  • Property is read-only in Oracle Field Service Core Manage/ Oracle Field Service Mobility.
  • Property is displayed in Oracle Field Service Core Manage/ Oracle Field Service Mobility according to formatting specified on property description page.
  • APIs may be used to set property value (e.g. Inbound API, Activity API or a "set_property" Message Step).

 Glossary - (Click  to expand this section.) 

XML - Is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable.

XML Document - A string that conforms to XML markup rules.

XSLT - "Extensible Stylesheet Language Transformations" - Is a language for transforming XML documents into other XML documents or other objects such as HTML for web pages

XPath - Xml query language. It is used to select portions of XML document that match a query. XPath is used by XSLT to select which parts of the document to transform. Example of using XPath in XSLT: <xsl:for-each select="//product/price" />. The following XSLT block will be executed for each "price" element that has a parent "product" element. XPath (in bold) is used to select elements matching patterns.

CSS - "Cascading Style Sheets" are used in for describing the look and formatting of a web page.

Regular Expression - Is a language that provides means to "match" (specify and recognize) a pattern in string of text.

Regular Expression Transformation - is a way to transform a string into another string using a regular expression and a transformation rule.

Identity Transformation - it is a transformation that does not modify the input data. It looks like f(x) = x, where f is identity transformation, basically this means that data is not changed by this transformation.

This is useful for example in these cases:

  • When the property value already contains XML, so regular expressions are not needed to produce XML
  • When the regular expression is enough to produce HTML, so that XSLT Transformation is not needed.
  • When the property value already contains valid HTML, so that no transformations are needed at all

Regular Expression Identity Transformation

/&lt;/ = <
/&gt;/ = >
/&amp;/ = &

These 3 lines unescape XML special characters which are escaped by Property Formatting engine.

XSLT 1.0 Identity Transformation
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
   <xsl:copy-of select="."/>
</xsl:template>




HOW PROPERTY FORMATTING WORKS

Whenever a property with Formatting enabled is to be displayed in Oracle Field Service Core Manage/ Oracle Field Service Mobility, our engine performs the following operations:

  • Get raw value of property - a string of data
  • Escape XML special characters: & to &amp; < to &lt; > to &gt;
  • Apply to escaped value all the Regular Expression Transformations to produce XML
*Note* if the resulting data is not a valid XML then property is not displayed
  • Put resulting XML into a root node named "<root>"
  • Apply to this XML the XSLT Transformation to produce HTML
*Note* if the XSLT Transformation is syntactically incorrect then property is not displayed
  • Strip "unsafe" HTML tags: <img>, <iframe>, <script>, <object>
  • Display the resulting HTML where the property should appear on the form


HOW TO CONFIGURE PROPERTY FORMATTING

  • Open "Company Settings -> Properties -> Your string property" (or "Add String Property")
  • Check "Formatting" checkbox
  • You will see two new fields:
    • Regular Expression
    • XSL Transformation


SETTING UP "REGULAR EXPRESSION" TO PRODUCE XML

The "Regular Expression" text area is multi-line. One or more regular expressions can be entered in this field, each on separate line. Each regular expression line must be of the following form:

{pattern} = {replacement}, e.g. /[0-9]+/ = <number>$0</number>
Where:
  • pattern - a regular expression
  • " = " - is an equals sign set between two spaces - "<SPACE>=<SPACE>". It is used to delimit regular expression and transformation rule.
  • replacement - transformation rule - a string describing how to transform the matching substring
*Note 1* The result must be an XML document

The purpose of regular expressions is to produce XML, because XSLT Transformation engine only accepts XML as input. So after the regular expressions are applied, the result must be an XML document.

*Note 2* Order of regular expressions matters

When there are multiple lines of regular expressions, each subsequent expression takes as input the output of previous expression, not the original string. Must take care to ensure that expressions do not conflict. See examples below for details.

 Example 1 - Simplest Regular Expression that produces XML 

Regular Expression Transformation:

/[0-9]+/ = <number>$0</number>

Above will find all numeric strings in the input value and replace put them into <number> XML tag. So, given input data like this: 12345 67890 1 22 333 4444, it will produce the following XML:

<root>
  <number>12345</number>
  <number>67890</number>
  <number>1</number>
  <number>22</number>
  <number>333</number>
  <number>4444</number>
</root>

(The XML above is formatted for clarity. Actual XML would be on a single line)

Note that the <root> parent element is added by OFS because a valid XML document must have a single root element.

 Example 2 - Multiple regular expressions 

When there are multiple lines of regular expressions, each subsequent expression is takes as input the output of the previous expression.

For example, given the input 123 ABC:

a) expression that replaces all alphabet characters with zeros:

/[A-Z]/ = 0, will produce: <root>123 000</root>

b) expression that replaces all number characters with X'es:

/[0-9]/ = X, will produce: <root>XXX ABC</root>

c) the 2 regular expressions combined:

/[A-Z]/ = 0 (making input for 2nd regular expression <root>123 000</root>)
/[0-9]/ = X, will p
roduce <root>XXX XXX</root>

d) but if the order is reversed:

/[0-9]/ = X (making input for 2nd regular expression <root>XXX ABC</root>)
/[A-Z]/ = 0, will produce <root>000 000</root>

 Example 3 - Capturing CSV spreadsheet into XML Document 

Suppose that the property value contains a CSV data - a spreadsheet with columns separated by commas, such as:

"Bananas","2.99","45"
"Appless","3.99","34"
"Oranges","6.99","22"

Expression that makes it into structured XML document is:

/"([^"]+)","([^"]+)","([^"]+)"/ = <product><name>$1</name><price>$ $2</price><number_in_stock>$3</number_in_stock></product>

The result of transformation:
<root>
 <product>
   <name>Bananas</name>
   <price>$ 2.99</price>
   <number_in_stock>45</number_in_stock>
 </product>
 <product>
   <name>Appless</name>
   <price>$ 3.99</price>
   <number_in_stock>34</number_in_stock>
 </product>
 <product>
   <name>Oranges</name>
   <price>$ 6.99</price>
   <number_in_stock>22</number_in_stock>
 </product>
</root>

(The XML above is formatted for clarity)



SETTING UP "XSLT TRANSFORMATION" TO PRODUCE HTML

The "XSLT Transformation" text area must contain a valid XSLT 1.0 document. Note that ETAdirect works with XSLT version 1.0 An XSLT document may contain several things:

  • HTML elements which will be displayed on the web page
  • Static text placed in HTML elements
  • CSS styles that define how HTML elements are displayed on the web page
  • XSLT constructs for transforming input XML document into HTML

Since we are using XSLT with no modifications, we will not describe XSLT language features in this document but will go straight to examples.

Example 1 - Simplest XSLT transform

This example will take a property which contains several numbers separated by spaces and display it as a list in Oracle Field Service. It will also use XSLT to calculate and display sum of these numbers.

Example property value: 1 2 3 4 5

Regular expression: /([0-9]+)/ = <item>$1</item>

XSLT Transformation:


<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
  <style> <!-- CSS styles -->
    div.example_style { background-color: yellow; border: 2px dashed; padding:6px; }
    div.example_style li {margin-left:20px;}
  </style>
  <div class="example_style"> <!-- HTML elements -->
    List of items  <!-- Static text -->
    <xsl:for-each select="//item">  <!-- XSLT constructs -->
       <li> <xsl:value-of select="."/> </li>
    </xsl:for-each>
    Sum of all items is: <!-- Static text -->
    <b> <xsl:value-of select="sum(//item)" /> </b> <!-- XSLT constructs -->
  </div>
</xsl:template>
</xsl:stylesheet>

Produces the following result on Activity Details screen in OFS Core Manage: 
Test Formatting shows: List of items > bullet list of numbers > Sum of all items is: 15

 Example 2 - Formatting property using only Regular Expression

This example will take a property which contains a color name and display it as a color bar.

Since regular expression is enough to do this, we will put Identity Transformation (see Glossary) into XSLT Transformation text area.

Example property value: red

Regular expression: /^(.*)$/ = <span style="color:$1;background-color:$1;border:2px solid black">----</span> ($1)

XSLT Transformation:  


<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 <xsl:template match="/">
   <xsl:copy-of select="."/>
 </xsl:template>
</xsl:stylesheet>

Produces the following result on Activity Details screen in OFS Core Manage:
Door color field displays in the color that was set.

Available Languages for this Answer:

Notify Me
The page will refresh upon submission. Any pending input will be lost.