Integrating CRM into IBM WebSphere Portal with Digital Data Connector

Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Introduction              1




Integrating CRM into IBM WebSphere
Portal with Digital Data Connector
Table of Contents
Introduction ............................................................................................................................................ 2
The Sample solution................................................................................................................................ 3
   Components ........................................................................................................................................ 3
       IBM WebSphere Portal including IBM Web Content Manager ...................................................... 3
       IBM® Digital Data Connector (DDC) ................................................................................................ 3
       Cast Iron .......................................................................................................................................... 3
       CRM System – Salesforce Sales Cloud ............................................................................................ 3
Prerequisites ........................................................................................................................................... 5
       IBM WebSphere Portal ................................................................................................................... 5
       DDC ................................................................................................................................................. 5
       WebSphere Cast Iron ...................................................................................................................... 5
       Salesforce ........................................................................................................................................ 5
Creating Salesforce content .................................................................................................................... 6
Creating the Cast Iron project ................................................................................................................. 8
   Creating the Cast Iron Project: Get Contacts .................................................................................... 11
   Creating the Cast Iron Project: Get Notes......................................................................................... 16
   Creating the Cast Iron Project: Add Contact ..................................................................................... 17
   Testing / Calling a feed...................................................................................................................... 20
Displaying Salesforce results in WebSphere Portal .............................................................................. 21
   Create the DDC profiles .................................................................................................................... 21
   Enabling SSL ...................................................................................................................................... 25
   Configuring the WebSphere Portal Proxy ......................................................................................... 26
   Credential Vault ................................................................................................................................ 27
   Creating the WCM Components ....................................................................................................... 28
Creating Configuration Content ............................................................................................................ 38
Testing the DDC application.................................................................................................................. 39
Conclusion ............................................................................................................................................. 40
Appendix ............................................................................................................................................... 41
   Troubleshooting and optional steps ................................................................................................. 41
Authors.................................................................................................................................................. 41




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Introduction    2




Introduction
The aim of this sample is to demonstrate the use of IBM WebSphere Portal’s Digital Data Connector
(DDC) component to display customer information from an external CRM system within the context
a portal site. IBM Cast Iron was used as the integration layer to consume the CRM information using
out-of-the-box adapters, from Salesforce Sales Cloud in this case, and provide a feed for the DDC
control. IBM Web Content Management (WCM) portlets then allow the customised display of the
data in keeping with the portal user experience. This document describes the required components
and steps to recreate the solution.




Figure 1 - Solution Overview

The DDC component provides a simplified approach to integrating and interacting with content
external to WebSphere Portal. Already extensively used in rendering social-based content from IBM
Connections, the DDC component can be used to integrate many other content sources. This article
walks you through how to present and interact with Salesforce Sales Cloud CRM content using a
combination of IBM Cast Iron as an integration layer and IBM WebSphere Portal to consume and
display.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Integrating CRM into IBM WebSphere Portal with Digital Data Connector
The Sample solution     3



The Sample solution
Using an intermediary Cast Iron orchestration this article provides the outline steps for building a
solution to integrate customer related content from Salesforce into an IBM WebSphere Portal digital
user experience. This section reviews the sample components and prerequisites needed.

Components
IBM WebSphere Portal including IBM Web Content Manager
A market leader in integrating content and applications to deliver a single role-based digital
experience framework for businesses. WebSphere Portal has a heritage and comprehensive list of
rich features that include security, integrated web content management, content targeting, virtual
portals and more.

IBM® Digital Data Connector (DDC)
A new component in WebSphere Portal v8.0.0.1 CF11 and onwards, DDC provides a powerful
framework to integrate data from external data sources on your portal pages by using IBM Web
Content Manager presentational components. External data is not stored directly but rendered
virtually so updates can be immediately seen.

DDC is an extensible framework which provides an open approach to rendering many different types
of data sources including news feeds, task lists, contact information, product catalogue information
and many others. By default, XML (e.g. ATOM / RSS) sources can be integrated with no extra coding.

Cast Iron
Cast Iron Live delivers a hybrid solution capability for integrating multiple data sources through
visual orchestrations created in an on-premise client application. It is hybrid because it’s delivered
through the cloud, hypervisor a physical appliance. It provides a minimal or no-coding approach to
integrating data sources such as Salesforce.com, SAP, databases and many others.

CRM System – Salesforce Sales Cloud
Salesforce Sales Cloud is a popular Customer Relationship Management (CRM) system that is
accessible entirely through a web browser interface on a cloud platform. Salesforce has standard
CRM elements which can be extended. Other CRM systems could easily be used and are also
supported by standard Cast Iron components.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Integrating CRM into IBM WebSphere Portal with Digital Data Connector
The Sample solution   4




Figure 2 - Component relationship (DDC omitted)




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Prerequisites   5



Prerequisites
In order to build the sample application described below the following requirements must be in
place.

IBM WebSphere Portal
WebSphere Portal including IBM Web Content Manager is required to use this sample. As
mentioned before DDC requires the version of WebSphere Portal to be at least v8.0.0.1 CF11. For
installation steps please refer to the official documentation instructions, a trial version is also
available from here: https://ibm.biz/BdEbZN

DDC
No prerequisites required as this is included with WebSphere Portal at the correct version level.

WebSphere Cast Iron
WebSphere Cast Iron Cloud allows for integration of both cloud and on-premise applications. In this
guide we use Cast Iron to read in CRM data from Salesforce Sales Cloud and provide a feed to Portal
which is consumed by DDC. You will need a Cast Iron Live account, you can sign up for a 30 day trial
here (unless an IBM employee): http://www-01.ibm.com/software/integration/cast-iron-live/trial/

NOTE: Cast Iron supports Java 7

Salesforce
Salesforce Sales Cloud was chosen for this sample due to its cloud-based nature, accessibility
through APIs and availability of trial and developer accounts. To produce this sample you will need
access to a Salesforce Sales Cloud account; you can sign up for a developer account here:
https://developer.salesforce.com/

NOTE: When you create your Salesforce.com password avoid the hash (#) character as this prevents
URL authentication from working.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating Salesforce content     6



Creating Salesforce content

This sample uses the Salesforce Sales Cloud platform as a background source of CRM data.

    1. Log into the Salesforce Sales Cloud: https://login.salesforce.com/
    2. Firstly you need to reset a security token on your account to allow external service calls:
            o On your user account menu in the top toolbar, select the “My Settings” item
            o Expand the “Personal Category”
            o Select the “Reset My Security Token” option on the left-hand menu
            o Click the Reset Security Token button on this screen
            o Keep a record of your security token which will be sent to you by email
    3. From the main menu at the top of the screen click the plus icon to view “All Tabs”
    4. We will be working with Accounts to create an example company and Contacts. Click on the
       Accounts link (note that some example data is already present but will be ignored for this
       example).
    5. On the Accounts screen, click the New button
    6. The Account Name field is the only mandatory field and also the only field we will need. Fill
       in the Account Name field with “Rennovations Inc” and click the Save button at the top of
       the form.
    7. Now we need some Contacts for the new Account. Scroll down to the contacts section and
       click on the New Contact button




        Figure 3 - Salesforce Sales Cloud New Contact Screen




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating Salesforce content   7


    8. Enter values for the following fields:
            o First Name
            o Last Name
            o Account Name (with our new account name, “Rennovations Inc” which should be
                 prepopulated)
            o Phone
            o Email
            o Mailing City
            o Mailing Zip / Postal Code
    9. Now click Save & New and enter some additional contacts.
    10. Select a contact name from the Recent Items menu.
    11. Using the New Note button located below the contacts details in the Notes & Attachments
        table, create a new note.




        Figure 4 – Add new note(s)

    12. Enter vales for the following fields as shown:
            o Title
            o Body




        Figure 5 - Contact notes

        Click Save when complete. Repeat for more Note entries as required.

    13. The CRM system is now loaded with the data we will surface on our portal CRM page. Take
        note of your user name and password for use in the Cast Iron connection.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project   8



Creating the Cast Iron project

The Cast Iron project we are going to create consists of three orchestrations:

       CRM-get-contact : Returns all contacts for our “Rennovations Inc” account
       CRM-get-notes : Returns all notes associated with a contact
       CRM-new-contact : Creates a new contact in the CRM system

Three XML Schemas are required to return the data in the ATOM format used by DDC.

    1. Create a text file named FEED-CONTACT.xsd with the following content:

        FEED-CONTACT.xsd
         
         
             
             
                 
                      
                          
                          
                          
                          
                      
                 
             
             
                 
                      
                          
                          
                          
                          
                          
                      
                 
             
             
             
             
             
         


    2. Create a text file named CRM.xsd with the following contents:

        CRM.xsd
         
         
             



Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project   9


                 
                     
                         
                         
                         
                         
                         
                         
                         
                         
                     
                 
             

             
                 
                     
                         
                         
                         
                         
                     
                 
             

         



    3. Create a text file named FEED-NOTE.xsd with the following contents:

       FEED-NOTE.xsd
         
         
             
             
                 
                     
                         
                         
                         
                         
                     
                 
             
             
                 
                     
                         
                         
                         
                         
                         
                     
                 
             
             
             
             



Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project   10


             
         




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project     11



Creating the Cast Iron Project: Get Contacts

    1. Log into Cast Iron Live in your web browser https://eval-sl2-70.castiron.com/login and click
       on the Create tab and select “create one from scratch”
    2. Enter a project name “CRM” and click Save
    3. Your new project will now be listed, click on the Pencil icon under Actions in the new row
       and click on Edit Project in Designer to launch the designer tool (launches the Cast Iron
       Studio Java application)
    4. The project will load with a new orchestration open and start and end points shown, with an
       “Add Starter Activity” marker in the middle




        Figure 6 - New Cast Iron orchestration

    5. We need to add a Receive Request activity to handle the request for the feed from DDC.
       Click on the right-hand tabs to change to the Activities pane.
    6. From within the HTTP section, select the Receive Request activity (denoted by a blue
       endpoint icon) and drag it to the empty, “Add Starter Activity” marker.
    7. Once in the orchestration, the properties pane at the bottom of the screen will switch to
       show the properties for this activity. Click on Pick Endpoint in the Checklist, then click on the
       New button.
    8. A new window will open requesting details of the new HTTP endpoint.
        Tick the “Configure for WebSphere Cast Iron Live” box
        All other options will become disabled, click the OK button to close the window
        Now move on to the Configure step. Set the “URL [Path after hostname]” of the request
           to “/getcontacts” then tick the “Requires a Reply” option so that we can return data (our
           feed) as a response to this request.




            Figure 7 - Pick Endpoint properties

           The receive request endpoint is now configured.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project    12


    9. Now we need to add a Salesforce Query Objects activity to retrieve the Salesforce contacts.
        The Query Objects activity, within the Saleforce.com group will allow us to query the
        Salesforce.com environment for the desired information, Contacts in this case. Drag this and
        drop it onto the orchestration after the Receive Request activity.
    10. In the Properties panel, select Pick Endpoint then click New…
    11. Enter your Salesforce.com user name and password then click the Test Connection button.
        If the connection is successful then click “OK” to close the window (leave all other defaults)
        NOTE: This password is your account password with security token appended
    12. Now move on to the Configure step. This requires a query that will request our desired
        information from Salesforce.com. This is defined using SOSQL which is a Salesforce-specific
        SQL language for querying data. Here we are going to select a few fields from the Contact,
        but only for our specified example company (in this case “Rennovations Inc”).

               Copy and paste the SOSQL below into the Specify Query box, then click on the tick
                box to validate the query. If valid then the exclamation marks will change to ticks, if
                there are still problems then you will need to click the exclamation marks to get full
                details.

                SELECT id, AccountId, LastName, FirstName, Phone, Email, MailingCity,
                MailingPostalCode, Account.Name FROM Contact WHERE Account.Name =
                'Rennovations Inc'


               We can skip Map Inputs as we don’t have any inputs for the query.
               For Map Outputs we want to take the Saleforce.com objects and map them to an
                XML object so that we can manipulate the data to match our desired output. Click
                on the Copy button to generate a new output based upon the returned data.
               Pick the XML-based objects parameter then click Create. A new variable will be
                created with the fields correctly mapped (displayed as green mapping lines).




                Figure 8 - Mapping the outputs

               Click on the name objects at the top of the output item (in the “To Orchestration
                panel”) and rename the object to contacts.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project    13


    13. The Salesforce.com object is now mapped to an XML object with the equivalent structure,
        however we need to output our response as an ATOM-based XML feed. First we are going to
        upload an XML schema that defines the format of the feed. This will be a standard ATOM
        feed, but with an additional contacts node within the standard entry node that will hold our
        additional details; the contact details are all within our custom “crm” namespace:

        Sample of CRM XML feed:
         
         
            GetContacts
            Get Contacts Feed
            
            
            
            
            10
            1
            3
            
               003w000001G6rD7AAJ
               Amado
               
               See contact data within Contact nodes
               
                  003w000001G6rD7AAJ
                  Amado
                  Ted
                  London
                  SE11AB
                  +441784445000
                  tamado@renovations.com
                  001w000001ApWumAAF
               
            


    14. From the project tab on the right, click the add document icon in the top toolbar then select
        XML Schema.
    15. Browse to and select the file feed-contact.xsd, ensure the Type is set to “XML Schema” then
        click OK.
        The CRM namespace and elements are defined within the separate crm.xsd document. If
        this is in the same location as the feed-contact.xsd then it will be automatically located (as
        indicated by the green tick). Click the OK button. Once loaded you will see the new schema
        listed under the XML Schemas section of the project.
    16. Now we need to translate the contacts XML object to our feed XML. Drag a Write XML
        activity from the Transform category onto the orchestration.
    17. On the Configure panel we need to specify the new XML schema that we want to map to.
        Click the Browse… button
              Click the New… button to create a new variable
              Under XML Schemas expand feed-contact, select the feed node then click the Next
                  button.



Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project      14


                Optionally name the variable feed-contacts then click the Finish button.
    18.   Select our new feed-contacts variable from the list and click OK.
    19.   The schema will now be listed as our feed. Leave the encoding as “Data is text- Needs no
          encoding”.
    20.   Now select the Map Inputs settings.
    21.   We need to select an input from the orchestration to convert into our XML format. Click the
          Select Inputs… button. Then pick the contacts variable which was the output from the Query
          Objects Activity. Click OK.
    22.   Now we need to map the contact fields to our feed, click and drag the recurring Contact
          node from the left over to the contact node on the right (found within the repeating entry
          node). This will map some fields based upon name, id, phone and email.
    23.   We need to map the remaining fields manually by dragging and dropping:
                     AccountId > Account
                     LastName > familyName
                     FirstName > GivenName
                     MailingCity > City
                     MailingPostalCode > PostalCode
    24.   Optionally we may want to add some values to the standard entry elements such as id and
          title. This will mean information is visible to a feed reader (such as viewing in Firefox). To do
          this right-click on the nodes and select Define default value from the menu. You can also
          map the input fields to the feed fields, putting the LastName in the title field for example.
    25.   Switch to the Map Outputs section. Here we map the XML output to a variable that can be
          used by another activity. Select the XmlText node and click the Copy button.
    26.   In the new window click on the XmlText item listed and click the Create button to create a
          new variable of the same type. These will be automatically mapped.
    27.   The final step is to return our XML feed to the original request. Drag and drop a Send
          Response activity, found under the HTTP section, to the orchestration.
    28.   Under the properties section the Configure section should automatically list Receive
          Request as the Reply To item. If this list box is empty then the Receive Request did not have
          the “Requires a response” box ticked.
    29.   Under the Response Headers configuration tick the “Include pre-defined standard headers”
          box so that we can change the value of the Content-Type header to be XML.
    30.   Switch to the Map Inputs section. Click on the Select Inputs… button
    31.   Pick our XmlText variable and click on the OK button.
    32.   Drag the XmlText object on to “body”.
    33.   Finally set the content type by right-clicking the Content-Type node and picking Define
          Default Value from the menu.
    34.   Enter “application/atom+xml” and click the OK button.
    35.   To check the orchestration, click the Validate Project button in the toolbar.
    36.   Save the project in Cast Iron Designer
    37.   Go to Cast Iron Live and click the Publish icon.
    38.   In Cast Iron Live switch to the Development tab where you should see your project listed as
          un-deployed and not running.
    39.   Click on the green ‘run configuration’ icon to run the project and you will see the status
          change to “Running”.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project   15




       Figure 9 - The complete Get Contacts orchestration




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project   16



Creating the Cast Iron Project: Get Notes
This project orchestration is very similar to the previous example Get Contacts, but it takes a
parameter (the contact name) and returns different XML that contains the Notes fields within the
CRM namespace.

    1. Create a new orchestration called “CRM-Notes-Get” following the previous instructions but
       with the following changes.
    2. For the Receive Request activity:
            Specify an endpoint with the URL of “/getnotes?contactid=contactid”
            On the Map Outputs screen, select the contactid parameter under queryParameters
               and click Copy to create a new variable
    3. For the Query Objects activity, under the Configure property specify the SOSQL query to
       retrieve all notes for a specified contact:

         SELECT id, Title, Body, ParentId FROM Note WHERE Parentid = $contactid


                  Under Map Inputs, wire the contactid variable to the parameters > contactid
                   parameter that was created as a result of the above

    4. Browse to and select the file feed-note.xsd, ensure the Type is set to “XML Schema” then
       click OK.
    5. For the XML Schema used in the Write XML activity, select “feed-note.xsd”




Figure 10 - The complete Get Notes orchestration




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project      17



Creating the Cast Iron Project: Add Contact
This project orchestration is very similar to the first example Get Contacts, but it takes a HTTP post of
an XML block containing new contact information and creates a new Salesforce object. We work
with the same contact XML schema to translate our feed to match the Salesforce structure.




            Figure 11 - The complete Add Contact orchestration

    1. Create a new orchestration called “CRM-Contact-Add” following the previous instructions
       but with the following changes.
    2. For the Receive Request activity, in the Configure section
            specify an endpoint with the URL of “/addcontact”
            Change the method to “POST”




                Figure 12 - Configuring the receive request

             On the Map Outputs section copy the Body output into a new variable, using the
              Copy button, called “input-body”
    3. Add a Read XML activity mapped to the feed-contact object




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project   18


              In the Configure section set the XML Scheme to be the feed-contact




               Figure 13 - Setting the XML scheme or the read activity

               Under Map Inputs wire the variable “input-body” to the XmlText input
               Under Map Outputs wire the OutputXml to the repeating entry node of the variable
                named “feed”
    4. Instead of a Query Objects activity, add a Create Objects activity from the Salesforce.com
       section:
            Under Pick Endpoint select the existing Salesforce endpoint
            Under Configure select the Contact object type then tick the desired fields to create
                (AccoundId, LastName, FirstName, MailingCity, MailingPostalCode, Phone, Email)
            Under Map Inputs, wire the appropriate fields of the “feed” input’s contact node to
                those of the new Contact object




               Figure 14 - Mapping objects

             No outputs need to be set on Map Outputs
    5. In the Send Response section
             Under Configure, ensure that the Reply section is configured to reply to the
               “Receive Request” endpoint




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project   19




               Figure 15 - Reply configuration

             Under Map Inputs nothing needs to be set, but a response code or text can be
              defined to pass a message back to the requesting page if desired
    6. You can now Validate, Publish and Deploy this project.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating the Cast Iron project   20




Testing / Calling a feed
Once a project has been published and running, each orchestration can be called via their defined
trigger points. If you are logged into Cast Iron Cloud then you can test the feed without need to
authenticate by doing the following:

    1. Open a new tab in your browser
    2. Enter the Cast Iron Live address with the endpoint
       e.g.: https://eval-provide.castiron.com/env/Development/getcontacts
    3. The browser will display the response. Browsers such as Firefox will interpret the feed and
       display in a more graphical format. Right-click and View Source to see the XML being
       returned.

The feed can be called from another source with user credentials in the address using the following
method:

https://eval-
provide.castiron.com/envq/Development/getcontacts?ciUser=me@mycompany.com&ciPassword=
my-password1

Note: when adding the authentication parameters to the URL you must also alter the page from
/env to /envq

Note 1: Make a note of the Account ID as you will need that later.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal     21



Displaying Salesforce results in WebSphere Portal

In order for content to be displayed with WebSphere Portal a number of steps need to be followed.
We will use the following areas to do this:

       WebSphere Application Server Administration Console
        the administration console will be used to created entries relating to
        ListRenderingProfileService, a resource environment provider.
       IBM Web Content Manager (WCM)
        DDC relies upon WCM for formatting and presenting the content, we will be using various
        components from WCM to display the Salesforce content.

Create the DDC profiles
In our sample we will be using XML, specifically ATOM. DDC supports XML without the need for
further integration, extension or development. Where the data is not in an XML format you should
familiarise yourself with the DDC documentation as various options exist to develop new plug-ins
and extend the XML one.

The following steps will integrate data by deploying a ListRenderingProfile.

A ListRenderingProfile is required as it defines the set of attributes available through the DDC plug-
in, in our sample this is the default XML DDC plugin and it maps the attributes to their feed values.

    1. Open the WebSphere Administration Console and within the Environment section navigate
       to Resource Environment > Resource Environment Providers > WP
       ListRenderingProfileService | Custom Properties.

        The properties defined here in key value pairs associate the attribute definitions, what you
        see in the WCM AttributeResource tag, to individual XPath expressions.

        Click the New button to create a new key value pairs as shown in the screenshot below.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal    22




        Figure 16 - Contact Attributes

In this sample application crmContact.extends=ibm.portal.atom, this extends the crmContact profile
with the built-in atom profile shipped with DDC. The crmContact profile can now use its own
attributes and those attributes such as the ,  from atom.

It is worth noting that at a minimum a DDC ListRenderingProfile requires the following entries to be
present, if these entries are not present the profile is not seen in the WCM tag helper UI when
selecting a tag type of Attribute Resource.
        .Name
        e.g. crmContact.Name=ibm.portal.crm

        .ItemAttribute.id
        e.g. crmContact.ItemAttribute.id=./atom:id

        .ListItemSelection
        e.g. crmContact.ListItemSelection=//atom:entry




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal     23


         .BeanListProviderID
         e.g. crmContact.BeanListProviderID=ibm.portal.ddc.xml

A repeating node in the XML is denoted by a a ListItemSelection entry, for example the
crm.contact/crm:FamilyName will have a result for every time it occurs within the XML feed.

Note: Entities should always be namespaced to ensure an attribute is not selected from an incorrect
namespace.

Note 1: Whilst not used in this sample, attribute definitions can optionally include metatdata. The
notation for information only as follows, further information can be found in the DDC
documentation.
         .ItemAttribute.Item.
         e.g. crmContact.ItemAttribute.updated.Type=Date
         e.g. crmContact.ItemAttribute.updated.Format=yyy-MM-dd

Note that the .updated item has a Type and Format, these work together.

    2. The sample calls for two ListRendering profiles, the Contact created in step 1 but also a Note
       profile. In order to show a different approach to creating the entries required for a profile
       we will use the command line and ConfigEngine task for this second Note profile. This
       approach is useful if the profile is lengthy or being moved.

    3.   Open a command line terminal and navigate to the /wp_profile/portalserver/config
         directory. Open the file ListRenderingProfileService.properties in a text editor.

         ###################
         # crmNote profile #
         ###################
         crmNote.extends=ibm.portal.atom
         crmNote.NamespaceMapping.crm=http://www.ibm.com/social/crm
         crmNote.NamespaceMapping.atom=http://www.w3.org/2005/Atom
         crmNote.Name=ibm.portal.crmNote
         crmNote.ListProperty.id=/atom:feed/atom:id
         crmNote.ListItemSelection=//atom:entry
         crmNote.ItemAttribute.title=./crm:note/crm:Title
         crmNote.ItemAttribute.parentId=./crm:note/crm:ParentId
         crmNote.ItemAttribute.id=./crm:note/crm:Id
         crmNote.ItemAttribute.body=./crm:note/crm:Body
         crmNote.BeanListProviderID=ibm.portal.ddc.xml


    4. Paste the text listed above at the very bottom of the file below the last line of the existing
       ATOM Profile. Save and close the file. For the changes to the properties file to take effect,
       run the update-properties task from the command line:

         /IBM/WebSphere/Profiles/wp_profile/ConfigEngine/ConfigEngine.sh update-
         properties -DPortalAdminId= -DPortalAdminPwd= -
         DWasUserId= -DWasPassword=

         Note: The command above is for Linux, replace the .sh with .bat for Microsoft Windows.

    5. Review that the changes have been successfully added to the ListRenderingServiceProfile.
       Navigate to the WebSphere Administration Console, Resource Environment > Resource
       Environment Providers > WP ListRenderingProfileService | Custom Properties.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal     24


        Apply the Search term filter shown in the figure below to see the new Note profile.




        Figure 17 - Note profile.

    6. At this stage WebSphere Portal will need restarting for the ListRendering profile to be made
       available for use. At a later stage in this document we will describe an alternative approach
       to reloading the ListRendering profile without the need to restart the server.

Becoming familiar with XPath will be beneficial when working with DDC, there are several tutorials
available online (for example) to do this. In order to help understanding XPath and this sample
application Figure 12 depicts how the XML feed provided by the Cast Iron Live service is mapped to
DDC.

In this case the Salesforce Note item is mapped to the ListRendering profile in WebSphere Portal.
Key attributes are required for DDC and these are called out below, the BeanListProviderID is
ibm.portal.ddc.xml as we are using the built in XML profile. The profile requires a unique name,
ibm.portal.crmNote and the ListProperty.id is set to the top level node of . Finally
ListItemSelection is the repeating element the sample will be working within.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal   25




Figure 18 - Mapping of XML Feed to DDC Profile.

Enabling SSL
With the DDC profiles created the next step is to setup a security trust between WebSphere Portal
and the Cast Iron Live service.

    1. Open the WebSphere Administration Console and under the Security section navigate to SSL
       certificate and key management > Key stores and certificates > NodeDefaultTrustStore |
       Signer certificates.

    2. Click Retrieve from port. Set the field values as shown in the figure below and click the
       Retrieve signer information button.




         Figure 19 - SSL Certificate

    3. The SSL certificate information will be displayed, click OK, then Save to add the certificate
       information to WebSphere.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal   26




       Figure 20 - SSL Signer information

    4. With the SSL certificate retrieved from the Cast Iron Live service WebSphere should now
       display the certificate along with any others you may have installed previously.




       Figure 21 -SSL certificate after import

Configuring the WebSphere Portal Proxy
By default WebSphere Portal proxy service restricts HTTP outbound access to websites. The sample
application will need to request content from the Cast Iron Live URL http://eval-
provide.castiron.com, so this should be added to the proxy configuration.

    1. Open the WebSphere Administration Console, under the Resources section navigate to
       Resource Environment Providers > WP Config Service | Custom properties. Click New.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal   27


    2. Create a new key value pair as shown in the figure below.




        Figure 22 - Proxy Configuration

        wp.proxy.config.urlreplacement.digital_data_connector_policy.castiron=https:
        //eval-provide.castiron.com/*

    3. Click OK, and then Save.

    4. Navigate to Applications > Application Types > WebSphere Enterprise Applications. Select
       the AJAX Proxy Configuration, click the Stop button. When stopped select the AJAX Proxy
       Configuration again and click Start.




        Figure 23 - AJAX Proxy Config Application

Credential Vault
Authentication is required in order to retrieve the XML feed from Cast Iron, requesting the feed via
the HTTP request URL invokes Basic Authentication (Username & Password form).

Access the Portal Administration console, WebSphere Portal > Access > Credential Vault.

Click the Add a vault slot to create a new slot to store the cast Iron username and password.

        Name: castiron
        Vault resource associated with vault slot (new): castiron
        Vault slot is shared: check
        Shared userid: your Cast Iron user id
        Shared password: your Cast Iron password




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal    28


Click the OK button to save the new vault slot.




Figure 24 - New credential vault slot

NOTE: This is for information only, the username and password can alternatively be provided to
Cast Iron within the URL, in order to use this approach the URL environment needs to be modified
from /env to /envq and the parameter ?ciUser=&ciPassword=. This can be
useful for testing purposes.

For example,
https://eval-
provide.castiron.com/envq/Development/trigger?ciUser=sdaryn@.ibm.com&ciPassword=sec
ret

Creating the WCM Components
     1. Open WebSphere Portal and navigate to the Administration > Portal Content > Web Content
        Libraries page.

          Click the Create new library button, use “DDC Sample CRM” as the web content library
          name, optionally provide a description and then save the library by clicking the OK button.

     2. Navigate to the Content > Web Content Authoring Page and using the Preferences > Edit
        Shared Settings option add the newly created library to the Selected Libraries list. Click the
        OK button to save.

Now we have a library in which to store the WCM components, in the next steps will focus on
creating these. As with all components, content or design, we want to provide separation and
points of variability to deliver the best opportunity for re-use and interaction.

     3. Navigate into the DDC Sample CRM library.

     4. Click the New button, select the Authoring Template > Content Template option.

          Name: CRM
          Display Name: CRM
          Description: Authoring template to define CRM based lists

          Click the Manage Elements button and add the following elements, clicking the OK button
          when finished.



Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal   29




       Figure 25 - Elements for user interaction.

       Select the Default Content Properties tab and under the Workflow section deselect the
       “Enable workflow for items…” option. This will remove any need for new content items
       created with this content template to go through a workflow prior to saving. Click the Save
       and Close button.

    5. Click the New button, select Presentation Template option. Presentation templates are
       used as a mechanism to display/format content created with the content templates and
       other WCM components. We will create two in the next steps.

       Name: CRM Contact
       Display Name: CRM Contact
       Description: Presentation template for CRM contact lists.

       Presentation Template Options:
         
         
         
         
         
         

         
         html {
             font-size: 14px;
         }
         

         
         [Plugin:Equals text1="open" compute="once" text2="[Plugin:ToolbarState
         compute='once']"]
         Feed URL:
         [EditableElement context="current" type="content" key="path"
         mode="inplace"]
             [Element context="current" type="content" key="path" ifempty="Feed URL
         here..."]
         [/EditableElement]
         Results per feed (limit):
         [EditableElement context="current" type="content" key="Results"
         mode="inplace"]



Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal   30


             [Element context="current" type="content" key="Results"]
         [/EditableElement]
         Starting position in feed (offset):
         [EditableElement context="current" type="content" key="Start"
         mode="inplace"]
             [Element context="current" type="content" key="Start"]
         [/EditableElement]
         [/Plugin:Equals]

         
         [Plugin:Equals scope="1" text2="" text1="[Plugin:RenderParam
         type='private' key='prParams']"]
         [Plugin:ListRenderingContext extension-id="[Element context='current'
         type='content' key='plugin']" attribute="source=[Element context='current'
         type='content' key='path' htmlencode='false']&limit=[Element
         context='current' type='content' key='Results']&offset=[Element
         context='current' type='content' key='Start']" profile="[Element
         context='current' type='content' key='profile']"]
         [/Plugin:Equals]
         [Plugin:Otherwise scope="1"]
         [Plugin:ListRenderingContext extension-id="[Element context='current'
         type='content' key='plugin']" attribute="source=[Element context='current'
         type='content' key='path' htmlencode='false']&[Plugin:RenderParam
         type='private' key='prParams']" profile="[Element context='current'
         type='content' key='profile']"]
         [/Plugin:Otherwise]

         
         
         

         
         [Element context="current" type="content" key="Appearance"
         compute="always"]


       Click the Save and Close button when complete.

       Name: CRM Note
       Display Name: CRM Note
       Description: Presentation template for CRM notes.

       Presentation Template options:
         
         [Plugin:ListRenderingContext extension-id="[Element context='current'
         type='content' key='plugin']" attribute="source=[Element context='current'
         type='content' key='path'
         htmlencode='false']&contactid=[Plugin:RenderParam type='public'
         key='{http://crm}prp_contactid']" profile="[Element context='current'
         type='content' key='profile']"]

         
         [Element context="current" type="content" key="Appearance"
         compute="always"]


       Click the Save and Close button when complete.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal     31


    6. Navigate to Components and click the New button, select the Folder option. We will use a
       folder called List Appearances to store different visual styles to the content we want to
       display. Click the Save and Close button when complete.

       Name: List Appearances
       Display Name: List Appearances

    7. Navigate to the newly created List Appearances folder and click New > Current View >
       Personalization. The personalisation components will allow us to
           a. Set that we will be using a pluggable resource, mandatory for DDC
           b. Define what page mark-up we want to display using a combination of HTML and
              WCM tags

       Name: Contacts
       Display Name: Contacts

       Within the Personalization Element section click the New button. Click the link Web
       Content, select Pluggable Resources and the click Save button. There is no need to provide a
       description or any other information.

       Header:
         Contacts
         [Component name="ddc sample crm/fragments/navigation"]
             
                 
                 Name
                 Surname
                 City
                 Post Code
                 Phone
                 Email
                 
       Result Design:
                 
                    [AttributeResource attributeName="givenName"
         separator=","]
                    [AttributeResource attributeName="familyName"
         separator=","]
                    [AttributeResource attributeName="city" separator=","]
                    [AttributeResource attributeName="postalCode"
         separator=","]
                    [AttributeResource attributeName="phone"
         separator=","]
                    [AttributeResource attributeName="email"
         separator=","]
                 
       Footer:
             
         
         [Component name="ddc sample crm/interaction forms/add contact form"]
       No result Design:
         Whoops, no results.     Check the debug.

         
         




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal    32




       Click Save and Close.

    8. Within the List Appearances folder click New > Current View > Personalization.

       Name: Notes
       Display Name: Notes

       Within the Personalization Element section click the New button. Click the link Web
       Content, select Pluggable Resources and click the Save button. There is no need to provide a
       description of provide any other information.

       Header:
         Notes
         [Plugin:SessionAttribute key="addContactResult"]

             
                 
                 Title
                 Description
             
       Result Design:
                 
                    [AttributeResource attributeName="title"
         separator=","]
                    [AttributeResource attributeName="body" separator=","]
                 
       Footer:
             
         
       No Result Design:
         [Component name="ddc sample crm/fragments/no notes result"]


       Click Save and Close.

We now have created two different appearances for the CRM content, in the next steps we will
create some of the components referenced in the mark-up, for example the navigation and contact
link HTML components.

    9. Click the New button, select the Folder option. We will use a folder called Fragments to
       store different components like HTML. Click the Save and Close button when complete.

       Name: Fragments
       Display Name: Fragments

    10. Within the Fragments folder we are going to create several new HTML components, create
        each one as described. Once in the Fragments folder click New > Current View > HTML.

       Name: Contact Link
       Display Name: Contact Link
       HTML Markup:




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal   33


         [Plugin:RenderURL pr.mode="set" copyCurrentParams="true"
         pr.key="{http://crm}prp_contactid" pr.type="public"
         pr.value="[AttributeResource attributeName='contactId' separator=',']"]


       Name: First Link
       Display Name: First Link
       HTML Markup:
         [Plugin:RenderURL htmlencode="false" htmlencode="false" htmlencode="false"
         htmlencode="false" pr.mode="set" copyCurrentParams="true"
         pr.key="prParams" pr.type="private" pr.value="[Plugin:ListRenderingContext
         action='getListProperty' key='firstLink']"]


       Name: Last Link
       Display Name: Last Link
       HTML Markup:
         [Plugin:RenderURL htmlencode="false" htmlencode="false" htmlencode="false"
         htmlencode="false" htmlencode="false" htmlencode="false" pr.mode="set"
         copyCurrentParams="true" pr.key="prParams" pr.type="private"
         pr.value="[Plugin:ListRenderingContext action='getListProperty'
         key='lastLink']"]


       Name: Next Link
       Display Name: Next Link
       HTML Markup:
         [Plugin:RenderURL htmlencode="false" htmlencode="false" pr.mode="set"
         copyCurrentParams="true" pr.key="prParams" pr.type="private"
         pr.value="[Plugin:ListRenderingContext action='getListProperty'
         key='nextLink']"]


       Name: Previous Link
       Display Name: Previous Link
       HTML Markup:
         [Plugin:RenderURL htmlencode="false" htmlencode="false" htmlencode="false"
         htmlencode="false" copyCurrentParams="true" pr.key="prParams"
         pr.type="private" pr.mode="set" pr.value="[Plugin:ListRenderingContext
         key='prevLink' action='getListProperty']"]


       Name: Navigation
       Display Name: Navigation
       HTML Markup:
                 

                     First

                 [Plugin:ifNotEmpty value="[Plugin:ListRenderingContext
                 action='getListProperty' key='prevLink']"]
                     Previous
                 [/Plugin:ifNotEmpty]

                     Next

                     Last

         




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal       34




        Name: No Notes Result
        Display Name: No Notes Result
        HTML Markup:
         No notes
         Select a contact to display a list of associated notes


As an additional benefit to displaying content, DDC supports user interfaces for creating, modifying,
and deleting external data. In order to achieve this additional interaction within our application we
need to create some supporting HTML components.

The two main components in our application will be:

       Interaction Form, a HTML form with additional DDC parameters responsible for gathering
        new contact input (e.g. Name, Location, etc..) and sending this back via the generic XML data
        sink
       Interaction Template, a well formed XML document the new contact content will be merged
        with when sent back to the target service

The interaction form component in WCM is a standard HTML form, it utilises several DDC
parameters:

        ddc.method - Identifies the HTTP method, in our application we use a ‘post’

        ddc.uri.target – A URI that identifies the target of the outbound request.
        https://eval-
        provide.castiron.com/env/Development/addcontact?hpaa.slotid=castiron

        ddc.uri.template – Described in Figure 20 it identifies the template XML document that is
        required for set actions. This could be a direct pointer to an entry e.g atom:entry that will be
        modified, or as our sample shows, a skeleton of the XML stored as a HTML component in
        WCM.

        ddc.profile.in – The parameter of the list-rendering profile that you want applied to the data
        returned by the target service, e.g. ‘ibm.portal.crmContact’

        ddc.itemattribute.operation.suffix - A parameter use to modify the template document
        XML.
            1. 
            2. 

In all but the delete scenario the operation is made up of a key value pair. The operation in point 1
above will set what content is be modified e.g ‘itemAttributeName=givenName’. Point 2 denotes
the actual value that is being set, in the sample this is the value input by the user into the form.
Additional optional parameters are detailed in the Knowledge Center.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal   35




Figure 26 - DDC interaction template. ddc.uri.template

The components detailed below will be responsible for gathering a new contact’s information (i.e.
Name, Location, etc...) and passing this back via the generic XML data sink to the target data source.

For good practice we will separate the components as we have been doing previously.

    11. From within Components click the New button, select the Folder option. We will use a
        folder called Interaction Forms to store the HTML we will use to capture the users new
        contact. Click the Save and Close button when complete.

         Name: Interaction Forms
         Display Name: Interaction Forms

    12. Within the Interaction Forms folder we are going to create a new HTML components. Click
        New > Current View > HTML.

         Name: Add Contact Form
         Display Name: Add Contact Form
         HTML Markup:
           

           
           

                  New Contact
                  Fill in the fields below then click the Add Contact
           button to create a new contact in the CRM system.

                  
                  
                  
                  




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Displaying Salesforce results in WebSphere Portal   36


                
                
                
                
                       Given Name:
                              
                              
                
                
                       Family Name:
                              
                              
                
                
                       City:
                              
                              
                
                
                Postal Code:
                       
                       
                
                
                       Telephone:
                              
                              
                
                
                Email:
                       
                       
                
                
                Account:
                       
                       
                
                 




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
37


                
         



       Click Save and Close.

    13. Navigate to Components and click the New button, select the Folder option. We will use a
        folder called Interaction Template to store the HTML skeleton markup we will use to send
        the user’s new contact back in. Click the Save and Close button when complete.

       Name: Interaction Templates
       Display Name: Interaction Templates

    14. Within the Interaction Templates folder we are going to create a new HTML components.
        Click New > Current View > HTML.

       Name: Add Contact
       Display Name: Add Contact
       HTML Markup:
         
         
             
             
             
             
             
                
                
                
                
                
                
                
             
         




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Creating Configuration Content    38



Creating Configuration Content

WCM uses content items for displaying typical website content, for example News, FAQs, Events,
etc. In this sample we will be using content items as configuration to the WCM and DDC
components. The content configuration will provide the information for displaying the Contacts and
Notes coming from the CRM system.

    1. Click the New button, select the Site Area > Default Site Area Template option.

       Name: List Definitions
       Display Name: List Definitions
       Path: /DDC Sample CRM/

       Click the Save and Close button when complete.

    2. Navigate into the newly created List Definition site area. Click the New button, select the
       Content > DDC Sample CRM / CRM option. Note: If CRM is not shown use the Select from all
       Content Templates… option to show additional templates.

       Name: Contacts
       Display Name: Contacts
       List Appearance > Component: /DDC Sample CRM/List Appearances/Contacts
       Path to Feed: https://eval-
       provide.castiron.com/env/Development/getcontacts?hpaa.slotid=castiron
       Profile: ibm.portal.crmContact
       Plugin: ibm.portal.ddc.xml
       Results: 5
       Start: 1

       Click the Save and Close button when complete.

       Click the New button, select the Content > CRM option and create a second content
       configuration items for Notes.

       Name: Notes
       Display Name: Notes
       List Appearance > Component: /DDC Sample CRM/List Appearances/Notes
       Path to Feed: https://eval-
       provide.castiron.com/env/Development/getnotes?hpaa.slotid=castiron
       Profile: ibm.portal.crmNote
       Plugin: ibm.portal.ddc.xml
       Results: 5
       Start: 1

       Click the Save and Close button when complete.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Testing the DDC application    39



Testing the DDC application

Testing the application requires a new portal page to host two Web Content Viewer portlets, these
will be configured to display the Contact and Notes views.

    1. From a suitable location in the portal site and place the page in Edit mode. Create a new
       page using Create > Page > Basic.

        Page Title: CRM

        Click the Create Page button.

    2. Click “Add Content to Page” then select Page > Applications and search for “Web Content
       Viewer”. The type ahead will find it quickly. Add two instances of this portlet to the page,
       one in each column by dragging them to the page.

    3. Still in edit mode select Page > Layout and click on 2 Colum Left. This will space the portlets
       out better.

    4. For the first portlet (Left) that will contain the Contact view, edit the Shared Settings and
       configure as described below, click the OK button when done.

        Content Type: Content Item
        Content: DDC Sample CRM / List Definitions / Contacts
        Alternate Presentation template: DDC Sample CRM / CRM Contact

    5. For the second portlet (Right) that will contain the Notes view, edit the Shared Settings and
       configure as described below, click the OK button when done.

        Content Type: Content Item
        Content: DDC Sample CRM / List Definitions / Notes
        Alternate Presentation template: DDC Sample CRM / CRM Note

You should now see the portlets and page configured as the figure shows below. Take the page out
of edit mode now and you can start to use the application.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
Conclusion     40




Figure 27 - Final sample application

With everything configured selecting a contact name will display any associated notes in the second
portlet on the right, this uses the public render parameter (PRP) defined earlier in the HTML markup
components. Navigating through the contacts using the First | Previous | Next | Last options will
display additional contacts depending upon the number of results you defined earlier.

Conclusion

This article shows that the integration of external CRM based data can be simply achieved and with
no programming involved. Using DDC provides a powerful approach to delivering a unified digital
experience with multiple data sources.




Integrating CRM into IBM WebSphere Portal with Digital Data Connector
You can also read
Next part ... Cancel