Customized Subscription Massage

[Former Member]

Hello Kolegues,

i write a Workflow programm in java that uses the SAP Portal KM an with Java iViews as User-Frontend. It works fine and do what it should do. Every Workflowstep has its own Folder (sometimes with subfolders when many people responsible for this workflowstep and my programm must search for the right person) in the KM and the programm moves the data to the needed workflowstep. I use the SAP Portal User Management API for authorization and the subscription service for notification.

Now i want to add this feature:

The employe must get a customized Subscription Massage. I need for evry folder in the SAP Portal KM an Other subscription massage.

Is there a easy way to do this? In the moment i think i must write a new service an use Java-Mail. Is there a better way to do this?

Best regards,

Patrick Höfer

[Former Member]

Hi all,

I'm trying to customize the subscription service in order to use the standar "Recent Notifications" Iview in EP 6.0 SP2.

I'm not sure if the XML "SUBSCRIPTION_xx.xml" in /etc/notifications applies to this scenario or if it's only for EMAIL texts.

Is there other way to customize it?

I have found that JAVA class com.sapportals.wcm.control.subscription.NotificationRenderer is used to render the Iview. Is it necessary to modify this class? I want to delete some columns of the iview (created By and details link)

Thank you

[Former Member]

Hello,

i forgot something: The question is for an EP 5.0 SP5 Portal.

When anybody has a idea how to customize a subscription massage please Answer me!

Best regards,

Patrick

[Former Member]

Hello,

the self discussion is going on...

i think i have found a method to solve the problem without programming a new service that i have described up. Under KM_Admin - Content Management - Repository Services - Subscription Service i can make a new Subscription Service. So for this Subscription Service i can make my own subscription_de.xml (the Form in /etc/notification).

But there is no fun without an other problem

In the File subscription_de.xml are variables used like <resourcelink/>. But i dont found the class or an other xml Files where is variables are definied in the javadoc or in other xml Files. I need this because i want send the user an Link. When i enter the link in the normal html (with <a> tag) format in the xml file it is dont displayed in the email.

I will be happy about every hint that i get.

Best regards,

Patrick

BTW: In my PDK Javadoc (SP5) i am missing the UML Diagramm http://localhost:8080/irj/services/knowledgemanagement/docs/api/com/sapportals/wcm/repository/servic...

Can anybody email it to me?

[Former Member]

Hi Patrick,

I have the UML class diagram that u needed. What's your email address?

Best Regards,

Jacky

[Former Member]

Hi Jacky,

thats nice. It is:

mail@phoefer.de

Best regards,

Patrick

[Krasle]

How to Customize Notifications

Hi Patrick,

Of course it is possible to customize anything at some price. Customizing the

notifications is also possible, but of course you are introducing another

maintenance aspect that has to be upgraded by hand, possibly with major rework,

when a new patch/release is installed. This is not a decision you should take lightly.

Also, I am not a developer, but rather a UI guy, so the programming details

mentioned below may require some interpretation. If you don't know anything

about XSL, you might jump down to the QUICK AND EASY part.

-

-

---

Overview -

-

---

The subscription notifications are generated using an XML / XSL transformation

utilizing some additional parameter input. The XSL stylesheet consists of 3 main

parts: the parameter block, the message structure, and the parameter rendering

library. It make sense to first describe the XSL in order to understand the XML.

It is possible to do lots of customization by only changing the XML (and resource

bundles in EP6).

-

-

---

XSL -

-

---

Parameter Block

The parameter block defines which resource-specific data gets passed into the

transform as parameters. The data defined in the parameter block is the only

resource-specific data that can come across the API since this is hard-coded

on the other side. There is no point in changing this unless the calling code is

changed to deliver more parameters. A couple of additional parameters (such

as a Details link) were added recently, but I am not exactly sure when that hits

the street.

Rendering Library

The rendering library provides a set of little templates that can be referenced

to insert parameter values into messages. The library provides both "primitive"

templates which render just the text value of the parameter, as well as formatted

templates that will formulate HTML links. Since we wanted to use the same texts

for HTML and non-HTML channels, we built in a switch in the rendering which will

control the formatting based on whether the output format is HTML or not. The

primitive templates are:

resourcename subscriptionname notificationtext

eventid eventname parenturl

contentaccessurl folderaccessurl deleteurl

administrationurl mailto

It is left up to an exercise for the reader to figure out what these do.

As time goes by this may be changed or extended. Your installation

may already have a couple more. The formatted templates are:

subscriptionlink resourcelink parentlink

deletelink administerlink mailtolink

I would not recommend altering these templates unless you know your XSL

well, since there are a lot of consistency points that you have to observe.

Message Structure

This is the meat of the XSL, and is the ONLY part that is really interesting

to change. This portion defines the basic structure of the message, leaving

the language-dependent portions elsewhere (XML or resource bundles

via XML). In the standard e-mail notification, it may look as if everything

is doubled - well it is! That is because it includes both a plaintext and an

HTML version. This ensures that it will be somewhat readable in a non-HTML

mail client. The outputFormat XSL parameter is used to pick the formatting:

<xsl:with-param name="outputFormat" select="'plaintext'"/>

For formatted templates, using "plaintext" will cause the URL to be listed in

parentheses. "plaintextsms" will omit the URL entirely.

Here, the parameters may be used in logic expressions to be able

to do special stuff depending on resource-specific values. You see this

where a different message is generated depending on whether the isOwner

parameter is set or not. Conceivably, you could program a different message

for every parameter combination. You could even add attributes to the

textspans in the XML to implement a more complex matching scheme.

This is pretty much the area where you can do anything you want in XSL.

The burden, however, is that you make sure that if you introduce any new

text strings, that you define them in the XML (and resource bundles in EP6).

The XSL determines what nodes need to be in the XML. In EP6, that

propagates to the resource bundles.

-

-

---

XML -

-

---

The XML simply lists all the text strings that are used in the XSL. In EP6,

the language dependent text was moved from the XML to resource

bundles which are referenced in the XML. For the purpose of this post,

let us assume the texts are in the XML like in EP5.

The XML specifies a whole set of textspan tags which specify the text as

well as attributes used to select the proper tag in accordance with the

logic programmed into the XSL explicit logic and matching. Conceivably,

you could add more attributes to be able to have a finer degree of

distinction in the logic. An adept XSL XPATH expert could probably

leverage the resource path to generate custom messages based on the

position of the resource. I have not yet seen this done, but it is quite

specific to the way you have set up the repositories. It obviously also

involves reprogramming the XSL which creates a support problem

for future releases.

!!!!!!! HERE IS THE QUICK AND EASY PART !!!!!!!

The texts that are shown in the message are broken into the tidbits

in the XML textspan tags in EP5, or in the resource bundle file in EP6

(I think it is called "subscription.properties"). For each supported

language, you can specify a string that may incorporate resource-specific

information. Get this: you could reference completely different info

depending on the language, depending on what you put in the textspans.

You can also make the AVAILABLE resource-specific info show

up anywhere you want. The info available is fixed and may be incorporated

similar to HTML markup, although there are some limitations such as

that THE MARKUP MAY NOT BE NESTED. I hope you heard that.

If you want to change the HTML markup generated, you will need to change

the XSL. Okay, what can I include, you ask. You may reference any of

these markup tags below by including them in the text using the syntax

"sometext " <- BAD

Why? you may ask. It's because WE DO NOT SUPPORT NESTING.

Now you may say "but I want to include this or that property or

metadata" and the answer is .... if it is not in the parameter block in

your XSL, then it is not available without changing the Java. I admit

this would be a nice extension. If you really want that, you will need

to have your boss tell us that we need to do that.

-

-

---

Other Considerations -

-

---

E-Mail Header

This only describes how to customize the contents of the mail.

The Subject line and other properties cannot be influenced

by the XSL, and are more or less hard-coded in the Java.

Maybe someone else can write more on this.

HTML-Compatible Mail Clients

Be careful in customizing the messages to be purely HTML. This may

not look very nice on some mail clients. The standard notifications

include a header in plaintext equal to the HTML content to try to

best support the variety of mail clients. Examine the assumption that

all users have HTML-compatible mail clients.

Links

Be careful when including links in notifications. Targets in the portal

require both access to the portal and appropriate permissions.

Similarly, Internet links require an active Internet connection.

This might cause grief for mobile users. This applies to all kinds

of links - images AND CSS stylesheets. This is why the standard

notifications use no CSS.

EP6

The way languages are supported has changed from EP5 to EP6. The

language specific texts are now referenced by resource bundles. To

customize the texts you will have to maintain them in a different place

than in EP5. Upgrading customizations from EP5 will require some

manual work.

Approval Notifications

The approval notifications are generated in almost the exact same way

as the subscriptions.

Bundled Notifications

EP6 offers bundled notifications and the mechanism is somewhat different.

Bundled notifications dynamically build together the XML input for the

transform by combining some static XML with a generated parameter

block. A description of this is outside the scope here.

Character Encoding

I strongly recommend you do not change character encoding. Changing this

may cause things to break that are not obvious - specifically characters

that may be expected in other languages.

Prototyping

The best way to customize subscriptions is to use a client-based HTML

page. Then you can customize the notifications completely outside the

portal and KM on any PC with a suitable browser (supporting XSL

transformation). This will involve having to change some stuff in the header

that you will have to change back when you put it back in the portal.

Specifically, one thing you will need to change is putting some dummy

values for the parameters so they are not blank. There may also be

subtle differences in the client XSL processor you use and that in KM.

If you want to do extensive customization, this is the best way to get

an efficient dev/test cycle. If you have problems you may try a more

recent (or even older) XMLDOM control.

Here is an OLDER version of a test HTML page you might find useful

Don't forget you have to change the XSL header back and forth if you use this.

'xformed"";

This shows the transformed emails generated.

Disclaimer: I cannot guarantee the complete accuracy of the information

herein contained, especially in light of the fact that the system varies from

build to build. Use any of this information at your own risk! Customizing

notifications can create maintenance and upgrade difficulties!

If you notice any errors or can make clarifications, don't hesitate to REPLY!

Regards,

Darin Krasle

[Former Member]

Hello Darin,

thak you very much for this detailed article about the notification Service. Without your article i think i need Weeks to do it. I hope there comes the day i can help you too.

Best regards,

Patrick

[Krasle]

Feedback here is always appreciated

Hi Patrick,

I hope the info helps you achieve your goals. I do a lot of the UI Design for Knowledge

Management and Colloboration. Providing good feedback on the UI in this discussion

area is the best way to help me. I read the posts here and am often lurking to find

any suggestions I might be able to slip into the development along with other changes

or reworks. I can't promise that specific things will be changed, but I am very willing

to pursue good ideas, especially those that fix those little things that prevent you from

being able to use an entire feature, e.g., "if only this little thing was different, we could

use this, but this single issue is the deal-killer." If I better know the problems people are

having, I can better give them what they need.

Regards,

Darin Krasle

[Former Member]

Hi Darin,

I read your answer with great interest, too!

The question we at Siemens VDO are interested in is the following:

(I already posted a discussion entry, nobody answered, so I try i this way):

We have a problem concerning the daily and weekly notification mails.

Today the mail looks like this:

***

Weekly summary of subscriptions

-

---

Subscription Portal Migration Storage

Portal Strategie (Weekly notification)

The folder Storage was changed by on Mon Dec 01 19:21:42 CET 2003

-

---

***

That message is not very helpful for us, we would need a message, where all

the changed documents during the week (or day) are listed (eventually including

the subscription of the document) with a link to the document.

Is there a possibility to do this?

Has anybody done this already?

Thank you very much for your Help,

Theo Heindl

SiemensVDO

[Krasle]

Bundled Subscriptions

Hi Theo,

In an upcoming release, there is a feature we call "Bundled Subscriptions"

which provides information on more than one resource at a time. The rendering

pipeline is somewhat different than for a single resource in that an XML data

block containing the resource-specific info for all resources is generated, merged

with the static XML text file, and then transformed with the XSL. The rendering

library of templates is essentially the same as for single resources. The default

text for a changed resource will be something like:

The resource <resourcelink/> <detailslink>Details</detailslink> in the folder

<parentlink/> was changed by <lastmodifieduser/> on <lastmodified/>.

As in the case of single resource notifications, we kept the default formatting

simple so that it is more easily understood, is browser neutral, and does not

require a connection to the portal to read (e.g., no linked CSS).

I think this new feature ought to address the requirements you described.

The subscriptions should support daily, weekly, or monthly summaries.

As always, if you can better describe exactly what you want to do, it makes

it easier for us to provide appropriate facilities for achieving your objectives

and goals. This is your best chance to avoid having to deal with "gaps" later

that cause hassles for all of us.

Regards,

Darin Krasle