oracle demantra apis

8/12/2019 Oracle Demantra APIs

1/22

Oracle Demantra APIs

An Oracle White Paper

Dec 2010


2/22

Oracle Demantra APIs Page 2


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


3/22



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.


4/22


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


5/22


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:


3. User Management Login:


4. Workflow Login:



6/22


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:


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 DemantraspreLogin.jsp, with all the required URL

parameters.


7/22


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


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


9/22


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


10/22


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)


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


11/22


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)


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.


12/22


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


13/22


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,


14/22


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


15/22


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.


16/22


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:


17/22


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


18/22


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.


19/22


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)


20/22


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


21/22


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.


22/22


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.

oracle demantra apis

Documents