Oracle Demantra APIs

Oracle Demantra APIs
An Oracle White Paper

Dec 2010

Oracle Demantra APIs Page 2
Introduction ........................................................................................................ 3
External Login API ........................................................................................... 3
Single Sign On from External Portal ......................................................... 6
Other Key Requirements ............................................................................. 7
Integration Interface APIs ................................................................................ 9
API to Modify Series Attributes ................................................................. 9
API to Modify Fixed Date Definition ..................................................... 10
API to Modify Relative Date Definition ................................................. 11
API to Notify Application Server ............................................................. 11
Integration Interface APIs Use Cases ..................................................... 12
User Profile APIs ............................................................................................ 13
API to Create, Modify or Delete Users ................................................... 13
API to Modify User Security Filters ......................................................... 16
Dynamic open link .......................................................................................... 18

Introduction

Oracle Demantra application provides various APIs to facilitate integration with external/third
party/source system. This white paper details the following APIs with use cases.
External Login API to enable Single Sign On
Integration Interface API
User Profile Creation/Modification API
Dynamic Open Link

External Login API

Single Sign On referred as SSO becoming a common requirement in most of the major
implementations. Customers prefer end users with appropriate responsibility login into Demantra
application via common web portal with global user id maintained externally by customer IT.
In Oracle Demantra, currently Single Sign On (SSO) feature is supported only from EBS source
system where user with appropriate responsibility can login into Demantra application from EBS
without entering user credentials again. User credentials with Demantra Management responsibility
were synced automatically from EBS to Demantra during user profile creation in EBS. For non
EBS customer, Oracle Demantra application provides an external login API to facilitate SSO from
external portal/source system (i.e. EBS).
API named preLogin.jsp is available as part of standard product to facilitate remote login into all
of its modules from external SSO portal or source system. This web page accepts different URLs
(login URL, redirect URL) as IDs instead of URL strings to avoid phishing.
Following sections explains this API and its required parameters in detail with examples. It also
outlines recommended approach to enable SSO with external portals/source system leveraging this
external login API.

Example
http://<SERVER_URL>/<demantra>/common/prelogin.jsp?loginTo=<loginTo
ID>&redirectUrl=<redirectUrl ID>&loginUrl=<loginUrl
ID>&source=0&component=<COMPONENT_ID>&componentowner=1

Following section details the above highlighted parameters.

1. loginTo
Since all modules login mechanisms were united into one, a new parameter was added to the
request called loginTo. This parameter indicates to which module, you wish to login.

loginTo ID Login Module
0 COLLABORATOR_LOGIN
1 ANYWHERE_LOGIN
2 PARTNER_LOGIN
3 ADMIN_PAGES_LOGIN
4 WORKFLOW_LOGIN
5 USER_MANAGEMENT_LOGIN

2. loginUrl and redirectUrl
All significant login pages and landing pages where given a hard coded id, as listed in the following
table:

loginURL ID loginTo URL redirectURL ID Redirect URL
0 adminLogin.jsp 12 personalizeAdminMenu.jsp
1 loginpage.jsp 13 pagebuilder.jsp
2 partnerLogin.jsp
3 anywhereLogin.jsp 14 anywhereConsole.jsp
4 remoteloginpage.jsp
5 userManagement.jsp 15 userManagementConsole.jsp
6 DOLLogin.jsp 16 DOLQueries.jsp
7 StatisticalQueryLogin.jsp 17 StatisticalQueryList.jsp
9 /workflow/login.jsp 18 /workflow/ProcessManager.jsp

3. Component ID

Component ID Component Name
DM Demand Management
PTP Predictive Trade Planning
SOP Sales & Operations
Planning

4. ExternalLogoutUrl

The only URL that is external to the system is the logoutUrl. This parameter should be configured
manually in the Business Modeler as part of the system parameters configuration. A new system
parameter called ExternalLogoutUrl was added to the sys_parms table.

5. URL Examples

For DM Component and Component Owner user

1. Administrator Login:

http://<SERVER_URL>/<demantra>/common/prelogin.jsp?loginTo=3&redirectUrl=12&login
Url=0&source=0&component=DM&componentowner=1

2. Collaborator Workbench Login:


3. User Management Login:


4. Workflow Login:



For DM Component and Non Component User

Do not pass in "componnentowner" unless the UID is indeed the component owner

1. Administrator Login:

Url=0&source=0&component=DM

2. Collaborator Workbench Login:

http://SERVER_URL/demantra/common/prelogin.jsp?loginTo=0&redirectUrl=13&loginUrl=1
&source=0&component=DM

3. User Management Login:


4. Workflow Login:


Single Sign On from External Portal

Oracle Demantra version 7.1.1. & above is certified to work with EBS SSO and its implemented
leveraging preLogin.jsp which was detailed in the previous sections. Same framework can be
leveraged to enable SSO from external portal maintained by customers via third party SSO agents
(i.e. Site Minder).

Following details the software process flow for Oracle Demantra SSO from external portals

1. An end user will access Demantra through an URL embedded in external web portal. This
link should be an invocation to Demantras preLogin.jsp, with all the required URL
parameters.
2. A SSO (i.e. Site Minder) agent should be placed on the Apache web server fronting
Demantra. This is to intercept the end user request and enforce authentication by Site
Minder.
3. After SSO agent validated user's identity, it will pass user's uid as a HTTP header named
proxy-remote-user to Demantra's preLogin.jsp, which is running as a web application in
Web Logic.
4. preLogin.jsp retrieves UID by invoking getRemoteUser() function and authorizes the
request. It streams back the proper web page to the user and sets Demantras own session
cookie

Other Key Requirements

1. Make sure Demantra user credentials were in sync with SSO user credentials. If a user has
the proper credential to pass SSO authentication, but has no corresponding identity in
Demantra's user table, then user will see Demantra's own login page.
2. Get a browser plug-in so that you can inject HTTP header. Use Fiddler for IE, and
TemperData for Firefox.
3. For the preLogin.jsp component owner URL parameters:
a. Do not pass in "componnentowner" unless the User ID is indeed the component
owner
4. Component ID parameter should be populated in upper case (i.e. DM, PTP.etc)
5. To allow proper logout redirect (after the user clicked the "Logout" button"), modify the
Demantra system parameter named ExternalLogoutURL to point it to a URL that makes
sense for your environment. Restart Demantra web application after this parameter change.
6. If Oracle Demantra version 7.3.0.1 or lower and if you are using Oracle Web Logic 10.3,
then you have to start the web logic with the following JVM System flag.
-Dweblogic.http.enableRemoteUserHeader=true


Web Browser
End user access
Demantra from a
link on Web
Portal

Web Server
(i.e. Apache)
SSO Agent
Plug-in
J2EE server (i.e.
Web Logic)
Plug-in
SSO Agent protects
preLogin.jsp,
authenticate user
then set UID as
HTTP header
J2EE server (Web
Logic) Plug-in passes
request with UID as
HTTP header to
backend Web Logic

J2EE Server
(Web Logic)

preLogin.jsp
preLogin.jsp retrieve
UID through
request.getRemoteUser()
function
Demantra SSO Software
Component Layout

Integration Interface APIs

Oracle Demantra provides four APIs to change certain definitions of the Integration Interface data
profile when importing data from source/external system. This API will be helpful in specific
scenarios to reduce the no of Integration interfaces required to support the data load.

API to Modify Series Attributes

The procedural API API_MODIFY_INTEG_SERIES_ATTR can be leveraged to change
the following attributes of the profile series

Load Options
Purge Options

API_MODIFY_INTEG_SERIES_ATTR(ii_profile_id int, ii_series_id int, ii_load_option int,
ii_purge_option int)

It requires following 4 input parameters
ii_profile_id
Refers to internal ID of the concerned Integration interface
Select ID from transfer_query where query_name =<Integration Interface
Name>;
ii_series_id
Refers to internal ID (Series ID) of the concerned series. It can be found in one of
the following ways
Business Modeler > Configure Series > Series ID (General Properties tab)
Select forecast_type_id from computed_fields where computed_title =
<Series Name>;
ii_load_option
o Refers to load option series attribute
0 Override (Overrides the existing series value)
1 Accumulate (Adds to existing series value)
1 No Load (Series wont be loaded)

ii_purge_option
o Refers to purge option series attribute
0 No purge (Data of the series wont be purged from base table before
loading)
1 Purge All (Data of the series for combinations which has got no new
data will be purged from base table for all the time buckets in the system)
2 Purge Within (Data of the series for combinations which has got no
new data will be purged from base table for all time buckets within the
profile time range)

API to Modify Fixed Date Definition

The procedural API API_MODIFY_INTEG_SERIES_FDATE can be leveraged to modify
the profiles fixed date definitions. This API will become irrelevant if integration profile is set to
relative time definition.
API_MODIFY_INTEG_SERIES_FDATE(ii_profile_id int, id_from_date date, id_until_date
date)
ii_profile_id
Name>;
id_from_date
o Populate <from date> in mm/dd/yyyy format
id_until_date
o Populate <until date> in mm/dd/yyyy format

API to Modify Relative Date Definition

The procedural API API_MODIFY_INTEG_SERIES_RDATE can be leveraged to modify
profiles relative time definitions. This API will become irrelevant if integration profile is set to
fixed time definition.

API_MODIFY_INTEG_SERIES_RDATE (ii_profile_id int, id_rel_from_date int,
id_rel_until_date int)


ii_profile_id
Name>;
id_rel_from_date
o Refers to no of weeks to be included backwards from sysdate
id_rel_until_date
o Refers to no of weeks to be included forward from sysdate

API to Notify Application Server

System provides another procedural API named API_NOTIFY_APS_INTEGRATION
which has to be executed once after execution of above APIs to notify application server so it
refreshes the integration interface cache with the changed definitions.

API Execution

All these APIs can be executed via workflow procedure step and it should be executed before the
execution of corresponding transfer workflow step of Integration interface.

Integration Interface APIs Use Cases

Use Case I

In Standard EBS Demantra integration, EBS Price List integration interface brings price data in
31 different series (EBSPriceList0, EBSPriceList100, EBSPriceList101, EBSPriceList102,
..EBSPriceList129) from EBS into Demantra. Typically not all the 31 price fields in EBS will
have data and which of the 31 price fields have data varies from customer to customer. Instead of
changing (removing the unneeded series) the standard EBS Price List integration interface
definition, API API_MODIFY_INTEG_SERIES_ATTR to modify series profile attributes can
be leveraged to turn off the load (Set to No Load) and purge option (Set to No Purge) for the
EBS price list series which dont have data.

Use Case II

In implementations there could be a requirement for Demantra to receive data for different data
streams at same set of aggregation levels but at different time intervals due to various reasons i.e.
different sourcesetc. In such scenarios instead of creating multiple integration profiles for each
data series, one master integration profile with all relevant series can be built and API
API_MODIFY_INTEG_SERIES_ATTR can be leveraged to control the load and purge option
of the individual profile series depending upon which series contains data in the staging table.

For example if there is a need to bring data for 3 different series at Item and Organization level
and each come at different times

Create one Master Integration interface at Item and Organization level for the concerned 3
series
Configure 3 different workflows. Within each workflow call API
API_MODIFY_INTEG_SERIES_ATTR via stored procedure step with all relevant
parameters to change the load and purge options of each affected series. This API has to be
executed for each affected series within the profile. Instead of configuring multiple stored
procedure step in the workflow, alternately simple pl/sql wrapper can be written to call this
API within a loop for each series
If each of the profile series needs to have different from and end date definition, depending
upon profile time definition (Fixed or Relative) call either API
API_MODIFY_INTEG_SERIES_FDATE or
API_MODIFY_INTEG_SERIES_RDATE to change the time range
Within each workflow call API API_NOTIFY_APS_INTEGRATION via stored
procedure workflow step after above mentioned APIs stored procedure step and before
the transfer workflow step which executes the integration interface

USER PROFILE APIS
Oracle Demantra provides l APIs to create, modify, and delete user credentials as well as to alter
user security filters from batch routine.
API to Create, Modify or Delete Users
API_CREATE_ORA_DEM_USER is a procedural API can be leveraged either to create new
user or update the existing user credentials or recreate the existing user. In SSO implementations
with external system, this API can be leveraged to keep the Demantra user credentials in sync with
the customers source system which maintains SSO user credentials for their enterprise. It can be
called via batch routine when any new users added or existing users modified/replaced or deleted
in the customers source system. This API also refreshes the Demantra application server cache
with the updated user credentials and for the caches refresh to be successful system parameter
AppServerURL should be valid.
This API accepts following parameters. All inputs were varchar data type. User name and password
input are mandatory for all actions and component input is mandatory only when adding new user
or replacing existing user.

API_CREATE_ORA_DEM_USER
(
User name,
Password,
Permission,
First name,
Last name,
Company,
Phone number,
Fax number,
Email,
Language,
User group,
Component,
Series group,
Update action)

Permission
Possible values for permission input and its description were tabulated below. If no input is
provided then system defaults it to DP permission.
Permission Description Product Modules
DP Demand Management (Causal
User)
2, 3, 4, 6
DPA Demand Management
Administrator
1, 2, 3 ,4, 6
TPM Predictive Trade Planning
(Causal User)
2, 3, 4, 6
TPMA Predictive Trade Planning
Administrator
1, 2, 3 ,4, 6

Where Product modules are:
1 - Demantra Administrative Tools
2 - Demantra Demand Planner
3 - Demantra Demand Planner Web
4 - Demantra Collaborator Workbench
6 - Demantra Promotion Effectiveness

Language
Possible values of language input and corresponding description is tabulated below

Language Description
1 Canadian French
2 Chinese Simplified
3 Chinese Traditional
4 English
5 Japanese
6 Korean
7 Portuguese (Latin America)
8 Russian
9 Spanish (Latin America)

If language input is not provided, system will default to setting of system parameter
DefaultSystemLanguage in sys_params table and if the parameter value is null then system will
default language to 4 (English)

User Group
User group input value to be provided resides in column GROUP_NAME in table
USER_SECUIRTY_GROUP in Demantra application schema. If its not provided then system
will try to default it to p_portal user group.

Component
Component input value to be provided can be either from column PRODUCT_NAME or
APPLICATION_ID in table DCM_PRODUCTS in Demantra application schema.


Series Group
Series group input value to be provided resides in column GROUP_ID in table
SERIES_GROUPS in Demantra application schema.
Limitation: If a user requires access to multiple series groups, then the access has to be provided via
Business Modeler tool.

Update Action
This input indicates whether the user is added, modified or replaced
Options include:
ADD - Used only to add users. An error message appears if the user already exists.
UPDATE - Used to update existing user details.
REPLACE - If the user already exists, then the user along with all related data (worksheet owned
by the user, audit trail data, notesetc) is first deleted and creates the user.

API to Modify User Security Filters
Procedural API API_ADD_ORA_DEM_LEVEL_FILTERS can be leveraged to add data
security filters to an existing user.
It requires following inputs
API_ADD_ORA_DEM_LEVEL_FILTERS
(
User name,
Level Id,
Member Id,
Permission Id)
Where
User name is the Demantra user name.
Level Id is the group_table_id column value of the corresponding level from
group_tables in the Demantra schema. For e.g. to set filters by Item level, input 424 as
level id which is the group_table_id value of Item level in group_tables. SQL Query:
Select group_table_id from group_tables where upper(table_label) = <Level
Name>
Member Id is the internal member id (t_ep_xxxx_id column in t_ep_xxxx table) value of
the corresponding security level. For e.g. If security is set by Item level, then populate the
t_ep_item_ep_id value of concerned level member from t_ep_item table.
o To get the level lookup table name for the concerned level either you can find it via
Business Modeler > Configure Levels > Right Click on the Level > Select
Data Properties option> Note the Table Name or by SQL Query: Select
gtable from group_tables where upper(table_label) = <Level Name>
o To find the internal member id of the level member either you can find it via
Business Modeler > Configure Levels > Right Click on the Level > Select
Level Members option> Scroll the list to find the id of the concerned item
description or by sql query select <t_ep_xxxx_ep_id> from <t_ep_xxxx> where
<xxxx_code> = <xxxxxx>
Permission id value options:
1 - Not Visible
2 - Read Only
3 - Read & Write
4 - Full Control
Limitations:
If user requires access to multiple level members in a given level then this API has to be
executed several times once for each level member
Application server has to be re-started after executing this API for changes to take effect.
Cannot handle multi level security for a given user. In such scenario, security filter via has
to be set via Business Modeler tool


DYNAMIC OPEN LINK
Demantra provides access to its data from third party reporting tool (Microsoft Excel) via Dynamic
Open Link (DOL) service. Once the Demantra web query was setup in third party tool, data can be
refreshed on demand from the Demantra application schema without accessing the Demantra web
application.

DOL Set up
1. Login into http://<app server url>/portal/DOLLogin.jsp
2. Successful login will open up a web page which list all the worksheets that the user has
access to and the corresponding open link web query URL

3. Copy the open link web query for a given worksheet
4. Open MS Excel Spreadsheet and go to Data > Import External Data > New Web Query.
This will open up a web query window and paste the copied web query in the address bar
and click Go. Import option in the web window gets highlighted.

5. Import format and settings can be changed via Options menu in the web query window
(right hand corner)

6. Click Import and select the option where to import the data (New worksheet or Existing
worksheet)

7. Click Properties if any default settings have to be changed to meet your preference

8. Excel spreadsheet with imported worksheet data

9. To refresh the imported worksheet data in the spreadsheet with the data changes happened
in the system, go to Data Menu > Click Refresh Data
10. Imported data via DOL web query can be formatted via Macros

Limitations
DOL doesnt preserve worksheet display format and it supports only page view with time on the
vertical axis. To overcome this limitation, macros can be written to format the imported data to
user preference.

Dec 2010
Author: Nagappan Periakaruppan
Contributing Authors: [OPTIONAL]

Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065
U.S.A.

Worldwide Inquiries:
Phone: +1.650.506.7000
Fax: +1.650.506.7200
oracle.com

Copyright 2007, Oracle. 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 is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.

Oracle Demantra APIs

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Oracle Demantra APIs

Caricato da

Copyright:

Formati disponibili

Oracle Demantra APIs

An Oracle White Paper

Potrebbero piacerti anche