Migrating Integration Event Queue Configuration Data

This chapter describes how to migrate the integration event queue configuration data using the Oracle Migration Tool On Demand client. It contains the following topics:

Integration Event Queues

The integration events that are generated by workflow Create Integration Event actions are written to integration event queues. A default integration event queue (named Default Queue) is provided with Oracle CRM On Demand. However, you can also create additional queues. For more information about integration event queues, see Oracle CRM On Demand Online Help.

The following table describes the Oracle Migration Tool On Demand client commands used with the integration event queue configuration data. These commands are case sensitive.

Table Commands Used with Integration Event Queue Configuration Data in Oracle Migration Tool On Demand

Command	Description
`Read IntegrationEventQueue QueueName`	This command extracts the configuration data for the specified integration event queue. QueueName is the name of an integration event queue.
`ReadAll IntegrationEventQueue`	This command extracts the configuration data for all of the integration event queues.
`Upsert IntegrationEventQueue IntegrationEventQueueXML`	This command updates or inserts an integration event queue.

Privileges Required for Migrating Integration Event Queue Configuration Data

The following privileges are required for the user account running the Oracle Migration Tool On Demand client commands:

For the Read and ReadAll commands: Enable Web Services Access. In addition, Integration Event Administration must be set up for your company.
For the Upsert command: Enable Web Services Access, and Manage Integration Event Queues.

In addition, to use the Read, ReadAll, and Upsert commands, Integration Event Administration must be set up for your company.

For information about setting and checking privileges, see Oracle CRM On Demand Online Help.

Elements and Sections in the Integration Event Queue XML Output File

The following table describes the elements and sections in the integration event queue XML output file.

Table Elements and Sections in the Integration Event Queue XML File

Description	Element or Section
The <IntegrationEventQueue> section contains all of the information for a single integration event queue.	<data:IntegrationEventQueue> . . . </data:IntegrationEventQueue>
<QueueName> contains the name of the integration event queue.	<data:IntegrationEventQueue> <data:QueueName>TestQueue</data:QueueName> . . . </data:IntegrationEventQueue>
<Description> contains the description of the integration event queue.	<data:IntegrationEventQueue> . . . <data:Description>MyTestQueue </data:Description> . . . </data:IntegrationEventQueue>
<Disabled> specifies whether the integration event queue is disabled (true) or is not disabled (false).	<data:IntegrationEventQueue> . . . <data:Disabled>false</data:Disabled> . . . </data:IntegrationEventQueue>
<Created> contains the user name of the user who created the integration event queue, with the date and time that the queue was created. This element is read-only and is ignored for upsert requests.	<data:IntegrationEventQueue> . . . <data:Created>SysAdmin, 05/21/2017 04:40:52</data:Created> . . . </data:IntegrationEventQueue>
<Modified> contains the user name of the user who last modified the integration event queue configuration, with the date and time that the queue configuration was last modified. This element is read-only and is ignored for upsert requests.	<data:IntegrationEventQueue> . . . <data:Modified>SysAdmin, 06/19/2017 06:26:52</data:Modified> . . . </data:IntegrationEventQueue>
<FileLimit> shows the total number of events that your company can store for all queues. If the combined size of the existing queues matches this number, then you cannot create a new queue. This element is read-only and is ignored for upsert requests.	<data:IntegrationEventQueue> . . . <data:FileLimit>500</data:FileLimit> . . . </data:IntegrationEventQueue>
<UnassignedQueueCapacity> shows the remaining capacity for all integration event queues. This element is read-only and is ignored for upsert requests.	<data:IntegrationEventQueue> . . . <data:UnassignedQueueCapacity>70 </data:UnassignedQueueCapacity> . . </data:IntegrationEventQueue>
<QueueSize> specifies the size of the queue. When you create a new queue, the size of the queue cannot exceed the remaining capacity, which is shown in the <UnassignedQueueCapacity> element.	<data:IntegrationEventQueue> . . . <data:QueueSize>10</data:QueueSize> . . . </data:IntegrationEventQueue>
<NumberOfTransactions> shows the number of transactions currently in the queue. This element is read-only and is ignored for upsert requests. Note: For information about clearing integration events from queues, see About Clearing Transactions from Integration Event Queues.	<data:IntegrationEventQueue> . . . <data:NumberOfTransactions>0 </data:NumberOfTransactions> . . . </data:IntegrationEventQueue>
<NotificationEmailAddress> is the email address to which a warning email is to be sent when the queue is full or when the queue reaches a certain size, if a warning email is to be sent.	<data:IntegrationEventQueue> . . . <data:NotificationEmailAddress> jane.doe@company.com </data:NotificationEmailAddress> . . . </data:IntegrationEventQueue>
<WarningMailQueueSize> specifies the size that the queue is allowed to reach before a warning email is sent to the address specified in the <NotificationEmailAddress> element.	<data:IntegrationEventQueue> . . . <data:WarningMailQueueSize>5 </data:WarningMailQueueSize> . . . </data:IntegrationEventQueue>
<TimeZone> specifies how the dates and times are recorded in the integration events. The valid values are: UTC Format. If this value is specified, then the date and time in the GMT time zone are recorded, in the format specified by the W3C standard for Coordinated Universal Time (UTC), as follows: YYYY-MM-DDTHH:MM:SSZ For example, 2017-06-12T09:44:15Z, which corresponds to June 12th 2017, 9:44:15 GMT. Note: Fractions of seconds are not recorded. UTC. If this value is specified, then the date and time in the GMT time zone are recorded, in the following format: MM/DD/YYYY HH:MM:SS For example, 06/12/2017 09:44:15, which corresponds to June 12th 2017, 9:44:15 GMT. User Time Zone. If this value is specified, then the date and time in the time zone of the user who updated the record are recorded, in the following format: MM/DD/YYYY HH:MM:SS For example, 06/12/2017 09:44:15, which corresponds to June 12th 2017, 9:44:15, in the user’s time zone. Note: You can set the Time Zone field for the Default Queue only. All other queues inherit the setting that is selected for the Default Queue.	<data:IntegrationEventQueue> . . . <data:TimeZone>User Time Zone</data:TimeZone> </data:IntegrationEventQueue>
<PicklistFormat> specifies the format for recording picklist field values in the integration events, as follows: LIC. If this value is specified, then the picklist values are recorded as language-independent code (LIC) values. Note: The LIC values in picklists are usually the same as the values in the English-United States (ENU) locale. User Language. If this value is specified, then the picklist values are recorded in the language of the user whose action causes the integration event to be created. Note: After a queue is created, the Picklist Format field becomes read-only and you cannot change it, either in the UI or through an upsert operation. If you want to change the picklist format of an integration event queue, then contact Oracle CRM On Demand Customer Care, and ask them to change it for you.	<data:IntegrationEventQueue> . . . <data:PicklistFormat>User Language </data:PicklistFormat> . . . </data:IntegrationEventQueue>

Migrating Integration Event Queue Configuration Data

The following topics describe how to use the Oracle Migration Tool On Demand client to migrate integration event queue configuration data:

Note: Back up your configuration data and all other relevant data before running the Oracle Migration Tool On Demand client.

Extracting a Single Integration Event Queue

This topic describes how to extract the configuration data for a single integration event queue from the Oracle CRM On Demand server for your environment; that is, a customer test environment or production environment. The output from the extract is saved to a file and directory as follows:

migration tool install/repository/IntegrationEventQueue/queuename.xml

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract the configuration data for a single integration event queue:

migrationtool -u UserID -s ServerURL Read IntegrationEventQueue QueueName

where:

UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.
QueueName is the name of the integration event queue for which you want to extract the configuration data.

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (using the pipe command) to the client program from standard input; that is, from a file, from the command line, or from another program.

Example of Extracting a Single Integration Event Queue

The following is an example of extracting the configuration data for a single integration event queue:

migrationtool -u UserID -s ServerURL Read IntegrationEventQueue "My Queue"

Note: If the queue name contains spaces, then it must be enclosed with quotation marks.

Extracting All Integration Event Queues

This topic describes how to extract the configuration data for all of the integration event queues from the Oracle CRM On Demand server for your environment; that is, a customer test environment or production environment.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract the configuration data for all of the integration event queues:

migrationtool -u UserID -s ServerURL ReadAll IntegrationEventQueue

where:

UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (using the pipe command) to the client program from standard input; that is, from a file, from the command line, or from another program.

Updating or Inserting an Integration Event Queue (Upsert)

This topic describes how to update the configuration data for an integration event queue (if the queue exists) or insert an integration event queue (if it does not exist) on your Oracle CRM On Demand environment (customer test environment or production).

About the Upsert Operation

The Upsert command inserts or updates integration event queue configuration data based on the user key: <QueueName>.

Oracle CRM On Demand attempts to locate the integration event queue specified in the input file based on the user key. If a match is located, then the configuration data for the integration event queue is updated. If Oracle CRM On Demand cannot locate an integration event queue based on the user key, then a new integration event queue is created.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to insert or update the configuration data for an event queue:

migrationtool -u UserID -s ServerURL Upsert IntegrationEventQueue IntegrationEventQueueXML

where:

UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.
IntegrationEventQueueXML is the fully qualified path name of the integration event queue XML file, for example:
```
C:\My Files\MyQueue.xml
```
If the fully qualified path name contains any spaces, then it must be enclosed with quotation marks, for example:
```
migrationtool -u UserID -s ServerURL Upsert IntegrationEventQueue "C:\My Files\MyQueue.xml"
```

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (using the pipe command) to the client program from standard input; that is, from a file, from the command line, or from another program.

Example of Updating or Inserting the Configuration Data for an Integration Event Queue

The following is an example of updating the configuration data for an integration event queue (if the queue exists) or inserting an integration event queue (if it does not exist) in your Oracle CRM On Demand server:

migrationtool -u UserID -s ServerURL Upsert IntegrationEventQueue "C:\Oracle Migration Tool On Demand\repository\IntegrationEventQueue\MyQueue.xml"

Note: Quotation marks are required only if the fully qualified path name contains spaces.

About Clearing Transactions from Integration Event Queues

You can use the Upsert command to clear transactions from an integration event queue. You can clear all transactions from the queue by including the <ClearAllTransactions> element in the XML file for the upsert operation, with the value set to true, as follows:

<data:ClearAllTransactions>true</data:ClearAllTransactions>

Alternatively, you can clear older transactions from the queue by including the <ClearFromDate> element in the XML file for the upsert operation, with the value set to a date and time. The upsert operation clears all of the transactions that occurred before that date and time from the queue.

In the <ClearFromDate> element, you must use the date and time format specified by the W3C standard. The format is:

YYYY-MM-DDTHH:MM:SS

In the string:

YYYY specifies the year
MM specifies the month
DD specifies the day
T indicates the start of the required time section
HH specifies the hour
MM specifies the minute
SS specifies the second

If you express the time in UTC (Coordinated Universal Time), then append the letter Z to the string, as shown in the following example:

2002-05-30T09:30:10Z

If you express the time in a time zone other than UTC, then you must specify the positive or negative offset from UTC in hours and minutes, as shown in the following examples.

This example shows a time expressed in UTC:

2002-05-30T09:30:10Z

The following example shows the same moment expressed in a time zone that is six hours behind UTC:

2002-05-30T03:30:10-06:00

The following example shows the same moment expressed in a time zone that is six hours ahead of UTC:

2002-05-30T15:30:10+06:00

Note: Unless the <ClearAllTransactions> element is included in the XML file and is set to true, or the <ClearFromDate> element is included in the XML file with a date and time specified, any transactions currently in the queue are not affected by the upsert operation.