OneList data-driven User Interface design

OneList is designed to support flexible data content for display. The OneList task object has header and detail sections to hold hierarchical information of a workflow task. This is illustrated below:

Figure 5 - OneList User Interface Data Model

The OneList user-interface definition data model is described further below.

The model definitions

The OneList task definition:
{
Title: string,
Summary: string[],
Requestor: string,
RequestedDate: Date,
DueDate: Date,
Priority: string,
Status: string,
Sections: SectionElement[],
MetaData: Dictionary<string, string>
}
The SectionElement definition:
{
Title: string,
Summary: string[],
Value: string,
Sections: SectionElement[],
DataElements: DataElement[]
}
The DataElement definition:
{
Title: string,
Value: string,
}

Task header attributes

• Title – the task title;
• Summary – multi-line, summary information of the task;
• Requestor – the name of the requestor;
• RequestedDate – the requested date;
• DueDate – task due date;
• Priority – task priority specific to the source system;
• Status – task status specific to the source system.
• Sections – a recursive array of sections presenting drill-down levels of task detail
• MetaData – a dictionary of key-value to hold additional information required for OneList layout logic but not directly visible eg Escalated (Boolean) may be a property that is supplied and used in advanced formatting of the task and/or notification.

Task detail sections

Hierarchical information is represented in OneList using sections and sub-sections. A task can have one or many top level sections. Each section can have one or many child sections.
The section attributes are:

• Title – title of the section;
• Summary – multi-line text, section summary is optional and it is displayed when the section is collapsed;
• Value – optional, it is displayed aligned to the right when the section is collapsed;
• DataElements – the detail of the section;
• Sections – child sections.

Both DataElements and Sections can be empty in a section, in which case OneList only displays the title and summary of the section, and the section is not expandable.

Task actions

Task actions are configured in OneList and mapped back to the source system task IDs. When processing an Action in OneList, certain supplemental input may be required to be shown or provided. The definition of tasks in OneList is described below:
The Task Action definition:
{
Id: string,
Name: string,
Class: string,
IsQuickAction: bool,
SupplementalInfo: InfoElement[]
}
The InfoElement definition:
{
Title: string,
ValueType: string,
Editable: bool,
NumberOfLines: number,
ValidationRules: RuleElement[],
PredefinedOptions: OptionElement[]
}
The RuleElement definition:
{
Name: string
}
The OptionElement definition:
{
Title: string,
Value: string
}

• Id – the source system-specific action id eg SAP Decision task for leave approval action id "EXECUTE_APPROVE";
• Name – the display name of the action eg "Approve";
• Class – the CSS class. The value is a supported Bootstrap button class ie
  • btn-primary, btn-default, btn-success, btn-warning, btn-info, btn-report, btn-danger,
• IsQuickAction – true/false. Indicates that the action can be used to action tasks in bulk;
• SupplementalInfo – this is optional. It is used for defining the additional input when a user actions a task. The value of the input is passed to the source system as part of the task action request. The Value Type instructs OneList to present the user with an appropriate interface to capture user input.
• Editable – the supplementary info pop-up is editable by the user (otherwise info pop-up only)
• Number of lines – the number of empty lines presented (for Text Value Type only)
• Predefined options – the available selections (for Dropdown Value Type only)
• ValidationRules – currently only supports this value:
  • required – this will require that a value must be supplied before completing the action

The supported Value Types are:

• Text - multi-line text box for approval comment. This is the default if no Value Type is specified;
• Number – single-line text box;
• Dropdown - drop down to select from a list of predefined values;
• Boolean - checkbox for the user to select;
• Date - date picker.

Source data model

The SAP adapter presents Task details in a JSON format to OneList.
There is no pre-defined definition for the source system task data model. It can be any flat structure or hierarchical structure. In general, the configuration should respect the structure of the source model and represent its hierarchy in sections.

Task Adapter configuration overview

OneList task configuration includes these areas:

• Task layout configuration - defines a series of steps to transform the source workflow task to the OneList task layout. The source of the transformation is the source system workflow task and the target is the OneList task;
• Task action configuration – defines the supplemental information for the task action in the OneList task.
• Handling post sync task and task action events – these event handlers are outside of the scope of this document.

To access the configuration,

1. Navigate to OneList;
2. Select the System Admin menu;
3. Select Adapters under the Administration pane;
4. Select the particular task adapter;
5. Click the Configuration button to open the Task Adapter Configuration dialogue;
6. Select relevant option in the Transformer drop down:
   1. For FAB configured task layout, select "FAB"
   2. For OneList configured task layout, select "Custom"
7. Complete the task layout configuration in the On Sync Task tab.
8. Complete the task action configuration if required on the Enabled Actions tab.
9. Click the Save button to save your changes.

Figure 6 - Task adapter configuration example

Task layout configuration

The "Sync Task" tab contains the task layout configuration. This is specified in JSON format.

Task layout transformation steps

The format of the transformation JSON is as follows:

• "Source": - the source data property in source JSON Object is referenced via standard JSON property reference syntax (eg PO_ADDRESS.Name)
  • If a fixed constant is required use "Value" in place of source and specify a fixed string value.
• "Target": - the OneList task object property (eg "Sections[Header].Sections[1].Title")
• "FormatString": - This is required to combine multiple source properties into a single OneList task property using C# format string syntax. For example:

"Source": "PO_NUMBER,CREATED_BY,CURRENCY, TOTAL_AMOUNT",
"Target": "Summary",
"FormatString": "PO {0} By {1} - {2} {3:###,###.00}"

• "ValueConverter": - Transforms all source properties, if possible, using standard C# data conversion functions eg DoubleConverter will transform STRING properties that look like numbers to numbers
• "RegexReplacement": Regular Expression to identify replaceable string by pattern. If no replacement (see below) then a replaceable portion of the string is removed eg leading zeroes
• "Replacement": the replacement value for the regular expression replacement operation
• "ItemBinding" – a series of steps to transform each element in the source property array to create the task's sections and its detail.

By default OneList adapter posts these task header values to OneList, therefore they can be omitted in the configuration.

• Title
• Requestor
• RequestedDate, DueDate
• Priority
• Status

The target OneList task object instance syntax

The following target path format is supported based on the data-driven user interface model presented above (note: property name is case sensitive)

• Property - The Name of the standard task header properties to be set eg Title, Requestor, Priority
• Sections – The relevant task section element. The syntax for mapping to sections is as follows:
  • Sections[section title or array index (if dynamic)]. For example:
    • If the first section title is a static string eg "PO Header" then bind to Sections[PO Header]
    • If the first section title is dynamic eg "PO 4500124 Header" then bind to Sections[0].Title
  • Data Elements within Section use title ie Sections[section title or Index][data element title]. For example:
    • Sections[PO Header][PO_NUMBER]
• Sections[section title or Index] – reference task section by title;
• Sections[section title or Index].Summary – reference the summary property of the section;
• Sections[section title or Index].Value – reference the value property of the section;
• Sections[section title or Index][data element title] – reference data element by title in a section;
• Sections[section title or Index].Sections[child section title or Index] – reference child section by title or Index within a parent section;
• Sections[section title or Index].Sections[child section title][data element tile] – reference data element by title in a child section;

Built-in value converters

• DoubleConverter – converts to number (double precision). It is useful for formatting a currency;
• DateTimeConverter – converts to date & time.
• SAPDateConverter - converts SAP date string (ie YYYYMMDD) to formatable display string ;
• SAPTimeConverter – converts SAP time string to a formattable display string;

Example - Populate the task header summary

From this Source:
{
"PO_NUMBER": "4500017940",
"CREATED_BY": "DCOLE",
"CURRENCY": "EUR",
"TOTAL_AMOUNT": 14500.0000,
…
}
The following step creates "PO 4500017940 By DCOLE - EUR 14,500.00" row in the task summary:
{
"Source": "PO_NUMBER,CREATED_BY,CURRENCY, TOTAL_AMOUNT",
"Target": "Summary",
"FormatString": "PO {0} By {1} - {2} {3:###,###.00}",
"ValueConverter": "DoubleConverter"
}

Example - Create a section & sub-section in the task

From this source:
{
"PO_NUMBER": "4500017940",
"CO_CODE": "1000",
"CREATED_ON": "20190620",
"PURCH_ORG": "1000",
"PUR_GROUP": "004",
"CURRENCY": "EUR",
"REL_GROUP": "02",
"REL_STRAT": "PU",
"REL_IND": "B",
"REL_STATUS": null,
"SUBJ_TO_R": "X",
"TAXR_CNTRY": "DE",
"VEND_NAME": "Bike Retail & Co.",
"CURRENCY_ISO": "EUR",
"EXCH_RATE_CM": 0.00000,
"REL_CODE": "PU",
"REL_COD_TX": "Team leader",
"REL_GRP_TX": "Purchase Order Rel",
"REL_STRAT_TX": ">250.000\/PrchGrp 004",
"REL_IND_TX": "Blocked, changeable with value",
"REL_OPTION_TX": "Release possible",
"RESET_POSSIBILITY": "NO",
"PUR_GROUP_DESC": "004",
"PO_DOCTYPE_DESC": "",
"TOTAL_AMOUNT": 14500.0000
…
}
The following steps will create the Header section and the second child section.

• The title of the child section is populated with the currency code and amount of the PO;
• The child section's summary is populated with PO number, Release code, and the fixed "Further information" rows;
• The child section's detail is populated;

The summary information is displayed when the Header section is collapsed and the full detail is displayed when the section is expanded.
{
"Source": "CURRENCY,TOTAL_AMOUNT",
"Target": "Sections[Header].Sections[1].Title",
"FormatString": "Total amount: {0} {1:###,###.00}",
"ValueConverter": "DoubleConverter"
},
{
"Source": "PO_NUMBER",
"Target": "Sections[Header].Sections[1].Summary",
"FormatString": "PO #: {0}"
},
{
"Source": "REL_CODE,REL_COD_TX",
"Target": "Sections[Header].Sections[1].Summary",
"FormatString": "Release Code: {0} - {1}"
},
{
"Target": "Sections[Header].Sections[1].Summary",
"Value": "Further information"
},
{
"Source": "PO_NUMBER",
"Target": "Sections[Header].Sections[1][PO #]"
},
{
"Source": "PO_DOCTYPE_DESC",
"Target": "Sections[Header].Sections[1][PO Type]"
},
{
"Source": "PUR_GROUP_DESC",
"Target": "Sections[Header].Sections[1][Purchase Group]"
},
{
"Source": "CREATED_ON",
"Target": "Sections[Header].Sections[1][Order Date]",
"FormatString": "{0:dd/MM/yyyy}",
"ValueConverter": "SAPDateConverter"
},
{
"Source": "REL_GROUP,REL_GRP_TX",
"Target": "Sections[Header].Sections[1][Release Group]",
"FormatString": "{0} - {1}"
},
{
"Source": "REL_STRAT,REL_STRAT_TX",
"Target": "Sections[Header].Sections[1][Release Strategy]",
"FormatString": "{0} - {1}"
},
{
"Source": "REL_IND,REL_IND_TX",
"Target": "Sections[Header].Sections[1][Release Indicator]",
"FormatString": "{0} - {1}"
},
{
"Source": "REL_OPTION_TX",
"Target": "Sections[Header].Sections[1][Release Option]"
},
{
"Source": "RESET_POSSIBILITY",
"Target": "Sections[Header].Sections[1][Can be reset]"
},

Task action configuration

The Enabled Actions tab contains the task action configuration JSON. The task action configuration is optional and is only necessary when user input is required for the particular task action.
The JSON is an array of serialized form of the Task Action object. The OneList task transformation process merges the action object defined here with the action posted by the adapter.
To apply the configuration to all actions, assign '*' to the Id property.
This configuration adds the input for comment to all actions:
[
{
"Id": "*",
"SupplementalInfo": [
{
"Editable": true,
"NumberOfLines": 3,
"Title": "Comment"
}
]
}
]

This configuration only adds the input for comment to the Reject action, also makes the comment as required.
[
{
"Id": "Reject",
"Class": "btn-danger",
"SupplementalInfo": [
{
"Editable": true,
"NumberOfLines": 3,
"ValidationRules": [
{
"Name": "required"
}
],
"Title": "Comment"
}
]
}
]