|
Oracle Workflow Developer's Guide Release 2.6.3.5 Part Number B12161-02 |
|
|
|
|
|
||
| Previous | Next | Contents | Index | Glossary |
As a result, if you modify any of these objects, your changes immediately affect any active work items that reference the object. Plan your changes carefully to ensure that the changes do not cause any backward incompatibility.
Note: The Workflow Builder does not support the editing of PL/SQL code. PL/SQL code is listed as a Workflow object here solely for the purpose of explaining the consequences of changing the code referenced by a Workflow function activity.
Adding a new item attribute after work items have been initiated will not affect the active work items. However, these work items will not include the new item attribute unless you specifically create the attribute for them by calling the AddItemAttr() or AddItemAttributeArray APIs. If you also add references to the new item attribute in the existing PL/SQL code within the workflow process, those references may cause errors in active work items that do not include the attribute.
For example, if you change the PL/SQL API for a function activity by calling a Workflow Engine API to communicate with a new item attribute, the function activity will fail for active work items that do not have the new item attribute defined.
You should plan carefully when making any modifications to the existing PL/SQL code within a workflow process to ensure that you do not add references to a new item attribute without also creating the item attribute for active work items that require it. See: PL/SQL Code.
Note: You can, however, add references to new item attributes in the API that starts a workflow process, without making special provisions for active work items. For example, you can call the SetItemAttribute or SetItemAttributeArray APIs to populate the new item attributes at the start of the process. Active work items will not be affected by such changes, since these work items have already passed through this code.
The message body, however, is not copied into the notification tables. Instead, the message body is referenced by the various Notification System APIs at runtime, when the notification is displayed to the user. As a result, any modifications to a message body will affect notifications in active work items that were sent before the change, as well as notifications that are sent after the change.
You can make certain types of modifications to a message body without risking incompatibility errors. These modifications include:
However, inappropriate modifications, such as adding tokens for newly created message attributes, may cause notifications in active work items to be displayed incorrectly. You should plan your changes carefully to avoid errors.
If you need to add tokens for new message attributes to a message body, you should implement the change by creating a new message rather than by modifying the existing message. You can attach the new message to your existing notification activity without affecting active work items, since notification activities support versioning.
For example, if you create a new message attribute such as Approver Name and you add a token for that attribute in the message body, all notifications in active work items will include the new token when you access the notifications. However, notifications that were sent before the change will not include the new message attribute Approver Name as a notification attribute. The Notification System will not be able to resolve the reference to the new message attribute and will display the token "&APPROVER_NAME" in the notifications instead.
In this example, instead of modifying the original message body, you should create a new message that includes the new message attribute, add the token for the new attribute to the body of the new message, and attach the new message to your notification activity. When you save your changes, the notification activity will be versioned. Then active work items will continue to reference the old version of the notification activity, and the incompatible token will not appear in those notifications.
To avoid errors caused by backward incompatibility, follow these guidelines for lookup types that are referenced by active work items:
You can attach new lookup types to existing activities without affecting active work items, since activities support versioning. However, you should not attach new lookup types to existing message attributes, since Workflow messages do not support versioning.
The following examples show some errors that can be caused by inappropriate lookup type modifications:
To prevent changes in the PL/SQL API for a function activity from affecting active work items, you should implement the changes by creating a new API rather than by modifying the existing API. You can attach the new API to your existing function activity without affecting active work items, since function activities support versioning.
If you need to modify an existing API and you cannot create a new API instead, you should plan your changes carefully to ensure that the changes do not cause any backward incompatibility.
For example, if you plan to add a lookup code to the group of values that an API can return, you should first ensure that the function activity node has an outgoing transition, such as 'Default,' that the Workflow Engine can follow when the API returns that value. Otherwise, the process will enter an 'ERROR' state when that value is returned. If there is no appropriate outgoing transition, you must implement the change in a new API and update the process to model branching logic for the additional return value.
Also, if you change the existing PL/SQL API for a function activity by calling a Workflow Engine API to communicate with a new item attribute, you should ensure that you also create the new item attribute for active work items. Otherwise, the function activity will fail for active work items which do not have the new item attribute defined.
Calls to any of the following APIs with newly created item attributes as parameters may cause the function activity to fail if active work items do not have the item attributes defined:
for <each active work item>
begin
wf_engine.AddItemAttr(itemtype,
itemkey,
'<new_attribute_name>');
wf_engine.SetItemAttrText(itemtype,
itemkey,
'<new_attribute_name>',
'<New attribute value>');
end;
end loop;
Note: Active work items are identified as those items for which WF_ITEMS.END_DATE is null.
procedure <procedure_name>(
itemtype in varchar2,
itemkey in varchar2,
actid in number,
funcmode in varchar2,
result in out varchar2)
is
begin
--
-- RUN mode - normal process execution
--
if (funcmode = 'RUN') then
-- your run code goes here
null;
wf_engine.SetItemAttrText(itemtype,
itemkey,
'<existing_attribute_name>',
'<Existing attribute value>');
begin
wf_engine.SetItemAttrText(itemtype,
itemkey,
'<new_attribute_name>',
'<New attribute value>');
exception
when others then
if (wf_core.error_name = 'WFENG_ITEM_ATTR') then
wf_engine.AddItemAttr(itemtype,
itemkey,
'<new_attribute_name>');
wf_engine.setitemattrtext(itemtype,
itemkey,
'<new_attribute_name>',
'<New attribute value>');
else
raise;
end if;
end;
-- example completion
result := 'COMPLETE:';
return;
end if;
--
-- CANCEL mode - activity 'compensation'
--
-- This is in the event that the activity must be undone,
-- for example when a process is reset to an earlier point
-- due to a loop back.
--
if (funcmode = 'CANCEL') then
-- your cancel code goes here
null;
-- no result needed
result := 'COMPLETE';
return;
end if;
--
-- Other execution modes may be created in the future. Your
-- activity will indicate that it does not implement a mode
-- by returning null
--
result := '';
return;
exception
when others then
-- The line below records this function call in the error
-- system in the case of an exception.
wf_core.context('<package_name>',
'<procedure_name>',
itemtype,
itemkey,
to_char(actid),
funcmode);
raise;
end <procedure_name>;
| Previous | Next | Contents | Index | Glossary |
