2021 September Release

Creating Xtech DocumentsPermanent link for this heading

An Xtech document describes the structure of a document and consists of individual topics. The referenced stylesheet defines the XML schema and the notation of the document.

Creating Xtech DocumentsPermanent link for this heading

In order to create an Xtech document, follow these steps:

  1. Navigate into your Xtechwriter dashboard.
  2. Click the ”Create Xtech Document” action.
  3. Define the following metadata:
    • Name
      Defines the name of the Xtech document.
    • Shelf
      Defines the shelf that the Xtech document is assigned to.
    • Stylesheet
      Defines the XML schema and the notation of the document.
    • Category
      Defines the category of the document. For example, it can be used as the condition for the usage of topics and text modules.
    • Author
      Defines the user who forwards publications for approval (is used as workflow participant in the default approval process).
    • Reviewer
      Defines the user who approves the publication (is used as workflow participant in the default approval process).
  4. Click “Continue“.

Editing Xtech DocumentsPermanent link for this heading

The contents of an Xtech document are primarily created and maintained within the Xeditor. The document structure can be defined on topic-level as well in the tree view. Notably, existing topics can be re-used and added to an Xtech document.

Using XeditorPermanent link for this heading

The Xeditor is used to write the contents of the document. One can either edit the entire Xtech document or merely individual topics.

In order to edit an Xtech document with the Xeditor, follow these steps:

  1. Navigate into the desired Xtech document.
  2. Click the “Edit“ action.
  3. Write the desired content.
    Note: Further information on the usage of the Xeditor can be found in the next section.
  4. Click “Save“ (floppy disk symbol; keys: Ctrl + S) and close the Xeditor window.

Xeditor

The Xeditor offers the following possibilities.

Work Area

  • The document is displayed in the content area according to the referenced stylesheet to be edited.
  • On the right, in “Table of Contents“, the topics of the document are displayed in a tree view. Alternatively, in “Attributes”, the attributes of the currently selected element can be displayed. If necessary, attributes defined in the stylesheet can be added.

Tool Bar

  • General
    By default, the buttons “Save“, “Copy“, “Cut“, “Undo, “Redo“ and “Search/Replace” are visible.
  • Start
    Allows users to format elements and add new elements (e.g. topics).
  • Table
    Allows users to add and edit tables.
  • Review
    Allows users to add comments and activate/deactivate change tracking.
  • View
    Allows users to adjust the document view (e.g. tags or placeholders).
  • Fabasoft Cloud
    Allows users to insert text modules and fields.
  • Footer
  • XML Path
    Displays the path to the selected XML element. The drop-down menu of the path elements allows performing actions such as “Insert element” or “Delete”.
  • Notifications
    Notifications regarding, for example, a corrupt XML structure can be display by clicking the bell symbol.

The available XML elements are defined by the XML schema of the referenced stylesheet. Currently, the XML schema “Xeditor Schema Lightweight DITA“ is supported.

When you create a new document, start by creating a topic element that represents the document. You can subordinate further topic elements to this topic element which then represent the chapters of the document. A topic element generally contains a title element, a body element (which contains the paragraph elements) and – as may be necessary – further topic elements acting as sub-chapters.

Example

In order to create a document containing the chapters “1. Introduction“, “2. Preparation“, and “2.1 Operation“, follow these steps:

  1. Edit the Xtech document.
  2. In the tool bar, click the “Topic“ button.
    Note: Alternatively, open the drop-down menu of the first topic element in the footer and click “Insert element” > “Topic”.
  3. Enter the value “Introduction“ as the title. By pressing the enter key, a placeholder paragraph is inserted below. Hence, you can write the first paragraph of the chapter.
  4. Open the drop-down menu of the first topic element in the footer and click “Insert element” > “Topic”.
  5. Enter the value “Preparation“ as the title. By pressing the enter key, a placeholder paragraph is inserted below.
  6. In the tool bar, click the “Topic“ button.
    Note: Alternatively, open the drop-down menu of the second topic element in the footer and click “Insert element” > “Topic”. The second topic element of the currently selected XML path is the chapter “Preparation”. The corresponding element is highlighted in gray in the editor. Thus, you can quickly determine if you are in the correct XML path.
  7. Enter the value “Operation“ as the title. By pressing the enter key, a placeholder paragraph is inserted below.

Note: Alternatively, you can perform these actions via the context menu of the respective elements.

Arranging TopicsPermanent link for this heading

The structure of an Xtech document can also be arranged via the tree view. Thus, especially the re-use of topics is possible.

In order to alter the structure of an Xtech document, follow these steps:

  1. Navigate into the desired Xtech document or topic.
  2. Perform the desired “Insert Content“ action:
    • Create Topic
      Creates a new topic with the name given.
    • Paste Duplicate
      Pastes a duplicate of a topic in the clipboard.
    • Paste Shortcut
      Pastes a shortcut of a topic in the clipboard.
    • Insert Text Module
      Enables the selection and insertion of predefined text modules.

Note: In the properties of a topic, on the “Topic“ tab, you find the Expression for the Restriction of Usage field (see chapter “Usage“ ). The topic is only visible in the publication when the expression is true. Hence, there can be several variants of documents.

Text ModulesPermanent link for this heading

Text modules allow for the re-use of content in numerous documents. The content of the referenced text modules is not transferred into the document until the text modules are resolved. Therefor, the document is always up-to-date. Furthermore, conditions can be defined to determine if a text module is visible. Hence, it is very simple to publish several variants of the same document.

There are two kinds of text modules:

  • Static Text Module (Xeditor Section)
    Allows users to write content of a chapter, yet not a topic itself.
  • Static Text Module (Xeditor Topic)
    Allows users to write a chapter with subchapters.

Text modules are managed by Xtechwriter administrators in the Xtechwriter configuration (“Text Modules” area). These text modules are made available in all shelves. Xtechwriter users can manage text modules in their respective shelves (“Templates and Presettings” action > “Text Modules” area).

Creating Text ModulesPermanent link for this heading

In order to create a text module, follow these steps:

Navigate into the Xtechwriter configuration or into the desired shelf to the Text Modules area.

  1. Click the “Create Text Module” action.
  2. Click the “Static Text Module (Xeditor Section)” or “Static Text Module (Xeditor Topic)” entry.
  3. Set the metadata of the text modules (see the next section).
  4. Click “Next“.
  5. In the context menu of the text module, click “Edit”.
  6. Write the desired content, click the “Save“ button in the tool bar and close the Xeditor window.

Note: Text modules created in the Xtechwriter configuration must be released by clicking “Release for Usage” in the context menu before they can be used. Changes in the text modules must also be released via the “Re-Release” context menu command.

Metadata

The following metadata can be defined:

Static Text Module tab

  • Name
    The name of the text module.
  • Stylesheet
    Defines the stylesheet of the text module.
  • Text Module Categories
    The text module is offered upon inserting in an Xtech document under the defined categories.
    Note: In the context of the Xtechwriter configuration, text module categories can be created directly in this field. Alternatively, the Xtechwriter configuration offers the “Define Text Module Categories” action.
  • Text Module Language
    Defines the language of the text module. When inserting text modules into Xtech documents, you can filter them by language.

Usage tab

  • Topic
    Defines the object classes and categories of topics in which the text module can be used.
    Note: If a base form category is entered, the text module is also available to topics that were assigned a superordinate form category.
  • Xtech Document
    Defines the object classes and categories of Xtech documents in which the text module can be used.
  • Available Fields (Topic)
    Displays the fields available in the text module according to the definition in the Topic field.
  • Available Fields (Xtech Document)
    Displays the fields available in the text module according to the definition in the Xtech Document field.
  • Expression for the Restriction of Usage
    The text module is only visible in the publication when the expression is true (see chapter “Usage“). Hence, there can be several variants of documents.

Using Text ModulesPermanent link for this heading

Text modules can be inserted either in the tree view via the “Insert Content” > “Insert Text Module” action or in the Xeditor via the toolbar (“Fabasoft Cloud” > “Insert Text Module”). The availability of the text modules is computed based upon the context (e.g. which topic the cursor is located in).

FieldsPermanent link for this heading

In the Xeditor, certain metadata can be inserted into the document. Select these fields in the toolbar via “Fabasoft Cloud” > “Insert Field” (e.g. Valid From).

PublicationsPermanent link for this heading

Xtech documents can be published as PDF documents. This process takes the master data and the conditions of topics and text modules into account. The approval of the publication is handled via a default process which can be replaced with a custom process.

Publishing Xtech DocumentsPermanent link for this heading

In order to publish an Xtech document, follow these steps:

  1. Navigate into the desired Xtech document.
  2. If you use the default process that supplied with the product or a custom process in which the reviewer of the Xtech document is also defined as a workflow participant, make sure that the Reviewer field of the Xtech document contains the desired value.
  3. Click the “Publications“ > “Publish” action.

A publication is created and, in it, the approval process is started.

The publication is placed in the “Publications“ dashboard area and in the properties of the Xtech document (“Publications” tab). Additionally, publications are available via the “Publication” action of the Xtech document.

Approving PublicationsPermanent link for this heading

The approval of the publication is handled via a default process which can be replaced with a custom process (see chapter “Defining Default Processes“). The default approval process is implicitly started upon publishing.

The default process included in the product consists of the following activities:

  • Forward for Approval
    The process assigns this activity to the user referred to in the Author field.
    • Open
    • Open Properties
    • Comment
      Comments can be inserted into a publication.
    • Forward for Approval
      The publication is forwarded for approval to the user referred to in the Reviewer field of the Xtech document.
    • Discard
  • Release Publication
    The process assigns this activity to the user referred to in the Reviewer field.
    • Open
    • Open Properties
    • Comment
    • Release
    • Deny Release

Custom processes can also use the following publication-specific activities:

  • File Publication
    • Open
    • Open Properties
    • File PDF Copy
    • Do Not File
  • Register Publication
    • Open
    • Open Properties
    • Register PDF Copy
    • Do Not Register

Publication StatusPermanent link for this heading

A publication can display the following statuses:

  • In Progress
    As soon as a publication is created, it receives this status.
  • Discarded
    The publication was discarded (e.g. “Discard“ activity)
  • Released
    The publication was released (e.g. “Release“ activity)
  • Not Released
    The publication was not released (e.g. “Deny Release“ activity)

Master DataPermanent link for this heading

Xtech documents can store master data in JSON format. This data can be considered in the publishing process.

In order to upload master data, follow these steps:

  1. Navigate into the desired document.
  2. Click the “Import Master Data” action.
  3. Select a file containing the data in JSON format and click the “Upload” button.

The current master data of an Xtech document can be reviewed in “Properties” > “Master Data” tab.

Example

JSON file:

{
  "company": "Acme Ltd.",
  "formed": 2016,
  "active": true
}

Usage in a text module in the Expression for the Restriction of Usage field:

::document.xtdmasterdata.company == "Acme Ltd.";

UsagePermanent link for this heading

For topics and text modules, users can define the usage. By using app.ducx expressions, it is very simple to publish numerous variants of a document.

In the global scope, the following variables are available:

  • ::document
    The document that is to be published.
  • ::topic
    The superordinate topic.
  • ::hierarchy
    The hierarchy between the document and the current-computed object.

Example

// Category of the document must match the custom category with the
// Fabasoft Cloud ID "COO.1.506.2.4710"

::document.objcategory == COO.1.506.2.4710;

// The custom form field of the superordinate topic must have the value "Value 1"
::topic.[#formstr1] == "Value 1";

// The subject of the superordinate topic have the value "Value 1"
// (-1 is the last topic within the hierarchy)
::hierarchy[HasClass(#XtechTopic)][-1].objsubject == "Value 1";

// The custom form field "formstr1" of the current topic must
/
/ have the value "Value 1"
::cooobj.[#formstr1] == "Value 1";