Oracle Web Services On Demand Guide > Web Services On Demand API Calls > Service API Calls >

GetEvents

Returns events from an integration event queue.

Objects Supported

GetEvents is supported for all objects that use Web Services v2.0 Schema and the following objects that use Web Services v1.0 Schema:

Account, Account Competitor, Account Contact, Account Contact Role, Account Note, Account Team, Activity, Activity Attachment, Asset, Call PromItemDrop, Call SampleDropped, Campaign, Contact, Contact Campaign, Contact Interests, Contact Note, Contact Team, Custom Object 01 - 03, Custom Object 01 - 03 Team, Dealer, Event Household, Household Contact, HouseholdTeam, Lead, Lead Team, Opportunity, Opportunity Competitor, Opportunity Contact Role, Opportunity Note, Opportunity Partner, Opportunity Team, Portfolio, Portfolio Owner, PortfolioTeam, Product, ProductCategory, Program, Program Partner, Service Request, Service Request Note, Service Request Team, Solution, Territory, Vehicle.

Usage

You use the GetEvents method of the Integration Event Web service to return events from an integration event queue. Integration events are actions that are triggered based on meeting certain workflow criteria. An integration event stores information about data that has changed:

• User key information about the changed record, for example: objectID, externalsystemID
• Audit information, for example, created date, created by, modified date, modified by

For integration events resulting from merge operations, the objectId and externalsystemId of both the primary and duplicate records are returned:

• DeletedRecordExternalSystemId
• DeletedRecordId
• MergedRecordExternalSystemId
• MergedRecordId

When company administrators create an Integration Event action on a workflow rule, they can specify the schema version to be used for integration events. The default schema version is Web Services v2.0 schema, but for objects that support both Web Services v1.0 and Web Services v2.0 Schema, the company administrator can select either schema version.

Integration events are stored in one or more company queues on the hosted environment. The maximum number of events in the queues is set by Customer Care. Contact Customer Care to request support for the Integration Event Web Service and to specify the maximum total size of the integration queues you require.

In the Integration Event Queue Settings page in the UI, the Picklist Format field determines whether language-independent values or language-dependent values (in the user's language) for picklists are written to an integration event queue.

For more information about integration events and setting up workflow criteria, see Oracle CRM On Demand Online Help.

If the EventCount argument is not supplied, all events are returned.

The QueueName argument, if specified, must match the name of a queue defined for a company within Oracle CRM On Demand. The QueueName value is the localized display name value for the user. If the supplied name is not valid, an error message is returned.

If QueueName is not specified, the value is empty, or if the value is Default Queue, events are returned from the default queue.

When there is a pending request to a queue, another call to the same queue cannot be invoked until the previous request completes. However, another call to a different queue can be invoked before the previous request completes.

You can return events for all supported record types, or a subset of record types, depending on how you prepare the WSDL and Schema files associated with the Integration Event service, see Preparing the Integration Event WSDL File and Schema Files.

In some cases the names of objects in the list of events returned differ from the name of the object used in the UI of Oracle CRM On Demand, as shown in Mapping of Display Names to Service API Object Names.

Time Zone Setting for Integration Events

On the Integration Event Queue Settings page in the UI your company administrator can specify settings for the default queue. The Time Zone picklist determines how the values of date and time fields (for example, ModifiedDate, CreatedDate) are recorded in integration events.

You can also use the IntegrationEventQueueUpsert method to specify values for the Time Zone field, and the values you can specify are UTC, UTC Format, and User Time Zone (the default value) as explained in IntegrationEventQueueUpsert.

Arguments

Table 49 describes the arguments taken by the GetEvents method.

Return Value of the Call

A list of the events returned from the integration event queue. Also, the ID of the last event returned.

The QueueName value is returned, if it is specified in the GetEvents request.

For each event in the list of events, there are the following attributes:

• name. The name of the associated Workflow.
• object. The record type.
• operation. The operation performed. The attribute values can be:
  • insert - for items inserted
  • update - for items updated
  • merge - for items merged
  • purge - for items that have been purged from the Deleted Items area
  • delete - for items that have been deleted and are still in the Deleted Items area
  • restore - for items that have been deleted and then restored
  • associate - for child items that have been associated with a parent record type
  • dissociate - for child items that have been dissociated from a parent record type

    NOTE:  Only the Activity, Account, Contact, and Opportunity objects support the associate and dissociate operations. The integration events generated for these objects vary depending on whether the request is made through a Web service request or the UI. For more information, about these differences in integration events, see the information about workflow rules in Oracle CRM On Demand Online Help.

Sample SOAP Request and Responses

This topic contains sample SOAP requests that invoke GetEvents.

Sample SOAP Request 1 - GetEvents with No Arguments

In the following SOAP request, no arguments are passed in (there are no required arguments for GetEvents), all the events from the default queue are retrieved:

<?xml version="1.0" encoding="utf-8" standalone="no"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <soap:Header>

      <wsse:Security>

         <wsse:UsernameToken>

            <wsse:Username>%%%USERNAME%%%</wsse:Username>

            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">%%%PASSWORD%%%</wsse:Password>

         </wsse:UsernameToken>

      </wsse:Security>

   </soap:Header>

   <soap:Body>

      <IntegrationEventWS_GetEvents_Input xmlns="urn:crmondemand/ws/integrationevent/"></IntegrationEventWS_GetEvents_Input>

   </soap:Body>

</soap:Envelope>

Sample SOAP Response 1

The following shows the response for sample request 1. The events from the default queue are returned.

<?xml version="1.0" encoding="utf-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <SOAP-ENV:Body>

      <ns:IntegrationEventWS_GetEvents_Output xmlns:ns="urn:crmondemand/ws/integrationevent/">

         <ListOfEvent xmlns="urn:/crmondemand/xml/integrationevent">

            <Event object="Contact" name="cContact Update" operation="update">

               <SiebelMessage>

                  <ListOfContact xmlns="urn:/crmondemand/xml/contact">

                     <Contact>

                        <ContactId>ADSA-96CRZK</ContactId>

                        <ModId>1</ModId>

                        <CreatedDate>08/09/2011 10:17:48</CreatedDate>

                        <ExternalSystemId></ExternalSystemId>

                        <ContactFirstName>Testing</ContactFirstName>

                        <IntegrationId>ADSA-96CRZK</IntegrationId>

                        <ContactLastName>U2</ContactLastName>

                        <ModifiedById>HRZ780-I5RUE</ModifiedById>

                        <ModifiedDate>08/09/2011 10:21:16</ModifiedDate>

                        <AlternateAddressId>ADSA-6CRZM</AlternateAddressId>

                        <CreatedById>HRZ780-I5RUE</CreatedById>

                     </Contact>

                  </ListOfContact>

               </SiebelMessage>

            </Event>

            <Event object="Contact" name="cContact - Send Welcome Package" operation="insert">

               <SiebelMessage>

                  <ListOfContact xmlns="urn:/crmondemand/xml/contact">

                     <Contact>

                        <ContactId>ADSA-96D7AO</ContactId>

                        <ModId>0</ModId>

                        <AccountId>No Match Row Id</AccountId>

                        <CreatedDate>08/09/2011 10:40:52</CreatedDate>

                        <ExternalSystemId></ExternalSystemId>

                        <ContactFirstName>Testing2</ContactFirstName>

                        <IntegrationId>ADSA-96D7AO</IntegrationId>

                        <ContactLastName>U1</ContactLastName>

                        <ModifiedById>HRZ780-I5RUE</ModifiedById>

                        <ModifiedDate>08/09/2011 10:40:53</ModifiedDate>

                        <AlternateAddressId>ADSA-96D7AQ</AlternateAddressId>

                        <CreatedById>HRZ780-I5RUE</CreatedById>

                     </Contact>

                  </ListOfContact>

               </SiebelMessage>

            </Event>

            <Event object="Contact" name="cContact Update" operation="update">

               <SiebelMessage>

                  <ListOfContact xmlns="urn:/crmondemand/xml/contact">

                     <Contact>

                        <ContactId>ADSA-96D7EA</ContactId>

                        <ModId>2</ModId>

                        <CreatedDate>08/09/2011 10:45:39</CreatedDate>

                        <ExternalSystemId></ExternalSystemId>

                        <ContactFirstName>C</ContactFirstName>

                        <IntegrationId>ADSA-96D7EA</IntegrationId>

                        <ContactLastName>C8</ContactLastName>

                        <ModifiedById>HRZ780-I5RUE</ModifiedById>

                        <ModifiedDate>08/09/2011 10:57:52</ModifiedDate>

                        <AlternateAddressId>ADSA-96D7EC</AlternateAddressId>

                        <CreatedById>HRZ780-I5RUE</CreatedById>

                     </Contact>

                  </ListOfContact>

               </SiebelMessage>

            </Event>

            <Event object="Account" name="Accounts Create" operation="insert">

               <SiebelMessage>

                  <ListOfAccount xmlns="urn:/crmondemand/xml/account">

                     <Account>

                        <AccountId>ADSA-96DJL4</AccountId>

                        <ModId>0</ModId>

                        <CreatedDate>08/09/2011 11:04:50</CreatedDate>

                        <CurrencyCode>USD</CurrencyCode>

                        <ExternalSystemId></ExternalSystemId>

                        <IntegrationId>ADSA-96DJL4</IntegrationId>

                        <Location></Location>

                        <ModifiedById>HRZ780-I5RUE</ModifiedById>

                        <ModifiedDate>08/09/2011 11:04:51</ModifiedDate>

                        <AccountName>A1</AccountName>

                        <NumberEmployees>1000</NumberEmployees>

                        <PrimaryBillToAddressId>ADSA-96DJL6</PrimaryBillToAddressId>

                        <PrimaryShipToAddressId>ADSA-96DJL8</PrimaryShipToAddressId>

                        <CreatedById>HRZ780-I5RUE</CreatedById>

                     </Account>

                  </ListOfAccount>

               </SiebelMessage>

            </Event>

         </ListOfEvent>

         <ns:LastEventId>20110809160454038_QNMHRZ780-I5RT8_Account_Account_ADSA-96DJL4_0_ADSA-96DCMZ.xml</ns:LastEventId>

      </ns:IntegrationEventWS_GetEvents_Output>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Sample SOAP Request 2 - GetEvents with EventCount and QueueName

The following SOAP request retrieves one event from the queue High Priority Queue specified by using the <EventCount> and <QueueName> arguments.

<?xml version="1.0" encoding="utf-8" standalone="no"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <soap:Header>

      <wsse:Security>

         <wsse:UsernameToken>

            <wsse:Username>%%%USERNAME%%%</wsse:Username>

            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">%%%PASSWORD%%%</wsse:Password>

         </wsse:UsernameToken>

      </wsse:Security>

   </soap:Header>

   <soap:Body>

      <IntegrationEventWS_GetEvents_Input xmlns="urn:crmondemand/ws/integrationevent/">

         <QueueName>High Priority Queue</QueueName>

         <EventCount>1</EventCount>

      </IntegrationEventWS_GetEvents_Input>

   </soap:Body>

</soap:Envelope>

Sample SOAP Response 2

The following shows the response for sample SOAP request 2. The events from the named queue are returned.

<?xml version="1.0" encoding="utf-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <SOAP-ENV:Body>

      <ns:IntegrationEventWS_GetEvents_Output xmlns:ns="urn:crmondemand/ws/integrationevent/">

         <ListOfEvent xmlns="urn:/crmondemand/xml/integrationevent">

            <Event object="Contact" name="cContact Update" operation="update">

               <SiebelMessage>

                  <ListOfContact xmlns="urn:/crmondemand/xml/contact">

                     <Contact>

                        <ContactId>ADSA-96CRZK</ContactId>

                        <ModId>1</ModId>

                        <CreatedDate>08/09/2011 10:17:48</CreatedDate>

                        <ExternalSystemId></ExternalSystemId>

                        <ContactFirstName>Testing</ContactFirstName>

                        <IntegrationId>ADSA-96CRZK</IntegrationId>

                        <ContactLastName>U2</ContactLastName>

                        <ModifiedById>HRZ780-I5RUE</ModifiedById>

                        <ModifiedDate>08/09/2011 10:21:16</ModifiedDate>

                        <AlternateAddressId>ADSA-96CRZM</AlternateAddressId>

                        <CreatedById>HRZ780-I5RUE</CreatedById>

                     </Contact>

                  </ListOfContact>

               </SiebelMessage>

            </Event>

         </ListOfEvent>

         <ns:LastEventId>20110809152116757_QNMHRZ780-I5RT8_Contact_Contact_ADSA-96CRZK_1_ADSA-96CSA5.xml</ns:LastEventId>

         <ns:QueueName>Sample Queue</ns:QueueName>

      </ns:IntegrationEventWS_GetEvents_Output>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Preparing the Integration Event WSDL File and Schema Files

You can use the methods of the Integration Events service to track changes for the supported record types. You must download the integrationevent.wsdl file and the XSD Schema file for each record type that you require to track. You can download XSD files for all objects for the Web Services v1.0 API and for the Web Services v2.0 API. The integration event WSDL file imports the XSD files for each record type.

In addition, to get integration events generated for merge operations, you must download a Merge schema file and integrate this and the integration event WSDL file with your application. Existing customers must download the latest integrationevent.wsdl file, if they wish to use the Merge schema file.

NOTE:  The Merge schema file is only applicable to integration events processing and cannot be used for other purposes.

The integrationevent.wsdl file is dynamically generated based on which objects have an active workflow rule with an integration event action configured.

For each object with an integration event action configured, a child element of <SiebelMessage> is added to the WSDL files, for example, <ListOfAccount>.

For child objects, an element is added for the parent object, for example, an entry for the Account parent object is added for the Account Team child. For child objects with multiple parents, an element is added for each possibe parent, for example, Account, Contact, and Opportunity parent entries would be added for a Revenue child.

Also, for each object, one or more <import> elements are added to the WSDL file with attributes for the namespace and schema location of an XSD file. The attribute values depend on whether Web Services v1.0 or Web Services v2.0 Schema have been selected for the integration events for the object. The following is an example of an <import> element for an object with an integration event for which the Web Services v1.0 Schema is selected:

<xsd:import namespace="urn:/crmondemand/xml/account" schemaLocation="Account.xsd" />

The following is an example of an <import> element for an object with an integration event for which the Web Services v2.0 Schema is selected:

<xsd:import namespace="urn:/crmondemand/xml/Account/Data" schemaLocation="Account.xsd" />

For more information about specifying the schema version when creating integration event actions, see Oracle CRM On Demand Online Help.

To prepare the WSDL

1. Go to the Web Services Administration page in the Oracle CRM On Demand application.
2. Download the Integration Events WSDL.
3. Download the Generic Schema files for objects for which you wish to generate integration events and copy these to the folder where you downloaded the WSDL file.
4. If you have created custom fields or renamed fields for an object, download the Custom XSD file for the object.
5. If you require to access events resulting from merge operations, download the generic schema file for the Merge Service API.
6. In the integrationevent.wsdl file, remove references to any Schema files for objects you will not be using.
7. Add the integrationevent.wsdl file to your development environment.

NOTE:  You must repeat steps 3 through 7 each time a new custom field is added that will be tracked through integration events, or when you begin tracking a new object type. Otherwise, the client application cannot process events containing these newly added fields or objects.