Pervasive Data Integrator Oracle CRM On Demand Connector Guide Pervasive Software Inc. 12365 Riata Trace Parkway Building B Austin, Texas 78727 USA Telephone: (512) 231-6000 or (800) 287-4383 Fax: (512) 231-6010 Email: info@pervasive.com Web: http://www.pervasive.com
See copyrights.txt in the product installation directory for information on third-party and open software components. Oracle CRM On Demand Connector Guide Aug 2011 ii
Contents Oracle CRM On Demand... 1 Supported Versions... 1 Installation Requirements... 1 Property Options... 2 Supported Entities... 4 Connector Specific Notes... 6 Upsert with Relationships... 6 Attachments... 6 Using Sessions... 6 Mapping API... 6 Building Maps... 7 Field Lengths... 7 Non-Accessible Child Entities... 7 Data Type Support... 7 Debugging Tips... 7 iii
Oracle CRM On Demand Oracle CRM On Demand is a web-based CRM software platform that enables its users to access information using a Web Services interface. The Oracle CRM On Demand connector supports most entities exposed by the Oracle CRM On Demand Web Service, an open XML-based online platform that provides Simple Object Access Protocol (SOAP) access. SOAP relies on XML for its messaging format. This XML based protocol consists of three parts: an envelope, which defines what is in the message and how to process it, a set of encoding rules for expressing instances of application-defined data-types, and a convention for representing procedure calls and responses. This connector allows users to retrieve, insert, update, and delete data from/to Oracle CRM On Demand. To use the Design Studio with Oracle CRM On Demand, the API for your organization must be enabled within Oracle CRM On Demand. Entity names change with each version of the API. Custom entities are also supported. Supported Versions Oracle CRM On Demand Release 17 Oracle CRM On Demand Release 18 Oracle CRM On Demand Release 19 Installation Requirements User needs to have read/write access to a fully functional Oracle CRM On Demand account. The Hosting Server name (supplied by Oracle), User Sign In ID (Login ID) and Password for the account are needed for this connector to log into the Oracle CRM On Demand account. The Default Access Profile name of the logged in user is to be provided. This enables the connector with the ability to dynamically know the child objects to which the user has access to. The Oracle CRM On Demand Integration capability for your company needs to be enabled (An Oracle CRM On Demand Customer Care representative enables the same, on request, at no additional cost). In addition, Role Management service should be enabled for the Oracle CRM On Demand account. Using the Administrator role, the Record Type access and the Access Profile for the User's role should be turned ON (in the administration section) for all parent and child entities to be integrated. For additional information on the above requirements, please refer to the Oracle CRM On Demand documentation. 1
Property Options The following Source/ Target property options can be set in connections. Property S/T Use Server ST Enter the default URL of your Oracle CRM On Demand instance as given in below example. e.g. https://secure-ausomxhia.crmondemand.com Username ST User Sign In ID (Username) for logging into the Oracle CRM On Demand environment. If using the Siebel login invoker, you may replace the Username with a SessionToken of the form <serverurl>:jsessionid=<sessionid>. Note: If SessionToken is provided, leave the Password empty Password ST Password for connecting to Oracle CRM On Demand. Leave empty if SessionToken is being used Query Source S Table/View (default option): This option will list all the objects available in Oracle CRM On Demand. After selecting this option, click the arrow Next to Source Table/View, to choose the Table or View that you want to access from the list. You must choose at least one table or view to be able to run a transformation with this connector. Query Statement: This option will allow you to extract data from Oracle CRM On Demand using a Query written in XML format. After selecting this option, please click the ellipsis button to open the Query Statement Box to enter the Query XML. For details on writing Query XMLs, please see the following topic in the Oracle CRM On Demand Documentation: Web Services On Demand API Calls > Query Page. Please note that the XML format for Web Service 1.0 and Web Service 2.0 API calls are different as given in the CRMOD documentation. You can identify which version (1.0 or 2.0) to use for a given object by referring to the "Entity Names" section of this document. Query File: Use this option to extract data using a query stored in a text file. After selecting this option, please click the ellipsis button to browse and select your query file. Please note that this query file should contain the XML required for the Query Page API call as given in the example below. Note: THE XML SHOULD START WITH <ListOfxxxx> ELEMENT, where xxxx is the Parent Entity's name E.g.: <ListOfContact> <Contact> <ContactFirstName>= John </ContactFirstName> <ContactLastName/> <ListOfAddress> <Address> <Country>= Canada </Country> </Address> </ListOfAddress> </Contact> </ListOfContact> Table T Select the Table (Oracle CRM On Demand Object) and this should be the transformation target object where the data will be written. 2
Property S/T Use Batch Select the file name to which the target operations' responses are logged. Response In delete operations, one batch response entry exists for every delete action. In Insert, Upsert and Update operations, one batch response entry exists for every Insert or Update action. The return Code for individual operation will show the result of the operation execution. If the operation is success then the return Code will be 0. For failed operations, the error Description tag will show the detailed error message (See below). This will include message returned from Oracle CRM On Demand as well as PDI generated errors. Note: When the return Code is 0 (success) then this tag will return the Entity's unique ID for which the operation was successful. Example: <BatchResponse:batchResult xmlns:batchresponse="http://www.pervasive.com/batchresponse"> <BatchResponse:results> <BatchResponse:result> <BatchResponse:returnCode>34</BatchResponse:returnCode> <BatchResponse:errorDescription>No rows retrieved corresponding to the business component 'Campaign'(SBL-EAI-04378)</BatchResponse:errorDescription> <BatchResponse:objectContainerName>Campaign</BatchResponse:objectContainerNa me> <BatchResponse:updateOperation>DELETE</BatchResponse:updateOperation> </BatchResponse:result> </BatchResponse:results> <BatchResponse:componentInfo> <BatchResponse:returnCode>0</BatchResponse:returnCode> <BatchResponse:componentName>Oracle CRM On Demand</BatchResponse:componentName> </BatchResponse:componentInfo> </BatchResponse:batchResult> Batch Size S The number of records buffered by PDI before processing them to map and transfer data to the target. Page Size ST This determines the number of records fetched for each Query Page Web Service call. Max Page Size = 100 (Limit imposed by Oracle CRM On Demand). Default value is 50. Use Field Display Names ST If set to 'true', the Display Names of the fields are used as Field Names in the transformation. The display names are first stripped off any special characters and if this name is found to be a duplicate for that object, then a integer value is appended. When this is set to 'true', the Field Description column shows the actual Field Name Default value is False. 3
Property S/T Use UseChildAnd S Sets the 'UseChildAnd' property of Query Page web service call. Refer to Oracle CRM On Demand documentation for more details. The default value is True Default Access Profile Name ST The default Access Profile name for the Role assigned to the current logged in user. Login to the CRM OnDemand and follow these steps to get this value. Admin > UserManagementAndAccessControls > AccessProfiles > RoleManagement > [Edit] [rolename] > Step3-AccessProfiles > DefaultAccessProfile RecordsPerReq T Allows user to set the number of records inserted/updated during each request between 1-20. Eg : If the batch size is set to 20, and the 10th record fails, it will attempt reexecuting the operation one record at a time till all the records in that batch are processed. As a result the batch response will have individual record level success/failure entry. Default value is 20. Supported Entities This section lists the different Oracle CRM On Demand entities supported by this connector. The information about the supported operations can be obtained from the table below. Entity Name Create Read Update Delete Account (WebService 1.0 API) Yes Yes Yes Yes Activity (WebService 1.0 API) Yes Yes Yes Yes Asset (WebService 1.0 API) No Yes No No Campaign (WebService 1.0 API) Yes Yes Yes Yes Contact (WebService 1.0 API) Yes Yes Yes Yes CurrentUser (WebService 1.0 API) No Yes No No CustomObject1 (WebService 1.0 API) Yes Yes Yes Yes CustomObject2 (WebService 1.0 API) Yes Yes Yes Yes CustomObject3 (WebService 1.0 API) Yes Yes Yes Yes Lead (WebService 1.0 API) Yes Yes Yes Yes Opportunity (WebService 1.0 API) Yes Yes Yes Yes Product (WebService 1.0 API) Yes Yes Yes No ProductCategory (WebService 1.0 API) Yes Yes Yes Yes ServiceRequest (WebService 1.0 API) Yes Yes Yes Yes Solution (WebService 1.0 API) Yes Yes Yes Yes Territory (WebService 1.0 API) Yes Yes Yes Yes 4
Entity Name Create Read Update Delete User (WebService 1.0 API) No Yes No No UserGroup (WebService 1.0 API) Yes Yes Yes Yes Application ( WebService 2.0 API) Yes Yes Yes Yes BusinessPlan ( WebService 2.0 API) Yes Yes Yes Yes Claim ( WebService 2.0 API) Yes Yes Yes Yes ContactBestTimes ( WebService 2.0 API) Yes Yes Yes Yes Coverage ( WebService 2.0 API) Yes Yes Yes Yes CustomObject4 ( WebService 2.0 API) Yes Yes Yes Yes CustomObject5 ( WebService 2.0 API) Yes Yes Yes Yes CustomObject6 ( WebService 2.0 API) Yes Yes Yes Yes CustomObject7 ( WebService 2.0 API) Yes Yes Yes Yes CustomObject8 ( WebService 2.0 API) Yes Yes Yes Yes CustomObject9 ( WebService 2.0 API) Yes Yes Yes Yes CustomObject10 ( WebService 2.0 API) Yes Yes Yes Yes Damage ( WebService 2.0 API) Yes Yes Yes Yes DealRegistration ( WebService 2.0 API) Yes Yes Yes Yes FinancialAccount ( WebService 2.0 API) Yes Yes Yes Yes FinancialAccountHolder ( WebService 2.0 API) Yes Yes Yes Yes FinancialAccountHolding ( WebService 2.0 API) Yes Yes Yes Yes FinancialPlan ( WebService 2.0 API) Yes Yes Yes Yes FinancialProduct ( WebService 2.0 API) Yes Yes Yes Yes FinancialTransaction ( WebService 2.0 API) Yes Yes Yes Yes Fund ( WebService 2.0 API) Yes Yes Yes Yes Household ( WebService 2.0 API) Yes Yes Yes Yes InsuranceProperty ( WebService 2.0 API) Yes Yes Yes Yes InvolvedParty ( WebService 2.0 API) Yes Yes Yes Yes MDFRequest ( WebService 2.0 API) Yes Yes Yes Yes MedEd ( WebService 1.0 API) Yes Yes Yes Yes Objectives ( WebService 2.0 API) Yes Yes Yes Yes Partner ( WebService 2.0 API) Yes No Yes Yes PlanAccount ( WebService 2.0 API) Yes Yes Yes Yes 5
Entity Name Create Read Update Delete PlanContact ( WebService 2.0 API) Yes Yes Yes Yes PlanOpportunity ( WebService 2.0 API) Yes Yes Yes Yes Policy ( WebService 2.0 API) Yes Yes Yes Yes PolicyHolder ( WebService 2.0 API) Yes Yes Yes Yes Portfolio ( WebService 2.0 API) Yes Yes Yes Yes PriceList ( WebService 2.0 API) Yes Yes Yes Yes PriceListLineItem ( WebService 2.0 API) Yes Yes Yes Yes SPRequest ( WebService 2.0 API) Yes Yes Yes Yes SPRequestLineItem ( WebService 2.0 API) Yes Yes Yes Yes Vehicle ( WebService 2.0 API) Yes Yes Yes Yes Connector Specific Notes Upsert with Relationships Upsert is supported only for objects that are covered by Web Services 1.0 API as shown in the above entity list. Objects covered by Web Services 2.0 API (for example, Vehicle) are not supported for Upsert operation. Attachments For handling files/documents attached to an Oracle CRM On Demand object, the connector only supports uploading a file as an Attachment to an object i.e., the connector only supports file attachments on the target side. The option to download "Attached files" from Oracle CRM On Demand is not currently supported (The connector does not support reading/downloading the file attachments from Oracle CRM On Demand) Using Sessions This connector can be used with the Siebel Login Invoker. When using the login invoker, you will need to replace the Username with the SessionToken and leave the Password field empty. The SessionToken must use the format: <serverurl>:jsessionid=<sessionid> When SessionToken is used, all the entities are listed in the Tables list; irrespective of whether the particular user is having access to or not. Mapping API For certain entities, if the mapping API is not supported, then all the fields are listed irrespective of whether a particular field (custom field ) is enabled for that account or not. 6
Custom fields do support the display name in Map Designer, but only if the Mapping API is supported for that object. Building Maps When building maps using Oracle CRM On Demand as a target, please refer the Oracle CRM On Demand help file "OnDemWebSvcs.pdf" available at Admin-->Web Services Administration-- >DownloadDocumentation. This document shows which records you can add as children to other records and the supported operations, Key fields for each entity. Field Lengths The field lengths reported in the source schema and source map tab may be too short for some Oracle CRM On Demand values. If a value, such a text string, appears to be truncated, you must manually adjust the field length to a larger value. Non-Accessible Child Entities If the user does not have access to any child object of a particular entity, they will NOT be able to see the particular child object displayed in the list of objects available for viewing through the data browser. Data Type Support BigDecimal BigInteger Boolean Byte Bytes Character Date Double Float Integer Record String Text Debugging Tips Please check the Log file and Batch Response File for error messages returned by the Oracle CRM On Demand service. 7
A "Map... Successful" message in the transformation log file means that no serious errors occurred during the transformation. However, you should also check the batch file for individual record failures. *** 8