Views¶
The views
service allows creating and maintaining views, which are XML files configuring how Transactions and Workflow Tasks can be searched and how the results are organized and displayed.
In a view, you can add, update, specify and sort the searchable fields that will be displayed in the Search Panel and viewable fields that will constitute the columns of the data grid displaying the results of the search.
Sample display
For more information about the user interface, read the guide Views user interface.
Header fields¶
<View>
<DataType>TransactionInfo</DataType>
<DataModel>TransactionInfo</DataModel>
<DataPartition>TRANSACTION</DataPartition>
<ReprocessRouteUri>direct:p6router.p6_demo_Dispatcher</ReprocessRouteUri>
DataType, DataModel and DataPartition¶
The DataType
tag defines the type of item to be viewed.
The DataModel
tag is where the data model of the item to be viewed is referenced.
The DataPartition
will normally be TRANSACTION
(for transactions and workflow tasks). It could potentially also be LOGS
or TABLE_DATA
(if there was a need to show logs or table data as transactions).
Reprocess Route URI¶
Static¶
To allow the Transactions user interface to reprocess transactions using the P6route component, you must add the endpoint URI of the route definition to send the transaction for re-evaluation.
This is done using the element ReprocessRouteUri
in the XML configuration.
Example
<View>
<Name>Transactions</Name>
<Description>
<EN>Transactions</EN>
</Description>
<DataType>TransactionInfo</DataType>
<DataModel>TransactionInfo</DataModel>
<ReprocessRouteUri>direct:p6router.Hub</ReprocessRouteUri>
</View>
Dynamic¶
If you need a dynamic reprocess route URI you can provide inside the element ReprocessRouteIdentifier
the id of the script to be executed.
The arguments passed to the script are:
pk
: the primary key of the transactiontransaction
: the XML representation of a transaction
In response the script should write inside the pipeline the variable reprocessRouteUri. If the variable is not found, the reprocess will be skipped.
Example
<View>
<Name>Transactions</Name>
<Description>
<EN>Transactions</EN>
</Description>
<DataType>TransactionInfo</DataType>
<DataModel>TransactionInfo</DataModel>
<ReprocessRouteIdentifier>p6_demo.redirectHub</ReprocessRouteIdentifier>
</View>
import groovy.json.*;
def xmlSlurper = new XmlSlurper()
def pk = p6.transaction.getPKUsingPipelineRequest()
def transactionInfo = xmlSlurper.parseText(p6.pipeline.get("transaction"))
if(transactionInfo.TransferProtocol != 'Blockchain') {
p6.pipeline.put('reprocessRouteUri', 'direct:p6router.' + pk.dataType)
}
Key(s)¶
You may define the keys of the items the view will handle.
<ListOfKeys>
<Key>
<Name>Id</Name>
<Description>
<EN>Id</EN>
<FR>Id</FR>
</Description>
<XPath>TransactionInfo/Id</XPath>
</Key>
</ListOfKeys>
Searchable fields¶
To customize the behavior or the Transactions and Workflow Tasks UI search behavior, you need to edit the view XML definition.
Example of a searchable configuration
<View>
<ListOfSearchables>
<Searchable>
<Name>TechnicalStatusCode</Name>
<Description>
<EN>Technical Status Code</EN>
<FR>Code Statut Technique</FR>
</Description>
<XPath>TransactionInfo/TechnicalStatusCode</XPath>
<Type>String</Type>
<Default>Error</Default>
<Choice>Acknowledged, Error, Missing attachment(s), Sent</Choice>
</Searchable>
</ListOfSearchables>
</View>
Note
All possible statuses shall be listed in the searchable definition, as a multi-choice field.
For example, the TechnicalStatusDate should be set as a searchable, so users can search all transactions with a Technical Status updated at a particular date or during a period.
Note
By default, every Searchable is supposed to be indexed. If you want to disable that feature
for a specific Searchable just add the indexed="false"
attribute to the Searchable
node.
Optimisation
You can improve views performances by using the generated columns migrating from XPath
to Column
.
Display of the fields¶
Searchable fields shall be ordered in a way that combines logic and efficient Portal display (multi-choice searchable fields shall be either on the same row or in the first column(s) of a row).
Example of inefficient Portal display
The first two search fields are not stacked upon one another.
<XPath>
¶
The XPath used to evaluate the search of the XML document.
If the <Type>
isWords
and the <XPath>
element is repeated the underlying search logic will be changed from an AND to an OR.
For example:
... AND ( xpath1 CONTAINS "Error" OR xpath2 CONTAINS "Error" ) AND ...
<Column>
¶
Since 6.9.6
Instead of reading the xml using the XPath
you can directly define the name of the column
.
Note
Before updating the view, a manual operation on the database is required to create the corresponding columns.
Example
ALTER TABLE p6core.transaction
ADD COLUMN creationDate TEXT GENERATED ALWAYS AS (
CASE WHEN datatype = 'TransactionInfo' THEN
array_to_string_i(xpath('/TransactionInfo/CreationDate//text()', content)::text[], ' ')::text
END
) STORED;
CREATE INDEX transaction_transactiondate_index ON transaction (creationdate);
ALTER TABLE p6core.transaction
ADD COLUMN orgPath text[] GENERATED ALWAYS AS (
CASE WHEN datatype = 'TransactionInfo' THEN
xpath('/TransactionInfo/OrgPath//text()', content)::text[]
END
) STORED;
CREATE INDEX transaction_orgPath_index ON transaction (orgPath);
Since 6.9.8
The xpath
attribute must be set on the <Column>
if a permission set is based on it
Permission set
transactions=allow('ViewName'('TransactionType'='Invoice'))
Searchable
<Searchable>
<Name>TransactionType</Name>
<Column xpath="/TransactionInfo/TransactionType">transactionType</Column>
</Searchable>
Tip
You can also update your stored procedures
based on transaction XPath to use the generated column instead.
If needed you can also create new columns using the same way.
<Type>
¶
The available types are:
Words
RangeOfDates
String
CaseInsensitiveString
OrgPath
Flags
Padding
InList
AssigneeList
( Since 6.9.2)
Details of the behaviour of each searchable type can be found here
Translation¶
Since 6.9.9
On the <Type>
node you can add an i18n
attribute
to automatically translate the displayed value according to the user preferences.
<Searchable>
<Name>TransactionType</Name>
<Description>
<EN>Transaction Type</EN>
<FR>Type de transaction</FR>
</Description>
<XPath>TransactionInfo/TransactionType</XPath>
<Type i18="View.transactionTypes">String</Type>
<Choice>Order, Purchase Order, Invoice</Choice>
<DisplayChoice>Order, Purchase Order, Invoice</DisplayChoice>
</Searchable>
View.transactionTypes=Commande, Bon de commande, Facture
Warning
This feature is only available for <Choice>
to translate list values.
Choice values are displayed using the priority order:
- from the translation (according to
i18n
attribute) - from
<DisplayChoice>
- from
<Choice>
Tip
The i18n
attributes supports the ~
prefix.
It will be replaced automatically by ViewConfiguration.<name>
where name is the curent view name.
<Type i18n="~searchable.transactionTypes">String</Type>
ViewConfiguration.TransactionInfo.searchable.Invoice=Commande, Bon de commande, Facture
If the view belongs to an application (ie. O2C) the translations will be first searched on
ViewConfiguration.TransactionInfo.searchable.Invoice=Ma commande, Mon bon de commande, Ma facture
<Default>
¶
This is a default String value that will be placed in the search field. This value is only a default and can be modified or over-typed.
<Choice>
¶
This element contains a comma separated list of possible String values.
The presence of this element causes the text input field to be changed into a combo box control with the given <Choice>
values as options.
An empty value (just a comma) is often useful to allow the field to be set to blank or null.
Note
By default the combo box control is editable.
Select multi items¶
Using additional attributes it is possible to change the standard <Choice>
combo box control to a multi-select list control.
This control will allow multiple items to be selected or de-selected.
Often when multiple items are selected, the server processing will require them to be delimited with certain characters.
By default items will be delimited with commas.
More typically for systems with PostgreSql databases the delimiter character should be the pipe |
.
For example:
<Searchable>
<Name>TechnicalStatusCode</Name>
<Description>
<EN>Technical Status Code</EN>
<FR>Code Statut Technique</FR>
</Description>
<XPath>TransactionInfo/TechnicalStatusCode</XPath>
<Type>Words</Type>
<Choice multi-select="true" multi-select-delimiter="|">Acknowledged, Error, Missing attachment(s), Sent</Choice>
</Searchable>
Display a list of choices¶
When you need to display a list of choices but want to be more descriptive in the list displayed to the user, this element can be used in addition to the <Choice>
element.
This comma delimited list contains a display value that corresponds to the query value contained in the <Choice>
list.
For example:
<Searchable>
<Choice multi-select="true">SNT,REC,ACK,PEND,</Choice>
<DisplayChoice>Sent Invoices,Received Invoices,Acknowledged Invoices,Pending Invoices</DisplayChoice>
</Searchable>
This will show a multi select choice as follows:
Disallow the typing of custom values¶
This applies to the none multi-select choice: the combo box control. By default this control is editable. This means that a user can type an additional value for inclusion in a query.
Adding the <Choice>
attribute editable="false"
will ensure that only those values present in the <Choice>
list are selectable.
Restrict the height¶
By default a multi-select <Choice>
will size itself to an 3-line height.
To restrict the height of a multi-select <Choice>
input cell, add the field-line-height="xxx"
attribute.
Where xxx
is the number of lines to display in the field.
Warning
The user could scroll the multi-select-list to access all available values.
Viewable fields¶
To customize the search response format, you need to edit the view XML definition.
Example of a viewable configuration
<View>
<ListOfViewables>
<Viewable>
<Name>LoadDate</Name>
<Description>
<EN>Load Date</EN>
<FR>Date de création</FR>
</Description>
<XPath>TransactionInfo/CreationDate</XPath>
<Type>Date(yyyyMMdd'T'HH:mm:ss.S z)</Type>
<Display>
<hidden>true</hidden>
<textAlign>right</textAlign>
<textColor>red</textColor>
<columnWidth>250</columnWidth>
</Display>
</Viewable>
</ListOfViewables>
</View>
<Description>
¶
Fields that are both searchable and viewable may have different descriptions to accommodate column width. For example, description may be Document Type as searchable but only Doc. Type as viewable, same with Document Number vs. Doc. Number.
<Type>
¶
This is a display type inference that is used by a user interface to render the viewable
Supported types are:
- Date([format]) : a JDK date format string. E.g.
yyyy-MM-dd'T'HH:mm:ss.S z
- String : a text string
- Number : a number
- ReferenceString : text to be used as reference only and not displayed
- URI : a URI
- Flags : transaction flags (see below)
- I18nStringMap : an i18n Map of Strings
- ItemLink : a link to a transaction (see below)
- WorkflowStep : details of any workflow step that created this transaction
- Button : a button)
- Group : a column to group buttons ( Since 6.9.0)
Types may also use the following attributes:
- hidden : available to the user interface but not to be displayed
- exportable : available to the user interface but not to be exported
Note
By default fields are exported, except for types WorkflowStep
and Button
unless you set the exportable
attribute to another value
Button type may also use the following attributes:
- allowMultiAction : allow multiple action on the contextual menu
- multiActionIcon : multiple action icon classname
Translation¶
Since 6.9.9
On the <Type>
node you can add an i18n
attribute
to automatically translate the displayed value according to the user preferences.
<Viewable>
<Name>TransactionType</Name>
<Description>
<EN>Transaction Type</EN>
<FR>Type de transaction</FR>
</Description>
<XPath>TransactionInfo/TransactionType</XPath>
<Type i18n="View.transactionType">String</Type>
</Viewable>
View.transactionType.Invoice=Facture
View.transactionType.Order=Commande
Tip
The i18n
attributes supports the ~
prefix.
It will be replaced automatically by ViewConfiguration.<name>
where name is the curent view name.
<Type i18n="~viewable.transactionType">String</Type>
ViewConfiguration.TransactionInfo.viewable.transactionType.Invoice=Facture
ViewConfiguration.TransactionInfo.viewable.transactionType.Order=Commande
If the view belongs to an application (ie. O2C) the translations will be first searched on
ViewConfiguration.TransactionInfo.viewable.transactionType.Invoice=Ma facture
ViewConfiguration.TransactionInfo.viewable.transactionType.Order=Ma commande
URI¶
URI type may also use the following attributes
-
filename : xpath to retrieve the filename ( Since 6.9.4)
Example
<Viewable> <Name>Attachment</Name> <Description> <EN>Attachment</EN> </Description> <XPath>TransactionInfo/Attachments/Attachment[1]/URI</XPath> <Type filename="TransactionInfo/Attachments/Attachment[1]/FileName">URI</Type> </Viewable>
Tip
If no
filename
attribute is set in theType
node, the file name of the URI will be used
Date¶
Reading
Dates are stored inside documents according to a format (cf. p6.service.views.default.date.format
).
The format can be overridden to a specific one using the format
argument of the Type.
Example
<Type>Date(yyyy-MM-dd'T'HH:mm:ss.S z)</Type>
Warning
This format is used to read the date from the document.
Tip
If the date format is a match to the one defined in the configuration you can use the short syntax
<Type>Date</Date>
Displaying
Dates are by default displayed according to a format (cf. p6.service.views.default.date.displayFormat.default
).
The format can be overridden to a specific one using the type attributes with the following priority:
- displayFormat_
locale
- displayFormat
If no display format matching the locale
is found, the default format will be used.
Case sentive
The locale
must be written in lowercase
Example
Override the default format from configuration
<Type displayFormat="yyyy-MM-dd">Date</Type>
Override the format only for locale english
<Type displayFormat_en="yyyy-MM-dd">Date</Type>
Define format for french and english plus a fallback for unknwon locales
<Type
displayFormat_fr="dd-MM-yyyy"
displayFormat_en="yyyy-MM-dd"
displayFormat="yyyyMMdd"
>Date</Type>
Tip
You can globally define the locale
based display format. Update your configuration according to the following example.
Example
p6.service.views.default.date.dispkayFormat.fr: "dd-MM-YYYY"
If the date display format is a match to the one defined in the configuration you can use the short syntax
<Type>Date</Date>
I18nStringMap¶
This type is used to display localised strings. To use this feature, you must:
Update your view to use the I18nStringMap
.
<Viewable>
<Name>statusName</Name>
<Description>
<EN>Status name</EN>
<FR>Nom du status</FR>
</Description>
<XPath>/TransactionInfo/StatusNames/*</XPath>
<Type>I18nStringMap</Type>
</Viewable>
Warning
Take care to the syntax of the XPath
it must end with /*
to match the sub-nodes.
Update the data model referenced by your view, <DataModel>
node, to allow new nodes (i.e. StatusNames)
<xsd:element maxOccurs="1" minOccurs="0" name="StatusNames" nillable="false">
<xsd:complexType abstract="false" mixed="false">
<xsd:sequence maxOccurs="unbounded" minOccurs="0">
<xsd:any maxOccurs="1" minOccurs="1" namespace="##any" processContents="lax"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
Update the process generating the transactions to add a new section
<TransactionInfo>
...
<StatusNames>
<EN>To be payed</EN>
<FR>A payer</EN>
</StatusNames>
</TransactionInfo>
If the transaction service is not able to retrieve the translated string (wrong xpath or missing data) [N/A]
will be displayed instead in the column.
Note
Do not forget to restart the datamodel, views and then transactions after doing your modifications.
<Column>
¶
Since 6.9.6
Same as the searchables, instead of reading the xml using the XPath
you can directly define the name of the column
.
Refer to Column to build the columns
Warning
Column
is not compatible with the types: I18nStringMap
, ItemLink
and WorkflowStep
<Display>
¶
This is how should be displayed a viewable in a grid. The Display
node is optional.
Supported and optional sub nodes are:
- hidden : Hidden column - default is the Type hidden attribute or “false”
- textAlign: Text alignment (left, center, right) - default is “left”
- textColor: Text color - default is “#3a3a3a”
- columnWidth : Column width (in pixels) - default is “150”
- disableSort : Disable sort on column - default is “false”
- disableClick : Disable click on column - default is “false”
- group : The name of the grouping column ( Since 6.9.0)
Example of a display configuration
<View>
<ListOfViewables>
<Viewable>
...
<Display>
<hidden>true</hidden>
<textAlign>right</textAlign>
<textColor>red</textColor>
<columnWidth>250</columnWidth>
<disableSort>true</disableSort>
<disableClick>true</disableClick>
</Display>
</Viewable>
</ListOfViewables>
</View>
Example of a grouping configuration
<View>
<ListOfViewables>
<Viewable>
<Name>Actions</Name>
<Description>
<EN>Actions</EN>
<FR>Actions</FR>
</Description>
<Type>Group</Type>
</Viewable>
<Viewable>
<Name>Pay</Name>
<Description>
<EN>Pay</EN>
<FR>Payer</FR>
</Description>
<Type key="buttonPay">Button</Type>
<Display>
<group>Actions</group>
</Display>
</Viewable>
</ListOfViewables>
</View>
Item links¶
It is possible to create Item links, i.e. the ability to navigate between specific transactions (items, technically speaking) in the Transactions Portal UI.
Once a link is created, a View button is automatically displayed in the transactions list and clicking on the button will open the linked message.
In the transaction you want to link from, create an XML element containing the details of the transaction you want to link to, for instance:
<itemlink>
<view>Customer Portal</view>
<id>Invoice_Z5931030123_64711a55-f8ed-4919-abbb-2f2961ee8725</id>
</itemlink>
The name of the XML element, itemlink
in the example above, does not matter, however this element must contain at least:
- one view element which contains the name of the view which will be used to fetch and display the linked transaction
- one or more id elements which contain the linked transaction ids
The XML configuration of the view of the transaction you link from must contain a viewable of type ItemLink with an XPath pointing to the XML element above.
<Viewable>
<Name>itemLink</Name>
<Description>
<EN>Transaction</EN>
<FR>Transaction</FR>
</Description>
<XPath>/TransactionInfo/itemlink</XPath>
<Type>ItemLink</Type>
</Viewable>
Flags¶
The XML configuration for the view supporting flags must be updated with a new viewable of type Flags:
<Viewable>
<Name>Flags</Name>
<Description>
<EN>Flags</EN>
<FR>Flags</FR>
</Description>
<XPath>TransactionInfo/Flags</XPath>
<Type>Flags</Type>
</Viewable>
For a transaction to be flagged, the XPath in the viewable must exist in the XML of the transaction.
Thus, to flag existing transaction, all transactions will need to be first reprocessed to insert the appropriate element with an empty JSON Object as value {}
, so that they can be flagged.
Here is the list of flags and their corresponding names:
- The
eunread
flag indicates that the item is unread. If this flag is set totrue
, it means the item has not been read yet. - The
dwarning
flag indicates that the item has a warning associated with it. If this flag is set totrue
, it means there is a warning for this item. - The
cimportant
flag indicates that the item is important. If this flag is set totrue
, it means the item is considered important. - The
binfo
flag indicates that the item contains additional information. If this flag is set totrue
, it means there is additional information for this item. - The
aok
flag indicates that the item is in good condition. If this flag is set totrue
, it means the item is in good condition. - The
aavisible
flag indicates whether the item is archived or not. If this flag is set tofalse
, it means the item is archived.
Note
As shown below, each flag has his own associated icon.
When flags are used in the Viewables
a new icon is available inside the Actions
column.
Clicking on it will show a menu allowing the user to set/unset the flags for the transaction.
Storage structure
These flags are stored in a JSON object, where the flag is used as the key and the boolean value indicates whether the flag is set or not.
For the aavisible
flag, the logic is inverted, so a value of false
means the flag is set.
Examples:
{"aavisible": true, "eunread": false}
: Visible and read{"aavisible": true, "dwarning": true, "eunread": true}
: Visible, Warning and unread
Warning
There is no automatic mechanism to mark a transaction as read when it’s opened.
It has to be done inside the View_<viewName>
script using the method p6.transaction.updateFlags
(see examples)
or manually by manipulating the transaction XML.
Transformers¶
Since 6.9.9
A new mechanism to translate the view and the transactions named Transformers
is introduced.
<View>
<Searchables/>
<Viewables/>
<Transformers>
<Transformer mode="search">
<Content type="xpath" i18n="path.to.key" key="true">//path/to/node</Content>
</Transformer>
<Transformer mode="view">
<Content type="xslt"><![CDATA[model]]></Content>
</Transformer>
</Transformers>
</View>
Transformers
are applied accordingly to their definition order
Modes¶
A Transformer
has one of the two modes
search
- When displaying the search panel (Searchables)view
- When displaying a transaction (html parts)
Note
The search
mode is by default disabled.
If the i18n
attribute is not sufficient for handling the translation,
you can set the configuration entry p6.service.views.i18n.transformers.search.enabled=true
to enable the transformers on the search.
Types¶
A Transformer
has one of the two types
xpath
- Will perform the XPAth resolution and replace the content with the translationxslt
- Will perform the XSLT transformation
XPath¶
<Transformer mode="view">
<Content type="xpath" i18n="path.to.key">//path/to/node</Content>
</Transformer>
If the xpath
resolution of the node //path/to/node
equals value
, then the following translation will be searched
path.to.key.value=Translation
Tip
An optional key="true"
can be used in combination of the i18n
attribute.
Instead of using the node value as a key, the i18n
value will be used as the translation key.
path.to.key=Translation
Example
<View>
<Searchable>
<Name>TransactionType</Name>
<DisplayChoice>Order, Purchase, Invoice</DisplayChoice>
...
<Searchable>
<viewable>
<Name>TransactionType</Name>
<Type i18n="transactions.type">String</Type>
<Column>transactionType</Column>
...
<Searchable>
<Transformers>
<Transformer mode="search">
<Content type="xpath" i18n="transactions.types" key="true">//Searchable[Name = "TransactionType"]/DisplayChoice</Content>
</Transformer>
<Transformers>
</View>
transactions.types=Commande, Bon de commande, Facture
transactions.type.Order=Commande
transactions.type.Purchase=Bon de commande
transactions.type.Invoice=Facture
Tip
Look at the i18n
attribute on the searchable for an easy translation mode.
XSLT¶
<Transformer mode="view">
<Content type="xslt">
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:p6="http://platform6.io" exclude-result-prefixes="p6">
<xsl:output omit-xml-declaration="yes" indent="yes"/>
<xsl:strip-space elements="*"/>
<xsl:param name="locale" />
<xsl:template match="node()|@*">
<xsl:copy>
<xsl:apply-templates select="node()|@*"/>
</xsl:copy>
</xsl:template>
<xsl:template match="//TransactionInfo/Status/text()"><xsl:value-of select="p6:i18n(., $locale)"/></xsl:template>
</xsl:stylesheet>
</Content>
</Transformer>
The xslt defined in the Transformer
content node will be applied to the source XML (View definition or Transaction content based on the mode
).
In the XSLT you can use the locale
variable, automatically filled from the user preferred language.
The new function p6:i18n
method can also be used to perform the translation using the global mechanism.
Warn
If the p6:i18n
method is used, dont forget to define the xmlns:p6="http://platform6.io" exclude-result-prefixes="p6"
in the Xslt definition.
XSD validation¶
The structure of the XML is checked using a XSD.
To help you develop your application you can use that XSD to validate the code in your IDE (ie. if you are using P6Sync). Simply add the attributes to the root element as shown bellow:
<View
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://doc.p6.sidetrade.io/latest/reference/built-in-services/views/views-guide/resources/View.xsd">
...
</View>
The documentation displayed in the XSD has been extracted from that page.