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