1. General introduction
FirstSpirit enables customer-specific projects, which are subject to a huge variety of different requirements, to be realized. As a rule, the workflows used within these projects are just as individual, and are tailored to the respective project.
Despite the project-related differences, it is still possible to identify similarities in the form of "common" release and delete logics in workflows for releasing or deleting FirstSpirit elements. To prevent these from having to be re-implemented in each new project, they have been combined within new workflows. The ability to extend the workflows has also been taken into consideration so that project-specific adaptations can continue to be made.
This document describes these workflows for deleting or releasing elements in SiteArchitect and ContentCreator, which have been redeveloped for FirstSpirit Version 5. By taking release and deletion dependencies into account, potential generation errors are minimized, and the accessibility of elements is ensured.
In comparison with the workflows with which you are already familiar from earlier FirstSpirit versions, the new workflows offer an increased range of functions for editors in both FirstSpirit Clients. This range of functions can be individually extended by setting up your own implementations, and thus adapted to the special features within the project.
The document is divided into an explanation of the preparation work required for using the workflows, an explanation of their functions, and a description of how to implement extensions (see chapter Topics covered in this documentation).
You can find more detailed information about workflows in the Handbook for Developers.
|
To create and run workflows, a corresponding FirstSpirit license is required, in which the Tampering with |
|
The BasicWorkflows have the following technical requirements:
|
|
This document is aimed at technical project managers and FirstSpirit developers. It is not a handbook for editors. Such a handbook must be written for each specific project. It is therefore a prerequisite that the reader is familiar with FirstSpirit and has knowledge of the functions and use of workflows in SiteArchitect and ContentCreator in particular. |
1.1. Topics covered in this documentation
This document describes the new workflows for releasing and deleting FirstSpirit elements, and explains the various functions, as well as how to install the required module.
Chapter 2: This chapter explains how the required module is installed on the FirstSpirit Server, how the workflows for ContentCreator and the web component are activated, how the workflows are imported into a project, and the permission definition.
Chapter 3: This chapter describes the release workflow. A distinction is made between use in SiteArchitect, and use in ContentCreator. A comparison is also made with the release workflow with which you are already familiar from previous FirstSpirit versions, as well as the administrative release.
Chapter 4: This chapter describes the delete workflow. A distinction is made between use in SiteArchitect, and use in ContentCreator. A comparison is also made with the native deletion of objects.
Chapter 5: This chapter explains the actions to take to resolve a conflict which may arise when running a workflow.
Chapter 6: This chapter describes how to implement extensions. These enable the two new workflows to be individually extended. An example of such an extension is also provided.
Chapter 7: This chapter summarizes some frequently asked questions and their answers.
2. Module installation and importing workflows
Various steps need to be taken before using the two new workflows:
2.1. Installing the module on the server
The module must first be added to the FirstSpirit Server using the basicworkflows.fsm file that was supplied. To install the module, open the Server and Project Configuration and select Server properties Modules.
The main panel contains a list of modules installed on the server. After clicking Install, select the supplied basicworkflows.fsm file, and click Open to confirm your selection. After successful installation, a BasicWorkflows folder is added to the list (see figure List of modules in the server properties). Then close the Server properties by clicking OK.
More information is available in the FirstSpirit Documentation for Administrators.
|
After any module installation or update, the FirstSpirit Server needs to be restarted. |
2.2. Activating the workflows for ContentCreator
By installing the module, what is known as an Element Status Provider is made available, which must be selected manually. This Element Status Provider controls the state display in ContentCreator.
Open the Server and Project Configuration for setting the Element Status Provider, and select Project properties ContentCreator.
Various options for working in ContentCreator are visible in the main panel. Change the Element Status Provider setting to the BasicWorkflows Status Provider entry (see figure Selecting the Element Status Provider for ContentCreator). Next, close the project properties by clicking OK.
More information is available in the FirstSpirit Documentation for Administrators.
2.3. Activating the web component and web server
A web component must be added to the project. To do this, open the Server and Project Configuration and switch to the tab Project properties Web components ContentCreator.
After clicking Add, select the BasicWorkflows_ContentCreator_Libary web component, and click OK to confirm your selection. Once it has been successfully added, the web component appears as an entry within the tab (see figure Activating the web component and the active web server).
If no activated web server exists, this must also be activated. Select this (e.g. InternalJetty) in the selection list, and start the installation by clicking Install. After successful installation, activate the web server by clicking Activate.
If an activated web server already exists, this simply needs to be updated.
More information is available in the FirstSpirit Documentation for Administrators.
Next, close the Project properties by clicking OK.
2.4. Importing the workflows
To be able to use the workflow functions, these must be imported into the project first. The two workflows and the associated scripts are not automatically imported when installing the module. The import has to be carried out manually.
To do this, open your project Template Store in FirstSpirit SiteArchitect and add the workflows via the context menu. The Import context menu entry (see figure Context menu - Import) opens an import dialog box where you can select the export_basic_release or export_basic_delete import file from the workstation directories.
After successful import, the corresponding entries are added to the Workflows and Scripts points in the Template Store.
You can find more detailed information about importing in the Handbook for Developers.
2.5. Permission definition
To be able to start the workflows on FirstSpirit elements, execution must be permitted in the individual stores first.
To do this, on the root node of the stores, call up the permission assignment via the context menu, and in the dialog box which opens via the Change permissions context menu entry (see figure Extras context menu - Change permissions), go to the Workflow permissions tab.
|
Depending on the configuration of user permissions, this context menu item may potentially only be available to project administrators. |
On the Workflow permissions tab, the Authorized checkbox must be activated for both workflows, as well as the Use release permission check mark for the release workflow (see figure Authorizing the workflows).
Next, close the dialog box by clicking OK.
For more information about defining permissions for workflows, refer to the Handbook for Editors or the Handbook for Developers.
2.6. Selecting the workflow to delete elements
If elements within your FirstSpirit project are to be deleted by running the delete workflow as standard, this must be defined explicitly.
|
Per project, only one single delete workflow can be defined in the project properties. |
To do this, open the Server and Project Configuration and select Project properties Options.
Various options for configuring the project are visible in the main panel (see figure Selected delete workflow for a project). Clicking the selection button for the Workflow to delete elements point opens another dialog box, which contains a list of all existing workflows in the underlying project (see figure Selecting a delete workflow). This means that the delete workflow must already be present in the project (see chapter Importing the workflows). Select the delete workflow from this list, and click OK to confirm your selection.
The delete workflow is then displayed in the main panel (see figure Selected delete workflow for a project).
Next, close the project properties by clicking OK.
|
The workflow must be authorized in the stores for the underlying project (see chapter Permission definition). Otherwise, it will not be possible to delete elements. |
Any action to delete elements within the project (Del button, delete icon) now runs the delete workflow. The native (independent of a workflow) deletion of elements is no longer available - not even for the administrator.
The delete action must therefore be modeled explicitly in the delete workflow. Otherwise, although the delete workflow will have ended successfully, the element to be deleted will continue to exist.
More information on deleting elements using a workflow is available in the FirstSpirit Documentation for Administrators.
|
The delete workflow function differs in the two FirstSpirit Clients. The elements that the workflow is able to delete are listed and explained in detail in each of the relevant chapters: the chapter on SiteArchitect and the chapter on ContentCreator. |
3. Release workflow
The release workflow is based on the administrative direct release, which can be run in SiteArchitect via the context menu, and which is only available for administrators (see figure Administrative direct release dialog box).
You can find more detailed information about administrative direct release in the Handbook for Editors.
Some of the selection options for this release have been adopted in the new release workflow, and can therefore be run by editors as well. The only options which can be selected manually are the consideration of media and the recursive release. They are both made available via a form used in the workflow (see figure Release workflow form - SiteArchitect). While the consideration of media is selected by default, the recursive release must be specifically selected.
In principle, the workflow will only consider the element on which it was started. However, activating the Release recursively including child elements option will also release all the child elements of the selected element.
|
The recursive release is only available in SiteArchitect. |
If the Release including media option is activated, all directly referenced media is also released. It is irrelevant whether it has already been released previously. A page is therefore released "as seen".
If the Release including media option is deactivated, referenced media is not taken into consideration during release. However, if the volume of referenced media contains elements which have never been released beforehand, a conflict is triggered. This must be resolved manually first before the workflow can be completed (see chapter Resolving conflicts). Without this conflict, errors would occur during generation and on the live page.
The administrative direct release option of releasing only new objects is not available within the release workflow.
However, the accessibility of the element to be released, i.e., release of the parent chain, is automatically ensured by the workflow.
|
When the parent chain is released, its start nodes remain ignored. If, as a result, it contains elements of a start node path that have never been released, the editor is shown an error message indicating this. |
In addition, all other dependent elements are determined and checked for possible conflicts. With the exception of the elements referenced from the Template Store, all objects which are returned by the FirstSpirit relation graphs (outgoing references) are taken into account. In the case of a page reference, the outgoing edges of the referenced page are also taken into consideration.
|
In the case of the recursive release, the check for any potential conflicts is also performed in relation to the child elements and the elements that they reference. |
|
Metadata and references to objects from remote projects are ignored by the release workflow. |
An element is released using the release workflow by one of two release options, which are made available via the workflow dialog box (see figure Release workflow start dialog box - SiteArchitect):
-
Direct release
-
Request
Direct release
|
This option is only available to the editor if they have the release permission for the object to be released. |
The Direct release option offers the same functionality as the Request option described below. However, during direct release, assignment to a subsequent editor is avoided, and the check for potential conflicts is triggered automatically. If no conflicts arise while the workflow is running, the workflow runs through without any further interruption after starting. Therefore, the four-eye principle is not applied in this case.
The individual workflow steps are described in detail in the explanation of the Request option.
Request
By requesting a release, the workflow is assigned to the next editor. This editor either declines the request by manually triggering a conflict, or initiates the release of the element by advancing the workflow (see figure Advancing the workflow by the next editor).
As a result of advancing the workflow, a test is first run through before the actual release - e.g., to establish whether any of the objects affected by the release workflow are locked by an editor at the time the workflow is run. If errors occur during this test, a conflict is triggered and the workflow is interrupted. Only when this test is completed successfully is the release carried out, and the release workflow can be ended.
Cancel
The Cancel button performs the same function as the Close button: The workflow is not advanced and the selected element remains in the same state it was in before the dialog box opened.
3.1. Range of functions
The release workflow can be run in both clients. However, as the number of elements on which the workflow can be started diverges in the two clients, they are distinguished from one other.
In general, the release workflow which has been redeveloped for FirstSpirit Version 5 is used to release pages and/or datasets, including the media referenced by them. Furthermore, a check is carried out to prevent generation errors, whereby all referenced objects, which do not constitute media, are also taken into account by the workflow. In the case of the recursive release, this check also considers the child elements of the selected element.
|
From Version 1.0.8, the BasicWorkflows only support FirstSpirit Version 5.1 or higher. From this module version, they are no longer compatible with FirstSpirit 5.0. |
Formally, for successful release, one of the following conditions must be met:
-
Only media is referenced and the
Release including mediaoption is activated -
The
Release including mediaoption is activated and a release version of all directly referenced objects which do not constitute media exists -
The
Release including mediaoption is deactivated and a release version of all directly referenced objects exists
If none of the above conditions are met or there is a broken reference, a conflict is triggered which must be resolved manually (see chapter Resolving conflicts).
|
With regard to the required existence of a release version (point 2 and 3 in the above list), pages are an exception: They are viewed as a unit with the page reference associated with them. If the release workflow is started on a page reference, the referenced page is always automatically released as well - regardless of whether a release version of it exists (see also chapter Page reference (SiteArchitect) and chapter Page reference (ContentCreator)). |
|
Write protection is not applied to objects affected by the workflow when it is running. |
3.1.1. SiteArchitect
In SiteArchitect, the release workflow is started via the context menu. The workflow dialog box with which you are familiar opens. However, on its Form tab, the consideration of media and the recursive release can be activated or deactivated (see figure Release workflow form - SiteArchitect). While the consideration of media is selected by default, the recursive release must be specifically selected.
In SiteArchitect, the workflow can be run on numerous objects, whose references are also taken into consideration by the workflow. The possible objects are listed in this chapter.
|
Metadata and references to remote objects are ignored by the release workflow. This also applies to referenced datasets from read-only databases. |
Medium
Starting the release workflow on a medium releases the selected element and the associated parent chain. It is important to note that only folders which have never been released before are released (see also chapter Folder).
Entity
In contrast to releasing all lines of a data source, which can be run via the context menu, the workflow is only performed on the exact dataset on which it was started. The remaining (unreleased) lines of the associated data source remain unaffected by the workflow.
Datasets generally contain references in the Site Store and Media Store. References such as these are also taken into consideration by the workflow.
|
Metadata and references to remote objects are ignored by the release workflow. This also applies to referenced datasets from read-only databases. |
|
Activating the recursive release does not affect datasets. It is not possible to release multiple datasets. |
According to the conditions applicable to it (see chapter Medium), referenced media is only released if the Release including media checkbox within the workflow (see figure Release workflow form - SiteArchitect) is activated. Otherwise, only a check for potential conflicts is carried out.
Regardless of the state of the checkbox, references to objects which do not constitute media are also only checked for conflicts, and are not released by the workflow.
A conflict occurs if none of the conditions mentioned in chapter Range of functions are met.
The workflow can only be ended successfully once all conflicts have been manually resolved (see chapter Resolving conflicts).
Page
Starting the release workflow on a page in the Page Store releases the selected page and its parent chain. Here, the release conditions for folders must be noted.
The outgoing references of a page are also taken into consideration by the workflow. This also applies to section references (see also chapter Extending implementation).
|
Metadata and references to remote objects are ignored by the release workflow. This also applies to referenced datasets from read-only databases. |
The release of referenced media is dependent on the Release including media checkbox (see figure Release workflow start dialog box - SiteArchitect), and is only carried out if this is activated (see also chapter Medium). If it is deactivated, the referenced media is only checked for potential conflicts and ignored during release.
References to objects which do not constitute media are basically only checked for conflicts, and are not released by the workflow.
A conflict occurs if none of the conditions mentioned in chapter Range of functions are met.
The workflow can only be ended successfully once all conflicts have been manually resolved (see chapter Resolving conflicts).
Page reference
If the start element of the release workflow is a page reference, the referenced page must also be taken into consideration, as generation errors could occur otherwise.
A page reference can only be released on the basis of a previously released page. To guarantee this in every case, it is therefore released by the workflow first. The parent chain of the page is also released by the workflow if the nodes of this chain have never been released beforehand (see chapter Folder). If the referenced page has its own outgoing references, these will also be taken into consideration.
The page reference and the associated parent chain are then released under the conditions already mentioned.
The parent chain release relates exclusively to the higher-level folders of the selected page reference. The contents of these folders are not considered by the release, however. This means that, while menu items are released, their start nodes are not. As this reflects FirstSpirit’s default behavior, no conflict occurs and the workflow is completed successfully. However, the editor receives an error message indicating that the start nodes have not been released.
Page references also offer the option of being able to reference images for the sitemap (see figure Page reference with referenced image for the sitemap).
If the Release including media checkbox within the workflow (see figure Release workflow start dialog box - SiteArchitect) is activated, these are also released by the workflow in accordance with the conditions for media (see chapter Medium).
If the checkbox is deactivated, the referenced media is ignored during release. Only a check for conflicts is carried out.
A conflict such as this occurs if none of the conditions mentioned in chapter Range of functions are met.
The workflow can only be ended successfully once all conflicts have been manually resolved.
|
Metadata and references to remote objects are ignored by the release workflow. This also applies to referenced datasets from read-only databases. |
Document group
Page references and structure folders can be combined in a document group in order to be displayed as a page.
A release workflow run on a document group only releases the node of this document group and the node’s parent chain, provided that none of the nodes associated with this chain have been released before. The structure folders and page references referenced within the document group are ignored during release. However, they are checked for potential conflicts.
|
When the parent chain is released, its start nodes remain ignored. If, as a result, it contains elements of a start node path that have never been released, the editor is shown an error message indicating this. |
|
As nests of any depth may exist within a document group, only the first content level elements are used for the conflict check. Any child elements are ignored. A conflict occurs if at least one of the first content level elements has broken references or has never been released. |
Explanation based on an example
A structure folder added to a document group may contain folders with further subfolders itself. This type of nesting is illustrated in simplified form in the figure below.
In this example, the "Folder 1" and "Page 2" elements are located on the first content level. Only they are relevant for the conflict check.
If both elements have already been released and neither element has any broken references, the conflict check returns a positive result, the node for the associated document group is released, and the release workflow is ended.
If at least one of the two elements has never been released or one of them contains broken references, the conflict check returns a negative result, the release workflow is interrupted, and a conflict occurs. This must be resolved manually first before the workflow can be continued (see chapter Resolving conflicts).
For information on document groups, refer to the Handbook for Editors as well.
Folder
When starting the release workflow on a folder, this and the associated parent chain are released if the nodes of this chain have never been released beforehand. If the recursive release is activated as well, all child elements are also released, starting from the selected element.
The parent chain release relates exclusively to the higher-level folders of the selected element. The contents of these folders are not considered by the release, however. Where the Site Store is concerned, this means that, while menu items are released, their start nodes are not. As this reflects FirstSpirit’s default behavior, no conflict occurs and the workflow is completed successfully. However, the editor receives an error message indicating that the start nodes have not been released.
|
Parent nodes, which have already been released beforehand, are not automatically released once again. |
|
It is not possible to perform the release workflow on Data Store folders. The release workflow is not available on these nodes. |
Structure folder
Compared to folders from the other FirstSpirit stores, folders from the Site Store are special, since only they can have outgoing references (see figure Structure folder with referenced image).
These references are the result of the ability to select menu graphics.
If references to media exist, and the Release including media checkbox is activated (see figure Release workflow form - SiteArchitect), the referenced media is also released in accordance with the conditions applicable to it when running the workflow (see chapter Medium).
|
Metadata and references to remote objects are ignored by the release workflow. This also applies to referenced datasets from read-only databases. |
If the checkbox is deactivated, referenced media is ignored by the workflow during release. Only a check for potential conflicts is carried out. In the case of the recursive release, this check also affects the child elements of the selected element.
A conflict occurs if none of the conditions mentioned in chapter Range of functions are met.
The workflow can only be ended successfully once all conflicts have been manually resolved (see chapter Resolving conflicts).
|
As dependencies based on the structure variables and/or resulting from page groups are not displayed in the relation graph, they are not classified as outgoing references. They are therefore ignored by the release workflow. A conflict check is not carried out either. You can find more detailed information about structure variables and page groups in the Handbook for Editors. |
Global pages & project settings
The behavior of the release workflow for global pages and for the project settings in the Global Settings matches the behavior for pages from the Page Store.
3.1.2. ContentCreator
In ContentCreator, the release workflow is started via the state menu. This opens the workflow dialog box. By pressing a button contained in this dialog box, another dialog box can be opened in which the consideration of media during release can be activated or deactivated. This option is selected by default (see figure Release workflow start dialog box & form - ContentCreator).
In ContentCreator, the release workflow can only be run on page references, Content Store detail pages, and document groups. These elements are described in more detail below.
|
The recursive release is not available in ContentCreator. |
|
To use the release workflow in ContentCreator, it is mandatory that the Element Status Provider made available by the module is selected, and that the web component and web server have been activated (see chapter Activating the workflows for ContentCreator and chapter Activating the web component and web server). |
Page reference
In ContentCreator, editors work on page references which are based on pages, however. A page reference can only be released if a release version of the associated page exists. For this reason, page references, and the page serving as a basis for each of them, are viewed as one unit by the release workflow.
If the workflow is started on a page reference, the page is always automatically released first - regardless of whether a release version of it exists. To guarantee the accessibility of the page, its parent chain is also taken into consideration by the workflow if the nodes of this chain have never been released beforehand (see chapter Folder). If the page itself has outgoing references, these are checked for potential conflicts or - in the case of media - also released, if the option is activated when the workflow is started.
Only after this is the page reference and its parent chain edited under the conditions already mentioned. In contrast to the page structure, however, the parent folder is always released as well, even if it has already been released. All superior parent folders will only be released, if they have never been released before.
Page references can also have outgoing references to the Media Store. Although they are visible in ContentCreator, they can only be edited by the editor in SiteArchitect (see figure Page reference with referenced image for the sitemap). The same is true for structure folders (see figure Structure folder with referenced image).
If these references, which are "invisible" to the ContentCreator editor, are to be released by the workflow as well, the release of media must be activated (see figure Release workflow start dialog box & form - ContentCreator). If the option is not activated, only a check for conflicts is carried out (see also chapter Medium).
A conflict such as this occurs if none of the conditions mentioned in chapter Range of functions are met.
The workflow can only be ended successfully once all conflicts have been resolved (see chapter Resolving conflicts).
|
References to remote project objects are not taken into consideration by the release workflow. |
|
If the menu structure is changed in ContentCreator, the affected page is displayed as not released. This means it is possible to release the changed menu structure with ContentCreator too. |
Entity
In ContentCreator, a dataset can be changed at two points:
-
On the overview page for all datasets
-
On the detail page for the selected dataset
If the release workflow is initiated on an overview page, the context relates to the changes to the overview page, and not the dataset.
|
To release the changes to a dataset, the release workflow must be started on the detail page of the dataset and not on the overview page for all datasets. |
If the release workflow is started on the overview page, the changes to a dataset will not be taken into consideration, and therefore will not be released either. The overview page is a page reference and the release workflow behaves accordingly.
If the release workflow is initiated on a detail page, the context relates to the selected dataset, and not the detail page. Only the changes to the dataset are taken into consideration and released accordingly.
|
It is therefore not possible to release changes to the detail page of a dataset (not the dataset itself) in ContentCreator. This must be done in SiteArchitect. Here it is the equivalent of a page reference, and the release workflow behaves accordingly. |
The references which usually exist for one dataset to other FirstSpirit stores are also taken into consideration by the workflow.
|
References to remote project objects are not taken into consideration by the release workflow. |
According to the conditions applicable to it, referenced media is also released (see chapter Medium) if the Release including media checkbox is activated when the workflow is started (see figure Release workflow start dialog box & form - ContentCreator).
If the option was deactivated when the workflow was started, the referenced media is only checked for potential conflicts.
References to objects which do not constitute media - regardless of the state of the checkbox - are basically only checked for conflicts, and are never released by the workflow.
A conflict occurs if none of the conditions mentioned in chapter Range of functions are met.
To end the workflow, all conflicts must be resolved (see chapter Resolving conflicts).
Document group
In ContentCreator, document groups can only be opened and displayed by means of a direct link or by using the ContentCreator search. Referencing via the navigation, and editing a document group, is not possible in ContentCreator. However, running a workflow is permitted, and carried out in the usual manner via the state menu.
The release workflow run on a document group only releases the node of this document group. The structure folders or page references referenced by it are not taken into consideration during release. However, they are checked for potential conflicts.
|
As nests of any depth may exist within a document group, only the first content level elements are used for the conflict check. Any child elements are ignored. A conflict occurs if at least one of the first content level elements has broken references or has never been released. |
For an illustrative example, see chapter Document group (SiteArchitect).
For information on resolving a conflict, refer to chapter Resolving conflicts.
For information on document groups, refer to the Handbook for Editors.
3.2. Conflicts
The release workflow described is designed to generate a consistent release state. While the workflow is running, what are known as conflicts can occur, which must be resolved manually. Conflicts therefore indicate any threats to the consistency of the release state. Errors would arise during generation and on the live page, which would express themselves in the form of "dead links". The conflict check prevents this from happening. In the case of the recursive release, the check also relates to the child elements of the selected element.
|
When the parent chain is released, its start nodes remain ignored. This means that the parent chain may contain elements of a start node path that have never been released, even once the release workflow is complete. In such cases, the editor receives an error message to indicate this but no conflict occurs. |
From a formal point of view, a conflict always occurs when the release workflow is running if there is a broken reference or none of the following conditions are met:
-
Only media is referenced and the
Release including mediaoption is activated -
The
Release including mediaoption is activated and a release version of all directly referenced objects which do not constitute media exists -
The
Release including mediaoption is deactivated and a release version of all directly referenced objects exists
|
With regard to the required existence of a release version (point 2 and 3 in the above list), pages are an exception: They are viewed as a unit with the page reference associated with them. If the release workflow is started on a page reference, the page is always automatically released as well - regardless of whether a release version of it exists (see also chapter Page reference (SiteArchitect) and chapter Page reference (ContentCreator)). |
Applied to the elements in FirstSpirit, the following statement can therefore be made:
A FirstSpirit object always triggers a conflict if:
-
It was deleted despite the existence of a direct reference and therefore generates a broken reference.
-
_No release version of it exists, and it is referenced by the object on which the release workflow is run.
|
In addition to these conditions, a conflict occurs in the case of the recursive release if one of the child elements is already in a workflow. |
Exceptions
_Referenced media without a release version only triggers a conflict if the Release including media option is not activated (see figure Release workflow form - SiteArchitect and figure Release workflow start dialog box & form - ContentCreator).
If the release workflow is run on a page reference, there must not be a release version of the underlying page in existence.
_Folders which are part of the parent chain of a referenced object are only released if there is still no release version of them in existence. Their start nodes remain ignored by the release. However, if folders are directly referenced, the conditions mentioned above apply.
If a conflict arises while the workflow is running, the workflow is interrupted. The editor has the option to have the list of all objects to be dealt with displayed, and to resolve the conflicts manually, in order to end the workflow successfully afterwards (see figure Message dialog box regarding existing conflicts (ContentCreator and SiteArchitect)).
For more information on resolving conflicts, refer to chapter Resolving conflicts.
3.3. Feature comparison matrix
Compared to the release workflow and the administrative release with which you are already familiar from earlier versions of FirstSpirit, the release workflow which has been redeveloped for FirstSpirit Version 5 offers significant advantages. The comparison below shows this too:
| Previous release workflow | New release workflow | Administrative release | |
|---|---|---|---|
Consistent release state ensured |
— |
— |
|
Information about conflicts which have occurred |
— |
— |
|
Release of datasets |
— |
() |
|
Support for dynamic forms |
— |
— |
|
Consideration of section references |
— |
— |
|
Release of referenced media |
|||
Accessibility ensured (parent chain) |
|||
Recursive release |
— |
||
Release only new media |
— |
— |
|
From Version 1.0.8, the BasicWorkflows only support FirstSpirit Version 5.1 or higher. From this module version, they are no longer compatible with FirstSpirit 5.0. |
4. Delete workflow
The native deletion of elements changes the tree structure of the project. However, this change only applies in the current state. For it to be applied in the release state as well, the parent node of the deleted element must be released.
This aspect is not intuitive and can potentially lead to irritation. To simplify the delete process for editors, a delete workflow based on the four-eye principle has been developed for FirstSpirit Version 5, which removes the element to be deleted from both the current and release state.
|
From Version 1.0.8, the BasicWorkflows only support FirstSpirit Version 5.1 or higher. From this module version, they are no longer compatible with FirstSpirit 5.0. |
The new delete workflow offers two delete options, which are made available via the workflow dialog box (see figure Delete workflow start dialog box (SiteArchitect)):
-
Direct delete
-
Request
Direct delete
|
This option is only available to the editor if they have the delete permission for the object to be deleted. The editor must also have the delete permission for folders, as errors may otherwise occur when deleting folders. |
The Direct delete option offers the same functionality as the Request option described below. However, during direct delete, assignment to a subsequent editor is avoided, and the check for potential conflicts is triggered automatically. If no conflicts arise while the workflow is running, the workflow runs through without any further interruption after starting. Therefore, the four-eye principle is not applied in this case.
The individual workflow steps are described in detail in the explanation of the Request option.
Request
The request to delete an element does not initially change the current state. The element continues to exist and is also visible in the preview (see also Visualizing delete requests at the end of this chapter). The subsequent editor either declines the deletion of the element or initiates it by advancing the workflow (see figure Advancing the workflow by the next editor). Only by advancing the workflow is an automatic check for potential conflicts carried out.
A conflict such as this occurs if the element to be deleted is referenced by another FirstSpirit object. Deleting an element which is still being referenced would generate errors in the project, during generation, and on the live page, and must therefore be avoided.
If the check generates a negative result, a list of the elements preventing the deletion can be displayed (see figure List of objects which reference the element to be deleted). The elements displayed in this list cannot be called up directly. They must be identified manually to resolve the conflicts.
For more information on resolving conflicts, refer to chapter Resolving conflicts.
The workflow can only continue if all conflicts have been resolved or no conflicts have been identified. The element to be deleted is then removed from the current state, and the parent node is released, in order to apply the deletion of the element in the release state as well.
|
The parent node is released every time the delete workflow is run, and this is not dependent on the previously existing release state of the parent elements. This means that previously unreleased parent elements are also released by the delete workflow. For this step, in addition to the delete permission for objects and/or folders, the editor must also have the release permission The consequences of such a release must be considered before running the workflow. If the release is not desired, the workflow must be individually adapted (see chapter Extending implementation). |
|
The potential occurrence of inconsistencies when deleting folders, and the removal of child elements associated with this, is not checked by the delete workflow. Such inconsistencies always arise if at least one of the child elements is referenced by another FirstSpirit object (incoming references). If such a check is desired, the workflow must be extended accordingly (see chapter Extending implementation). |
Cancel
The Cancel button performs the same function as the Close button: The workflow is not advanced and the selected element remains in the same state it was in before the dialog box opened.
Abort delete
The workflow first runs an automatic step when it is started. Canceling this step would result in a state that the editor would not be able to resolve. For this reason, the Abort delete button has been added to the dialog box. The Cancel button is mapped to this transition in the first step of the workflow. This is required as it is not possible to assign a transition directly to the Cancel button.
The Cancel and Abort delete buttons therefore have the same function.
|
In FirstSpirit Version 5.2 R2, the A workflow of this kind can only be started in the |
Visualizing delete requests
As already mentioned in this chapter, the request to delete an element does not initially change the current state. The element continues to exist and is visible in the preview. Other editors are therefore not able to immediately recognize that the element is part of the delete workflow.
If you want to visualize the deletion of an element, this can be done by integrating the following code snippet into the page template used, for example. The code snippet is only a minimal example and should therefore be adapted accordingly.
$-- workflow example: begin --$
<style type="text/css">
.inWorkflow
{ background-color: white;
filter:alpha(opacity=50); /* IE */
opacity: 0.5; /* Safari, Opera */
-moz-opacity:0.50; /* FireFox */
z-index: 20;
height: 100%;
width: 100%;
background-repeat:no-repeat;
background-position:center;
position:absolute;
top: 0px;
left: 0px;
}
</style>
$CMS_VALUE(#global.node.getTask().refresh())$
$CMS_IF(#global.node.getTask().getWorkflow().getUid().equals("<Referenzname des Arbeitsablaufs>"))$
<div id="inWorkflow" class="inWorkflow"></div>
$CMS_END_IF$
$-- workflow example: end --$All pages and page references based on this page template, which are within the delete workflow, are then grayed out (see figure Visualizing the delete workflow which has been started). This view works both in the preview of SiteArchitect and in ContentCreator.
|
As a result of being grayed out, the EasyEdit buttons in ContentCreator are covered. It is then no longer possible to edit the page. |
4.1. Range of functions
This delete workflow can be run in both SiteArchitect and ContentCreator. However, as the number of elements on which the workflow can be started diverges in the two clients, and the workflow behaves differently in the clients, they are distinguished from one other.
Generally, the delete workflow is used to remove an element from both the current state and the release state of the project. The deletion is applied in the release state by releasing the parent node of the deleted element. The incoming references to the element to be deleted are also taken into consideration, in order to prevent any inconsistencies which may potentially arise as a result of the deletion.
|
Inconsistencies which arise when deleting folders, and the removal of child elements associated with this, are not prevented by the delete workflow. In this case, inconsistencies always arise if incoming edges (incoming references) exist for at least one child element. |
Formally, the workflow should take into account the following factors when deleting an element:
-
Dependencies resulting from the deletion of an object:
-
To transfer the deletion into the release state, the parent node must be released
-
A page reference may not exist without an underlying page
-
When deleting a start page in a Site Store folder, a new start page must be defined
-
-
Prevention of the deletion in the event of existing, incoming references to the object to be deleted (exception: child elements of a folder to be deleted)
-
Prevention of the deletion if workflow instances are still open, should the object to be deleted be a workflow
If conflicts arise when deleting an element, the workflow is interrupted until all conflicts have been resolved.
For more information on resolving conflicts, refer to chapter Resolving conflicts.
|
Write protection is not applied to objects affected by the workflow when it is running. |
|
It is not possible for the delete workflow to delete itself. In this case, the running of the workflow is canceled. |
4.1.1. SiteArchitect
In SiteArchitect, the delete workflow is started via the context menu or, if the project is configured accordingly, by running any delete action (see chapter Selecting the workflow to delete elements). The workflow dialog box with which you are familiar opens. When starting the delete workflow, depending on the user, two options are available in this dialog box (see figure Delete workflow start dialog box (SiteArchitect)):
-
Direct delete
-
Request
Since the Direct delete option is merely a way of bypassing the four-eyes principle, and otherwise has the same functions as the Request option (see description in chapter Delete workflow), the explanations in the following subchapters relate to the Request option only.
In SiteArchitect, the workflow can be run on numerous objects. To prevent conflicts, the incoming edges (incoming references) of an object to be deleted must also be taken into consideration by the workflow. This chapter explains how the workflow works when it is run on the different First-Spirit objects in SiteArchitect.
|
It is not possible for the delete workflow to delete itself. In this case, the running of the workflow is canceled. |
Medium
If the delete workflow is started on a medium, it is deleted once the workflow has been advanced by the next editor, and the parent node of the medium is released if there are no incoming references to the medium.
|
The parent node is released every time the delete workflow is run, and this is not dependent on the previously existing release state of the parent elements. This means that previously unreleased parent elements are also released by the delete workflow. For this step, in addition to the delete permission for objects and/or folders, the editor must also have the release permission. |
If there are incoming references to the medium to be deleted, a conflict arises without which the result would be an inconsistent release state. The conflict must be resolved manually first before the medium can be deleted (see chapter Resolving conflicts).
|
If the medium is a child element of a folder to be deleted, the incoming references of the medium are not checked. This can therefore lead to inconsistencies when deleting a folder. |
Entity
A dataset can only be deleted by the workflow if it is not referenced by other FirstSpirit objects (incoming references), as inconsistencies would arise otherwise.
If the dataset itself references other FirstSpirit objects (outgoing references), this does not affect the workflow.
To prevent inconsistencies, a conflict arises if there are existing incoming references. This must be resolved manually first before the dataset can be deleted by the workflow (see chapter Resolving conflicts).
Data source
It is not possible to perform the delete workflow on data sources.
As before, a data source can therefore only be deleted via the Extras Delete data source context menu entries. However, this option is only available to project administrators.
Page
Starting the workflow on a page in the Page Store deletes the page - once the workflow has been advanced by the next editor - and releases the parent node if the page is not referenced by another FirstSpirit object.
|
The parent node is released every time the delete workflow is run, and this is not dependent on the previously existing release state of the parent elements. This means that previously unreleased parent elements are also released by the delete workflow. For this step, in addition to the delete permission for objects and/or folders, the editor must also have the release permission. |
If the page itself references other FirstSpirit objects, this does not affect the workflow.
If there are incoming references, this triggers a conflict that must be resolved manually before the workflow can be continued (see chapter Resolving conflicts).
|
If the page is a child element of a content folder to be deleted, the incoming references of the page are not checked. This can therefore lead to inconsistencies when deleting a folder. |
Page reference
If the start element of the delete workflow is a page reference, this is deleted by the workflow and the associated parent node is released if the page reference does not have any incoming references.
|
The parent node is released every time the delete workflow is run, and this is not dependent on the previously existing release state of the parent elements. This means that previously unreleased parent elements are also released by the delete workflow. For this step, in addition to the delete permission for objects and/or folders, the editor must also have the release permission. |
If the page reference itself references another FirstSpirit object - by selecting an image for the sitemap (see figure Page reference with referenced image for the sitemap) - this does not affect the workflow.
Existing references of other FirstSpirit objects to the page reference to be deleted trigger a conflict, as errors in the release state would otherwise occur. A conflict must be resolved manually first before the deletion of the required element can be continued (see chapter Resolving conflicts).
|
If the page reference is a child element of a structure folder to be deleted, the incoming references of the page reference are not checked. This can therefore lead to inconsistencies when deleting a structure folder. |
|
If the deleted page reference was a start page of a structure folder, another page reference located in this folder is automatically selected as the start page. If there is no other page reference located in the folder, an error message appears when the workflow is run. |
Document group
Page references and structure folders can be combined in a document group in order to be displayed as a page.
The structure folders and page references referenced within the document group, as well as the pages associated with them, do not influence the delete workflow. They are also ignored by it, as they are outgoing references.
However, the delete workflow does take incoming references into consideration. Such a reference exists if the document group is referenced by another FirstSpirit object. In this case, a conflict is triggered when the workflow is run. This must be resolved manually first before the document group can be deleted and its parent node released (see chapter Resolving conflicts).
For information on document groups, refer to the Handbook for Editors as well.
|
The parent node is released every time the delete workflow is run, and this is not dependent on the previously existing release state of the parent elements. This means that previously unreleased parent elements are also released by the delete workflow. For this step, in addition to the delete permission for objects and/or folders, the editor must also have the release permission. |
Folder
When starting the delete workflow on a folder, this is deleted along with its child elements, and its parent node is released, if it is not referenced by other FirstSpirit objects.
|
The parent node is released every time the delete workflow is run, and this is not dependent on the previously existing release state of the parent elements. This means that previously unreleased parent elements are also released by the delete workflow. For this step, in addition to the delete permission for objects and/or folders, the editor must also have the release permission. |
Existing references to the folder to be deleted trigger a conflict, as errors in the release state would otherwise occur. A conflict must be resolved manually first before the workflow can be continued (see chapter Resolving conflicts).
|
It is not possible to perform the delete workflow on Data Store folders. The delete workflow is not available on these nodes. |
|
A check for the potential occurrence of inconsistencies when deleting folders, and the removal of child elements associated with this, is not carried out. This is always the case if incoming edges (incoming references) exist for at least one of the child elements due to existing references. |
Structure folder
Compared to folders from the other FirstSpirit stores, folders from the Site Store are special, since only they have start pages. A structure folder without a start page results in generation errors. This state must therefore be avoided.
If the start page of a structure folder is deleted by the delete workflow, another page reference located in the folder is automatically selected as the start page.
If no other page reference is located within the structure folder, and it would therefore subsequently be empty as a result of deleting the start page, a warning will be displayed while the workflow is running (see figure Deleting the start page as the last element of a structure folder).
|
By deleting a start page of a structure folder, a new start page is selected for this folder if it contains at least one other page reference. The new start page is automatically released by the workflow - regardless of its previous release state. This means that a previously unreleased page reference is also released if it has been selected as the start page. |
Global pages
The behavior of the delete workflow for global pages in the Global Settings matches the behavior for pages from the Page Store.
4.1.2. ContentCreator
In ContentCreator, the delete workflow is started via the State or Contents menu (see figure State and Contents menus in ContentCreator). Additionally, it can be run using the Media Store that was added to FirstSpirit Version 5.2 R2.
The entry within the State menu is always visible due to the fact that the delete workflow provided for running in ContentCreator is activated by default. However, the entry in the Contents menu and the option in the Media Store only appear if the delete workflow in the Project properties has been selected by default for all delete actions (see chapter Selecting the workflow to delete elements).
By starting the workflow, the associated dialog box opens in which the two available delete options are provided (see figure Delete workflow start dialog box).
In ContentCreator, the delete workflow can only be run on page references, Content Store detail pages, document groups, and - from FirstSpirit Version 5.2 R2 - on media and media folders. These elements are described in more detail below.
|
A workflow can only be started in the |
|
To use the delete workflow in ContentCreator, it is mandatory that the |
Page reference
In ContentCreator, editors work on page references which are based on pages, however. Therefore, when deleting a page reference, the underlying page must also be taken into consideration by the delete workflow.
If the workflow is started on a page reference, this is deleted first once the workflow has been advanced by the next editor. This only works if the page reference is not referenced by any other FirstSpirit object. Otherwise, a conflict is triggered in order to prevent inconsistencies. The elements which trigger the conflict can be displayed and must be identified manually (see figure List of the elements which triggered a conflict (ContentCreator)). The workflow can only be continued once all existing conflicts have been resolved (see Resolving conflicts).
After the page reference has been deleted, the parent node is released in order to apply the deletion in the release state as well.
The workflow then edits the page underlying the page reference. If no other references by other FirstSpirit objects exist for the page, it is also deleted by the workflow under the conditions which apply to pages.
|
The parent node is released every time the delete workflow is run, and this is not dependent on the previously existing release state of the parent elements. This means that previously unreleased parent elements are also released by the delete workflow. For this step, in addition to the delete permission for objects and/or folders, the editor must also have the release permission. |
|
If the deleted page reference was the last element within the structure folder which contained it previously, the folder is also deleted. This also applies recursively to the parent chain. This means that all parent folders of the deleted folder (which in turn contained the deleted page reference) are also removed if they do not contain any other child elements. The same applies to the page underlying the page reference and its parent chain. |
Entity
In ContentCreator, a dataset can be edited at two points:
-
On the overview page for all datasets
-
On the detail page for the selected dataset
If the delete workflow is initiated on an overview page, the delete context relates to the overview page, and not the dataset. The overview page is a page reference and the delete workflow behaves accordingly. In this case, the dataset is not deleted.
|
To delete a dataset in ContentCreator, the delete workflow must be started on the detail page of the dataset and not on the overview page for all datasets. |
If the delete workflow is initiated on a detail page, the delete context relates to the selected dataset, and not the detail page.
The FirstSpirit objects referenced by a dataset do not influence the delete workflow, and they are ignored by it, as they are outgoing references.
However, the delete workflow does take incoming references into consideration. These exist if the selected dataset is referenced by other FirstSpirit objects. In this case, the dataset cannot be deleted by the workflow and a conflict occurs. This must be resolved manually first before the dataset can be deleted (see chapter Resolving conflicts).
Medium
Media are maintained in ContentCreator via the Media Store, which is opened by selecting Media Manage media. If the delete workflow is selected in the Project properties, a button with a trash can icon is shown for each image (see figure Image in the Media Store).
|
The Media Store was first added to ContentCreator in FirstSpirit Version 5.2 R2. This means that it is not available in earlier versions of FirstSpirit. In earlier versions, it is only possible to delete media in SiteArchitect (see chapter Medium). |
Clicking on the trash can button starts the delete workflow. Running this workflow removes the medium from the project. After the image has been deleted, the parent node is released in order to apply the deletion to the release state as well.
|
The parent node is released every time the delete workflow is run, and this is not dependent on the previously existing release state of the parent elements. This means that previously unreleased parent elements are also released by the delete workflow. For this step, in addition to the delete permission for objects and/or folders, the editor must also have the release permission. |
|
As with the page references, deleting the image affects the entire parent chain recursively. This means that all parent folders of the deleted image are also removed if they do not contain any other child elements. A parent folder is only retained if it is being referenced and deleting it would therefore create inconsistencies. |
Deleting the medium only works if it is not referenced by other FirstSpirit objects. Otherwise, a conflict occurs which must be resolved manually (see chapter Resolving conflicts).
A workflow can only be started in the Media Store; it cannot be advanced. Therefore, if a conflict arises at this point, it represents a state that can only be resolved in SiteArchitect. In such cases, the editor is shown a dialog box indicating this (see figure Information dialog box in the event of a conflict).
The same applies to the Request button in the start dialog box of the delete workflow. It puts the workflow into a state that needs to be advanced in SiteArchitect. If the trash can button is clicked again, the editor is informed that the medium to be deleted is already in a workflow.
Folder
In contrast to the folders in the other stores, media folders can be maintained in ContentCreator. This is possible thanks to the Media Store, which is opened by selecting Media Manage media. If the delete workflow is selected in the Project properties, the Delete item is shown in the context menu of the selected folder (see figure Folders in the Media Store).
|
The Media Store was first added to ContentCreator in FirstSpirit Version 5.2 R2. This means that it is not available in earlier versions of FirstSpirit. In earlier versions, it is only possible to delete folders in SiteArchitect (see chapter Folder). |
When the delete workflow is run on a media folder, the media folder is deleted along with its child elements, and its parent node is released.
|
The parent node is released every time the delete workflow is run, and this is not dependent on the previously existing release state of the parent elements. This means that previously unreleased parent elements are also released by the delete workflow. For this step, in addition to the delete permission for objects and/or folders, the editor must also have the release permission. |
|
As with the page references, deleting the folder affects the entire parent chain recursively. This means that all parent folders of the deleted folder are also removed if they do not contain any other child elements. A parent folder is only retained if it is being referenced and deleting it would therefore create inconsistencies. |
Existing references to the folder to be deleted trigger a conflict, as errors in the release state would otherwise occur. A conflict must be resolved manually first before the workflow can be continued (see chapter Resolving conflicts).
|
A check for the potential occurrence of inconsistencies when deleting a folder, and the removal of child elements associated with this, is not carried out. This is always the case if incoming edges (incoming references) exist for at least one of the child elements due to existing references. |
A workflow can only be started in the Media Store; it cannot be advanced. For this reason, the delete workflow must be continued in SiteArchitect in the event of a conflict. In such cases, the editor is shown a dialog box indicating this (see figure Information dialog box in the event of a conflict).
The same applies to the Request button in the start dialog box of the delete workflow. It puts the workflow into a state that needs to be advanced in SiteArchitect. If deletion is attempted again, the editor is informed that the folder to be deleted is already in a workflow.
Document group
In ContentCreator, document groups can only be opened and displayed by means of a direct link or by using the ContentCreator search. Referencing via the navigation, and editing a document group, is not possible in ContentCreator. However, the delete workflow can be run.
The delete workflow started on a document group only removes the node of this document group. The structure folders and page references referenced by it are not taken into consideration and remain in place.
Deleting the node of the document group only works if it is not referenced by other FirstSpirit objects. Otherwise, a conflict occurs which must be resolved manually (see chapter Resolving conflicts).
For information on document groups, refer to the Handbook for Editors as well.
4.2. Conflicts
The delete workflow described is designed to remove an element to be deleted from the current state, and - by releasing the parent node - from the release state as well. While the workflow is running, what are known as conflicts can occur, which must be resolved manually. Conflicts indicate that the element to be deleted is still being referenced by other FirstSpirit elements. As a result of deletion, there would be references to an element which no longer exists. The conflict check prevents this from happening.
If a conflict arises while the delete workflow is running, the workflow is interrupted. The editor then has the option to have a list of all objects preventing the deletion to be displayed, and to resolve the conflicts manually, in order to end the workflow successfully (see figure List of elements which reference the element to be deleted).
|
Media or media folders to be deleted in ContentCreator are a special case where conflicts are concerned, as the workflow is started in the |
For more information on resolving conflicts, refer to chapter Resolving conflicts.
4.3. Feature comparison matrix
Compared to native deletion, the delete workflow which has been redeveloped for FirstSpirit Version 5 offers significant advantages, which are illustrated in the comparison below:
| Native deletion | New delete workflow | |
|---|---|---|
Consistent release state ensured |
( — ) |
|
ContentCreator-Support |
— |
|
Information about conflicts which have occurred |
||
Deletion of datasets |
||
Automatic release of dataset deletion |
— |
|
Consideration of section references |
||
Recursive deletion in SiteArchitect (without checking of child elements) |
|
From Version 1.0.8, the BasicWorkflows only support FirstSpirit Version 5.1 or higher. From this module version, they are no longer compatible with FirstSpirit 5.0. |
5. Resolving conflicts
What are known as conflicts may arise while running both the release workflow and the delete workflow (see chapter Conflicts (SiteArchitect) and chapter Conflicts (ContentCreator)). Conflicts indicate existing references which would lead to inconsistencies in the release state.
The release workflow deals with outgoing references, which refer to objects which have been deleted or have never been released.
The delete workflow deals with incoming references from other FirstSpirit objects which refer to the object to be deleted.
Both workflows offer three options for how to proceed when a conflict occurs:
|
Media or media folders to be deleted in ContentCreator are a special case where conflicts are concerned, as the workflow is started in the |
5.1. Triggering a cancelation
When canceling the corresponding workflow, the workflow is ended and the selected FirstSpirit object on which the workflow was originally started is reset to its previous release state (exception: datasets). The object is only released or deleted if the respective workflow is restarted and carried out successfully.
|
It is a known issue with FirstSpirit that the release state of datasets is not reset as a result of canceling workflows. Previously released datasets are then classified as changed, and are no longer released. |
5.2. Forcing an action
|
This option is only available to project administrators. |
In both workflows, you can force the action made available despite existing conflicts.
The element on which the corresponding workflow was started is released or deleted without resolving the conflict. No further check is carried out.
The inconsistencies resulting from this are deliberately accepted.
5.3. Checking unreleased or incorrect objects
To manually resolve existing conflicts, both workflows make available a list of the objects which are causing a conflict (see figure Objects triggering a conflict (release and delete workflow)).
This is purely textual information. This means that the objects displayed in the relevant list cannot be called up via the dialog box, and they must be identified manually.
As the two workflows have different types of references (outgoing/incoming references), the procedure for resolving conflicts which have occurred differs. The following subchapters describe the corresponding procedure.
5.3.1. Release workflow
With the exception of the Template Store, the release workflow check takes into consideration only the outgoing references of the object on which the workflow was started. Therefore, only outgoing references can cause conflicts.
In this case, SiteArchitect offers the use of the relation graph to manually identify the objects which have generated a conflict (see figure Page reference relation graph in SiteArchitect). This can be displayed using the Extras Display dependencies context menu items, or using the key combination CTRL + R.
|
Child elements that are already in a workflow also lead to a conflict in the case of the recursive release. However, they are not included in the relation graph and therefore need to be identified independently. |
You can jump directly to an element via the context menu of the elements displayed within the relation graph.
ContentCreator offers the same option via the Related objects report and the Outbound links area contained within it (see figure "Related objects" report in ContentCreator).
In this way, the referenced elements can be identified in both SiteArchitect and ContentCreator, and all conflicts resolved by releasing the corresponding elements.
A renewed release attempt can then be triggered within the workflow originally started (see figure Triggering a renewed release (SiteArchitect)).
5.3.2. Delete workflow
Running the delete workflow always generates a conflict if the element to be deleted is still being referenced by other FirstSpirit elements. Therefore, only incoming references can cause conflicts.
In this case, SiteArchitect offers the Show usages function to identify the elements which have triggered a conflict (see figure Page reference usage (SiteArchitect)). The associated dialog box can be opened using the Extras Show usages context menu items, or using the key combination CTRL + U.
You can jump directly to an element by pressing the Display button or by double-clicking one of the elements displayed.
ContentCreator offers the same option via the Related objects report and the Inbound links area contained within it (see figure "Related objects" report in ContentCreator).
|
The |
In this way, the elements referencing the object to be deleted can be identified in both SiteArchitect and ContentCreator, and all conflicts resolved by means of removing the existing references.
A renewed delete attempt can then be triggered within the original workflow (see figure Triggering a renewed deletion (SiteArchitect)).
6. Extending implementation
Workflows are generally subject to project-specific requirements. Therefore, the workflows described in this document can only cover the basic functions of deleting or releasing FirstSpirit objects. If functions which go above and beyond this are desired, these must be implemented individually. Two examples are presented in the following subchapters.
6.1. MultiNode ability
Unlike the delete workflow, the release workflow is MultiNode-enabled with regard to page references. This means that it can take into account multiple page references at the same time. For these additional page references, the user must decide whether they are to be checked for conflicts only or released.
The parameters relatedPageRefElements and releasePageRefElements are provided for both cases. They can be transferred to the put method of a session together with the list of page references to be taken into account. The following syntax is to be observed:
// PageRef elements that should be checked
workflowScriptContext.getSession().put("relatedPageRefElements", pageRefUids);
// PageRef elements that should be released
workflowScriptContext.getSession().put("releasePageRefElements", pageRefUids);The parameter pageRefUids corresponds to a list of strings (List<String> pageRefUids). The list must include the reference names of the page references to be taken into account. This list must be transferred to the workflow via a script which is to be added to an activity. It makes sense to select the first activity in this case.
|
If the transferred list has been filled, only the elements that it contains are taken into account by the workflow. This rule also applies to the page reference on which the workflow is started. The page reference will only be checked for conflicts and/or released if it is also part of the list. Otherwise, it will not be taken into account by the workflow, which could potentially cause problems. If no list is transferred or it is empty, the release workflow behaves according to its default behavior. |
6.2. Section references
Section references are already taken into consideration by the release workflow (see chapter Feature comparison matrix). However, this function is a good example of how the workflows can be extended.
Assuming that this function was not covered by the release workflow, this chapter describes how it would be added.
Since adding a function requires the code to be changed, the code must be downloaded first. The current version of the source code is available via a GitHub repository, which can be accessed at https://github.com/e-Spirit/basicworkflows.
|
The source code is available under the Apache license. |
The WorkflowObject.java class contained within the com.espirit.moddev.basicworkflows.release package contains the getRefObjectsFromSection and checkReferences methods. The getRefObjectsFromSection method detects all outgoing references of an element section on which the release workflow was started. The checkReferences method checks whether all referenced elements of the element to be released have already been released.
The getRefObjectsFromSection method has an if query which corresponds to the following code extract without taking into account section references:
// add outgoing references of page sections
if (!(section instanceof Content2Section) && !(section instanceof SectionReference)) {
[...] }If section references are also to be taken into account by the release workflow, the second condition of the if query within the code extract must be removed:
// add outgoing references of page sections
if (!(section instanceof Content2Section)) {
[...] }The checkReferences method has a for loop which contains several if queries. Without checking section references, the else part of the first if query within this loop corresponds to the following code extract:
IDProvider idProvider;
if (object instanceof IDProvider) {
idProvider = (IDProvider) object;
} else {
idProvider = (IDProvider) ((ReferenceEntry)object).getReferencedObject();
}
// check if current PAGE within PAGEREF-Release
boolean isCurrentPage = false;
[...]To take into account section references, this query must be extended as follows:
IDProvider idProvider;
if (object instanceof IDProvider) {
idProvider = (IDProvider) object;
} else {
idProvider = (IDProvider) ((ReferenceEntry)object).getReferencedObject();
}
if (idProvider instanceof Section) {
idProvider = idProvider.getParent().getParent();
}
// check if current PAGE within PAGEREF-Release
boolean isCurrentPage = false;
[...]To apply all changes to the FirstSpirit Server and therefore within the project, the module needs to be regenerated and reinstalled.
A pom.xml file can also be found in the GitHub repository where the source code is provided. This enables the module to be regenerated using Maven.
|
To install Maven, follow the installation instruction steps on the page: |
To enable the amended source code to be compiled successfully, the fs-access.jar file of the FirstSpirit Server used must be installed in the local Maven repository first. The fs-access.jar file is located in the directory:
<FirstSpirit Server directory>/data/fslib
It is installed by entering the following command into the command line:
mvn install:install-file -Dfile=<path-to-acces.jar> -DgroupId=de.espirit.FirstSpirit -DartifactId=fs-access -Dversion=<fs version e.g. '5.0.0'> -Dpackaging=jar
Within this command, the parameters for the path to the fs-access.jar file and the FirstSpirit version used must be substituted accordingly.
Example
mvn install:install-file -Dfile=C:\fs-access.jar -DgroupId=de.espirit.FirstSpirit -DartifactId=fs-access -Dversion=5.1.2 -Dpackaging=jar
|
Running the installation command within the directory in which the |
During installation, the local Maven repository has been automatically created in the user directory under ${user.home}/.m2/repository. After the fs-access.jar file has been successfully installed, it should be located in this directory (see figure Local Maven repository with installed fs-access.jar file).
The amended source code can then be compiled by entering the following command into the command line:
mvn package -Dci.version=<version> -DFirstSpirit.version=<fs-version>
Within this command, the version and fs-version values must be replaced accordingly. The fs-version value must match the value for the Dversion parameter in the previous command.
Example
mvn package -Dci.version=1.0.0 -DFirstSpirit.version=5.1.2
Within the directory containing the pom.xml file, a target subdirectory is created as a result of the compilation. This is where the regenerated module is located (see figure Regenerated fsm file within the target directory).
The regenerated module must then be reinstalled on the server, as described in chapter Installing the module on the server.
7. Frequently Asked Questions
Q: The range of functions for the workflows described is insufficient or unsuitable. What can I do now?
A: If the range of functions for the workflows described in this document does not cover your project requirements, you can extend the workflows individually, and adapt them to the special features of your project.
A description of how to implement such an extension can be found in chapter Extending implementation.
Q: I already have my own workflows, but would like to use the new functions of the workflows described as well. How do I do that?
A: The workflows described do not offer any automatic system for applying the functions of other workflows. A corresponding adaptation must therefore be carried out manually.
You should consider whether you would like to apply the functions of the described workflows in your existing workflow, or whether you would like to extend the described workflows to include the functions of your workflow.
A description of how to extend the workflows described can be found in chapter Extending implementation.
Q: I’ve found an error in the workflows. Where can I report this?
A: To report an error found in the workflows, please contact our Technical Support.
If you have already resolved the error and would like to provide us with your changes, please note the following question.
Q: I’ve carried out an extension to one of the workflows which may be of interest for other projects. What should I do about it?
A: The source code which is available for the workflows described in this document is provided in a GitHub (see chapter Extending implementation). If you would like to provide us with an extension to one of the workflows, you must create what is called a Pull request for this GitHub.
An explanation of how to do this can be found on the following page:
https://help.github.com/articles/using-pull-requests
8. Help
The Technical Support of the Crownpeak Technology GmbH provides expert technical support covering any topic related to the FirstSpirit™ product. You can get and find more help concerning relevant topics in our community.
9. Disclaimer
This document is provided for information purposes only. Crownpeak Technology GmbH may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. Crownpeak Technology GmbH specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.