The Generic Service Component Framework helps to simplify and automate the management of background Java services. Service component containers and their service components are run through Generic Service Management (GSM), which you can control through Oracle Applications Manager (OAM).
A service component container is an instance of a service that manages the running of the individual service components that belong to it. The container monitors the status of its components and handles control events for itself and for its components. These actions are recorded in a log for the container.
A service component is an instance of a Java program which has been defined according to the Generic Service Component Framework standards so that it can be managed through this framework. Currently, Oracle Workflow provides four service component types: Workflow Mailer, Workflow Agent Listener, Workflow Java Agent Listener, and Workflow Web Services Outbound.
Oracle Workflow provides several seeded service components of these types, within seeded containers, to perform standard processing. You can optionally create additional service components to perform custom processing. If you create custom service components, you can either assign them to the seeded containers, or, based on the volume to be handled by the seeded containers, you can also choose to create your own custom containers.
All service components have certain attributes required by the Generic Service Component Framework. General definition attributes for a component include the component name, startup mode, container type, inbound agent, outbound agent, and correlation ID. Detail attributes include the container that owns the component, the maximum idle time for an on-demand component, maximum error count, number of inbound and outbound processing threads, component log level, read timeout period, minimum sleep time, maximum sleep time, error sleep time, and whether to close connections when the read timeout period expires.
A service component can have one of three startup modes.
Automatic - When a component container is started, it will automatically start its automatic service components. It will also monitor these components and restart them automatically when necessary.
On-Demand - A component container will start its on-demand service components if those components have messages waiting to be processed. For example, an on-demand notification mailer service component will be started if there are messages waiting on the WF_NOTIFICATION_OUT queue. The container will stop an on-demand service component when that component's maximum idle time has been exceeded.
Manual - You must manually start and stop the service component through Workflow Manager. The component container does not start or stop its manual service components.
All service components use the Oracle Applications GSM container type. A component can have either an inbound agent to process inbound messages, an outbound agent to process outbound messages, or both. An Oracle Advanced Queuing (AQ) correlation ID can be assigned to a component to limit its processing to only messages marked with that correlation ID.
Oracle Workflow provides three predefined containers in which you can create components, the Workflow Mailer Service, the Workflow Agent Listener Service, and the Workflow Document Web Services Service. For an on-demand service component, you can specify the maximum amount of time that the service component can remain idle before it is stopped by its container. A service component can have either one inbound processing thread, to enable inbound processing, or none, to disable inbound processing. A service component can have one or more outbound processing threads, to enable outbound processing depending on the volume of outbound messages, or none, to disable outbound processing. Some types of service components perform only inbound processing or only outbound processing. For example, agent listeners only process inbound event messages and consequently should always have an outbound thread count of zero.
A diagnostic log is recorded for each component container, from the time the container starts to the time it stops. When a container is restarted, a new log is begun. You can view the log through Workflow Manager. Each log entry is marked with the container ID, and, if applicable, with the ID of the service component that generated it. You can specify the level of detail of the information you want to record for each component container. You can also specify a separate log level for an individual service component within the container. The log levels you can select, in order from most detailed to least detailed, are as follows:
1 - Statement
2 - Procedure
3 - Event
4 - Exception
5 - Error
6 - Unexpected
The default log level for both containers and service components is Error. This level is the recommended setting for normal usage.
A processing thread for a service component runs in a loop in which it reads messages from the queue associated with its assigned agent and then waits during a specified amount of sleep time before checking the queue for messages again. The read timeout period defines the amount of time the service component continues attempting to read messages from the queue, after the last message has been dequeued, before timing out. If another message is received before this time expires, that message is processed and the timeout period begins again. If the timeout period expires and no more messages have been received, the service component stops reading and its sleep time begins.
The minimum sleep time for a service component defines the minimum amount of time during which the service component waits, after its read timeout period expires, before it checks the queue for messages again. If a queue receives messages infrequently, you can choose to increase the sleep time between read attempts when no messages are received by setting a maximum sleep time greater than the minimum sleep time. In this case, the service component initially waits for the minimum sleep time after it finishes reading messages from its queue. If no messages are read in subsequent attempts, then the sleep time between read attempts gradually increases until the maximum sleep time is reached. Increasing the sleep time can help enhance performance if messages are received infrequently. You can also set the maximum sleep time parameter to 0 (zero) to indicate that the sleep time should not be increased. In this case, the service component always waits for the minimum sleep time between read attempts.
The error sleep time for a service component defines the amount of time during which the service component waits, after an error occurs, before it attempts to begin processing again. Additionally, a service component processing thread can either close its connections after its read timeout period expires, when its sleep time begins, or the connections can remain open until the processing thread stops.
A service component may also have additional configuration parameters that are specific to the type of processing it performs. For example, a notification mailer service component has configuration parameters to specify the inbound and outbound e-mail servers it uses.
Among both the common and the type-specific configuration parameters, some parameters can be refreshed dynamically while a service component is running. These parameters are identified by a refresh icon in the configuration pages for the component. For example, the component log level, inbound thread count, and outbound thread count are refreshable parameters.
The control events you can perform for a service component include:
Starting a service component
Suspending a running service component, so that the threads stop processing but connections are not closed
Resuming a suspended service component
Refreshing a running service component with changed parameters
Stopping a running or suspended service component
A service component may also have additional control commands that are specific to the type of processing it performs. For example, Workflow Mailer components include a command to launch summary notifications.
You can perform these control events manually at runtime by choosing the relevant command for the component in the Service Components page. You can also schedule single or repeating control events when you are configuring a service component.
A service component can have one of the following statuses.
Not Configured - Some required configuration parameters for the component have not been completed. The component cannot be started until its configuration is complete.
Starting - The component is preparing to run.
Running - The component is running normally. You can choose to suspend processing for a component in this state, refresh the configuration parameters for the component that are dynamically refreshable, or stop the component.
Suspending - The component is preparing to suspend its processing.
Suspended - The component's thread has stopped processing, but its connections remain open. When a component is suspended, you can either resume its processing or stop it altogether.
Resuming - The component is preparing to resume processing and return to a Running status.
Stopping - The component is preparing to stop running.
Stopped - The component was stopped normally, without errors.
Stopped with Error - The component reached the maximum number of errors specified in its Max Error Count parameter and has stopped. The component container will restart an automatic component in this status, or an on-demand component in this status that has messages waiting to be processed.
System Deactivated - An automatic or on-demand component was deactivated automatically by its container because the component was stopped with an error the maximum number of times specified in the container's SVC_COMP_MAX_ERROR_COUNT service parameter. A component in this status will not be restarted automatically until the container is restarted.
User Deactivated - An automatic or on-demand component was manually stopped by a user. It will not be restarted automatically. If you want to restart it, you must do so manually.
A component with a status of Starting, Running, Suspending, Suspended, Resuming, or Stopping is considered to be active. While a component is active, you cannot edit the component name, startup mode, container type, inbound agent, outbound agent, correlation ID, container, or, for an on-demand component, the maximum idle time. You must stop the component before you can change these attributes. However, you can edit the component's other configuration parameters while it is active. If you edit any refreshable parameters, the component will be dynamically refreshed with the new parameter values.
You can manually stop a component from any status. Also, if a container stops for any reason, all of its components are stopped as well.
If the status of a service component changes to Stopped with Error or System Deactivated, Oracle Workflow posts a system alert to the System Alerts and Metrics page in Oracle Applications Manager.
The Service Components page shows the service components that are defined in your Oracle Workflow installation.
Navigation: Applications Dashboard > (pull-down menu) Workflow Manager > (B) Go > Service Components status icon
To add the information from this page to your support cart, click the Add to Support Cart button.
For each service component, the list displays the service component name, status, type, startup mode, container type, and container. Click any column heading to sort the list by that column.
To filter the service components displayed in the list, select a service component property from the Filter pull-down menu, enter a filter value in the text field, and click the Go button. You can filter by the following properties:
Service component name
Service component status
Service component type display name
Service component type internal name
To verify that the statuses displayed for the service components in the list are current, click the Verify All button.
To create a new service component, click the Create button.
To edit a service component's configuration, select the service component and click the Edit button. The steps to edit the configuration depend on the service component type.
To view the diagnostic log of the service component container in which this service component is running, select the service component and click the View Log button. The log includes log messages for this component and any other component belonging to that container.
To view details about a service component, either click the service component link in the Name column, or select the service component and click the View Details button. The information that is displayed depends on the service component type.
To review the events that have been scheduled to control the running of the service component, click the View Event History button. For each event, the Event History page displays the event name, status, user who requested the event, component status before the event was processed, date the event processing was completed, container for the service component, container type, and any event parameters for a refresh event. You can use this event history as an audit trail to review who scheduled control events for the service component. The status of an event may be Pending, Skipped, In Progress, Completed, or Error. In some cases, an event may be skipped if the component is not in an appropriate status at the time for which the event is scheduled. For example, a refresh event cannot be executed if the component is stopped at the scheduled time.
To delete a service component, select the service component and click the Delete button. If the service component is currently active, you must stop it before you can delete it.
Note: Several of the seeded service components are required by Oracle Workflow and Oracle XML Gateway and cannot be deleted. If you want to disable them, you can stop them manually using the Stop command from the command pull-down menu. However, note that stopping these components disables the features they support. For example, stopping the Workflow Error Agent Listener and Workflow Java Error Agent Listener disables error handling for the Business Event System.
To manually control the running of a service component, select the service component, choose the command you want from the command pull-down menu, and click the Go button. You can choose the following commands:
Refresh
Resume
Start
Stop
Suspend
Launch Summary Notifications (Workflow Mailer service components only)
To manage the service instances for the container of a service component through GSM, click the container link in the Container column.
The Pick Component Type page lets you choose the type of service component you want to create. This page lists the name and description of each available type. Select the type that you want and click the Continue button. The steps to complete the service component configuration depend on the type you select.
Oracle Workflow provides the following service component types.
Workflow Mailer - Service components that perform send and respond e-mail processing for the Notification System.
Workflow Agent Listener - Service components that process inbound messages on Business Event System agents in the database.
Workflow Java Agent Listener - Service components that process inbound messages on Business Event System agents in the middle tier.
Workflow Web Services Outbound - Service components that process outbound Web service messages.
Navigation: Applications Dashboard > (pull-down menu) Workflow Manager > (B) Go > Service Components status icon > Create
The Component Details page lets you review the configuration of a service component.
Navigation: Applications Dashboard > (pull-down menu) Workflow Manager > (B) Go > Service Components status icon > (B) View Details
The Component Details page displays the configuration parameters defined for the service component and any special status information, as well as the control events that are currently scheduled for the service component. For each event, the list shows the event name, initial start time, whether the event is currently running, the next scheduled execution time for a repeating event, the last previous execution time for a repeating event, the interval in minutes between executions of a repeating event, the number of times the event has failed, the job ID of the DBMS job used to schedule the event, and the PL/SQL API that DBMS job runs.
To add the information from this page to your support cart, click the Add to Support Cart button.
For Workflow Mailer service components only, to send test messages, click the Test Mailer button. In the Test Notification Mailer page, select the recipient role to which the messages should be sent, and click the Send Test Message button.
Note: To send a test message successfully, you must select a recipient role that either has a valid e-mail address defined, or that has members with valid e-mail addresses defined. The recipient role must also have a notification preference that includes individual e-mail notifications.
If you set an override e-mail address for the notification mailer, the Test Notification Mailer page displays that address. In this case the test message is sent to the override address rather than the e-mail address of the recipient role. However, you must still select a recipient role to enable the notification mailer to send the test messages.
Oracle Workflow sends two test messages to the recipient role: one message with content built using PL/SQL and one message with Oracle Application Framework content. Check the e-mail account for the recipient role to view the test messages and reply to them with the Acknowledge response. If you did not implement inbound e-mail processing for this mailer, use the Worklist pages to respond to the test messages after viewing the outbound messages in e-mail. After you acknowledge both test messages, Oracle Workflow sends a confirmation message to the same recipient role to show that the notification mailer successfully processed the inbound response e-mails.
If you do not receive the test messages or the response confirmation message, or if the message content does not appear correctly, check the notification mailer setup, including the mail servers and the mailer configuration parameters. In particular, if the Oracle Application Framework content does not appear correctly, check the Application Framework Agent and WF: Workflow Mailer Framework Web Agent profile options, as well as the Framework User, Framework Responsibility, Framework Application ID, and Framework URL Timeout parameters in the advanced configuration wizard. See: Setting Up a Notification Mailer and Message Generation.
Note: Oracle Workflow sends the test messages by launching the PLSQL/OAFwk Response Test Process in the System: Tests (WFTESTS) item type. This item type is stored in a file called wftstmlr.wft in the $FND_TOP/import/<lang> subdirectory. You can optionally use the Status Monitor to check the status of the test process.
For Workflow Mailer service components only, to set an override address where you want to send all outgoing e-mail notifications, click the Set Override Address button. Use an override address when you are testing workflow definitions or mailer processing so that you can automatically receive all the test notifications at one e-mail address, instead of having to check or change each individual recipient's e-mail address. To ensure that the override address is accessible and that its use is authorized, you must verify the request before the notification mailer can use the address.
In the Set Override Address page, review the current override address, if any. Enter the e-mail address you want to set as the new override address, and choose Submit. Then check the e-mail account you specified for the verification e-mail message.
In the Verify Override Address page, enter the verification code shown in the e-mail message, and choose Apply. If necessary, you can use the link provided in the verification e-mail message to navigate back to the Verify Override Address page. You must log in to Oracle Applications Manager before you can access this page.
To remove the override address, navigate to the Set Override Address page and choose the Clear Override Address button. The notification mailer then resumes sending e-mail notifications to the individual recipients' e-mail addresses.
To review the events that have been scheduled to control the running of the service component, click the View Event History button. For each event, the Event History page displays the event name, status, user who requested the event, component status before the event was processed, date the event processing was completed, container for the service component, container type, and any event parameters for a refresh event. You can use this event history as an audit trail to review who scheduled control events for the service component. The status of an event may be Pending, Skipped, In Progress, Completed, or Error. In some cases, an event may be skipped if the component is not in an appropriate status at the time for which the event is scheduled. For example, a refresh event cannot be executed if the component is stopped at the scheduled time.
To view the diagnostic log of the Generic Service Management (GSM) service component container in which this component is running, click the View Log button. The log includes log messages for this component and any other component belonging to that container.
To change the values of the configuration parameters or the scheduled events, click the Edit button and navigate to the appropriate page within the service component configuration wizard.
To return to the Service Components page, click the OK button.
You can use Oracle Applications Manager to control service component containers as service instances of type Generic Service Component Container in GSM.
Among other properties, a GSM service instance can have work shifts assigned to it. A work shift in turn can have service parameters associated with it. For a service instance that is a service component container, these service parameters apply to the container as a whole to determine how the container manages the components that belong to it.
Navigation: Applications Dashboard > (pull-down menu) Workflow Manager > (B) Go > Service Components status icon > container link > (B) Edit > (B) Edit Service Parameters
The Edit Service Parameters page initially displays the service parameters that can be specified for a container in the Edit Service Parameters field, together with their seeded default values. In most cases, you do not need to change these values. However, you can optionally edit these values in the Edit Service Parameters field if you choose.
You can also optionally delete any of the service parameters from the Edit Service Parameters field. In this case, for all parameters except the proxy setting parameters, the parameter values are obtained from the global settings stored in the WF_RESOURCES table. The default values in the WF_RESOURCES table are the same as the initial default values in the Edit Service Parameters page.
In the Edit Service Parameters field, the service parameter names and values should be specified separated by colons, in the following format:
<name1>=<value1>:<name2>=<value2>: . . . <nameN>=<valueN>
The following service parameters can be specified for a container:
SVC_WRITE_DIAG_TO_GSM_LOG - Specify Y if you want to write diagnostic information to the GSM log file in all cases. The default value is Y. Specify N if you want to let the FND: Debug Log Filename (AFLOG_FILENAME) profile option determine where to write the log, either to a specified file or to the database if no file is specified. For more information about FND: Debug Log profile options, refer to Oracle E-Business Suite Setup Guide.
SVC_CONTAINER_LOOP_SLEEP - Specify the sleep time in seconds during which the container waits, after it finishes reading control messages from its GSM queue, before it checks that queue for messages again. The default sleep time is 10 seconds.
SVC_CONTAINER_READ_TIMEOUT - Specify the maximum amount of time in seconds that the container continues to block on the GSM queue after processing the last message. If another message is received before this time expires, that message is processed and the timeout period begins again. If the timeout period expires and no more messages have been received, the container stops blocking on the queue and its sleep time begins. The default timeout period is 10 seconds.
SVC_CONTAINER_LOG_LEVEL - Specify the level of detail to record for the container in its log. The default value is 5 (Error). The valid levels, in order from most detailed to least detailed, are:
1 - Statement
2 - Procedure
3 - Event
4 - Exception
5 - Error
6 - Unexpected
SVC_COMP_MONITOR_LOOP_SLEEP - Specify the sleep time in seconds during which the container waits, after it starts any automatic components that need to be started, before it checks its automatic components again. The default value is 60 seconds.
SVC_COMP_MONITOR_ONDEMAND_FREQ - Specify the interval in seconds to determine how often the container checks whether its on-demand components need to be started or stopped. This activity is more costly than monitoring the automatic components and should usually be performed less frequently. The default value is 300 seconds.
SVC_COMP_MAX_ERROR_COUNT - The container-level maximum error count. If any automatic or on-demand component in the container is stopped with an error the specified number of times, the component status will be set to System Deactivated, and the container will no longer automatically restart the component. The default value is 5.
You can also optionally specify the following service parameters for proxy settings. You should set these parameters if components in this container need to use a proxy server to access web content that is outside a firewall. For example, a mailer component may need to access outside web content that is to be included in an e-mail notification. The Generic Service Component Framework uses the values you set in these service parameters to set the relevant Java System Properties.
SVC_PROXY_SET - Specify true to indicate that you want to use a proxy for your connections. The default value is NONE.
SVC_PROXY_HOST - Specify the host machine for the proxy. The default value is NONE.
SVC_PROXY_PORT - Specify the port on which the proxy is listening. The default value is NONE.
SVC_NONPROXY_HOSTS - Specify any hosts that components in this container should access directly, rather than through the proxy server. When the service container starts, the Generic Service Component Framework uses the value of this parameter to set the http.nonProxyHosts System Property. Specify the list of hosts separated by vertical bars (|), without any spaces. You can use an asterisk (*) as a wildcard character within the host names. For example:
*.us.example.com|*.example.org|*.example.net
Note: If you use AutoConfig to specify proxy settings for your Oracle E-Business Suite instance, then you do not need to set the proxy-related service parameters here. In this case it is recommended that you continue to use AutoConfig to manage your proxy settings.
Use the proxy-related service parameters only if you do not use a proxy setup elsewhere, but you do require it for service components such as workflow mailers or agent listeners.
For Workflow Mailer service components only, you can also set one additional parameter that does not appear in the Edit Service Parameters field by default. TheIGNORE_BASE64_DECODE_ERRORS parameter lets you specify whether to ignore or throw any BASE64 decoding errors that occur during response processing for Workflow Mailer components. If this parameter is not specified, as is the default, or if it is set to TRUE, then any BASE64 decoding errors are ignored. If you want to retain the decoding errors, add this parameter to the list for the Workflow Mailer service component you want, and set its value to FALSE. This parameter does not apply for any other type of service component.
You can use the Service Status page to control the running of a service component container, including changing the log level for the container. The log level controls how much information is recorded in the log. Note that the log level you select here applies only to the log messages for the container. You can assign separate log levels to the individual components within the container.
Navigation: Applications Dashboard > (pull-down menu) Workflow Manager > (B) Go > Service Components status icon > container link > (B) View Status
The log level with which the container starts is determined by the value of the SVC_CONTAINER_LOG_LEVEL service parameter. If no value is defined for that parameter, the log level is obtained from the default setting stored in the WF_RESOURCES table. The default container log level, which is also the recommended setting, is Error.
If the container is running, you can optionally specify a different container log level for the current session. To change the log level, select the level you want from the Change Log Level To pull-down menu and click the Go button. The log levels you can select, in order from most detailed to least detailed, are as follows:
1 - Statement
2 - Procedure
3 - Event
4 - Exception
5 - Error
6 - Unexpected
Note that the log level you set dynamically in the Service Status page applies only for the duration of the current container session, and does not change the log level stored for the container in the service parameters. To set the log level permanently, so that the container starts with that log level in each new session, edit the value of the SVC_CONTAINER_LOG_LEVEL service parameter in the Edit Service Parameters page. See: Editing Service Parameters for a Container.
If the log level has been changed dynamically for the current session, the Service Status page may not display the log level that is currently in effect for the container. However, you can always review the current log level in the container log file by choosing View Log in the Service Components page or the Component Details page.
If you create custom service components, you can choose to create custom containers to manage those service components. You create a container as a GSM service instance of type Generic Service Component Container in Oracle Applications Manager.
Navigation: Applications Dashboard > (pull-down menu) Workflow Manager > (B) Go > Service Components status icon > container link > (B) Create New
Among other properties, a GSM service instance can have work shifts assigned to it. A work shift in turn can have service parameters associated with it. For a service instance that is a service component container, these service parameters apply to the container as a whole to determine how the container manages the components that belong to it. If you create a custom container, you should specify service parameters for the work shifts for your new service instance in order to specify how to run the new container. To enter service parameters easily, copy the service parameters from one of the seeded Oracle Workflow containers to your new container.
After creating a customer container, you can assign service components to it using the appropriate service component configuration wizard. Ensure that your custom containers are running in order to run the service components belonging to them.