Section Seven: Siebel Integration Scripting
Module 24: Data Mapping with Scripts
Module Objectives
• After completing this module you will be able to:
o Describe the types of integration situations that require data
transformation by scripts rather than by Siebel Data Mapper
o Create a business service containing a custom script to transform
data between a Siebel application and an external application
o Write code to access input and create output integration object and
XML Hierarchy instances
o Create EAI Value Maps and use them with the EAIGetValueMap
and Translate methods
o Use exception handling functions in data mapping scripts
• Why you need to know
o You may need to write custom scripts for data transformation
between a Siebel application and an external application
Module 24: Data Mapping with Scripts 2 of 26
When to Use Scripts for Data Mapping
• There are no integration objects to represent external metadata
• To aggregate or index multiply-occurring components
Address Source Address Target
Street: 123 Roe St. Street: 123 Roe St., Apt. 4G
Street2: Apt. 4G
City: Pacifica
• To map City:
twoPacifica
or more source components, with non-trivial
relationships, to the same target component
• To exercise programmatic control
o Example: Using if/then or case statement logic
Otherwise, use Siebel Data Mapper instead of scripts
to create maps that are easy to define, maintain, and upgrade
Module 24: Data Mapping with Scripts 3 of 26
Preliminary Ideas
• Siebel data mapping scripts manipulate data in property sets
• The eaisiebel.js library file contains high-level APIs
o Based on property set APIs
o Easy to transfer a value from one property set to another
o Includes a uniform error-handling approach
Module 24: Data Mapping with Scripts 4 of 26
Data Transformation Tasks
In Siebel Tools:
• Create integration objects
o Siebel integration objects to represent Siebel data
o External integration objects to represent external data
• Create a business service to hold the data transformation code
• Write the data transformation eScript code
o Use Siebel data transformation functions to build maps that:
Transform incoming external data into the Siebel structure
Transform outgoing Siebel data into the external system's structure
Module 24: Data Mapping with Scripts 5 of 26
Create Integration Objects
• Create a Siebel integration object based on a business object
o Use the Integration Object Builder with the EAI Siebel Wizard
• Create an interface integration object based on a document type
definition (DTD) from the external application
o Use the Integration Object Builder with an EAI wizard
For XML: EAI DTD Wizard – requires DTD of external XML
EAI Siebel Wizard EAI DTD Wizard
Business Object Siebel (Internal) External
Integration Object Integration Object DTD of XML
BC IC from
IC
External
SVF SVF ICF ICF ICF ICF ICF Application
Module 24: Data Mapping with Scripts 6 of 26
Create a Business Service
In Siebel Tools:
1. Create a new business service
o Set the Project property
1. Set the Class property to CSSEAIDTEScriptService
2. Add a method named Execute to the business service
– Add the following arguments to the Execute method
Module 24: Data Mapping with Scripts 7 of 26
Create a Business Service Continued
1. With the new Execute method selected,
right-click to display the pop-up menu
and select Edit Server Scripts
– Choose the (declarations) procedure of
the (general) object, and add the line
#include "eaisiebel.js"
Include the eaisiebel.js
library of helper functions
Module 24: Data Mapping with Scripts 8 of 26
Create a Business Service Continued
1. Change the Service_PreInvokeMethod Execute method
(provided by workflow)
function to be:
function Service_PreInvokeMethod (MethodName, Inputs, Outputs)
{
return EAIExecuteMap (MethodName, Inputs, Outputs);
}
Passed to the myMapFn function Transformed
(next slide) data return
argument
Module 24: Data Mapping with Scripts 9 of 26
Write the Data Transformation Code
• The EAIExecuteMap function passes its arguments to the
function specified in the input arguments
function myMapFn (objectIn, objectOut)
Transformation function name: Input Object: object type Output Object: object type
passed as MapName business set by the Input Type set by the Output Type
service argument business service argument business service argument
Business Service
Function Argument Object
Argument Description
Input Type Output Type Input Object Output Object
Siebel Siebel CSSEAIInt CSSEAIInt Maps to and from an integration
Message Message MsgIn MsgOut object format (such as XML)
Siebel XML CSSEAIInt XML Maps to external XML
Message Hierarchy MsgIn Hierarchy (no XML integration object)
XML Siebel XML CSSEAIInt Maps from external XML
Hierarchy Message Hierarchy MsgOut (no XML integration object)
Module 24: Data Mapping with Scripts 10 of 26
Data Transformation Script Actions
• Accessing an Input Integration Object instance
• Creating an Output Integration Object instance
• Accessing an Input XML Hierarchy instance
• Creating an Output XML Hierarchy instance
Module 24: Data Mapping with Scripts 11 of 26
Accessing an Input Integration Object: Sequence
Passed Input Object GetArgument() Business
(CSSEAIIntMsgIn) Service
Arguments
GetIntObj()
Exists() Integration Object Instance
FirstInstance() (CSSEAIIntObjIn)
NextInstance()
GetPrimaryIntComp()
Exists() Primary Integration GetFieldValue() Integration
FirstRecord() Component Instance Component
NextRecord() (CSSEAIPrimaryIntCompIn) Fields
GetIntComp()
Exists()
FirstRecord() Integration Component GetFieldValue() Integration
NextRecord() Instance Component
(CSSEAIIntCompIn) Fields
Module 24: Data Mapping with Scripts 12 of 26
Accessing an Input Integration Object: Code
function myMapFn (ObjectIn, ObjectOut) {
inIntObj = ObjectIn.GetIntObj(); //Get integration object
//Iterate over all integration object instances
while (inIntObj.NextInstance()) {
//Get the primary component which is called "Quote"
primaryIntComp = inIntObj.GetPrimaryIntComp("Quote");
//Iterate over all instances of the primary component
while (primaryIntComp.NextRecord()) {
Quote Id = primaryIntComp.GetFieldValue ("Id");
//Get component Quote Item which is child of Quote
comp = primaryIntComp.GetIntComp ("Quote Item");
//Process component similar to primary component
while (comp.NextRecord()) {
Quote Item Id = comp.GetFieldValue ("Id");
Module 24: Data Mapping with Scripts 13 of 26
Creating an Output Integration Object: Sequence
Passed Output Object SetArgument() Business
(CSSEAIIntMsgOut) Service
Arguments
CreateIntObj()
NewInstance()
Integration Object Instance
(CSSEAIIntObjOut)
CreatePrimaryIntComp()
NewRecord() Primary Integration SetFieldValue() Integration
Component Instance Component
(CSSEAIPrimaryIntCompOut) Fields
CreateIntComp()
NewRecord() Integration Component Integration
SetFieldValue()
Instance Component
(CSSEAIIntCompOut) Fields
Module 24: Data Mapping with Scripts 14 of 26
Creating an Output Integration Object: Code
function myMapFn (ObjectIn, ObjectOut) {
outIntObj = ObjectOut.CreateIntObj("Sample Quote");
while (need new integration object instance) {
outIntObj.NewInstance();
//Create primary integration component called "Quote"
primaryIntComp = inIntObj.CreatePrimaryIntComp("Quote");
while (need new primary integration component instance) {
primaryIntComp.NewRecord();
primaryIntComp.SetFieldValue ("Id", Quote Id);
//Create component Quote Item, a child of Quote
comp = primaryIntComp.CreateIntComp ("Quote Item");
//Process component similar to primary component
while (need new integration component instance) {
comp.NewRecord();
comp.SetFieldValue ("Id", Quote Item Id);
Module 24: Data Mapping with Scripts 15 of 26
Accessing an Input XML Hierarchy: Sequence
XML Hierarchy
(Input Passed)
XPSGetRootElement() XPSGetTagName()
Tag Name
XPSGetTextValue()
XML Root Element Value
XPSGetAttribute()
Attribute
XPSFindChild()
XPSGetChild()
XPSGetChildCount()
XPSGetTagName()
Tag Name
XML Element XPSGetTextValue()
Value
XPSGetAttribute()
Attribute
Module 24: Data Mapping with Scripts 16 of 26
Accessing an Input XML Hierarchy: Code
//XML: <message><Quote Id="id">Quote Val…
function myMapFn (ObjectIn, ObjectOut) {
root = XPSGetRootElement(ObjectIn);
//Find the first child of root called quote
Quote = XPSFindChild(root, "Quote");
//Instead of finding first, iterate over all children called Quote
numberChildren = XPSGetChildCount(root);
while (iterator < numberChildren) {
Quote = XPSGetChild (root, iterator);
//Skip children of root that are not Quote
if (XPSGetTagName(Quote) != "Quote") continue;
Quote Val = XPSGetTextValue(Quote);
Id = XPSGetAttribute(Quote, "Id");
...
}
Module 24: Data Mapping with Scripts 17 of 26
Creating an Output XML Hierarchy: Sequence
XML Hierarchy
(Output Passed)
XPSCreateRootElement() XPSSetTagName()
Tag Name
XPSSetTextValue()
XML Root Element Value
XPSSetAttribute()
Attribute
XPSAddChild()
XPSSetTagName()
Tag Name
XML Element XPSSetTextValue()
Value
XPSSetAttribute()
Attribute
Module 24: Data Mapping with Scripts 18 of 26
Creating an Output XML Hierarchy: Code
//XML: <message><Quote Id="id">Quote Val...
function myMapFn (ObjectIn, ObjectOut) {
root = XPSCreateRootElement(ObjectOut, "message");
while (need new Quote element) {
Quote = XPSAddChild (root, "Quote");
XPSSetTextValue(Quote, Quote Val);
XPSSetAttribute(Quote, "Id", id);
}
...
Module 24: Data Mapping with Scripts 19 of 26
Data Transformation Script Example
• Integration object to integration object map: Maps the Siebel
Account object to its corresponding SAP/R3 object
Input integration object components: Output integration object components:
• Order Object • BAPI Import
(Order - Get SAP Order Status (Siebel)) (Order - Get SAP Order Status (BAPI Input))
• Order • Import Parameters
function GetSAPOrderStatus_SiebelToBAPI (inputMsg, outputMsg)
{
var iOrderObj; // Siebel Order instance Set up EAI Input
var iOrderComp; // Order Message objects
var oGSObj; // BAPI instance
var oGSImportComp; // Import Parameters
iOrderObj = inputMsg.GetIntObj ("Order - Get SAP Order Status Set up EAI Output
(Siebel)"); Message objects
oGSObj = outputMsg.CreateIntObj ("Order - Get SAP Order Status
(BAPI Input)"); Read an input integration object instance
Write an output integration object instance
Module 24: Data Mapping with Scripts 20 of 26
Data Transformation Script Example Continued
Read integration object instances
from the EAI message
while (iOrderObj.NextInstance ())
{ Get the primary integration
oGSObj.NewInstance (); Create the object component, “Order”, from this
"Get Status"
iOrderComp = iOrderObj.GetPrimaryIntComp ("Order"); integration object
oGSImportComp = oGSObj.CreatePrimaryIntComp ("Import Parameters");
if (iOrderComp.NextRecord ())
{
oGSImportComp.NewRecord ();
oGSImportComp.SetCopySource (iOrderComp);
oGSImportComp.CopyFieldValue ("SALESDOC","Integration Id");
} // end if Write the "Import Parameters"
} // end while component
} // end function
Module 24: Data Mapping with Scripts 21 of 26
Using EAI Value Maps in a Script
• To return a value map, use this statement in the eScript code
EAIGetValueMap (type, direction, unmappedKeyHandler)
String from the "Siebel Inbound" or (Optional) Literal value
Type field "Siebel Outbound" or function to return if a
• Returns a CSSEAIValueMap interface object key has no mapping
• To find specific keys in the Type-Direction map and retrieve the
translated values, use the interface object’s Translate method
o Example: Translate an inbound SAP Country value
var LangMap = EAIGetValueMap ("SAP Country", "Siebel Inbound", "");
TranslatedCountry=LangMap.Translate ("TR");
Module 24: Data Mapping with Scripts 22 of 26
Data Transformation Business Services at Run Time
• Outbound:
o Reads an internal integration object instance (property set)
o Writes the data into an
interface integration object
instance (property set) Internal External
Integration Object Integration Object
• Inbound: IC IC
o Reads an interface integration IC IC IC IC IC
object instance (property set)
o Writes the data into a Siebel
integration object instance Business Service
(property set)
Business Service
Property Set Property Set
map and Customer
Contact
transform
Chris Li Dr. Chris Li
Module 24: Data Mapping with Scripts 23 of 26
Exception Handling
• Types of errors
o Siebel errors (fatal)
Examples: Run-time eScript errors, business service invocation errors,
BusComp errors, errors in data transformation functions
o User errors (fatal)
Raised by calls to the EAIRaiseErrorCode function in custom maps
o Map status flags
Custom status information placed in the output property set using the
SetArgument method
• Exception handling functions
o EAIRaiseError (message, formatParameters)
o EAIRaiseErrorCode (errorSymbol, message)
o EAIFormatMessage (message, formatParameters)
Module 24: Data Mapping with Scripts 24 of 26
Summary
• This module showed you how to:
o Describe the types of integration situations that require data
transformation by scripts rather than by Siebel Data Mapper
o Create a business service containing a custom script to transform
data between a Siebel application and an external application
o Write code to access input and create output integration object and
XML Hierarchy instances
o Create EAI Value Maps and use them with the EAIGetValueMap
and Translate methods
o Use exception handling functions in data mapping scripts
Module 24: Data Mapping with Scripts 25 of 26
Lab
• In the lab you will:
o Examine and run a data mapping eScript, then review the output
Module 24: Data Mapping with Scripts 26 of 26
