Demystifying text determination – how to implement some basic use-cases
Test determination is a feature that allows filling automatically Text Collection of SAP TM documents with, well, texts. For instance, in Air Freight scenarios, the texts for Nature of Goods are quite standardized and can be filled automatically with predefined templates that need only minor adjustments. Other scenarios require an automatic propagation of e.g. shipping instructions – from forwarding orders or ERP-based requirements (OTR/DTR) to the freight documents, so that they can be transmitted to carriers during subcontracting.
The functionality was intended actually for SAP TM 9.0, but it required a coordinated development in two software components – in SAPTM as well as in Business Suite Foundation (SAP_BS_FND), since the Text Collection is actually a reusable business object from this layer. Due to some TM-specific modelling particularities, the out-of-the-box BS FND functionality did not work properly in TM 9.0.
The development can be used fully in 9.1 and 9.2 – even if it took some additional SAP Notes (2111951, 2113678, 2113736, 2114090, 2116402 and 2116403) to have it working satisfactorily.
The text determination can be set up in the customizing of Text Schema (IMG path Cross-Application Components -> Processes and Tools for Enterprise Applications -> Reusable Objects and Functions for BOPF Environment -> Dependent Object Text Collection -> Maintain Text Schema). I assume the reader is familiarized with the text collection concepts – if not, feel free to consult the documentation. Also, it should have gone without saying: some basic knowledge about TM internal modelling (business objects, nodes, associations) is a prerequisite when setting up this feature.
Text Schemas can be attached to SAP TM documents via type customizing (e.g. IMG path Transportation Management -> Forwarding Order Management -> Forwarding Order -> Define Forwarding Order Types).
Coming back to Text Schema customizing, the functionality is activated by specifying an Access Sequence for a text type while maintaining Text Type to Text Schema Assignment. The access sequence is a collection of so-called Accesses – steps that attempt to find a text according to some logic. Both concepts can be maintained in the same customizing cluster – we’ll see immediately how.
When an access sequence is maintained in the type-schema assignment, the flag Reference becomes meaningful:
- If left empty, the result of the determination is written immediately in the target document, but there is no “update handling” (if the source of the texts changes, the text in the target document remains untouched).
- If the flag is set, the result of text determination is not persisted completely in the target document – the text content is left intentionally empty. Every time the collection is accessed, the text determination is executed again and the consumer (e.g. the UI) sees its current result. As soon as the text is modified in the target document, it becomes “local”: the changed value is saved in the text content and the reference flag is removed. It’s worth noting that this option poses a certain runtime overhead, since the determination must be executed more often.
There are four types of accesses: (1) association navigation, (2) association navigation with node attributes, (3) external BO access and (4) external source. #1 and #2 are similar to each other – they attempt to follow some BOPF associations to reach another text collection representation node, from which the requested text type is copied (if existing). #3 and #4 rely on external classes, implementing certain ABAP interfaces.
I am going to describe now the necessary steps required to set up the text determination for the following use cases:
- Use a given standard text (maintained using t-code SO10) as soon as the TM document is created.
- Copy a text from one related TM document
- Copy and/or adjust texts from more related TM documents
Use-case 1: standard text
To use them in text determination, we need an access of type External Source (we obviously cannot use BOPF associations to get there, and we need to provide some parameters – the identification of the text). External source require a so-called external text determination class. For this particular case, there is already a library class that can be used, delivered in BS Foundation software component – /BOFU/CL_ACCESS_SO10_TEXT:
In the my example, I modified the SAP-delivered schema FWOHDR, which is assigned to the forwarding order type FWO. As a result of the steps above, creating a forwarding order of this type leads to the automatic creation of a NOTE text having content To be packed with extra care.
Use-case 2: copy FWO/OTR/DTR text to freight unit
Here we can use the simplest method – association navigation. The “business entities” must be defined in advance in another Foundation customizing (IMG path Cross-Application Components -> Processes and Tools for Enterprise Applications -> Reusable Objects and Functions for BOPF Environment ->General Settings -> Maintain Business Entities) and represent a combination of BOPF business object and node:
The path to be followed must described in Access Details – starting from the target documents to the requested text collection object representation node of the source document. So we’ll use the association BO_TRQ_ROOT to navigate from freight unit header (the ROOT node of business object /SCMTMS/TOR) to forwarding order/ERP-requirement header (ROOT node of /SCMTMS/TRQ), then the association TEXTCOLLECTION from there to the representation node. It looks like a rudimentary version of the TM Data Crawler:
As soon as a freight unit (which has a type that references this schema…) is created, the corresponding NOTE text from FWO/OTR/DTR header is copied.
One side-remark: in most FWO-based scenarios, the freight unit is created automatically soon as the consistency checks allows it – entering a text in forwarding order after this point does not lead to the update of the freight unit! This can be overcome by either disabling the automatic creation of freight units (in FWO type customizing), or by changing the items in FWO (which usually lead to a rebuild of the freight unit). In ERP integration scenarios, however, the document (OTR/DTR) is usually created completely in one step, including texts, before freight units are built. But if some texts are added manually in OTR/DTR afterwards, these too are not propagated automatically.
Who knows, perhaps SAP will offer in the near future a possibility to manually trigger the text determination to overcome such cases (e.g. a button in the Notes UI). 😉
This procedure can be used every time when a 1:1 relationship between business entities exists. For instance, you can use it to propagate FOW/OTR/DTR header/item texts to freight order items as well.
Copy texts from more source documents into one text
Let’s consider a more exotic requirement – to propagate the freight unit texts to the freight order header. Here there is a problem: usually there are more freight units assigned to a FO, but a certain text can only be created only once in a text collection. Therefore, the association-based approach described above does not work (the text from one freight unit only will be determined).
One solution is to concatenate the text content – but this is a more complex procedure, that can only be covered again by a specialized determination class. We’ll use again external source as access type.
The most important step is to create a class, implementing the interface /BOFU/IF_ACCESS_EXTERNAL_TEXT, and then write the code for method GET_EXTERNAL_TEXTS. I attached the source code of my demo class to this article. In a nutshell, my implementation finds all freight units attached to a freight order by using the association REQ_TOR, then goes to their header-level text collection and finally concatenates the matching texts into one content, inserting in the process some contextual information (the identfication of the freight unit) as separator. When the texts are available in the requirement documents (FWO/OTR/DTR), one can use in coding the association BO_TRQ_ROOT_ALL to directly access the ROOT nodes of these documents – this avoids the additional determination required to propagate the texts from there to freight units.
After the class is created and activated, create a new external source and specify the new determination class; my implementation does not require parameters (although one can imagine a more generic class that can find texts in various documents):
My sample code takes data from the NOTE text of the freight units, but with external access some other options are possible, like combining more text types into a single entity in the target document.
Another fact worth mentioning: text determination is usually executed only when the corresponding node instance is created. For freight orders, there is a special logic – the determination at header level is executed every time a requirement is added to (or removed from) the freight order.