Siebel CRM and Oracle Documents Cloud

Service Integration
ORACLE WHITE PAPER

JUNE 2015

Table of Contents
Executive Overview

Introduction

Functionality

Security Considerations

Installation

Siebel Tools

Siebel Application

Setup

Symbolic URL

Encrypting the Password

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

1 | SIEBEL CRM - ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

18

Troubleshooting

2 | SIEBEL CRM ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

20

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 users 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 entitys 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

Applet: Account Document Cloud Applet

o

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

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.

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.

Includes a function for setting the Document Cloud password.

Business Component: DOCS Password Encryption

7 | SIEBEL CRM ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Used for encrypting the Oracle Documents Cloud Service users password in the Siebel
database.

Business Object: DOCSPasswordEncryption

Table: CX_ENCRYPT_PWDS
o

3.

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

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
urce

/documents/api/1.1/applinks/fold The folder created for the current entity will

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/
urce

REST resource path for creating folders in

DOCS. The DOCSAttachmentsTopFolderGUID
will be added to the end of this string when
creating a new folder to store an entitys
attachments.

DOCSAttachmentsBusin
essObject

Account

This defines what type of Entity the business

service is being used on. This could be Oppty,
or other business object depending on which
Siebel entity is being configured.

DOCSAppLinkRestReso
urce

/documents/api/1.1/applinks/fold REST resource path for creating AppLinks in

er/
DOCS. A GUID gets added to the end of this
path when creating an AppLink to a specific
folder.

DOCSAttachmentsTopF
olderGUID

GUID value of a folder that

already exists in DOCS.

DOCSSalesCollateralGU GUID to the Sales Collateral

ID
Library folder in DOCS.

11 | SIEBEL CRM ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

Top level folder where sub folders will be

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.
This is a fixed GUID value that will load every
time in the business service for the Sales
Collateral demo.

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 users 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 notes 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 publishers 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

Oracle Corporation, World Headquarters

Worldwide Inquiries

500 Oracle Parkway

Phone: +1.650.506.7000

Redwood Shores, CA 94065, USA

Fax: +1.650.506.7200

CONNECT W ITH US

blogs.oracle.com/siebelopenui
facebook.com/oraclecrm
twitter.com/oraclecrm
oracle.com/siebel

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

21 | SIEBEL CRM ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION

2 | SIEBEL CRM ORACLE DOCUMENTS CLOUD SERVICE INTEGRATION