Siebel CRM and Oracle Documents Cloud

Service Integration
ORACLE WHITE PAPER | JUNE 2015
Table of Contents

Executive Overview 3

Introduction 4

Functionality 5

Security Considerations 6

Installation 7

Siebel Tools 7

Siebel Application 8

Setup 9

Symbolic URL 9

Encrypting the Password 9

List of Values 11

Configuration Changes 12

Sales Collateral 12

Add New Field 12

Business Service: DOCSServiceSalesCollateral 12

Attachments 13

Add New Fields 13

Business Service: DOCSServiceAttachments: 14

Browser Script 14

Changed Objects 16

Testing 18

1 | SIEBEL CRM - ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Troubleshooting 20

2 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Executive Overview

This document details how to use the Siebel CRM integration with Oracle Documents Cloud Service
for associating files stored in the cloud as attachments to Siebel records.

This white paper is not intended to replace or reuse any of the standard Siebel File Attachments
functionality. It is intended to illustrate how to use the Siebel application with the Oracle Documents
Cloud Service for storing file attachments and documents in the cloud.

The solution is valid for any Siebel CRM deployment where a licensed Oracle Documents Cloud
Service is available. For this white paper, the solution was tested with Siebel Web Client 15.0 running
in Open UI mode and Oracle Documents Cloud Service.

Please note that this technical white paper details an example configuration and the steps
required may be different for various environments and architectures.

3 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Introduction

The solution offered in this white paper provides the following benefits:

 Throughout the Siebel CRM application this solution can be used to store documents in the
cloud rather than on a traditional file system.

 It is possible to view documents in the browser without needing to download them. This also
removes the need for proprietary desktop applications to be installed on client devices. Many
different MIME types are supported by the Documents Cloud viewer.

 The ability to drag-and-drop files effortlessly into the browser and automatically associate
them to the Siebel entity.

 Storing documents in the cloud provides a faster alternative to a traditional file system. By
using the Oracle cloud infrastructure this can reduce the total cost of ownership (TCO) in the
enterprise.

 Using Oracle Documents Cloud Service for document storage provides more scalability in
comparison to the existing file system solutions.

 The ability to share documents with Fusion Cloud CX apps – for example associating folders
to both Siebel CRM and Sales Cloud

 The Documents Cloud user interface applies the user’s browser language setting for display.

4 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Functionality
This document demonstrates two primary use cases for integrating the Oracle Documents Cloud Service with
Siebel CRM that leverage two specific resources in the Documents Cloud REST API; the Folder Resource, and the
AppLink Resource. The REST call returns an XML data structure to Siebel, which can be parsed using the Siebel
Transcode Service. Documentation for the DOCS REST API is available at the following link.

http://docs.oracle.com/cloud/latest/documentcs_welcome/WCCCD/odcs-restapi.htm#WCCCD3724

The primary use cases are:

1. Sales Collateral Library

The example solution is based on a solution for a Sales organization and the process of managing and
sharing sales collateral within a team. A Documents Cloud folder with key content can be provided to all sales
representatives within an applet displayed in a Siebel CRM view.

In this example, the new applet is added to the ‘Opportunity Screen Homepage View’.

Figure 1.Screenshot showing a view where a user can see a document folder in the cloud

2. Attachments

Storing Siebel CRM entity attachments in the cloud provides an easy drag-and-drop interface for contributing
and storing content. Each entity being used would have its own folder in the cloud. When a Siebel user

5 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

 navigates to a specific entity (e.g. Account) and clicks “Cloud Attachments”, a folder is created in Documents
Cloud Service if one does not already exist for that entity.

An Oracle Documents Cloud Service embedded page, known as an “AppLink,” is then displayed granting the
user “Contributor” rights so that the Siebel user can create or delete documents in the folder. The folder ID is
persisted in Siebel CRM so that upon re-entry to the Attachments page, the AppLink is connected to the same
folder for all users accessing the entity’s Attachments page.

In this example, the new applet is added to the ‘Account List View’.

Figure 2.Screenshot showing a view where a user can drag and drop files and also see related documents in the browser.

Security Considerations
It is required to encrypt a password for the Oracle Documents Cloud Service in the Siebel database. This is
performed by a single execution of a Business Service (provided). This will only work on the Siebel Server because
the keyfile.bin which stores the encryption keys does not exist on the Siebel mobile client. The keyfile.bin is provided
as standard, and therefore is the same for all customers, so for a production implementation, new keys should be
placed in the key file before encrypting any data. More information is provided in the Security Guide in Siebel
Bookshelf.

http://docs.oracle.com/cd/E14004_01/books/Secur/booktitle.html

6 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Factors to consider for security:

 The Oracle Documents Cloud Service user has system administration access to all folders and documents
and therefore their authentication parameters should be carefully withheld. Using the AppLink feature of
Documents Cloud, the folder views in Siebel CRM are limited to one folder only (and its sub-folders).

 Web traffic will run on HTTPS and Port 443 by default.

 Web content from the Symbolic URL is generated on the Siebel Server. The Documents Cloud embedded
iFrame contains standard HTML5 compliant pages.

Installation
An overview of the installation steps to enable this solution is detailed below; it is assumed that an existing
subscription to Oracle Documents Cloud Service is available.

For more information on the Oracle Documents Cloud service, please see: cloud.oracle.com/documents

The installation steps for this solution are as follows:-

Siebel Tools
Please note, the steps below use the archive files provided with this white paper and offer a fast way to import the
new objects and changes into the repository.

1. Extract the zip file.

2. Import DOCS.sif. The contents of the SIF file include:

 Project: DocumentsCloudService

 Applet: Document Cloud Applet

o New applet to display the Oracle Documents Cloud Service folder for Opportunities

 Applet: Account Document Cloud Applet

o New applet to discplay the attachments for an Account

 Business Service: DOCSService

o Creates an AppLink to the Sales Collateral library. Returns AppLink URL to an entity field
for use in a Symbolic URL.

o Creates a Folder in Oracle Documents Cloud. Persists Folder GUID in a Siebel entity field.
Creates a corresponding AppLink URL, and returns the AppLink URL to an entity field for
use in a Symbolic URL.

o Includes a function for setting the Document Cloud password.

 Business Component: DOCS Password Encryption

7 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

 o Used for encrypting the Oracle Documents Cloud Service user’s password in the Siebel
database.

 Business Object: DOCSPasswordEncryption

 Table: CX_ENCRYPT_PWDS

o Used for storing the encrypted value for the Oracle Documents Cloud Service user.

3. Observe the proposed changes and choose appropriately to ‘Overwrite’ changes or just keep the default
‘Merge’ option.

4. Apply the table changes (click Apply/DDL > choose Apply)

5. Stop Siebel Server, Compile and deploy the SRF, Restart Siebel Server

Siebel Application
1. Configure the Symbolic URL (see steps in the Setup section)

2. Follow the steps to encrypt the password by running the Business Service in the Simulator (see steps in
the Setup section)

3. Create a new Responsibility (optional) and associate the relevant modified Views

4. Add new List of Values (see Picklists section) depending on which output types you want. This LOV can
also be multilingual.

5. Clear the cache for LOV and Responsibilities accordingly, re-login to Siebel application

8 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Setup

Symbolic URL

When configuring the URL field of the Symbolic URL, use square brackets to represent the AppLink value. Also,
the argument “Append as Argument” must be unchecked. The IFrameStyle height and width can be adjusted as
needed depending on the view.

Append as Argument - When this field is checked (default), the value is added as a URL argument on the outgoing
request. If this field is not checked, the value will be substituted in the text of the outgoing URL.

The FixupName for the Applet may need to be set to OutsideApplication or InsideApplet, depending on where the
IFrame is being placed.

For more information on setting Symbolic URL Arguments, please refer to Siebel Portal Framework Guide >
Integrating External Content > Portal Agent Administration > Defining Symbolic URL Arguments
http://docs.oracle.com/cd/E14004_01/books/PortalFrame/PortalFrameAggExtCont21.html#wp1009178

Figure 3.Configuring the Symbolic URL.

Figure 4.Configuring the Symbolic URL Arguments

Encrypting the Password

The steps to encrypt the password are outlined below:

9 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

 1. Navigate to Site Map  Administration – Business Service  Simulator

2. Navigate to the Simulator tab.

3. Create a new record in the top applet to run the business service DOCSService and the method
SetPassword.

Figure 5.Running the Business Service in the simulator.

4. Create a new record in the Input Arguments applet. Open the Property Name MVG and create a new
property with name=’New Password’ and value=<your new password>

Figure 6.Viewing the password value in the database.

5. Click “Run”

10 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

System Preferences
Configuration values for the Oracle Documents Cloud Service REST API calls can be stored in System Preferences

System Preferences can be either entered in Siebel Tools (Screens > System Administration > System Preferences)
or in the web client (Administration – Application > System Preferences).

1. Add the following system preferences:

SYSTEM PREFERENCES

Name Value Comments

DOCSUser myusername@oracle.com Documents Cloud username

DOCSHost https://domain.documents.us2.o Host and port of Documents Cloud
raclecloud.com
DOCSAppLinkRestReso /documents/api/1.1/applinks/fold The folder created for the current entity will
urce er/ need an AppLink created. This is the rest
resource path for creating an applink. A GUID
must be added to the end of this path.
DOCSCreateFolderReso /documents/api/1.1/folders/ REST resource path for creating folders in
urce DOCS. The DOCSAttachmentsTopFolderGUID
will be added to the end of this string when
creating a new folder to store an entity’s
attachments.
DOCSAttachmentsBusin Account This defines what type of Entity the business
essObject service is being used on. This could be Oppty,
or other business object depending on which
Siebel entity is being configured.
DOCSAppLinkRestReso /documents/api/1.1/applinks/fold REST resource path for creating AppLinks in
urce er/ DOCS. A GUID gets added to the end of this
path when creating an AppLink to a specific
folder.
DOCSAttachmentsTopF GUID value of a folder that Top level folder where sub folders will be
olderGUID already exists in DOCS. created. Customers may desire a different top
level folder for Account, Opportunity, Suspects,
etc – a “top” folder for each of the different entity
types. This demonstration just creates one
folder. Another option would be to have a
different DOCS user for each Siebel entity
where attachments are being used – One
DOCS user for Accounts, another for
Opportunities, another for Suspects, etc. This
would give complete separation in DOCS from
one set of attachments to another.
DOCSSalesCollateralGU GUID to the Sales Collateral This is a fixed GUID value that will load every
ID Library folder in DOCS. time in the business service for the Sales
Collateral demo.

11 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Manual Configuration Steps
The DOCS.sif file includes the changed repository objects, detailed here are also the manual steps to create the
same.

Sales Collateral
The following configuration changes and primary properties are contained in the archive files associated with this
white paper, the changes include creating a new field that calls a business service method.

Add New Fields

To enable the Sales Collateral functionality requires only a single field creation. Since this scenario creates an
AppLink for the same folder every time, there is no need to persist any folder GUIDs in the Siebel database.

DocumentCloud: A calculated field for holding the name of the Symbolic URL. Calculated value =
“DocumentCloud” (the name of the Symbolic URL setup earlier).

DOCSAppLinkURL: A field used for holding the AppLink URL, which is then used in the Symbolic URL to display
the Oracle Documents Cloud Service page. It is important to include the Siebel CRM entity [Id] field, and the entity
description value [Name] since that identifies the Siebel CRM entity and is used for the Documents Cloud folder ID
and Description. The last parameter is the return value from the Business Service.

Calculated Value:

InvokeServiceMethod("DOCSService","DOCSAppLinkSalesCollateral", "idFieldVal=eval([Id])","appLinkURL" )

Figure 9. New field creation in Tools

Business Service: DOCSService

Business Service Method: DOCSAppLinkSalesCollateral

The Business Service performs the following steps:

12 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

 1. Use the LOV folder GUID (DOCSSalesCollateralGUID) to create an AppLink request via REST to Oracle
Documents Cloud Service. Preserve the refresh and access tokens in profile data, and return the
AppLink URL.

2. Symbolic URL loads the URL.

3. Browser script event handler passes the access and refresh tokens to the iFrame when the event
“appLinkReady” occurs.

Attachments
The following configuration changes and primary properties are contained in the archive files associated with this
white paper; the changes include creating two new fields that calls a business service method.

Add New Fields

For Attachments functionality two new fields are required: one for storing a Oracle Documents Cloud Service folder
GUID, and the other for the AppLink URL. Edit a project for where you wish to add Documents Cloud as the
attachments option. In this example, “Account” is the project being used. Sample names for the fields are detailed
below with descriptions.

DocumentCloud: A calculated field for holding the name of the Symbolic URL. Calculated value =
“DocumentCloud” (the name of the Symbolic URL set up earlier).

DOCSAppLinkURL: A field used for holding the AppLink URL, which is then used in the Symbolic URL to display
the Oracle Documents Cloud Service page. It is important to include the Siebel CRM entity [Id] field, and the entity
description value [Name] since that identifies the Siebel CRM entity and is used for the Documents Cloud folder ID
and Description. The last parameter is the return value from the Business Service. Note that the “entityDescription”
parameter passed into the business service will be used as the description on the Oracle Documents Cloud
Service folder.

Calculated Value:

InvokeServiceMethod("DOCSService","DOCSAppLinkAttachments",
"idFieldVal=eval([Id]),entityDescription=eval([Name]),folderGUID=eval([DOCSFolderGUID])","appLinkURL" )

DOCSFolderGUID: A field used for persisting/querying a Oracle Documents Cloud Service folder ID related to the
entity. Note that this field must be linked to a column in a Siebel CRM table. For example, extend the S_ORG_EXT
to have a column called X_DOCS_GUID or use one of the extension fields in S_ORG_EXT_X. A varchar field of
around 255 characters long should suffice. The Oracle Documents Cloud Service folder GUID can then be
persisted to the column in the Business Service for subsequent calls. Set Force Active = True for this field.

13 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

 Figure 10. New field creation in Tools

Business Service: DOCSService:

Business Service Method: DOCSAppLinkAttachments

Only two REST calls to Oracle Documents Cloud Service are needed in the Business Service. One to create a
folder (if needed) and one to create an AppLink URL. The Business Service performs the following steps:

1. Get the entity ID.

2. Check if an Oracle Documents Cloud Service folder is already created for this entity.

a. If no folder has been created, call the Oracle Documents Cloud Service REST service to create
a new folder. Persist the folder GUID to the database.

3. Use the folder GUID to create an AppLink request via REST to Oracle Documents Cloud Service.
Preserve the refresh and access tokens in profile data, and return the AppLink URL.

4. Symbolic URL loads the URL.

5. Browser script event handler passes the access and refresh tokens to the iFrame when the event
“appLinkReady” occurs.

Browser Script
Event handling is performed in the Applet_Load browser script. Once the AppLink URL loads, handling of the
event “appLinkReady” must be done to display the page. The access token and refresh token must be passed to
the iFrame. The following sample code works for both use cases.

14 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

 Figure 11.Applet_Load script in Tools

The script for Applet_Load is detailed below:

function Applet_Load ()
{
console.log("applet_preinvoke method called");

$( document ).ready(function() {
console.log("applet_preinvoke method called in ready function");
function OnMessage (evt) {
if (evt.data.message === 'appLinkReady') {
console.log("OnMessage invoked for appLinkReady event...");
var dAppLinkRefreshToken = theApplication().GetProfileAttr("appLinkRefreshToken");
console.log(dAppLinkRefreshToken);
var dAppLinkAccessToken = theApplication().GetProfileAttr("appLinkAccessToken");
var dAppLinkRoleName="contributor";
var embedPreview = "true";

//Assuming only 1 iframe exists on Siebel page. If more than this, will need refined selection of
iframe to send the message to.
var iframe= $("iframe")[0];
var iframewindow= iframe.contentWindow ? iframe.contentWindow :
iframe.contentDocument.defaultView;
var msg = {
message: 'setAppLinkTokens',
appLinkRefreshToken:dAppLinkRefreshToken,
appLinkAccessToken:dAppLinkAccessToken,
appLinkRoleName:dAppLinkRoleName,
embedPreview: embedPreview
}
console.log("applet_preinvoke, sending message to iframe with access and refresh tokens");

iframewindow.postMessage(msg, '*');
}
};
window.addEventListener && window.addEventListener('message', OnMessage, false);
});
}

15 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Changed Objects

APPLETS

NAME BUSCOMP COMMENTS

Documents Cloud Opportunity Applet which displays the embedded Documents Cloud page
Applet

BUSINESS COMPONENTS

NAME TABLE COMMENTS

DOCS Password CX_ENCRYPT_PWDS This BC is used for Password Encryption

Encryption

BUSINESS OBJECTS

NAME COMMENTS

DOCSPasswordEncryption BusComps: DOCS Password Encryption

BUSINESS SERVICES

NAME COMMENTS

DOCSService Generic business service for mapping to Service Documents

Methods: DOCSAppLinkAttachments

DOCSServiceAttachments Generic business service for mapping to Sales Documents

Methods: DOCSAppLinkSalesCollateral

16 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

TABLE

NAME COMMENTS

CX_ENCRYPT_PWDS Table to store encrypted password

VIEWS

NAME COMMENTS

Opportunity Screen Homepage View Modifed View to include Documents Cloud Applet

17 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Testing
This section outlines how the integration can be easily tested.

The AppLink should load the folder that was created. With the AppLink, access is locked down only to this folder and
no navigation allows the user to go elsewhere, even if the open the applink in a new window using the popout icon.

Login to Oracle Documents Cloud Service outside of Siebel. The user that owns the file is the folder owner (e.g. the
user defined in the LOV for calling REST Services).

Figure 12.Screenshot showing view where user can drag and drop files and also view related documents in the browser.

The files that are added to the folder will show the owner as the Oracle Documents Cloud Service user, but the
created user will be the Siebel username.

18 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

 Figure 13.Screenshot showing view where user can drag and drop files and also view related documents in the browser.

Current known limitations of this solution:

 Currently all Applinks are created with the “Contributor” role. There may be a need for business context specific
Applinks for different Siebel users based on a user’s permissions on the entity.

 This demo only enables Oracle Documents Cloud Service attachments for the Account entities. If this was
needed on other views, additional configuration may be needed. In particular, in the LOV setup additional “top
folder GUID” values may be needed, such as a top level folder for Contacts, Opportunities, etc. Likewise, the
Business Service is hardcoded to look for “DCSTopFolderGUID”, but the eScript code would need to seek a
specific GUID for Contacts and Opportunities if this was to be enabled elsewhere in the Siebel CRM instance.

 The Oracle Documents Cloud Service user interface does not dynamically adopt the Siebel CRM application
language settings for the Siebel user. The language needs to be set in the browser settings.

 For Account integration, it was noticed that for some sample Accounts such as ‘AG Edwards & Sons, Inc’
where the name contains special characters, the page did not render. This would require encoding to be
included in the Business Service.

19 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Troubleshooting
Common troubleshooting issues are documented here.

AREA DESCRIPTION

REST Service Issue with certificate on calling REST services in Business Service

This note’s solution can be applied to fix the issue.

Note: 1335511.1 - Outbound Web Service SBL-EAI-04116: HTTP Internet Exception during 'Data Send': '', code: '12057'

Log in to the Siebel Server console as the OS user and open Internet Explorer:

In Internet Explorer > Tools > Internet Options > Advanced tab

In the Security section, uncheck or clear the box for:

 Check for publisher’s certificate revocation

 Check for server certificate revocation

Close all instances of Internet Explorer.

Stop the Siebel Server and restart

iFrame IFrame height and width

Issue with using the method from Managed Attachments for setting the IFrame height and width.

Need to set it according to this note. However, for width, use 100% instead of 480px to get the IFrame to stretch to full screen.

Name: Style

Required Argument: TRUE

Argument Type: Command

Argument Value: IFramestyle="height: 320px; width: 480px;"

Append as argument: FALSE

Substitute in text: FALSE

Please refer to the following documents on My Oracle Support:

SYMBOLIC URL IN SIEBEL VIEW HAS A DIFFERENT SIZE IN SIEBEL OPEN UI (Doc ID 1534105.1)

20 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION


CONNECT W ITH US
blogs.oracle.com/siebelopenui
facebook.com/oraclecrm
twitter.com/oraclecrm
oracle.com/siebel
21 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION
Oracle Corporation, World Headquarters Worldwide Inquiries
500 Oracle Parkway Phone: +1.650.506.7000
Redwood Shores, CA 94065, USA Fax: +1.650.506.7200
Copyright © 2015, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only, and the
contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other
warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or
fitness for a particular purpose. We specifically disclaim any liability with respect to this document, and no contractual obligations are
formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any
means, electronic or mechanical, for any purpose, without our prior written permission.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and
are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are
trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.0115
Siebel CRM – Oracle Documents Cloud Service Integration
June 2015
Authors: John Bedford, Peter Flies, Jack van Dijk
2 | SIEBEL CRM – ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION