This chapter covers the following topics:
You can set up events to execute a specific outcome if certain conditions are met. For example, you could set up contracts of a specific type to renew 90 days prior to expiration. An event can be action based, such as contract signed, or date based such as renew contract 90 days prior to expiration.
In order to set up an event you must have the following:
Action (an action can be action-based or date-based).
Condition
Outcome
After you define an action the following occurs:
If the condition is true, the system executes the outcome. If the outcome is successful, the system sends a success notification. If the outcome fails, the system sends failure notification.
If the condition is false, the outcome is not executed, and a notification is not sent.
Note: This group of procedures covers the Contract Events menu assigned to the Service Contracts Manager responsibility, except for the following:
The procedure for creating processes is covered in Defining a Process.
The procedure for creating independent conditions is covered in Creating Independent Conditions for the Renewal
Caution: Custom events and actions are not supported. If you customize events, you are doing so at your own risk. Oracle Support cannot help you create or debug actions, functions, or outcomes. If you encounter problems with customizations and wish to obtain support, you must recreate the problem using standard Oracle objects.
You can use condition templates to define multiple samples of conditions. The templates can then be used to define independent conditions or conditions attached to a contract.
Prerequisite
Create an outcome.
Select the Service Contracts Manager responsibility. Navigate to Setup: Contract Events, and then select Condition Template.
Enter a name and a description.
Check the Create a Task check box, to create a task for the Schedule tab in the execution overview.
Enter the task owner.
Select Action or Date.
To create an action condition, select an action.
To create a date condition, enter the date information.
Build your condition lines.
Note: When using the LIKE operator, do not use quotes. For example, when building a condition, where contract_number like %-2000%, your right value must be %-2000 and not "%-2000".
To enter fixed values for parameters for a function, click Parameters and enter the information
Click Show Condition to display all condition lines and check their syntactical validity.
If the condition has validated successfully, then Condition Valid is automatically selected.
Select Outcomes.
To assign fixed values or action attribute values to the outcome parameters, click Parameters and enter the information.
Select Notifications.
Select a success notifier from the LOV.
Select a failure notifier from the LOV.
Save.
You can search all conditions, including independent conditions, condition templates, and instances created by condition templates.
Select the Service Contracts Manager responsibility. Navigate to Setup: Contract Events, and then select Condition Search.
From the View menu, select Query By Example and choose Enter.
You can query any of the fields that are blue. These are the only fields that are active.
Enter or select your criteria. You can use wildcards such as %.
From the View menu, select Query By Example and choose Run.
The window is populated with the conditions that match the criteria that you entered.
Press the Page Down button on your keyboard to see additional conditions that match your search criteria.
The Events Component is dependent on asynchronous processing. It uses Advanced Queuing System. This system is transparent to the user. The messages processed may encounter exceptions and as a result the messages are rolled back and will be reprocessed again at a specified time. There is a need to record any exceptions encountered. Hence whenever an exception is encountered, the Evaluator writes the details of the exceptions to a table OKC_AQERRORS and the error stack to OKC_AQMSGSTACKS tables. The Asynchronous Errors window displays all error messages of advanced queueing processes that have failed. This window displays Queue Name, Message ID, and the Message Text. This window is generally used by your support representative to resolve issues.
Select the Service Contracts Manager responsibility. Navigate to Setup: Contract Events, and then select Condition Errors.
The following provides a description of the attributes:
Source Name: Provides source name.
Begin Date: Provides begin date.
Queue Name: Identifies name of the Advanced Queue.
Message ID: Provides message ID.
Retry Count: Displays number of times the queue tried to dequeue the message.
Queue Contents: Displays queue content.
Message Text: Displays error message text.
The Events Controller is a tool for the system administrator to debug any environment problems related to the queues. This is a query only form which gives the system administrator the provision to check common problems related to advanced queues, for example whether the listeners are running, queue objects are valid, or if there are any errors thrown by the queues. This form provides a more convenient method of viewing more information from one location. The Events Controller has a start and stop option for queues and concurrent programs. The queues must always be enabled (started). The listeners will be running as scheduled and will show an error if the queues are disabled (stopped). The start and stop option is an extra DBA provision provided to the system administrator and can also be used when debugging certain queue problems. If the Events Controller is used to stop queues, it will automatically terminate any Listener for Events/Outcome concurrent programs. You can start the queues again and restart the listeners. This will not cause any data loss from the queues.
Note: The Asynchronous window form only displays queue errors.
Select the Service Contracts Manager responsibility. Navigate to Setup: Contract Events, and then select Events Controller.
Select the Background Process tab.
This tab displays the events and outcome listeners that are running in the background and the workflow background process. In the event of an error, this tab provides you with the ability to access the Errors window which describes the error and the cause.
The following provides a description of the attributes:
Request ID: Provides ID of the submitted concurrent program.
Listener/Program: Identifies the name of the event, outcome, or workflow background process.
Phase: Provides update, such as Pending, Running, or Completed.
Status: Displays Normal or Error. When a program has been completed with an Error status, you can click Diagnostics to view the error details returned by the concurrent program.
Request Date: Provides date submitted.
Requestor: Identifies user who submitted the request.
Select the Queue Content tab.
This tab displays the Queue Messages and Queue Errors that have occurred. If an event is launched (such as contract signed) you can expect to see the queue content within this tab. If there is nothing in the queue, then the Queue Status tab is used to check the queue status and also to check if all queue objects are valid.
The following provides a description of the attributes:
Queue Name: Identifies name of the Advanced Queue.
Correlation: Identifies the correlation ID of an action such as KSIGN and KEXTEND.
Consumer: Describes the program which parses and consumes the message in the queue.
Enqueue Time: Shows when message was placed in queue.
Queue Content: Displays queue content.
Source Name: Shows source of error.
Retrys: Displays number of times the queue tried to dequeue the message.
Begin Date: Shows date when error occurred.
Error Details (Button): Enables you to view the details of queue errors.
Select the Queue Status tab.
This tab displays the queue names, queue objects, and their status (valid or invalid).
The following provides a description of the attributes:
Queue Name: Identifies name of the Advanced Queue.
Queue Table: Shows table name.
Queue Type: Displays the queue type such as Normal and Exception.
Enqueue Enabled: Yes/No.
Dequeue Enabled: Yes/No.
Start Queue/Stop Queue (Buttons): Enables you to stop or start queue.
Queue Objects: Names all the advance queue objects.
Object Name: Provides name of object.
Object Type: Displays type of object such as Table and View.
Status Type: Shows whether object is valid or invalid.
Last Modified: Displays date last modified.
Details (Button): Shows details for rules and subscriber objects.
You can set up Oracle Contracts Service to automatically create a service request. This occurs when the updated value of a service counter that is attached to a service line, satisfies an event condition, that is attached to the service line as well. When a condition template is created for a service item with condition lines based on the counters associated to the service item, the OKSEVENT-CREATE_SR process, which has been set up as a workflow in the process definition, can be used as an outcome. After you capture a counter for the contract line and the condition is satisfied, the system creates a service request and notifies the user defined in profile OKS: Service Request Creator.
For example, a service provider that checks atmospheric humidity every ten days, sets up a time based counter and associates the counter to service item. After they create a contract for the service item, the counters time-based engine tracks the number of days. On the tenth day, the system creates a service request and notifies the user set up in the OKS: Service Request Creator profile with the service request number.
Note: This functionality is limited to service counters, not product counters. To implement product counters based service request creation, please refer to Preventive Maintenance Setup Steps section in the Oracle Field Service Implementation Guide.
Prerequisites:
Set the following profile options:
Service: Default Service Request Type
Service: Default Service Request Status
Service: Default Service Request Severity
OKS: Service Request Creator (set it at site level)
Note: If the profile Service: Use SR Type - Responsibility Mapping is set to Yes, then the responsibility mapped to default service request type must also be added to the application user as set up in profile OKS: Service Request Creator. The default service request type is set up in the profile Service: Default Service Request Type. To leverage the service security, schedule the listener concurrent processes and the contract alert workflow background processes from the same responsibility, which has access to the service request type set in the profile Service: Default Service Request Type. For Service application security related setup, refer to Oracle TeleService Implementation Guide.
Define a contact for the Customer Party type of the Contract. Refer to Adding Contact Points for a Customer and Adding Contact Points for a Customer site in the Oracle TeleService User Guide. The service request creation process requires a customer contact point
Schedule the following concurrent programs:
Listener for Events Queue
Listener for Outcome Queue
Workflow Background process for workflow item type Contract Alert
Define a Condition for the Service item
When defining the Condition for the service item, make sure to select Counter group updated as an Action and attach the OKSEVENT-CREATE_SR process as an outcome. Also, select the K_LINE_ID as the parameter.
Note: If you requery the parameter, it appears as SOURCE OBJECT ID, not K_LINE_ID, which is the same.
Select the Service Contracts Manager responsibility. Navigate to Setup: Contract Events, and then select Condition Template.
Enter a name.
In the condition type region, select Counter Group Updated from the Action LOV.
Select the Counter tab, and select Service from the Item/Product list.
From the Description LOV, select a service.
In the Left Counter Value field, select a counter.
Select an operator and enter a value in the Right Counter Value field.
From the Outcomes secondary tab, select OKSEVENT-CREATE_SR from the Outcomes LOV.
Select the Notifications secondary tab and choose the individual(s) to send the Success Notifiers and the Failure Notifiers.
Select Parameters.
The Parameters window appears, the value K_LINE_ID is the default.
Click OK.
Select an action attribute for K_LINE_ID and click OK The K_LINE_ID represents the contract line id, which is passed to the OKSEVENT-CREATE_SR workflow process, for fetching the contract and the service line information that is needed for service request creation.
Save.
From the Navigator, select Launch Contracts and create a Service Agreement.
Make sure the party role is Customer and that you select the contact you set up in the Contact Center. Enter a service line with the service you selected in the condition template.
Select the Lines tab and Event subtab.
You should see the condition that you created in the Events region.
Select the Lines tab and Counters subtab.
From the Actions menu select Counter Capture. Enter the counter reading to trigger the event.
After the counter is captured for the contract line, and if the condition evaluates to true, the condition creates a service request. Subsequently, the service request creator gets the notification of the service request creation that can be viewed from the Inbox the Launch Contracts window.
For events other than automatic renewals to work, there are two concurrent programs that must be scheduled to run. These are:
Listener for Events Queue
Listener for Outcome Queue
Use the concurrent request set to start both programs. After submitting the Listener request set, each concurrent program should end with a normal completion status.
If the database or the concurrent managers have been restarted, verify these two processes are restarted.
There are two profile options to set the work load of the listeners: OKC: Event Listener Iterations and OKC: Outcome Listener Iterations. These profiles control the number of messages the listeners will dequeue for every run. The profiles can be set at the site and application levels.
If the preceding profiles are not set, OKC Event and Outcome listeners will keep checking the queue messages, even if there is no message in the queue. This check is CPU extensive and uses memory resources.
If these profiles are set, the listeners stop checking the queue if there are no messages and resume checking the next time listeners are scheduled to run (based on the schedule parameter you set when running the concurrent request for Event and Outcome Listeners).
The default load value is set to 100, which is recommended. This number can be changed to suit the Advanced Queue load. The minimum should be greater than 1 and the maximum should not exceed 1,000.
This number should be set to a higher value for systems that have larger work loads. Setting a higher value for the profile options, results in longer running and more resource CPU intensive listener processes.
Submit requests to start both listeners using a Periodic schedule. The suggested period is every three to five minutes. Failure to run the Listeners on a regular schedule will severely limit functionality in Contracts and other applications using the Contracts Events System. It will also cause Events system Advanced Queue to become back logged.
Listeners run and complete rather than running indefinitely. In order to process messages in the queue, you must set the listeners to run on a regular schedule. Increase or decrease the interval/period at which the Listener process run according to your system load. The sleep parameter seen when submitting a request is now redundant. You should balance these processes with the iterations and request schedule. Use both these methods to fine tune your listener processes.
Note: You should stop these concurrent requests if you are applying product upgrades or performing system maintenance. Terminating the concurrent request will not stop the listener process. For a detailed description on stopping these requests see Doc ID 183558.1 on OracleMetalink.
The following procedure describes the Events Controller, which has a role in starting and stopping listeners. See Using the Events Controller.
Select the Service Contracts Manager responsibility. Navigate to Requests, and then select Run.
The Submit a New Request window appears.
Select Single Request and click OK.
The Submit Request window appears.
From the Name LOV select Listener for Events Queue.
The Parameters window appears.
Enter a value for the following parameters:
Wait
Click OK.
Click Schedule.
The Schedule window appears.
Select Periodically from Run the Job block.
From the Re-run Every field, enter 5 and select Minutes.
Click OK.
Click Submit.
Make a note of the Request ID.
Select the Service Contracts Manager responsibility. Navigate to Requests, and then select Run.
The Submit a New Request window appears.
Select Single Request and click OK.
The Submit Request window appears.
From the Name LOV select Listener for Outcome Queue.
The Parameters window appears.
Enter a value for the following parameters:
Wait
Click OK.
Click Schedule.
The Schedule window appears.
Select Periodically from Run the Job block.
From the Re-run Every field, enter 5 and select Minutes.
Click OK.
Click Submit.
Make a note of the Request ID.
If you are using Oracle Workflow with other applications, the program Workflow Background Processes is most likely running in recurring intervals. If the Workflow Background Processes is not scheduled to run, the system administrator must start this process to run regularly, such as every five minutes.
Select the Service Contracts Manager responsibility. Navigate to Requests , and then select Run.
The Submit a New Request window appears.
Select Single Request and click OK.
The Submit Request window appears.
From the Name LOV select Workflow Background Process.
The Parameters window appears.
Select a value for the following parameters:
Contract Alert from the Item Type LOV.
Yes from the Process Deferred LOV.
Yes from the Process Timeout LOV.
Click OK.
Click Schedule.
The Schedule window appears.
Select Periodically from Run the Job block.
From the Re-run Every field, enter 5 and select Minutes.
Click OK.
Click Submit.
Make a note of the Request ID.
You should run the Date Assembler concurrent program once every day, preferably later in the evening.
The Date Assembler checks if the end date of the contract is between the last_rundate + variance and sysdate + variance. So, if the last_rundate is 4-Jan-2005 and sysdate is 5-Jan-2005 and variance is 90 days, then Date Assembler renews all contracts expiring on 5-Apr-2005.
Select the Service Contracts Manager responsibility. Navigate to Requests, and then select Run.
The Submit a New Request window appears.
Select Single Request and click OK.
The Submit Request window appears.
From the Name LOV select Date Assembler.
Select Submit.
Verify that you have confirmed the procedures covered in the preceding group of procedures. If you are still experiencing problems, the following may help you to troubleshoot issues with events.
Validate that Date Assembler Found Eligible Contracts
The Date Assembler evaluates each Independent Condition. Contracts that satisfy the criteria defined in the condition appear in the output log file.
Possible causes for the Date Assembler to fail to find eligible contracts include:
Independent Condition has an end-date prior to the current date
Independent Condition is invalid (verify that the Condition Valid check box is enabled)
Desired contract does not meet defined condition
Confirm Error Messages
From the Service Contracts Manager responsibility, you can navigate to Contract Events, and then Query Asynchonous Error Message. If this does not return errors, you can use the following details to help you troubleshoot:
Messages are placed in two tables OKC_AQERRORS and OKC_AQMSGSTACKS.
You can find the contract id from OKC_AQERRORS and specific error messages from OKC_AQMSGSTACKS.
The following conditions prevent records from being placed in the error tables:
The Listener for Outcomes did not run.
The Independent Condition did not fire.
A problem with the (Success or Failure) notification prevented processing from completing correctly.
You can use the following query to confirm that errors were detected by the Listener for Outcomes or Listener for Events:
SELECT SOURCE_NAME, Q_NAME, RETRY_COUNT, QUEUE_CONTENTS, CREATION_DATE FROM OKC_AQERRORS
You can use the following query to view the specific errors detected for each contract:
SELECT AQE_ID, MSG_SEQ_NO, MESSAGE_TEXT FROM OKC_AQMSGSTACKS
You can write additional queries by matching the column ID from OKC_AQERRORS to the column AQE_ID from OKC_AQMSGSTACKS. For example:
SELECT QUEUE_CONTENTS, MESSAGE_TEXT FROM OKC_AQMSGSTACKS MSG, OKC_AQERRORS ERR WHERE ERR.ID = MSG.AQE_ID
If the query returns values, you can conclude that the Advanced Queuing worked at least one time.
Validate Queues Exist
The Date Assembler places messages in the queue. The Listener for Outcomes and Listener for Events dequeues these messages.
You can use the following queries to establish that the queues are defined correctly and that the Advanced Queuing process is functioning correctly:
SELECT NAME, QUEUE_TABLE, QID, QUEUE_TYPE, ENQUEUE_ENABLED, DEQUEUE_ENABLED FROM DBA_QUEUES WHERE QUEUE_TABLE = 'OKC_AQ_EV_TAB'
This query should return three rows. Take note of the values for QID as they are needed in the second query.
Expected queue names and queue types are as follows:
OKC_AQ_EV_QUEUE (NORMAL_QUEUE) OKC_AQ_OC_QUEUE (NORMAL_QUEUE) AQ$_OKC_AQ_EV_TAB_E (EXCEPTION_QUEUE)
The results of the query indicate whether records are in the queue (column ENQUEUE = YES), and whether records have been processed by the Listener for Outcomes and Listener for Events, (column ENQUEUE = YES).
NAME QUEUE_TABLE QID QUEUE_TYPE ENQUEUE DEQUEUE
OKC_AQ_EV_QUEUE OKC_AQ_EV_TAB 108816 NORMAL_QUEUE YES YES
OKC_AQ_OC_QUEUE OKC_AQ_EV_TAB 108817 NORMAL_QUEUE YES YES
AQ$_OKC_AQ_EV_TAB_E OKC_AQ_EV_TAB 108815 EXCEPTION_QUEUE NO YES
SELECT * FROM V$AQ WHERE QID IN (queue id #1, queue id # 2, queue id #3)
Note: Replace queue id #1, queue id #2, and queue id #3 with the QID values returned in the first query.
Check Status of Messages in Queue
You can use this query to find the number of non-expired messages in the queues:
SELECT MSG_STATE,CORR_ID,CONSUMER_NAME,COUNT(*) FROM OKC.AQ$OKC_AQ_EV_TAB WHERE MSG_STATE <> 'EXPIRED' GROUP BY MSG_STATE,CORR_ID,CONSUMER_NAME ORDER BY 1,2
You can use this query to find the number of times the messages were retried:
SELECT CORR_ID,RETRY_COUNT,COUNT(*) FROM OKC.AQ$OKC_AQ_EV_TAB WHERE RETRY_COUNT >=1 AND MSG_STATE = 'READY' GROUP BY CORR_ID,RETRY_COUNT ORDER BY 1,2
Check Status of Queue
You can run this query to verify that Advanced Queuing is working for the queue OKC_AQ_EV_TAB:
SELECT STATE FROM OKC_AQ_EV_TAB
AQ Message States:
Queue tables are created using the procedure DBMS_AQADM.CREATE_QUEUE_TABLE and can be listed using the dictionary view DBA_QUEUE_TABLES. <queue_table>.state is a NUMBER column containing value in {0,1,2,3}.
0 'READY': = Message is ready for dequeue.
1 'WAITING': = The delay specified by message_properties_t.delay while executing dbms_aq.enqueue has not been reached.
2 'RETAINED': = The message has been successfully processed (dequeued) but will remain in the queue until the retention_time specified for the queue while executing dbms_aqadm.create_queue has been reached.
3 'EXPIRED': = The message was not successfully processed (dequeued) in either: the time specified by message_properties_t.expiration while executing dbms_aq.enqueue or; the maximum number of dequeue attempts (max_retries) specified for the queue while executing dbms_aqadm.create_queue.
Note: Consult with a qualified DBA if the query returns no rows, or if the result of the query is 3. If the query returns no rows, this may indicate that your Success and Failure Notifiers have not been defined for the Independent Condition. Define these values and retest.
Check Contract Alert Workflow
Use the System Administrator login and responsibility and navigate to Workflow, and then Find Processes.
Enter a Query for Item Type, Contract Alert.
Find one of your processes (probably one of the more recent processes).
Select View Diagram to see where the process failed.
The workflow process branches in five directions from the initial process, Version. If it branches through leg 5, Generic Function, and the Loop Prompt and Loop Counter are highlighted in green, this is an indication that the notification process failed. This failure could prevent error messages from being placed in the table OKC_AQERRORS.
Verify that the Success and Failure notifiers are identified in the Independent Condition.
More detailed information can be obtained by selecting the option Advanced Options before selecting View Diagram. Enable all of the Activity Type check boxes, then select the Filter Activities button and select View Diagram.
Confirm Packages and Procedures
The following packages are used by the Date Assembler, Listener for Outcomes and Queuing. You should be prepared to provide the package version numbers if you continue to experience problems and contact Oracle Support.
| Package | Filename | Function |
| OKC_AQ_PVT | OKCRAQB.pls | Listener for Outcomes executable Listener for Events executable |
| OKC_AQ_PUB | OKCPAQB.pls | Standard API for advanced queuing |
| OKC_DATE_ASSEMBLER_PUB | OKCPDASB.pls | Date Assembler program |
| OKC_CONDITIONS_PUB | OKCPCNHB.pls | Public API for inserting, updating, validating and deleting records for Condition Headers and others |
| OKC_EXP_DATE_ASMBLR_PVT | OKCREDAB.pls | Contracts expiry date assembler |
| NA | OKCCINDX.sql | Creates composite index on queue table |
| NA | OKCCQUET.sql | Creates queue table,queues and subscribers |
| NA | OKCQGRNT.sql | Create grants/synonyms on queue objects (tables and sequences) |
| NA | OKCSTQUE.sql | Adds rule based subscribers and starts queues |