A lot of questions on the OTN forums are about customizing the out of the box taskflows for WebCenter. Although the documentation from Oracle is quite straight forward and complete, it lacks proper examples and use cases. It just explains the very basic concept on how to customize taskflows.
Therefore I am going to focus a little more on customizing these taskflows. This will be the first of many posts about customizing taskflows.
In this post I will describe the basic concept for customizing taskflows in a WebCenter Portal application. Later on, I will explain how to do the same thing in WebCenter Spaces.
For this post we are going to change the Content Presenter taskflow. More specific, we are going to add an Update Metadata link on the single item display of the content presenter. We will only change a specific section of the content presenter so I will explain the process on how to know where to find the files and update them.
Finding the correct file and section in the file is the most difficult part about customizing the taskflow. Therefore I will explain the process in this post.
Customizing a taskflow is done in JDeveloper. Before you can customize them, you need to configure your application to allow these customizations. By default, an application does not support these customization so we have to enable it. This is called Seeded customization. Seeded customizations uses layers which means that you customize a taskflow for a specific value. A typical use case could be that you could customize a taskflow in one way for department A and have a complete different customization for department B. I will try to explain this in another post so for now just remember that you have to enable seeded customizations which allows you to configure layers and values.
In order to enable these seeded customization you have to go to the Project Properties. Select ADF view in the list on the left and check the Enable Seeded Customizations checkbox:
Once this has been done, you can customize taskflows.
I bet that almost everybody has checked the checkbox to hide the popup screen to select the role when you start JDeveloper. You just select Default Role and that's it. Never bother about the other roles.
Well, we need to use the customization role because we are customizing taskflows.
There are big differences in functionality between the customization role and other roles. It is important to know that you can only customize which means that you cannot create new files, change security, create connections and so on.
Therefore it can be confusing that if you want to create a connection or add security to a taskflow from a library while you are customizing, these items will be disabled. You are only allowed to change files that are configured for customization.
Because of this you have to develop your application (create managed beans, configure security, define security on taskflows, and so on) in default or development role so when you switch to customization role, you have all the tools available.
Customizing in JDeveloper is actually the same as customizing pages in runtime. You do not edit the actual files but JDeveloper will create a delta and store that in MDS. You will see this clearly by the end of the post.
So as told in the beginning of this section, we have to be able to select our role so we need to enable the popup.
So let's enable the popup. From the Tools menu select Preferences. In the preferences select Roles in the left menu. Make sure you check the Always Prompt for role selection on startup checkbox:
Now you will get the popup when you start JDeveloper.
Before we close JDeveloper we need to make sure our application is prepared for it. As said in the introduction we are going to customize the content presenter by adding a link to update the metadata. I have created a separate taskflow that I include via a library so in the default role I added the library as a normal File System Connection in the Resource Palette:
Because I added this library to my project, I also have to specify security for that taskflow if I want to use it:
If you don't know much about adding taskflow from a library you can read part 6 of my WebCenter tutorial.
I also created a connection to UCM because I need this in that taskflow:
Remember that this cannot be done during Customization Role! If you forget to do it before you begin customizing, you have to switch back to default role which means you have to close JDeveloper and reopen it which can cause quite some loss of time.
Now that we have prepared everything, we can close JDeveloper and reopen it. Make sure you select Customization Role.
When JDeveloper has been started you notice that the layout of the windows is a little different. There is a Customization Context window in the bottom window:
This is exactly the place where you select the value of the layer. By default the application has created a layer called site and it has some possible values (Site One, Site Two, Site). By default Site One will be selected but notice that the application is using Site by default. This means that the customizations you will be doing will not affect the real application because it is using the Site layer so you have to select Site in the dropdown list as shown on my screenshot.
The way the application selects the layer is by using a Customization Class. There are a few CC's out of the box. When you enable Seeded Customizations, the application will automatically add the SiteCC to the MDS Configuration. This can be checked in the adf-config.xml:
This will return Site as the name of the layer so that's why we need to select Site in the layer value. I will create a different post about creating our own Customization class so you have full control over which layer the application will use.
Also notice that the customizations you do at runtime will be stored in the same layer!
Now that we have selected the layer we can start finding the content presenter taskflow.
Taskflows from WebCenter are stored in libraries so we have to browse in the library. In order to do so we need to list the libraries in the application navigator.
You can enable the libraries in the Navigator Display options:
When you open the Portal project you will see all the libraries listed.
There are a lot of libraries so it can be difficult to find where your taskflow is stored. Fortunately Oracle has some good naming standard. The typical name is WebCenter <service> Library Service View
So if we want to customize the content presenter we have to look in the WebCenter Document Library Service View because the content presenter is part of the document service. If you want to customize the tagging taskflows you want to look in the WebCenter Tagging Service View.
So we open the WebCenter Document Library Service View:
From here on its common sense. When you open the content package you notice it contains and integration and internal package. Makes sense that these packages do not contain the taskflows and fragment so let's have a look at the doclib package.
It has a package view. Maybe fragments and taskflows are stored there? Makes sense so let's open it. Now we have jsf, resource and spaces package. Again, common sense says we should take a look at the jsf package.
Aha, fragments and taskflows package. We have a winner!
We are going to change the content presenter so let's have a look at the taskflow package. You notice that Oracle has done a proper job. Each taskflow has their own package which is quite easy for us to find.
The content presenter is defined in the presenter package. There you can find the actual content presenter taskflow definition.
When you double click on it you can see the diagram:
From here on we can easily follow the taskflow and double click on the view we want to customize.
Because we are going to customize the single node view it makes sense to double click on the presenter-single-node-view. This will open a file called presenterSingleView.jsff which is the actual fragment that is responsible for rendering a single node item.
As you can see, this process is quite straight forward and allows you to easily find the fragment that you want to customize. It requires just a little bit common sense.
Now that the fragment is open we can change it.
Remember that customizations are stored as delta's. This has some consequences during the process of customization. We cannot directly modify the source of the page because than we would change the base file. We need to modify the source in a way that JDeveloper can keep track of the changes and create the delta required for the MDS.
Therefore you can only use drag and drop to add components. This can be done in both design or source view. When you are used to working in source mode, you have to get used to changing attributes in the property inspector and use the structure window to move and edit the source.
So in order to add my taskflow, I had to drag and drop the taskflow from the resource palette on top of the first panelGroupLayout of the fragment. By doing this, Jdeveloper will add following code:
This will not be added to the original file but instead, a delta will be created.
When the taskflow has been added to the fragment I can simply run the portal project. This can be done in customization role so you don't have to close JDeveloper before running which is a good thing.
When I test the content presenter I can see my link when I use a single node in the content presenter:
As you might noticed I wrote a lot of text but it's important to understand the process and how the customizations are stored.
Hope this post helped a few people and you can expect some more posts about customizing taskflows with some more advanced use cases. This was just the introduction.