Download - Oracle Demantra APIs
-
8/12/2019 Oracle Demantra APIs
1/22
Oracle Demantra APIs
An Oracle White Paper
Dec 2010
-
8/12/2019 Oracle Demantra APIs
2/22
Oracle Demantra APIs Page 2
Oracle Demantra APIs
Introduction ........................................................................................................ 3External Login API ........................................................................................... 3
Single Sign On from External Portal ......................................................... 6Other Key Requirements ............................................................................. 7
Integration Interface APIs ................................................................................ 9API to Modify Series Attributes ................................................................. 9API to Modify Fixed Date Definition ..................................................... 10
API to Modify Relative Date Definition ................................................. 11API to Notify Application Server ............................................................. 11
Integration Interface APIs Use Cases..................................................... 12User Profile APIs............................................................................................ 13
API to Create, Modify or Delete Users ................................................... 13API to Modify User Security Filters ......................................................... 16
Dynamic open link .......................................................................................... 18
-
8/12/2019 Oracle Demantra APIs
3/22
Oracle Demantra APIs Page 3
Oracle Demantra APIs
Introduction
Oracle Demantra application provides various APIs to facilitate integration with external/third
party/source system. This white paper details the following APIswith 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 Demantraapplication 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 sourcesystem where user with appropriate responsibility can login into Demantra application from EBSwithout entering user credentials again. User credentials with Demantra Management responsibilitywere synced automatically from EBS to Demantra during user profile creation in EBS. For nonEBS customer, Oracle Demantra application provides an external login API to facilitate SSO fromexternal portal/source system (i.e. EBS).
API named preLogin.jsp is available as part of standard product to facilitate remote login into allof 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 alsooutlines recommended approach to enable SSO with external portals/source system leveraging thisexternal login API.
-
8/12/2019 Oracle Demantra APIs
4/22
Oracle Demantra APIs Page 4
Example
http:////common/prelogin.jsp?loginTo=&redirectUrl=&loginUrl=&source=0&component=&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 therequest called loginTo. This parameter indicates to which module, you wish to login.
loginTo ID Login Module0 COLLABORATOR_LOGIN1 ANYWHERE_LOGIN2 PARTNER_LOGIN3 ADMIN_PAGES_LOGIN4 WORKFLOW_LOGIN5 USER_MANAGEMENT_LOGIN
2. loginUrl and redirectUrlAll 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.jsp1 loginpage.jsp 13 pagebuilder.jsp2 partnerLogin.jsp3 anywhereLogin.jsp 14 anywhereConsole.jsp
4 remoteloginpage.jsp5 userManagement.jsp 15 userManagementConsole.jsp6 DOLLogin.jsp 16 DOLQueries.jsp7 StatisticalQueryLogin.jsp 17 StatisticalQueryList.jsp9 /workflow/login.jsp 18 /workflow/ProcessManager.jsp
-
8/12/2019 Oracle Demantra APIs
5/22
Oracle Demantra APIs Page 5
3. Component ID
Component ID Component Name
DM Demand ManagementPTP Predictive Trade PlanningSOP Sales & Operations
Planning
4. ExternalLogoutUrl
The only URL that is external to the system is the logoutUrl. This parameter should be configuredmanually in the Business Modeler as part of the system parameters configuration. A new system
parameter called ExternalLogoutUrlwas added to the sys_parms table.
5. URL Examples
For DM Component and Component Owner user
1. Administrator Login:
http:////common/prelogin.jsp?loginTo=3&redirectUrl=12&loginUrl=0&source=0&component=DM&componentowner=1
2. Collaborator Workbench Login:
http:////common/prelogin.jsp?loginTo=0&redirectUrl=13&loginUrl=1&source=0&component=DM&componentowner=1
3. User Management Login:
http:////common/prelogin.jsp?loginTo=5&redirectUrl=15&loginUrl=5&source=0&component=DM&componentowner=1
4. Workflow Login:
http:////common/prelogin.jsp?loginTo=4&redirectUrl=18&loginUrl=9&source=0&component=DM&componentowner=1
-
8/12/2019 Oracle Demantra APIs
6/22
Oracle Demantra APIs Page 6
For DM Component and Non Component User
Do not pass in "componnentowner" unless the UID is indeed the component owner
1. Administrator Login:
http:////common/prelogin.jsp?loginTo=3&redirectUrl=12&loginUrl=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:
http://SERVER_URL/demantra/common/prelogin.jsp?loginTo=5&redirectUrl=15&loginUrl=5&source=0&component=DM
4. Workflow Login:
http://SERVER_URL/demantra/common/prelogin.jsp?loginTo=4&redirectUrl=18&loginUrl=9&source=0&component=DM
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 DemantraspreLogin.jsp, with all the required URL
parameters.
-
8/12/2019 Oracle Demantra APIs
7/22
Oracle Demantra APIs Page 7
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-userto 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 topoint 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
-
8/12/2019 Oracle Demantra APIs
8/22
Oracle Demantra APIs Page 8
Web Browser
End user accessDemantra from alink on Web
Web Server(i.e. Apache)
SSO AgentPlug-in
J2EE server (i.e.Web Logic)
Plug-in
SSO Agent protectpreLogin.jsp,authenticate userthen set UID asHTTP header
J2EE server (WebLogic) Plug-in pasrequest with UID aHTTP header tobackend Web Logi
J2EE Server(Web Logic)
preLogin.jsp
preLogin.jsp retrieveUID throughrequest.getRemoteUfunction
Demantra SSO SoftwareComponent Layout
-
8/12/2019 Oracle Demantra APIs
9/22
Oracle Demantra APIs Page 9
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_ATTRcan 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 =;
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 =
;
ii_load_option
o Refers to load option series attribute
-
8/12/2019 Oracle Demantra APIs
10/22
Oracle Demantra APIs Page 10
0Override (Overrides the existing series value)
1Accumulate (Adds to existing series value)
1No Load (Series wont be loaded)
ii_purge_optiono Refers to purge option series attribute
0No purge (Data of the series wont be purged from base table before
loading)
1Purge 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)
2Purge 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_datedate)
It requires following 3 input parameters
ii_profile_id
Refers to internal ID of the concerned Integration interface
Select ID from transfer_query where query_name =;
id_from_date
o
Populate in mm/dd/yyyy format
id_until_date
o Populate in mm/dd/yyyy format
-
8/12/2019 Oracle Demantra APIs
11/22
Oracle Demantra APIs Page 11
API to Modify Relative Date Definition
The procedural API API_MODIFY_INTEG_SERIES_RDATEcan 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)
It requires following 3 input parameters
ii_profile_id
Refers to internal ID of the concerned Integration interface
Select ID from transfer_query where query_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.
-
8/12/2019 Oracle Demantra APIs
12/22
Oracle Demantra APIs Page 12
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_ATTRcan 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_ATTRvia stored procedure step with all relevant
parameters to change the load and purge options of each affected series. This API has to beexecuted 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
-
8/12/2019 Oracle Demantra APIs
13/22
Oracle Demantra APIs Page 13
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_RDATEto change the time range
Within each workflow call API API_NOTIFY_APS_INTEGRATION via stored
procedure workflow step after above mentioned APIsstored procedure step and before
the transfer workflow step which executes the integration interface
USER PROFILE APIS
Oracle Demantra provides lAPIs 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,
-
8/12/2019 Oracle Demantra APIs
14/22
Oracle Demantra APIs Page 14
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
-
8/12/2019 Oracle Demantra APIs
15/22
Oracle Demantra APIs Page 15
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_GROUPin 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_PRODUCTSin Demantra application schema.
-
8/12/2019 Oracle Demantra APIs
16/22
Oracle Demantra APIs Page 16
Series Group
Series group input value to be provided resides in column GROUP_ID in table
SERIES_GROUPSin 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 ownedby 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_FILTERScan 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 columnvalue 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:
-
8/12/2019 Oracle Demantra APIs
17/22
Oracle Demantra APIs Page 17
Select group_table_id from group_tables where upper(table_label) =
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) =
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 from where
=
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
-
8/12/2019 Oracle Demantra APIs
18/22
Oracle Demantra APIs Page 18
DYNAMIC OPEN LINK
Demantra provides access to its data from third party reporting tool (Microsoft Excel) via DynamicOpen 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 webapplication.
DOL Set up
1. Login into http:///portal/DOLLogin.jsp
2.
Successful login will open up a web page which list all the worksheets that the user hasaccess 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 barand click Go. Import option in the web window gets highlighted.
-
8/12/2019 Oracle Demantra APIs
19/22
Oracle Demantra APIs Page 19
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 Existingworksheet)
-
8/12/2019 Oracle Demantra APIs
20/22
Oracle Demantra APIs Page 20
7. Click Properties if any default settings have to be changed to meet your preference
-
8/12/2019 Oracle Demantra APIs
21/22
Oracle Demantra APIs Page 21
8. Excel spreadsheet with imported worksheet data
9. To refresh the imported worksheet data in the spreadsheet with the data changes happenedin 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 thevertical axis. To overcome this limitation, macros can be written to format the imported data to
user preference.
-
8/12/2019 Oracle Demantra APIs
22/22
Oracle Demantra APIs
Dec 2010
Author: Nagappan PeriakaruppanContributing 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.