In his blog post “BPM OData: Implementing a Basic Custom Task Execution UI”, Andre demonstrates how the OData service of BPM combined with the power of SAPUI5 can be leveraged to create modern custom UIs for your BPM tasks. One thing, however, is missing compared to previous technologies like Web Dynpro (Java) and Visual Composer: the ability to quickly generate a rough UI based solely on the process information using the ‘New Task’ wizard. Providing a structure and a lot of the necessary boilerplate coding is extremely useful, both for just trying out some prototypes, for example, in trainings, and also as a starting point for custom implementations.
Starting with SAP NetWeaver 7.3 EHP 1 SP 13, the enhanced ‘New Task’ wizard now provides such ability. The first version has some limitations (see below), but is already fully useable for a simple roundtrip.
Let’s take the same process Andre uses in his blog:
This is the XSD for the data objects (also used for the process start):
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/Customer"
xmlns:tns="http://www.example.org/Customer" elementFormDefault="qualified">
<complexType name="Customer">
<sequence>
<element name="firstName" type="string"></element>
<element name="lastName" type="string"></element>
<element name="address_street" type="string"></element>
<element name="address_city" type="string"></element>
<element name="address_zip" type="int"></element>
<element name="address_country" type="string"></element>
<element name="currency" type="string" default="EUR"></element>
</sequence>
</complexType>
<complexType name="Credit">
<sequence>
<element name="creditLimit" type="double"></element>
</sequence>
</complexType>
</schema>
(Note that I used underscore in the element names instead of hyphens as the wizard disallows those)
In the properties of the human activity ‘Verify Customer Data’, we can now choose to create a new task:
The ‘New Task’ wizard opens providing an option to create an UI implementation for us:
Of course, we select the new ‘SAPUI5’ technology.
The generated files will be written to a Web-DC which can then be easily deployed using the standard deployment process (using an EAR project). If no Web-DC exists yet, simply create one using the “New” Button.
In the next step, we have to specify the names of the component, complete and error event. The wizard already provides defaults, so we do not need to change anything, here.
Each generated UI will use a separate folder to enable placing several UIs in the same Web-DC. The name of this folder is taken from the component name. In this example, I changed it from the default VerifyCustomerComponent to VerifyCustomer, to create a nicer URL.
Finally, we can choose the context attributes we want to include in this UI from the data objects.
Internally, a new XSD is created from the selection made, here. This allows freely combining attributes from different data objects. For simplification, the same XSD type is used for both input and output as well as for faults. Those could be changed later in the task properties, if the generated files are accordingly adjusted.
The first version of this generator has a few limitations:
- Only simple types of text, numbers and booleans (displayed as checkboxes) are supported
- No complex types (with the exception of a root complex type containing all other simple types, as shown in this screenshot)
- No array types
- No date and time types
The wizard will create a new task of the ‘Custom UI Component’ variant. It also assigns the internally generated XSD to it.
The URL (displayed in the ‘Component’ field) needs to point to the full (relative) path to the new UI, which resides in the Web-DC. Don’t worry, the wizard will set it automatically for you. You can see my change to the component name reflected:
Relative URLs are used here, but when using the BPM Inbox, the base URL with the hostname needs to be configured. If this configuration differs from the actually used URL (for example, domain name and IP address), the OData calls will fail due to the “Same Origin" security policy.
Adding input and output mapping can be done in the same way as for any task.
That’s it – now, you can deploy and run your process and the task is useable.
For further development of SAPUI5, please, refer to the respective documentation (see also the Development Toolkit).
But to get you started I'll explain a few basic changes to the generated UI to make it look nicer.
Have a look into the generated folder structure:
Index.html is the file, which is referred to by the ‘custom UI Url’ (‘Component’ field in the task) and thus called from the BPM Inbox. The main display description (the ‘view’) is in the file DO_CustomerForm.fragment.xml, where fragment implies that it is rendered as part of an outer container. When we open this file, we can re-arrange the XML elements and thus achieve the desired order of fields.
The displayed texts are externalized (ready for localization) and taken from the messageBundle.properties file. You can freely change that content to, for example, translate your UIs. The defaults are uppercase versions of the attribute element names, for easier identification, which values needs to be adjusted.
Caveat: the file needs to be in UTF-8 format. NWDS sometimes does not correctly recognize the file encoding, which leads to strange looking artifacts when characters outside the US-ASCII 7bit range are used. Thus, make sure to set UTF-8 in the properties of the file before opening it in the internal Editor!
Now this looks much nicer:
Nothing has changed? Remember to clear your browser cache.
The generated UI uses OData for back-end communication. This is fully automated and needs no further effort. You can see that it works by completing the task and verifying the changed data in the process context:
Aside from reading the task input data and writing the changed data back, the generated logic also automatically claims the task upon opening the Task Execution UI and closes the browser tab when the task has been completed. Of course, this can be disabled by changing the generated source.
The process flow would now expect to have this data confirmed (or changed – let’s do that) and as a second task a credit limit added. Again, use the ‘New Task’ wizard to create an UI, selecting those fields:
Note: explicitly not selecting the DO_Customer / DO_CreditLimit nodes will ensure that a single complex type consisting of only simple types will be generated (and named ‘Form’)
The generated files /CreditLimit/view/FormForm.fragment.xml and CreditLimit/i18n/messageBundle.properties can again be adjusted as described above. In this case, I added editable=”false” to the TextFields in the XML to create read-only UI input fields for all attributes except currency and creditLimit. I also mapped only those two in the Task Output Mapping.
The result looks like this – a nice UI, with custom field labels, sorted, partly read-only. It displays the changed data from the first task UI and lets me enter currency and credit limit:
Further improvements of the generator might be adding generated code for fault generation (like a ‘Cancel’ button) and an enhanced type support. But with the enhanced ‘New Task’ wizard and the automatic SAPUI5 generation for a task, the main work is done, and thus, you have a powerful tool as a first step for your own customized UIs.
Appendix
For deployment of the Web-DC, an ‘EAR Project’ is needed. If there is not already one available, a new one could be created as new project of type ‘Development Component’ and by selecting ‘JavaEE’ / ‘Enterprise Application’. The last page in the wizard offers the possibility to add referenced projects. Alternatively, the reference can be added later in the ‘Component Properties’ (right-click on the project and select ‘Development Component’ / ‘Show In’ / ‘Component Properties’). On the second tab, ‘Dependencies’, the Web-DC project can be added.
Now, when deploying this EAR, the referenced Web-DC is deployed as well.
Update 2015-01-09:
The JavaScript coding generated by SAP NetWeaver Developer Studio versions before 7.31 SP16 / 7.40 SP 11 made an assumption about a naming convention in the OData NavigationProperties. Unfortunately, a necessary correction on the server side – released with SAP Note 2103609 – broke this assumption. UIs which have been generated with the older version of the Developer Studio will need to be adjusted to run correctly on an updated runtime. Otherwise, the error "Uncaught TypeError: Cannot read property 'navigationProperty' of null" will occur and process data will fail to load. Luckily the correction is very easy. Just a few lines of code in a single file need to be replaced. For details, please see SAP Note 2113891.
- SAP Managed Tags:
3 Comments
