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

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 transaction
transaction: 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.

Searchable fields

`<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 (transactiondate);

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);

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

`<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.

Single select choice

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:

Multi select choice

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

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 the Type 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.

Item Link

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 to true, 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 to true, it means there is a warning for this item.
The cimportant flag indicates that the item is important. If this flag is set to true, it means the item is considered important.
The binfo flag indicates that the item contains additional information. If this flag is set to true, 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 to true, it means the item is in good condition.
The aavisible flag indicates whether the item is archived or not. If this flag is set to false, 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.

Viewable flags

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.

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.

Views¶

Header fields¶

DataType, DataModel and DataPartition¶

Reprocess Route URI¶

Static¶

Dynamic¶

Key(s)¶

Searchable fields¶

Display of the fields¶

<XPath>¶

<Column>¶

<Type>¶

<Default>¶

<Choice>¶

Select multi items¶

Display a list of choices¶

Disallow the typing of custom values¶

Restrict the height¶

Viewable fields¶

<Description>¶

<Type>¶

URI¶

Date¶

I18nStringMap¶

<Column>¶

<Display>¶

Item links¶

Flags¶

XSD validation¶

`<XPath>`¶

`<Column>`¶

`<Type>`¶

`<Default>`¶

`<Choice>`¶

`<Description>`¶

`<Type>`¶

`<Column>`¶

`<Display>`¶