7 Configuring and Mapping Custom Fields in Oracle CRM On Demand

This chapter provides an overview of how to create custom fields in CRM On Demand and synchronize those fields to Oracle E-Business Suite. This chapter includes the following sections:

• Section 7.1, "Overview"

• Section 7.2, "Creating a Custom Field in CRM On Demand"

• Section 7.3, "Adding Custom Fields in CRM On Demand"

• Section 7.4, "Updating the CRM On Demand Schema and WSDL"

• Section 7.5, "Adding the Custom Fields to the Common Utility Query XSL Files"

• Section 7.6, "Mapping Custom Fields in the BPEL Process Custom XSL Files"

• Section 7.7, "Deploying the BPEL Process After Amending the Custom XSL File"

7.1 Overview

This chapter describes the steps involved in creating custom fields in CRM On Demand and synchronizing those fields to Oracle E-Business Suite. Perform the following tasks in this sequence:

1. Create a custom field in CRM On Demand.

2. Add custom fields in CRM On Demand.

3. Update the CRM On Demand schema and Web Service Definition Language (WSDL) in the Service-Oriented Architecture (SOA) server.

4. Add the custom fields to the Common Utility Query XSL files.

5. Map the custom field in the BPEL process custom XSL files.

6. Deploy the BPEL process.

Note:

Do not add custom fields to CRM On Demand Quote and Order objects that are marked Required. It causes the integration to fail because the quote and order conversion processes cannot determine the values to enter in the required fields.

7.2 Creating a Custom Field in CRM On Demand

This topic describes how to create a custom field in CRM On Demand.

To create a custom field:

1. Perform step 4 of the procedure, Section 6.4.3.1, "Creating the Integration Status Fields".

2. Click Rename Fields, Advanced.

3. Note the Integration Tag created for the custom field that you just created.

7.3 Adding Custom Fields in CRM On Demand

This custom field is for multi-org implementation only.

For more information, see Appendix C, "Settings for Multi-Org Implementation"

7.4 Updating the CRM On Demand Schema and WSDL

This topic describes how to update the schema and WSDL in the SOA server.

To update the schema and WSDL:

1. Log in to Oracle CRM On Demand as a user with Administrator privileges.

2. Navigate to Admin, Web Services Administration, and select Web Services v 1.0 Services.

3. Select the relevant record type.

4. Click the Download Custom WSDL link.

5. Search for the Custom Field Integration Tag assigned to the field that you created in the Section 7.2, "Creating a Custom Field in CRM On Demand" procedure.

   For example, if you created a custom field titled Phone Extension, it appears as follows:

   <xsd: element name="PhoneExtension" type="xsdLocal: string10"/>

6. Log in to the SOA server.

   For more information, see Oracle Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack 11g Release 1, "Using MDS in AIA."

7. Navigate to AIA_HOME>/AIAMetaData/AIAComponents/ApplicationObjectLibrary/CRMOD/V1/wsdls.

   A WSDL file exists for each object type; the format of the file name is ObjectName.wsdl.

8. Locate the WSDL for the object for which you created the custom field.

9. Take a backup copy of the object.wsdl file.

10. Edit the object.wsdl file by adding the tag in Example 7-1 as the last element under the <xsd:complexType name="object "> node:

    Example 7-1 Tag for Object.wsdl File

    <xsd:sequence>
    <!-- Existing Fields -->
    <!-- Custom Field Added -->
    <xsd:element name="PhoneExtension"
    type="xsdLocal1:string10"/>
    </xsd:sequence>
    </ xsd:complexType>
    

    Example 7-2 shows the entry for the Account object:

    Example 7-2 Account Object Entry

    <xsd:complexType name="Account">
    <xsd:sequence>
    <!-- Existing Fields -->
    <!-- Custom Field Added -->
    <xsd:element name="PhoneExtension"
    type="xsdLocal1:string10"/>
    </xsd:sequence>
    </ xsd:complexType>
    

11. Repeat the same procedure for the schema file for the relevant object.

    On Demand object schema files are located in the <AIA_HOME>/AIAMetaData/AIAComponents/ApplicationObjectLibrary/CRM OD/V1/schemas directory.

    Ensure that the WSDL and schema files are edited correctly. If they are not, the relevant BPEL processes do not deploy successfully.

7.5 Adding the Custom Fields to the Common Utility Query XSL Files

A query XSL file exists for every parent object, such as an Account or Contact object. You must add details relating to the custom fields that you create to the XSL file of the object for which you created the custom field. This topic describes the mentioned task.

Note:

If an XSL file does not exist for an object, for example, for the Product object, you do not have to perform the steps in this procedure.

To add custom fields to the Common Utility Query XSL files:

1. Locate the XSL files by navigating to <AIA_HOME>/AIAMetaData/AIAComponents/ApplicationObjectLibrary/CRM OD/V1/utils.

   The format of the name of each XSL file is XFormCRMODObjectNametQuery.xsl.

2. Take a backup copy of the XSL file for the relevant object.

3. Edit the XSL file by adding the Integration tag assigned to each custom field that you created to the XSL file for the object.

   Add the Integration tag after the plSync_Status element. For example, if a custom field named Alternate Name is created for the Account object, and if it has an Integration tag of lt_AlternateName, the XSL file looks like Example 7-3:

   Example 7-3 XSL File

   <xsl:if test="$QueryChildrenOnly != 'Y'">
   <od:ParentAccountId/>
   <!-Already Defined Mappings „
   <od:Status/>
   <od:plSync_Status/>
   <od:lt_AlternateName/>
   </xsl:if>
   

7.6 Mapping Custom Fields in the BPEL Process Custom XSL Files

To ensure that the custom fields you create in CRM On Demand can be synchronized to Oracle E-Business Suite, you must add details relating to the custom fields to the custom XSL files of the BPEL processes associated with the relevant object.

Table 7-1 lists the BPEL processes and the associated custom XSL files that must be edited whenever a custom field has to be mapped, for each object type.

Table 7-1 BPEL Processes and XSL Files for Objects

Object	BPEL Process	Custom XSL file
Account	SyncCustomerCRMODProvABCSImpl CreateCustomerCRMODReqABCSImpl UpdateCustomerCRMODReqABCSImpl	CustomerEBM_to_AccountABM_Custom.xsl CreateCustomerCRMODABM_To_CreateCustomerPartyEBM_Custom.xsl UpdateCustomerCRMODABM_To_UpdateCustomerPartyEBM_Custom.xsl
Contact	SyncCustomerCRMODProvABCSImpl ProcessContactCRMODReqABCSImpl	CustomerEBMList_To_ContactABMList_Custom.xsl Xform_ContactABMReqMsg_to_CustomerPartyEBMReqMsg_Custom.xsl
Product	SyncItemListCRMODProvABCSImpl	ItemEBMList_to_ProductABMList_Custom.xsl

You can locate the BPEL processes for which an XSL file must be changed on the SOA server at AIA_HOME/services/Core/CRMOD.

This topic describes procedures to map the custom field Account AlternateName, which has an Integration Tag of lt_AlternateName, in a provider BPEL process and a requester BPEL process. The Account object AlternateName field is a custom field to the CustomerPartyAccount/Name Element in the CustomerPartyEBO.

Note:

Do not change existing field mappings defined for the Oracle Lead to Order Integration Pack for Oracle CRM On Demand and Oracle E-Business Suite PIP. Amending these field mappings can cause the integration to function incorrectly.

7.6.1 Mapping the Custom Field in a Provider BPEL Process

This topic describes how to map the custom field Account AlternateName in a provider BPEL process.

For account objects, field mappings have to be defined in the CustomerEBM_to_AccountABM_Custom.xsl file of the SyncCustomerCRMODProvABCSImpl BPEL process.

Example 7-4 illustrates the contents of the CustomerEBM_to_AccountABM_Custom.xsl file.

Example 7-4 Contents for the CustomerEBM_to_AccountABM_Custom.xsl File

<xsl:stylesheet version="1.0" namespacedeclarations >
<!-- User Defined Templates -->
<xsl:template name="AddressType_ext"/>
<xsl:template name="AccountType_ext"/>
</xsl:stylesheet>

Two templates are defined: one for the account and another for addresses. When a new custom field is created that represents parent or top-level account details, the corresponding mappings must be defined within the template named AccountType_ext.

The following steps are used to map the Name field from the CustomerPartyAccount node in the CustomerPartyEBM to the AlternateName custom field created in CRM On Demand.

To map the Name field to the AlternateName field in the Provider BPEL process:

1. Identify the template in which the field has to be mapped.

2. Check the name space of the Name field in the CustomerPartyEBO and note the corresponding namespace prefix from the custom XSL file.

   In this example, the prefix is custebo=http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/CustomerParty/V2

3. Check the name space of the AlternateName field in the CustomerPartyEBO and note the corresponding namespace prefix from the custom XSL file.

   In this example, the namespace prefix and value is xsdLocal1="urn:/crmondemand/xml/account"

4. Identify the XPATH expression for the Name source field in the CustomerPartyEBO.

   The following example illustrates the XPATH expression, excluding the namespace prefix: SyncCustomerPartyListEBM/DataArea/SyncCustomerPartyList/ CustomerPartyAccount/Name

5. To map the custom field, AltenateName, add the following under the template AccoutnType_ext:

   <xsdLocal1:lt_AlternateName>
   <xsl:value-of select="custebo:Name"/>
   </xsdLocal1:lt_AlternateName>
   

   By default, the main XSL file that performs the mapping between Enterprise Business Message (EBM) and the Account CRM On Demand Application Business Message ABM loops through each CustomerPartyAccountNode. If any field under this node must be mapped, then just specifying the Name field is sufficient.

   For example, if the Name field exists in the Organization node, which is a child of SyncCustomerPartyList, then the XPATH is similar to the following:

   <xsl:value-of select="../corecom:Organization/custebo:Name"/>

   where "../" indicates to move the control out of CustomerPartyAccount and refer the Name field under the Organization node.

Example 7-5 illustrates the CustomerEBM_to_AccountABM_Custom.xsl after you have completed the mapping:

Example 7-5 CustomerEBM_to_AccountABM_Customer.xsl

<xsl:stylesheet version="1.0"
xmlns:xsdLocal1="urn:/crmondemand/xml/account"
xmlns:corecom="http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2
xmlns:custebo="http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/CustomerParty/V2" >
<xsl:template name="AddressType_ext"/>
<xsl:template name="AccountType_ext"/>
<!--Map Name Field in CustomerPartyAccount Node to AlternateName -->
<xsdLocal1:lt_AlternateName>
<xsl:value-of select="custebo:Name"/>
</xsdLocal1:lt_AlternateName>
<!--Map Organization/MissionStatement to Custom AccountStmt Field -->
<xsdLocal1:lt_AccountStatement>
<xsl:value-of select="corecom:Organization/corecom:MissionStatement"/>
</xsdLocal1: lt_AccountStatement >
</ xsl:template >
</xsl:stylesheet>

7.6.2 Mapping the Custom Field in a Requester BPEL Process

This topic describes how to map the custom field Account AlternateName in a requester BPEL process.

In the topic Mapping the Custom Field in a Provider BPEL Process, the AlternateName field from CRM On Demand was mapped to the Name field in the CustomerPartyAccount node of the CustomerPartyEBO for the Account object. The flows affected by this mapping are:

• CreateCustomerCRMODReqABCSImpl

• UpdateCustomerCRMODReqABCSImpl

For the CreateCustomerCRMODReqABCSImpl BPEL, the custom XSL file is CreateCustomerCRMODABM_To_CreateCustomerPartyEBM_Custom.xsl.

Example 7-6 describes the contents of the CreateCustomerCRMODABM_To_CreateCustomerPartyEBM_Custom.xsl file:

Example 7-6 CreateCustomerCRMODABM_To_CreateCustomerPartyEBM_Custom.xsl File

<xsl:stylesheet version="2.0" xmlns:customcorecom="http://xmlns.oracle.com/EnterpriseObjects/Core/Custom/Common/V2"
xmlns:corecom="http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2"
xmlns:customebo="http://xmlns.oracle.com/EnterpriseObjects/Core/Custom/EBO/CustomerParty/V2">
<xsl:template name="CreateCustomerParty_ext">
<!-- Customers add transformations here -->
</xsl:template>
. . . . . . . . . . . . . . . . . . . . . . .
<xsl:template name="PartyContact_ext">
<!-- Customers add transformations here -->
</xsl:template>
</xsl:stylesheet>

The following steps are used to map the custom field in the Requester BPEL process.

To map the Name field to the AlternateName field in the Requester BPEL process:

1. The CreateCustomerCRMODABM_To_CreateCustomerPartyEBM_Custom.xsl file has extension templates defined for each node that is available in the CustomerPartyEBO. Identify the Extension Template in which the CRM On Demand custom field must be mapped.

   In this example, the template name is "CustomerPartyAccount_ext"

2. Check the namespace for the AlternateName field and note the corresponding namespace prefix that is specified in the appropriate custom XSL file.

   In this example, the namespace prefix and value is xsdLocal1="urn:/crmondemand/xml/account"

3. Check the name space for the Name field in the CustomerPartyEBO and note the corresponding namespace prefix from the custom XSL file.

   In this example, it is ebo=http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/CustomerParty/V2

4. Identify the XPATH expression for the source field AlternateName in the CRM On Demand Account schema.

   The following example illustrates the XPATH expression, excluding the namespace prefix: ListOfAccount/Account/AlternateName.

5. To map the AlternateName custom field, add the following under the template named "AccountType_ext"

   <ebo:Name>
   <xsl:value-of select="xsdLocal1:AlternateAddress"/>
   </ebo:Name>
   

6. Repeat the same procedure for the UpdateCustomerCRMODReqABCSImpl BPEL process.

Example 7-7 illustrates the contents of the CreateCustomerCRMODABM_To_CreateCustomerPartyEBM_Custom.xsl file after you have completed the mapping:

Example 7-7 CreateCustomerCRMODABM_To_CreateCustomerPartyEBM_Custom.xsl File

<xsl:stylesheet version="2.0" xmlns:customcorecom="http://xmlns.oracle.com/EnterpriseObjects/Core/Custom/Common/V2" xmlns:corecom="http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2" xmlns:ebo="http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/CustomerParty/V2" xmlns:customebo="http://xmlns.oracle.com/EnterpriseObjects/Core/Custom/EBO/CustomerParty/V2"
xmlns:xsdLocal1="urn:/crmondemand/xml/account">
. . . . . All Other Defined Templates . . . . . .
<xsl:template name="CustomerPartyAccount_ext">
<!-- Newly Added Mapping -->
<ebo:Name>
<xsl:value-of select="xsdLocal1:AlternateAddress"/>
</ebo:Name>
</xsl:template>

7.7 Deploying the BPEL Process After Amending the Custom XSL File

The procedure in this topic describes how to deploy the BPEL process after you amended the related custom XSL file.

To deploy the BPEL process, copy the appropriate BPEL process, for example, the SyncCustomerCRMODProvABCSImpl process, to a temporary folder as follows:

1. Navigate to the <aia.home> directory and run the following command:

   Source bin/aiaenv.sh

2. Go to the appropriate process directory folder on the SOA server by running the following command:

   cd BPEL Process Name

3. Run the following command:

   (ant -f build.xml)

4. Verify that the process was deployed.

5. Restart the SOA server.