14Data Transfer Utilities Business Service
Data Transfer Utilities Business Service
This chapter describes the Data Transfer Utilities business service. It includes the following topics:
About Data Transfer Utilities
This business service allows you to transfer data from a source business component to a destination component. For example, a user can enter data in one view, then use a toolbar command to navigate to another view. Data entered in the first view is automatically entered in the second view.
Considerations for Data Transfer Utilities
This topic covers considerations that are important when you use the Data Transfer Utilities.
Use of Active Business Objects
Data Transfer Utilities execute inside a client's object manager.
The DTU reuses the current active business objects. It does not instantiate an independent source business object unless directed. This leads to both a leaner memory use and better performance. This is even more so if the destination business object is the same as the source business object. In such a case, no new business objects are instantiated for the business service.
Because of the reuse of active objects, you must exercise caution to preserve the current business object context. For example, the business components must not be in the query state when DTU is launched.
Invocation Context
You can pass a reference to the active Buscomp to DTU, if you invoke the business service from Event Manager, Buscomp Named Method, or from a workflow process that is invoked by the event manager. You are not required to have an active Buscomp.
Not all Buscomp events can be used to invoke the DataTransfer method. For example, Query event in general must not be used to trigger DataTransfer, as the buscomps are not in an updateable state.
In general, use PreDeleteRecord event; do not use DeleteRecord event. The Siebel event manager does not pass in a reference to the active Buscomp in the DeleteRecord event.
Use special care when the service is used with other business services in a workflow. Other business services should not interfere the passing of a reference to the active buscomp. Use a spooled SQL statement to confirm the operations carried out are correct.
Well-Positioned Buscomps
A well-positioned Buscomp is a Buscomp that has been positioned correctly, and whose position should not be disturbed. DTU uses the following rule:
The initiator Buscomp is a well-positioned Buscomp.
The ascendants of a well-positioned Buscomp are well-positioned.
For a given data map component, the buscomps involved in all its parent data map components are well positioned.
If the source Buscomp is well-positioned:
Data transfer is only invoked on the current row of the source BusComp. Otherwise, the operation is carried out on all rows in the source BusComp at the moment of invocation.
Advanced options such as source search spec, source sort spec should be empty.
If the destination Buscomp is well-positioned:
You do not need to specify key fields to retrieve the destination record. Even if you do in this case, DTU would ignore them.
And if the current operation is Insert, it would change to Update by default, unless overridden by Operation Overrides.
Example of Buscomp That is Not Well-Positioned
Calling the DTU Data Transfer method from an applet that is based on buscomp Quote, but which has the data mapped source buscomp Opportunity. In this case:
The UI context (Quote) does not match the data mapped buscomp (Opportunity), and
DTU must query all Opportunity buscomp records, unless the RowId parameter is additionally passed, to identify a single opportunity record.
Recursive Invocation
By default, you cannot use the DataTransfer operation to invoke another DataTransfer operation. In other words, at anytime within a client's object manager, there is only one DataTransfer method in the call stack.
Using Named Parameters in DTU
You can use named parameters to pass in a run-time dynamic value into Data Transfer Utilities (DTU). For example, imagine you want to pull a contact's latest information into your Buscomp. At design-time, you cannot foresee what is the contact’s ID. Instead, you use a named parameter, &ContactId, and at run time, you pass in the value &ContactId.
Named parameters are defined implicitly in two ways:
Business Service Arguments. Pass in the named parameters when DTU is invoked. DTU knows an argument is a named parameter if the argument name is prefixed with an ampersand (&).
For example:
var psinputs, psoutputs;
var myContactId = '0-45TU890';
psinputs = TheApplication().NewPropertySet();
psoutputs = TheApplication().NewPropertySet();
psinputs.SetProperty ("DataMapObj", "My Test DTU Object");
psinputs.SetProperty ("Operation", "Update");
psinputs.SetProperty ("&ContactId", myContactId);
var obs = TheApplication().GetService("FINS Data Transfer Utilities");
obs.InvokeMethod ("DataTransfer",psinputs, psoutputs);
&ContactId serves as a named parameter.
The input value of a named parameter can be a calculation expression. In order to do so, set the value to:
Expr: "YourExpression"
which is the syntax of Buscomp field predefault. At run time, the expression is evaluated against the initiator Buscomp. For more information about initiator buscomp, see the argument description in DataTransfer Method.
Assignment by DTU. At run time, you can transfer into a named parameter if the field type is Parameter. When this happens, if the named parameter is still not defined, it is instantiated.
A named parameter must be implicitly defined first before it can be used. In other words, un-assigned named parameters cannot be used.
Named parameters can be used to define Data Map Component Advanced Options, and Data Map Field Source or Destination that are of type Expression.
All named parameters are output into the DTU service output arguments.
Calculation Expressions in DTU
When Data Map Field Source or Destination Type is Expression, the Source or Destination Fields are calculation expressions that follow Siebel Query Language syntax. See Siebel Personalization Administration Guide for more information about Siebel Query Language.
DTU contains two extensions to Siebel Query Language: curly bracket pair {field}, and named parameter.
Curly Bracket Pair {field}
Use this syntax to refer to a buscomp field at the other business component side. For example, if you define the following expression as the source:
{ContactId}
[ContactId] would be evaluated at the destination bsucomp. When {} is involved, please note that {} takes the highest precedence over other operator. Thus, if you have an expression like:
‘{Last Name}' + 'Test'
{Last Name} has precedence over quotes "". If the person's last name is Agee, {Last Name} is evaluated to be "Agee". As a result, the final value is:
"Agee" Test
instead of
{Last Name} Test
Named Parameter
A calculation expression can contain named parameters, using the syntax of [&Parameter]. It is important to pre-fix the ampersand to indicate a named parameter. For example,
"Sadmin's opportunity #" + [&OpptyId]
For more information about named parameters, see Using Named Parameters in DTU.
Using DTU with Order Management Signals
Order Management signals are a powerful infrastructure that allow you to define complicated runtime events. For more information, see Signals.
DTU can be directly invoked through a signal. When this happens, the signal infrastructure passes the row ID of the current instance buscomp to the RowId argument of DTU. This tells DTU which source buscomp record to work with.
In a rare case when you invoke DTU from a signal, but you do not want DTU to use RowId passed from the signal as the context, simply set the IgnoreRowId argument to Y.
Since signals pass the RowId argument instead of the buscomp instance into DTU, a new instance of source buscomp is always created.
About Working with Hierarchical Business Components
Hierarchical business components, such as Quote Item, are business components that define a recursive hierarchical foreign key field to themselves. In Web Tools, these buscomps have the Hierarchical Parent Field attribute defined. Sometimes, their buscomp user properties also contain a definition for Root ID Field Name. For more information, see Siebel Tools Online Help.
When the data of a hierarchical buscomp is copied to another hierarchical buscomp, care must be taken to re-wire the hierarchical foreign keys: the hierarchical parent field and the root ID field. They must be re-wired to point to the corresponding destination records. DTU automatically re-wires those two foreign keys when a hierarchical buscomp is copied to another hierarchical buscomp.
For performance reasons, many data map objects in Siebel Order Management use a flattened version of a hierarchical buscomp instead. For example, data map object QuoteToSalesOrder, which creates a sales order based on a quote, contains the Line Item component that uses Quote Item (Simple) and Order Entry - Line Items (Simple). Both simple buscomps are not hierarchical. The reason for using simple buscomps is performance, as hierarchical buscomps require more CPU and memory. However, when those simple buscomps are used, you must define the foreign key mapping yourself. This is generally achieved using the field-level advanced option ID Mapping Component described in the following table.
This option was referred to as MapId in ISS Copy Service (described in Data Map Fields), which is not used by DTU in 8.0. For more information, see ISS Copy Service and the Data Transfer Utility.
In rare cases, you do not want DTU to automatically set hierarchical parent ID and root ID when a hierarchical buscomp is copied to another hierarchical buscomp. Set the component advanced option Disable Hierarchy to Y. You must type this option yourself, as it is not available from the pick list in the data map administration screen.
ISS Copy Service and the Data Transfer Utility
The DataTransfer method of the DTU replaces the Copy method of the ISS Copy Service. DTU offers more functionality and usability.
ISS Copy Service is still supported. Earlier configurations that use the Copy Service will still work with the Copy Service in 8.0. Only the AutoOrderSalesQuote and AutoOrderServiceQuote signals are re-configured to use DTU. It is recommended that new development be based on DTU.
Some differences are between DTU and ISS Copy Service are:
DTU does not require you to instantiate the source and destination instances first. Instead DTU instantiates and deletes them automatically. This makes the invocation easier and safer.
Copy service data map field options include:
SequenceField. For the DTU data map, SequenceField is renamed as Sequence Field.
MapId. For the DTU data map, MapId is renamed as the ID Mapping Component option. The difference is that the MapId option value is a source buscomp name, and ID Mapping Component is the data map component name, as DTU allows a buscomp to be used in multiple components.
For backward compatibility, DTU still recognizes the copy service field options.
Configuring Event-Based Commands for DTU
The Data Transfer Utilities (DTU) business service allows you to configure toolbar and menu commands based on Siebel Event Manager.
To configure event-based commands
In Web Tools, create or open a workspace and then navigate to Object Explorer.
To use the workspace dashboard, see Using Siebel Tools.
Define a command where:
Business Service is “FINS Data Transfer Utilities” and method is “FAFireEventxxx”.
The method name can be anything that begins with “FAFireEvent”. When the command is invoked, it, in turn, invokes method EventMethodxxx on the primary buscomp of the active view, where xxx is of the same value as in FAFireEventxxx.
Define a toolbar.
Define a toolbar item for the command you defined.
Save your changes and submit the workspace for delivery.
In the Siebel client, define a run-time event that will receive EventMethodxxx.
Navigate to the Administration - Runtime Events screen, then the Events view, and create a Buscomp run-time event as listed in the following table. See Siebel Personalization Administration Guide for more information about run-time events.
Field Entry Sequence
-1
Object Type
BusComp
Object Name
The name of the business component in which the event is invoked. For a toolbar command, this is the primary business component in the view in which the command is invoked.
Event
InvokeMethod
Sub Event
EventMethodxxx. Choose the same value for xxx that you chose for FAFireEvent.
Action Set Name
The action set that invokes Siebel Workflow Manager or a business service.
Alternatively, you can define a workflow that has a Start step that contains run-time events. When the workflow is activated, both the Action Sets and run-time events are created automatically for you. For more information, see Siebel Business Process Framework: Workflow Guide.
Siebel run-time events are cached. After you make changes, click the Runtime Events applet menu item Reload Runtime Events.
Configure dynamic enabling of the command. For more information, see Dynamic Enabling of Commands for DTU.
Define command visibility:
In Siebel Tools, navigate to Business Services, then FINS Data Transfer Utilities.
Define a user property in which Name is MethodName GotoView, and Value is set to the name of a view. MethodName is the name of the command method.
When you define this user property, this method is enabled only for users who have visibility to the view defined in the value. If the method does not contain a GotoView, visibility is not imposed on the method.
Dynamic Enabling of Commands for DTU
When a command is invoked from a toolbar button or menu, the Data Transfer Utilities business service invokes the method EventMethodxxx on the primary business component of the active view. The primary business component should be derived from CSSBCBase to allow the invocation to be captured by Siebel Event Manager.
When the view is changed, Siebel framework polls each command for the application-level toolbar buttons and application menu to determine whether the button or menu items should be made read-only.
There are two mechanisms for the dynamic enabling and disabling of commands in DTU:
Srf mode
Mock Event Sink
The System Preference FINS DTU Enable FireEvent Mode is used to determine the mode. The value should be Srf or Runtime Event. The default value is Srf.
Srf Mode
In the Srf mode, a FAFireEventxxx invocation on a buscomp is enabled if there is a user property underneath the FINS Data Transfer Utilities business service as such that the name of the user property is:
Name: FAFireEventxxx Static Enabled BC [n]
Value: Buscomp Name
You can define multiple Buscomps for a FAFireEventxxx method.
Srf mode is introduced primarily for performance reasons. Compared with Runtime Event mode, it allows fast enabling and disabling of a command button without actually invoking a run-time event. Srf mode is the default mode.
Mock Event Sink
When System Preference FINS DTU Enable FireEvent Mode is Runtime Event, Data Transfer Utilities determines at run time whether a FAFireEventxxx method should be disabled or not by initializing Mock Event Mode. It sets up a global mock event flag within the client’s object manager. It then invokes EventMethodxxx on the primary business component of the active view. If this EventMethodxxx is finally captured by a Mock Event Sink, a global response flag is set. When the Data Transfer Utilities finds out the response flag is set by a mock event sink, it enables the FAFireEventxxx method for that particular view. Otherwise, the method is disabled.
Mock Event Sinks are specialized business service methods that capture mock events. They check whether the client’s OM is in the mock event mode. If not, they do nothing. If so, they reply to the mock event by setting the response flag as well as the output argument.
MockMethodReplied is Y.
TryMockMethod in Data Transfer Utilities is a mock event sink. DataTransfer method has a built-in mock event sink.
Performance Tuning for DTU
You can improve performance of DTU by using the following tips:
"When the operation is insert, and you are sure no duplicate records would be created in the process, do not check Key flags. This means that DTU does not need to query the database to identify duplicates.
Use BatchMode in the Option argument whenever possible.
Use Cached Updates whenever possible.
For bounded picklist fields, MVG primary ID, and MVG source ID fields, skip field validation whenever possible. Note that skipping the bounded picklist validation would also skip setting fields of the pick map.
When a reference to the active instance buscomp is passed to DTU, it is a delicate balance to decide whether or not to launch the DTU with a new instance of the source buscomp or re-use the current active instance. By using the active instance, you avoid using CPU and memory for the new business object. On the other hand, when DTU works off the active instance, it has to restore the buscomp context to its original state, causing refreshing and looping of buscomps. When a large number of buscomps or buscomp records are involved , this can be expensive. This is why the NewSrcBusObj option is used in the "Auto Order Web Service" example.
About Data Maps
Data maps are the logic defining the flow of data from one location to another. The DTU business service uses data maps to transfer data from one location in the Siebel application to another.
This topic includes information about the following:
Data Map Objects
Data map objects indicate the data that is being transferred from the source business object to the destination business object. You can use the Administration - Application screen, then the Data Map Administration view to define data map objects. Only Siebel administrators have access to this screen. Data map objects are described in the following table.
| Object | Description |
|---|---|
Name |
Data map object name. Enter a unique name. |
Source Business Object |
Source business object name. |
Destination Business Object |
Destination business object name. You can specify the same business object as both source and destination business object. |
Inactive |
Check this box to make the data map object inactive. |
You can import or export data map objects as XML files through the Data Map Object applet menu items: XML Import, XML Export.
Data Map Components
Data map components define the mapping at the child business component level. Each data map object can contain multiple data map components. You can arrange data map components in a parent-child hierarchy, but you must specify a parent for all except one data map component. The parentless data map component is called the root data map component. Data map components are described in the following table.
| Component | Description |
|---|---|
Name |
Data map component name. Enter a unique name for each data map component in a data map object. |
Source or Destination Business Component |
Source or destination business component name. If you specify a parent for this data map component, you must define this business component as a child of the source or destination business object to which the parent data map component is mapped. |
Parent |
Parent data map component name. If you:
|
Inactive |
Check this box to make the data map component inactive. |
Data Map Component Advanced Options
Fine-tune data transfer at the component level by using Advanced Options multi-value fields. Data map components advanced options are described in the following table.
All advanced option values can contain named parameters. At run time, the named parameter is substituted by its run-time value.
If the source Buscomp has been well positioned, the source search spec, the source sort spec, and source record row number must be evaluated to be empty at run time, otherwise a wrong advanced option error is encountered. See Well-Positioned Buscomps for more information.
Advanced Options does not apply to multi-value group subcomponents.
| Component | Description |
|---|---|
Source Search Specification Source Sort Specification |
Defines the source Buscomp search spec and sort spec. The value can be a literal search spec or sort spec string. It can also contain a named parameter. See Using Named Parameters in DTU. For example: [Id] = [&ContactId] where ContactId is a named parameter. At run time, only named parameters are replaced by their string values. |
Source Record Row Number |
One can selectively transfer only a subset of source Buscomp records. This can be defined in three formats:
For example, 0-5, 4-, 0.
Note: The row number starts at 0.
|
Operation Override |
This option allows one to override the operation at the component level. For example, if the current operation is Insert, you can use this option to set some component to operate Update instead. |
No Association |
Y or N. Applicable to buscomps that have association list. By default, it is Y. Data Transfer Utilities first try to locate the desired destination record in the associate list. If successful, the located record is associated. Otherwise, a new record is created. If N, association of existing records is not attempted. A new record is created instead. |
Cached Updates |
The valid values include:
This is a performance enhancement option that defers sending SQL statements to the database until they can be sent together. Since none of the SQL statements is sent until the end, subsequent steps in the block cannot be dependant on a previous step having been committed to the database. When you turn on this option, make sure to confirm all SQL statements are generated correctly and there is no inter-dependency. |
Field Validation |
Y or N. By default it is Y. By default, setting field values in a Siebel BusComp triggers field value validation. If you have a bounded picklist, the new value is validated against the picklist and the fields in the pick maps are set. Disabling field validation also turns off picklists. It is a performance enhancement option. |
Source Filter Specification |
An expression in Siebel search specification syntax that is used to filter out records at the runtime. Only source records whose filter specification evaluates to be true are transferred. Filter specification differs from search specification in that search specification is imposed at the database query, and filter specification is imposed while looping through the records. |
Disable Order Management Signals |
The valid values include
When the Disable Order Management Signals option is imposed on the source or destination components, buscomp operations on those buscomps do not trigger order management signals during the data transfer process. |
Data Map Fields
Data map fields define the field-to-field mapping. Data map fields are described in the following table.
| Field | Description |
|---|---|
Source Type or Destination Type |
Type of the source or destination field. Can be: Field, Expression, or Parameter:
|
Source or Destination |
The contents of these fields depends on the source and destination type. If the type is:
If the destination field is a calculated expression, then the record is not used to update the destination Buscomp. Instead, the result of the expression, evaluated at run time, is written back into the source field at the end of the data transfer operation of the component. If the Source is:
|
Key |
Matches the destination records with source records. For example, the Update operation updates the record in the destination business component whose key destination fields all match those of the corresponding source fields. Each data map component in general contains at least one key field. When there is no key defined, if the operation is:
If the destination business component is populated with an associated list business component, at least one key field is required. |
Source or Destination Multi-Value Link |
This link indicates that the source and destination fields are multi-value fields. Data is transferred from one multi-value field to another by dividing data map fields into several subcomponents. All entries with the same source and destination multi-value link constitute a subcomponent. Specify a key for each subcomponent.
Note: Data transfer from a multi-value field to a single-value field is not allowed.
|
Data Map Field Advanced Options
Data map field advanced options allow you to fine tune data transfer operations at the field level. These options are described in the following table.
| Option | Description |
|---|---|
Field Validation |
Possible values are Y or N. The default is Y. For more information, see the Field Value component in Data Map Component Advanced Options. If Field Validation option is defined at both component and field levels, the field level definition wins. |
Sequence Field |
Possible values are Y or N. The default value is N. If the value is Y, a sequence number starting from 1 and increased by 1 is assigned to the destination field in each record. |
Id Mapping Component |
The option is used to re-wire foreign keys. The valid values are the names of data map components in the data map object. At run time, the source ID to destination ID mapping of the named data map component defines the foreign key mapping used by the data map field. For example, when you copy from quote item to order item in a data map component Items, the hierarchical parent ID of a quote item cannot be literally copied to the order item parent ID. It needs to be re-wired to the corresponding order item ID. The ID mapping component must be Items, as the quote to order ID mapping is used to look up the order parent ID field using the value of the quote parent ID field. For related information, see Configuring Event-Based Commands for DTU. |
Migrating Data Map Objects Between Environments
Data map definitions are enabled for export and import by the Application Deployment Manager (ADM). For information about using ADM, see Siebel Application Deployment Manager Guide.
Example of Defining Data Maps to Use with the DTU
This topic shows how data mapping is defined to convert a quote into a sales order using the DTU. This is in essence Auto Quote function of the DTU. This example guides you though the mapping in the application.
The data copied over mainly consists of a three-level hierarchy:
Header
Line items
Extended attributes (XA)
There are also other auxiliary entities such as payments, requested, and promised scheduled lines. This example shows how header (Mapping Headers), line items (Mapping Line Items) and XA (Mapping the Extended Attributes) are mapped. Other entities are mapped like either line items or XA. First, you must find the data map object where the header, line item, or XA are mapped as described in Finding the Data Map Object.
Finding the Data Map Object
You must find the data map object where the header, line items, and XA are mapped.
To find the data map object
Navigate to the Administration - Application screen, then the Data Map Administration view.
In the Data Map Object list, select the record named QuoteToSalesOrder.
The components of this data map object, including Header, Line Item, and XZ, appear in the Data Map Component list, after the Data Map Object list.
Mapping Headers
First, look at the mapping of the header component, to see how the quote header buscomp is mapped to the order header buscomp.
Notice that a calculation expression is used to look up the order type LOV to default the order type to sales order.
Two advanced options at the component level are of interest, because they are both important to improve performance:
Cached Updates. Enables cached updates at the destination buscomp level. All updates at the order buscomp, and its descendant buscomps, are cached and issued in one batch to the database.
Skip Order Management Signals. Because of this option, setting field values at the order buscomp does not trigger order management signals that usually would invoke pricing and eligibility workflows.
To view the header mapping
In the Data Map Component list, select the record named Header.
Look at the mapping in the Data Map field list.
Notice that the record with Expression in the Source Type field has the expression LookupValue("FS_ORDER_TYPE","Sales Order"), which is used to default the order type to sales order.
Click the select button in the Advanced Options field of the Header record to see that Cached Updates and Skip Order Management Signals are selected as options.
Mapping Line Items
Next, look at the Line Item component.
The record defines its parent as Header, so it is invoked as a child of the Header component.
To improve performance, use simple buscomps instead of the line item buscomps used in the Siebel Call Center user interface. These improve performance because they are light-weight and, most important, because they are not defined as hierarchical buscomps.
Because they are not hierarchical, you must define their hierarchical parent fields in the mapping, using the Data Map Field records with Root Quote Item ID and Parent Quote Item ID in their Source field.
Both these records use the advanced option with the name ID Mapping Component to define the foreign keys to define hierarchical parent fields.
For more information, see Configuring Event-Based Commands for DTU.
To view the line item mapping
In the Data Map Component list, select the record named Line Item.
Look at Advanced Option and the mapping in the Data Map field list.
Mapping the Extended Attributes
Next, look at the XA component.
Note that deep XA buscomps are used. In Web Tools, these buscomps are defined as children of the header buscomps, not as children of line items. This improves performance, because one query can retrieve all grand-children XA attributes that belong to a quote. To mirror the Tools configuration, XA is defined as a child of Header in the Data Map Component.
As deep XA buscomps are defined as children of the header, you cannot rely on Siebel buscomp links to set the parent line item IDs, which are stored in the Object Id field. You also cannot literally take object ID from quote to order, as the quote XA object ID points to a quote item, and the order XA object ID points to an order line item. You need to use ID mapping to look up the foreign keys in the order side. This is realized by the advanced options:
Name: ID Mapping Component
Value: Line Item
For more information, see Configuring Event-Based Commands for DTU.
To view the line item mapping
In the Data Map Component list, select the record named XA.
Look at Advanced Option and the mapping in the Data Map field list.
Examples of Invoking the DTU
The following topics illustrate the two ways of invoking the DTU, as they are used in the Siebel application, and how to use DTU services:
Example of Invoking DTU from a Workflow: Auto Order Web Service
Example of Using DTU Services shows how to use a DTU business service to copy data from one business component to another business component.
Example of Invoking the DTU from a Signal: Auto Sales Order
Auto sales order is a function that creates a sales order from the current quote. It can be invoked by clicking the Sales Order button in the Quote screen, then the Order view. This button invokes the signal AutoOrderSalesQuote. This example shows you how this signal invokes the DTU.
To see how the signal Auto SalesOrderQuote invokes the DTU
Log into Siebel application as an administrator.
Navigate to the Administration - Order Management screen, then the Signals view.
Query for AutoOrderSalesQuote.
In the last version list applet, drill into version 3.
You can see the three actions taken by the signal. Be sure that the you have selected the action that uses the method DataTransfer of the DTU Business Service, which copies the data into a new order.
In the Properties list, you can view the arguments of the DataTransfer method in the Parameter list, as shown in the following table:
Name of Parameter Value DataMapObj
QuoteToSalesOrder
Operation
Insert
Option
/BatchMode
SharedGlobalDestID
Y
At runtime, the signal infrastructure also passes the RowId of the current quote ID to DTU.
The SharedGlobalDestId parameter allows the destination record ID to be output to a shared global variable called SharedGlobalDestId. This variable is picked up in by the RefreshBCFromInstance method, whose arguments are shown in the following table:
Name of Parameter Value BusCompName
Order Entry - Orders
InstanceName
ISS Instance
TargetRowIdShared Global
DTUSharedGlobalDestId
The TargetRowIdSharedGlobal argument repositions the order buscomp to this row ID after refreshing, which is the row ID of the order just created.
Example of Invoking DTU from a Workflow: Auto Order Web Service
The Auto Order web service exposes Siebel's auto order function as a web service. It takes a quote row ID as the input argument, creates an order based on the quote, and returns a quote integration object. The web service is implemented by a workflow.
To see how the workflow SISOMAuto OrderWebService invokes the DTU
In Oracle’s Siebel Tools, locate the workflow SISOMAutoOrderWebService.
In this workflow, select the step DTU Auto Order, which uses DTU to create a new order from a quote using the DataTransfer method.
Display input arguments, which have the values shown in the following table:
Input Argument Sequence Type Value Property Name DataMapObj
1
Literal
QuoteToSalesOrder
None
Operation
2
Literal
Insert
None
Option
3
Literal
/BatchMode/NewSrcBusObj
None
RowID
4
Process Property
None
Object Id
Notice that there are some subtle differences from the input arguments of the previous example:
Here, RowId is explicitly passed in as an argument, but when you use a signal, the order management infrastructure implicitly passes in a RowId argument.
The Option argument contains "NewSrcBusObj". In the previous example, since signals pass the "RowId" argument instead of the buscomp instance into DTU, a new instance of the source buscomp is always created. This workflow specifies its Business Object as Quote. As a result, DTU receives a reference to the quote business component as part of the invocation context. Because you use NewSrcBusObj in this argument, DTU does not work off the instance of the quote buscomp associated with the workflow. Instead it creates a new instance of the quote business object. For information about why NewSrcBusObj is used, see Performance Tuning for DTU.
Display the output argument for this step, which has the values shown in the following table:
Property Name Sequence Type Output Argument ActiveOrderId
5
Output Argument
&OrderId
The newly created order ID is output through the DTU named parameter &OrderId. The parameter is defined in the data map Header component data map field view, which has the values shown in the following table:
Order Source Type Source Destination Type Destination 52
Parameter
&OrderId
Expression
[Id]
Example of Using DTU Services
The following example shows how to use the FINS Data Transfer Utility business service to copy data from one business component to another business component.
To copy a business component and specify a search specification
Create an input property set and search specification as follows:
Operation = "Insert" Option = "/NewSrcBusObj /NewDstBusObj" DataMapObj = "CopyContact" &ContactId = "<the contact row_id you want to copy>"
Configure DataMapObj ("CopyContact") to include a named parameter as follows:
Go to the root level data map component in the Data Map Component Applet.
Open the Advance Options Picker.
Add following New Advanced Option:
Name: Source Search Specification
Value: [Contact Id]=[&ContactId]
Clear cache.
In the business service simulator, invoke the FINS Data Transfer Utility business service using the DataTransfer method, passing in the input property set specified in Example of Using DTU Services.
The Siebel CRM client starts copying all the contacts.
From the documentation, it may seem like the Init parameters are needed, but they are not. The InitBO/InitBC input arguments cannot be used to construct a buscomp to start DTU. They are used to indicate from which buscomp of the active busobj you want to use to launch DTU.
Data Transfer Utilities Methods
This topic describes the following Data Transfer Utilities business service methods.
DataTransfer Method
The DataTransfer method transfers data from the source business component to the destination business component. Its arguments are described in the following table.
| Argument | Description |
|---|---|
Data Map Object (Required) |
The name of the data map object that defines the mapping. |
Operation (Required) |
Valid entries include Insert, Update, Delete, and Upsert. |
GotoView (Optional) |
The name of a view that appears to users after the data transfer operation. |
Option (Optional) |
A text field that allows you to specify additional options for the operation. Supported options include:
|
The following syntax is recommended for defining Option: /option1 /option2 … For example, /NewSrcBusObj /NewDstBusObj |
|
Initiator Business Object (Optional) |
Used as a sanity check. If the BusObject that invokes DTU is different from what is specified by the InitBO argument, DTU exits as an external error. Initiator Business Object is part of the invocation context. DTU receives a reference of the initiator business object only when invoked from Runtime Evens, Buscomp Named Methods, or workflow processes with its business object defined. DTU can be invoked without an initiator business object. |
Initiator Business Component (Optional) |
By default, the Buscomp that invokes DTU serves as the InitBC. Initiator Buscomp plays an important role in determining how records are transferred. Use the InitBC argument to set other Buscomp in the Initiator BusObject as the Initiator Buscomp. |
Initiator Search Specification or Initiator Sort Specification (Optional) |
Initiator Buscomp search spec and sort spec. |
Initiator Buscomp Enumerate Flag (Optional) |
Y or N. By default, Initiator Buscomp Enumerate Flag is N. When it is true, DataTransfer is applied to each record in the initiator Buscomp. When InitSearchSpec or InitSortSpec is specified, InitEnumFlag is implicitly true, even if InitEnumFlg is set to N. |
MockMethodReplied |
Y or N. |
RowId (optional) |
The ID of the root source buscomp record. For more information, see Using DTU with Order Management Signals. |
IgnoreRowId (optional) |
Y or N. If Y, RowId argument is then ignored. For more information, see Using DTU with Order Management Signals. |
SharedGlobalDestId (optional) |
Y or N. If Y, the destination record ID is output to a shared global called DTUSharedGlobalDestId. |
FAFireEventxxx Method
FAFireEventxxx is a hidden method that you can use to create a toolbar command. It invokes the method “EventMethodxxx” on the primary business component of the active view. “EventMethodxxx” triggers the event manager, which invokes either a workflow or a business service.
GetActiveViewProp Method
This is an auxiliary function to retrieve the active view’s properties. It does not take any input arguments.
Arguments
| Argument | Description |
|---|---|
Business Object |
Business object name. |
View |
Active view name. |
Screen |
Active screen name. |
Thread Applet |
Thread applet name. |
Is Administration Mode |
Y or N. |
View Mode Code |
An integer representing Siebel view mode:
|
TryMockMethod Method
This is an advanced auxiliary function for administration of the tool bar button workflow. It does not take any input arguments.
Arguments
| Argument | Description |
|---|---|
MockMethodReplied |
Y or N. |
QueueMethod Method
Launch a queue method on an applet in another view. When invoked, the UI navigates to the view specified, and then the Queue method is invoked on the specified applet.
Other input arguments of this method will be cached into the application Shared Global, which can be retried back.
DTU DataTransfer method has built-in integration with the QueueMethod. When the input argument DataMapObject has the format:
SharedGlobal: NameofSharedGlobal
The data map object name can be retrieved from Shared Global with the name NameofSharedGlobal.
Arguments
| Argument | Description |
|---|---|
GotoView |
Name of the view to go to. |
Applet |
Applet name. |
Method |
Queued method to be invoked on the applet. |