Workflow Manual / Version 2512.0
Table Of ContentsUploaded workflow definitions are parsed and stored in the database as serialized objects. These serialized objects may require to be updated in case of incompatible changes to their used classes. See Section 5.9, “Pitfalls of Implemented Classes” how to reduce such incompatible changes in your custom extensions as, for example, actions, expressions and handlers. Also, when updating the Workflow Server the workflows need to be parsed and serialized again. Otherwise, object deserialization errors can occur (see Oracle JDK documentation for details).
The Workflowconverter takes care of this process either as an automatic
conversion, or it can be triggered manually. The automatic conversion on every Workflow Server start
can be enabled by the workflow.server.enable-workflow-converter flag (see
Section 6.1.2, “Configuration of Workflow Server Properties”). The manual conversion can be triggered by
the Workflow Server tool cm workflowconverter. The manual conversion must be
triggered before starting the Workflow Server. A possible example call for manual conversion:
cm workflowconverter --convert.
Workflowconverter Tool: The workflowconverter tool used for manual conversion has the following syntax:
cm workflowconverter [-?]
[-A [<ids>] | -c [<ids>] | -f [<ids>] | -r <id> <jar> | -v | -X [<ids>]]
Destroyed Running Workflows
Conversion modes -A (--archive) and -X (--destroy)
will destroy running workflows if the workflow definition cannot be parsed anymore.
If your workflow creates intermediate states, that must be rolled back, you will need to manually apply these, as also final actions will not be triggered. You may want to take extra care, if the workflow is bound to external services (like translation services), that require to be informed if workflows they are bound to are not available anymore.
Server States
Make sure that the Workflow Server is stopped prior to running this tool. Make sure that the involved Content Management Server is up and running.
The parameters have the following meaning:
| Parameter | Description |
|---|---|
-A, --archive [<ids>]
|
Conversion Mode:
Same as Note, that workflow definitions that are parsed and eventually serialized in this mode are dysfunctional (cannot be used to start new workflows), which is why the corresponding workflow definition is also marked as disabled.
A workflow definition disabled this way must not be enabled again via
Parsing Errors:
If the workflow definition XML cannot be parsed anymore even in this mode, the conversion for
the affected workflow definition will fail. If fixing the parsing error is not an option, you may
want to consider using Running Workflows: Running workflows for successfully parsed workflow definitions will not be affected and continue to work after Workflow Server start. Any running workflow based on now dysfunctional workflow definitions will be destroyed. Thus, also any defined final actions will not be applied anymore. Archived Workflows: Archived workflows will not be affected and continue to be accessible after Workflow Server start. ID Parameter: If not given, all workflow definitions will be validated, otherwise just the given ones. |
-c, --convert [<ids>]
|
Conversion Mode: Applies conversion to workflow definitions by parsing the workflow definition XML anew when the serialized object is considered invalid.
Parsing Errors:
If the workflow definition XML cannot be parsed anymore, the conversion for the affected workflow
definition will fail. If fixing the parsing error is not an option, you may
want to consider using Running Workflows: Running workflows will not be affected and continue to work after Workflow Server start. Archived Workflows: Archived workflows will not be affected and continue to be accessible after Workflow Server start. ID Parameter: If not given, all workflow definitions will be validated, otherwise just the given ones. |
-f, --force [<ids>]
|
Conversion Mode: Forcibly applies conversion to workflow definitions by parsing the workflow definition XML anew no matter of the state of the serialized object. Forced conversion is useful if group IDs used in the serialized workflows have become invalid. Even though this should be an exceptional case, sometimes it happens that external groups (like LDAP groups) vanish and reappear, for example, by a temporary misconfiguration of the user provider, and then get a new ID in the CMS. The workflow converter does not detect this, because it is not a matter of deserialization, so you have to enforce the conversion.
Parsing Errors:
If the workflow definition XML cannot be parsed anymore, the conversion for the affected workflow
definition will fail. If fixing the parsing error is not an option, you may
want to consider using Running Workflows: Running workflows will not be affected and continue to work after Workflow Server start. Archived Workflows: Archived workflows will not be affected and continue to be accessible after Workflow Server start. ID Parameter: If not given, all workflow definitions will be converted, otherwise just the given ones. |
-X, --destroy [<ids>]
|
Conversion Mode:
Similar to Parsing Errors: If the workflow definition XML cannot be parsed anymore, the workflow definition will be removed (in other words: destroyed). Running Workflows: Running workflows for successfully parsed workflow definitions will not be affected and continue to work after Workflow Server start. Any running workflow based on removed workflow definition will be destroyed. Thus, also any defined final actions will not be applied anymore. Archived Workflows: Archived workflows for successfully parsed workflow definitions will not be affected and continue to be accessible after Workflow Server start. Any archived workflow based removed workflow definition will be destroyed. ID Parameter: If not given, all workflow definitions will be validated, otherwise just the given ones. |
-r, --replace-jar <id> <jar>
|
Replace a custom-made JAR file for a workflow with a new version (see Section 3.5.4, “Upload” for the upload of a JAR file). |
-v, --verify
|
Only validates workflow definitions (all of them) whether they can still be deserialized or
not. If fixing the deserialization error is not an option (like re-adding missing classes), you may
want to consider running the tool with |
Table 3.6. Parameters of the workflowconverter tool
The argument id refers to a single numeric id of a workflow process. The argument
ids refers to a list of space-separated numeric process ids. For conversion modes
all given or available workflow definitions will be processed, thus, conversion continues with
the next even on intermediate invalid workflow definitions.
To convert the workflows, use the cm workflowconverter tool as follows:
Make sure that the Workflow Server is stopped.
Make sure that the Content Management Server to which the Workflow Server is attached is running. If necessary, start the Content Management Server.
Copy the changed classes (if any) into the appropriate directories.
Start the
workflowconvertertool. Note that the conversion only takes place, if the-c,-f,-Xor-Aflag is given.Finally, start the Workflow Server again.
The Content Management Server must run so that usernames and group names can be resolved while reparsing the workflow definitions.
