Retrieving uploaded attachments -UCM-
As stated in my previous blog entry, Oracle BPM 11g 11.1.1.5.1 (aka PS4FP) introduced a new cool feature whereby you can use Oracle WebCenter Content (previously known as Oracle UCM) as
the repository for
the human task attached documents. For more information about how to use or enable this feature, have a look here.
The attachment scope (either TASK or PROCESS) also applies to UCM-attachments. But even with this other feature, one question might arise when using UCM attachments. How can I get them from within
the process?
The first answer would be to use
the same getTaskAttachmentContents() XPath function already explained in my previous blog entry. In fact, that's
the way it should be. But in Oracle BPM 11g 11.1.1.5.1 (PS4FP) and 11.1.1.6.0 (PS5) there's a bug that prevents you to do that. If you invoke such function against a UCM-attachment, you'll get a null content response (bug#13907552). Even if
the attachment was correctly uploaded.
While this bug gets fixed, next I will show a workaround that lets me to retrieve
the UCM-attached documents from within a BPM process. Besides,
the sample will show how to interact with WCC API from within a BPM process.Aside note: I suggest you to read my previous blog entry about
Human Task attachments where I briefly describe some concepts that are used next, such as
the execData/attachment[] structure.
Sample Process
I will be using
the following sample process:
A dummy UserTask using "HumanTask2"
Human Task, followed by an Embedded Subprocess that will retrieve
the attachments payload. In this case, and here's
the key point of
the sample, we will retrieve such payload using WebCenter Content WebService API (IDC):
and once retrieved, we will write each of them back to a file in
the server using a File Adapter service:
In detail:
We will use
the same attachmentCollection XSD structure and same BusinessObject definition as in
the previous blog entry. However we create a separate variable, named attachmentUCM, based on such BusinessObject.
We will still need to keep a copy of
the HumanTask output's execData structure. Therefore we need to create a new variable of type TaskExecutionData (different one than
the other used for non-UCM attachments):
As in
the non-UCM attachments flow, in
the output tab of
the UserTask mapping, we'll keep a copy of
the execData structure:
Now we get into
the embedded subprocess that will retrieve
the
attachments' payload. First, and using an XSLT transformation, we feed
the attachmentUCM variable with
the following information:
The name of each attachment (from execData/attachment/name element)
The WebCenter Content ID of
the uploaded attachment. This info is stored in execData/attachment/URI element with
the format ecm://<id>. As we just want
the numeric <id>, we need to get rid of
the protocol prefix ("ecm://"). We do so with some XPath functions as detailed below:
with these two functions being invoked, respectively:
We, again, set
the target payload element with an empty string, to get
the <payload></payload> tag created.
The complete XSLT transformation is shown below. Remember that we're using
the XSLT for-each node to create as many target structures as necessary.
Once we have fed
the attachmentsUCM structure and so it now contains
the name
of each of
the attachments along with each WCC unique id (dID), it is time to iterate through it and get
the payload. Therefore we will use a new embedded subprocess of type MultiInstance, that will iterate over
the attachmentsUCM/attachment[] element:
In each iteration we will use a Service activity that invokes WCC API through a WebService. Follow these steps to create and configure
the Partner Link needed:
Login to WCC console with an administrator user (i.e. weblogic). Go to Administration menu and click on "Soap Wsdls" link. We will use
the GetFile service to retrieve a file based on its dID. Thus we'll need such service WSDL definition that can be downloaded by clicking
the GetFile link. Save
the WSDL file in your JDev project folder.
In
the BPM project's composite view, drag & drop a WebService adapter to create a new External Reference, based on
the just added GetFile.wsdl. Name it UCM_GetFile.
WCC services are secured through basic HTTP authentication. Therefore we need to enable
the just created reference for that:
Right-click
the reference and click on Configure WS Policies.
Under
the Security section, click "+" to add
the "oracle/wss_username_token_client_policy" policy
The last step is to set
the credentials for
the security policy. For
the sample we will use
the admin user for WCC (weblogic/welcome1). Open
the composite.xml file and select
the Source view.
Search for
the UCM_GetFile entry and add
the following highlighted elements into it:
<reference name="UCM_GetFile" ui:wsdlLocation="GetFile.wsdl">
<interface.wsdl interface="http://www.stellent.com/GetFile/#wsdl.interface(GetFileSoap)"/>
<binding.ws port="http://www.stellent.com/GetFile/#wsdl.endpoint(GetFile/GetFileSoap)"
location="GetFile.wsdl" soapVersion="1.1">
<wsp:PolicyReference URI="oracle/wss_username_token_client_policy"
orawsp:category="security" orawsp:status="enabled"/>
<property name="weblogic.wsee.wsat.transaction.flowOption"
type="xs:string" many="false">WSDLDriven</property>
<property name="oracle.webservices.auth.username"
type="xs:string">weblogic</property>
<property name="oracle.webservices.auth.password"
type="xs:string">welcome1</property>
</binding.ws>
</reference>
Now
the new external reference is ready:
Once
the reference has just been created, we should be able now to use it from our BPM process. However we find here a problem.
The WCC GetFile service operation that we will use, GetFileByID, accepts as input a structure similar to this one, where all element tags are optional:
<get:GetFileByID xmlns:get="http://www.stellent.com/GetFile/">
<get:dID>?</get:dID> <get:rendition>?</get:rendition> <get:extraProps> <get:property> <get:name>?</get:name> <get:value>?</get:value> </get:property> </get:extraProps></get:GetFileByID>
and we need to fill up just
the <get:dID> tag element. Due to some kind of restriction or bug on WCC,
the rest of
the tag elements must NOT be sent, not even empty (i.e.: <get:rendition></get:rendition> or <get:rendition/>). A sample request that performs
the query just by
the dID, must be in
the following format:
<get:GetFileByID xmlns:get="http://www.stellent.com/GetFile/"> <get:dID>12345</get:dID></get:GetFileByID>
The issue here is that
the simple mapping in BPM does create empty tags being a sample result as follows:
<get:GetFileByID xmlns:get="http://www.stellent.com/GetFile/">
<get:dID>12345</get:dID>
<get:rendition/>
<get:extraProps/>
</get:GetFileByID>
Although
the above structure is perfectly valid, it is not accepted by WCC. Therefore, we need to bypass
the problem.
The workaround we use (many others are available) is to add a Mediator component between
the BPM process and
the Service that simply copies
the input structure from BPM but getting rid of
the empty tags. Follow these steps to configure
the Mediator:
Drag & drop a new Mediator component into
the composite.
Uncheck
the creation of
the SOAP bindings and use
the Interface Definition from WSDL template and select
the existing GetFile.wsdl
Double click in
the mediator to edit it. Add a static routing rule to
the GetFileByID operation, of type Service and select References/UCM_GetFile/GetFileByID target service:
Create
the request and reply XSLT mappers:
Make sure you map only the dID element in
the request:
And do an Auto-mapper for
the whole response:
Finally, we can now add and configure
the Service activity in
the BPM process. Drag & drop it to
the embedded subprocess and select
the NormalizedGetFile service and getFileByID operation:
Map both
the input:
...and
the output:
Once this embedded subprocess ends, we will have all attachments (name + payload) in
the attachmentsUCM
variable, which is
the main goal of this sample. But in order to test
everything runs fine, we finish
the sample writing each attachment to a
file. To that end we include a final embedded subprocess to concurrently
iterate through each attachmentsUCM/attachment[] element:
On each iteration we will use a Service activity that invokes a
File Adapter write service. In here we have two important parameters to
set. First,
the payload itself.
The file adapter awaits binary data in
base64 format (string). We have to map it using XPath (Simple mapping doesn't recognize a String as a base64-binary valid target):
Second, we must set
the target filename using
the Service Properties dialog box:
Again, note how we're making use of
the loopCounter index variable to get
the right element within
the embedded subprocess iteration.
Final blog entry about attachments will handle how to inject documents to
Human Tasks from
the BPM process and how to share attachments between different User Tasks. Will come soon.
Again, once I finish will all posts on this matter, I will upload
the whole sample project to java.net.
