Integrating CRM into IBM WebSphere Portal with Digital Data Connector

(1)

Integrating CRM into IBM WebSphere

Portal with Digital Data Connector

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.

(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.

(4)

(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.

(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

(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.

(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 <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.w3.org/2005/Atom" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:crm="http://www.ibm.com/social/crm"> <xs:import namespace="http://www.ibm.com/social/crm" schemaLocation="crm.xsd"/> <xs:element name="feed"> <xs:complexType> <xs:sequence>

<xs:element name="id" form="unqualified" type="xs:string"/>

<xs:element name="title" form="unqualified" type="xs:string"/>

<xs:element name="updated" form="unqualified" type="xs:string"/>

<xs:element maxOccurs="unbounded" ref="atom:entry"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="entry"> <xs:complexType> <xs:sequence> <xs:element ref="atom:id"/> <xs:element ref="atom:title"/> <xs:element ref="atom:updated"/> <xs:element ref="atom:content"/> <xs:element ref="crm:contact"/> </xs:sequence> </xs:complexType> </xs:element>

<xs:element name="id" type="xs:string"/> <xs:element name="title" type="xs:string"/> <xs:element name="updated" type="xs:string"/> <xs:element name="content" type="xs:string"/> </xs:schema>

2. Create a text file named CRM.xsd with the following contents: CRM.xsd <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.ibm.com/social/crm" xmlns:atom="http://www.w3.org/2005/Atom"

(9)

<xs:complexType> <xs:sequence>

<xs:element name="Id" type="xs:string"/>

<xs:element name="FamilyName" type="xs:string"/> <xs:element name="GivenName" type="xs:string"/> <xs:element name="City" type="xs:string"/> <xs:element name="PostalCode" type="xs:string"/> <xs:element name="Phone" type="xs:string"/> <xs:element name="Email" type="xs:string"/> <xs:element name="Account" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="note"> <xs:complexType> <xs:sequence>

<xs:element name="Id" type="xs:string"/> <xs:element name="Title" type="xs:string"/> <xs:element name="Body" type="xs:string"/> <xs:element name="ParentId" type="xs:string"/> </xs:sequence>

</xs:complexType> </xs:element>

</xs:schema>

3. Create a text file named FEED-NOTE.xsd with the following contents: FEED-NOTE.xsd <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.w3.org/2005/Atom" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:crm="http://www.ibm.com/social/crm"> <xs:import namespace="http://www.ibm.com/social/crm" schemaLocation="crm.xsd"/> <xs:element name="feed"> <xs:complexType> <xs:sequence>

<xs:element name="id" form="unqualified" type="xs:string"/>

<xs:element name="title" form="unqualified" type="xs:string"/>

<xs:element name="updated" form="unqualified" type="xs:string"/>

<xs:element maxOccurs="unbounded" ref="atom:entry"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="entry"> <xs:complexType> <xs:sequence> <xs:element ref="atom:id"/> <xs:element ref="atom:title"/> <xs:element ref="atom:updated"/> <xs:element ref="atom:content"/> <xs:element ref="crm:note"/> </xs:sequence> </xs:complexType> </xs:element>

<xs:element name="id" type="xs:string"/> <xs:element name="title" type="xs:string"/> <xs:element name="updated" type="xs:string"/>

(10)

<xs:element name="content" type="xs:string"/> </xs:schema>

(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

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.

(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.

(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:

<?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> <id xmlns="">GetContacts</id>

<title xmlns="">Get Contacts Feed</title> <updated xmlns=""/> <link href="https://eval-provide.castiron.com/env/Development/getcontactspaged?limit=3&offset=0 " rel="first"/> <link href="https://eval-provide.castiron.com/env/Development/getcontactspaged?limit=3&offset=7 " rel="last"/> <link href="https://eval-provide.castiron.com/env/Development/getcontactspaged?limit=3&offset=4 " rel="next"/> <totalResults xmlns="http://a9.com/-/spec/opensearch/1.1/">10</totalResults> <startIndex xmlns="http://a9.com/-/spec/opensearch/1.1/">1</startIndex> <itemsPerPage xmlns="http://a9.com/-/spec/opensearch/1.1/">3</itemsPerPage> <entry> <id>003w000001G6rD7AAJ</id> <title>Amado</title> <updated/>

<content>See contact data within Contact nodes</content> <contact xmlns="http://www.ibm.com/social/crm"> <Id>003w000001G6rD7AAJ</Id> <FamilyName>Amado</FamilyName> <GivenName>Ted</GivenName> <City>London</City> <PostalCode>SE11AB</PostalCode> <Phone>+441784445000</Phone> <Email>tamado@renovations.com</Email> <Account>001w000001ApWumAAF</Account> </contact> </entry>

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.

(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”.

(15)

(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”

(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”

(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

(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

(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

(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.

(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 <id>, <title> 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.

<namespace>.Name

e.g. crmContact.Name=ibm.portal.crm <namespace>.ItemAttribute.id

(23)

<namespace>.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.

<namespace>.ItemAttribute.Item.<metatdata> 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 updateproperties DPortalAdminId=<yourportalid> DPortalAdminPwd=<yourportalpwd> -DWasUserId=<yourwasid> -DWasPassword=<yourwaspwd>

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.

(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 <feed>. Finally ListItemSelection is the repeating element the sample will be working within.

(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.

(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.

(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

(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 /envto /envqand the parameter ?ciUser=<username>&ciPassword=<password>. 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

(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:

<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.cs s"> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap-theme.min.css"> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"> </script>

<style>

html {

font-size: 14px; }

</style>

[Plugin:Equals text1="open" compute="once" text2="[Plugin:ToolbarState compute='once']"]

[EditableElement context="current" type="content" key="path" mode="inplace"]

[Element context="current" type="content" key="path" ifempty="Feed URL here..."]

[/EditableElement]

<h4>Results per feed (limit):</h4>

[EditableElement context="current" type="content" key="Results" mode="inplace"]

(30)

[Element context="current" type="content" key="Results"] [/EditableElement]

<h4>Starting position in feed (offset):</h4>

[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]

<! [Plugin:ListRenderingContext action="getExceptionMessage" key="id"] -->

[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"]

(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:

<h4>Contacts</h4>

[Component name="ddc sample crm/fragments/navigation"] <table class="table table-hover">

<tr> <th>Name</th> <th>Surname</th> <th>City</th> <th>Post Code</th> <th>Phone</th> <th>Email</th> </tr> Result Design: <tr>

<td><a href="[Component name="ddc sample crm/fragments/contact link"]">[AttributeResource attributeName="givenName"

separator=","]</a></td>

<td>[AttributeResource attributeName="familyName" separator=","]</td>

<td>[AttributeResource attributeName="city" separator=","]</td> <td>[AttributeResource attributeName="postalCode" separator=","]</td> <td>[AttributeResource attributeName="phone" separator=","]</td> <td>[AttributeResource attributeName="email" separator=","]</td> </tr> Footer: </table> <br/>

[Component name="ddc sample crm/interaction forms/add contact form"] No result Design:

Whoops, no results. Check the debug.

(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:

<h4>Notes</h4>

[Plugin:SessionAttribute key="addContactResult"] <table class="table table-hover">

<tr> <th>Title</th> <th>Description</th> </tr> Result Design: <tr> <td>[AttributeResource attributeName="title" separator=","]</td>

<td>[AttributeResource attributeName="body" separator=","]</td> </tr>

Footer:

</table> <br/>

No Result Design:

[Component name="ddc sample crm/fragments/no notes result"]

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:

(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:

<li><a href="[Component name="ddc sample crm/fragments/first link"]">First</a></li>

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

<li><a href="[Component name="ddc sample crm/fragments/previous link"]">Previous</a></li>

[/Plugin:ifNotEmpty]

(34)

Name: No Notes Result

Display Name: No Notes Result HTML Markup:

<h4>No notes</h4>

<p>Select a contact to display a list of associated notes<p>

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. <input type="hidden" name="ddc.itemattribute.operation.addGivenName" value="action=set,itemAttributeName=givenName" />

2. <input id="givenName" class="form-control" type="text"

name="ddc.itemattribute.value.addGivenName" placeholder="Given Name" />

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.

(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:

<input type="button" value="New Contact"

onclick="document.getElementById('addContact').style.display =

'block';this.style.display='none';" class="btn btn-primary btn-sm" />

<form role="form" id="addContact" method="POST" style="display:none" enctype="multipart/form-data" action="[Plugin:ActionURL

param="resultSessionAttribute=addContactResult" action="post" copyCurrentParams="true"]">

<h4>New Contact</h4>

<p>Fill in the fields below then click the <mark>Add Contact</mark> button to create a new contact in the CRM system.</p>

(36)

<input type="hidden" name="ddc.uri.template"

value="wcmrest:LibraryHTMLComponent/[Component name="ddc sample crm/interaction templates/add contact" format="id"]"/>

<label for="givenName">Given Name:</label> <input type="hidden"

name="ddc.itemattribute.operation.addGivenName" value="action=set,itemAttributeName=givenName" />

</div>

<label for="familyName">Family Name:</label> <input type="hidden"

name="ddc.itemattribute.operation.addFamilyName" value="action=set,itemAttributeName=familyName" />

</div>

<label for="postalCode">Postal Code:</label> <input type="hidden"

name="ddc.itemattribute.operation.addPostalCode" value="action=set,itemAttributeName=postalCode" />

</div> <div class="form-group"> <label for="telephone">Telephone:</label> <input type="hidden" name="ddc.itemattribute.operation.addPhone" value="action=set,itemAttributeName=phone" />

<input id="telephone" class="form-control" type="text" name="ddc.itemattribute.value.addPhone" placeholder="Phone" /> </div> <div class="form-group"> <label for="email">Email:</label> <input type="hidden" name="ddc.itemattribute.operation.addEmail" value="action=set,itemAttributeName=email" />

<input id="email" class="form-control" type="email"

name="ddc.itemattribute.value.addEmail" placeholder="Valid Email Address" /> </div> <div class="form-group"> <label for="accountId">Account:</label> <input type="hidden" name="ddc.itemattribute.operation.addAccount" value="action=set,itemAttributeName=account" />

</div>

(37)

btn-<input type="button" value="Cancel" class="btn btn-default btn-sm" onclick="document.getElementById('addContact').style.display='none'"/> </form>

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: <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom"> <id/> <title/> <updated/> <content/> <contact xmlns="http://www.ibm.com/social/crm"> <FamilyName></FamilyName> <GivenName></GivenName> <City></City> <PostalCode></PostalCode> <Phone></Phone> <Email></Email> <Account></Account> </contact> </entry>

(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

(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.

(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.

(41)

Appendix

Troubleshooting and optional steps

When using DDC you may run into circumstances when something doesn’t work as expected or you receive no results. In this situation you should enable tracing on the server. From the Portal administrative interface (Portal Analysis > Enable Tracing) set the following parameters and review the results in the trace.log file located in your <profile>\logs\WebSphere_Portaldirectory.

com.ibm.workplace.wcm.pzn.xml.*=all

com.ibm.workplace.wcm.pzn.plr.renderingplugins.*=all

The WCM Plugin:ListRenderingContext tag can also be used to render out useful messages to understand errors that may be occurring, action="getExceptionMessage" and

action="getExceptionHttpStatusCode" can be used to return any exception messages and HTTP responses such as a 401.

The action="dumpList" will also provide details information about all ListBeanProvider profiles and related information. It is best that this tag be enclosed within HTML comments for example:

Public Render Parameters (PRP)

Information is passed within the page through the use of PRPs, in order to validate that this is happening the page state can be viewed, and also the values of any PRPs.

From the URL, select the entire content to the right of port value (including the /), if no port is used then select to the right of the domain name. Revise the URL to state

/wps/mycontenthandler?uri=state: and paste the text you copied, e.g.

http://<domainname>:10039/wps/mycontenthandler?uri=state:<your URL> Reloading ListRenderingProfile

If you add additional attributes to the ListRenderingProfile service they will not be known to the system until after a server restart. In order to address this and not to restart the server each time create a HTML component that contains:

[Plugin:ListRenderingContext action="reloadProfiles" compute="once"] Profiles successfully reloaded.

Add the new HTML component to a Web Content Viewer portlet on a separate page. Accessing the page will cause a reload of the profile service and any additional attributes can be used.

When using the TAG Helper UI you will have noticed that the drop down menu lists the attributes from the ListRenderingProfile, for example familyName. This particular attribute is easily read, however could be better displayed as Family Name. Also, if we were reading these attributes in France or Germany it would be ideal for these to say Nom de famille for French and Familienname for German. Our sample doesn’t extend to showing how this can be achieved but you can read more about Language support in the Knowledge Center.

(42)

Stuart Crump

IBM Certified L2 Senior IT Specialist, IBM Collaboration Solutions

Daniel Kilpatrick – IBM IT Specialist, IBM Collaboration Solutions

Special thanks go to Andreas Nauerz, Thomas Steinheber, Dieter Buhler, Matthias Falkenberg, Stefan Koch and Graham Harper for help during the creation of the sample application and reviewing of this final document.

Integrating CRM into IBM WebSphere Portal with Digital Data Connector