Skip to content

Commit

Permalink
Fix lint errors in docs
Browse files Browse the repository at this point in the history
  • Loading branch information
bheisig committed Oct 17, 2023
1 parent c5a49fa commit 54a87eb
Show file tree
Hide file tree
Showing 9 changed files with 120 additions and 125 deletions.
2 changes: 1 addition & 1 deletion docs/admin/custom-categories.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ To assign custom Categories to Classes you need the `Rights > CMDB > Manage Clas

Custom categories are created at `Settings > Categories` there you need to Click on the `New Category` Button. You need to fill out a `Name` for the Category and you need to select a `Category Type` either `Single value` or `Multi value`.
Each custom category will have a unique `Constant` to identify the Category.
Custom Categories must be [assigned to a Class](link to classes) to be displayed there.
Custom Categories must be [assigned to a Class](../user/basics/classes.md) to be displayed there.

## Single or Multi value Categories

Expand Down
2 changes: 1 addition & 1 deletion docs/dev/addon/frontend.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,4 +117,4 @@ docu.Routing.generate(routeName: string, params: Record<string, any>)
External add-ons can access more internal API then `docu.Routing`.
Furthermore you can also access CMDB data directly from docupike using `docu.Models` without calling add-on specific endpoints.

Please check [JS Interface](/dev/addon/js-api.html) for further information.
Please check [JS Interface](js-api.md) for further information.
115 changes: 55 additions & 60 deletions docs/dev/addon/introduction.md
Original file line number Diff line number Diff line change
@@ -1,76 +1,75 @@
# Introduction

docupike provides an integration interface which allows you to include special features that are
not implemented in docupike by default.
docupike provides an integration interface which allows you to include special features that are not implemented in docupike by default.

Features can be anything and fully depend on the use-case:

* Provide special CMDB structures like collections, classes and categories
* Integrate a third-party application
* Implement heavily UI based workflows to fulfill special tasks and missions
- Provide special CMDB structures like collections, classes and categories
- Integrate a third-party application
- Implement heavily UI based workflows to fulfill special tasks and missions

## What is an add-on?

An add-on is a service that can be registered into docupike in order to extend the application with additional
functions or information. That means any add-on can provide a range of CMDB structures, like
An add-on is a service that can be registered into docupike in order to extend the application with additional functions or information.
That means any add-on can provide a range of CMDB structures, like

- Collections
- Classes
- Categories
- Properties
- Collections
- Classes
- Categories
- Properties

Additionally any add-on can access CMDB-data through our REST-API. It is also possible to implement your own UI in docupike.
Additionally any add-on can access CMDB data through our REST API.
It is also possible to implement your own UI in docupike.

Each docupike add-on is a standalone application which can be registered. The only requirement is that
it is reachable via HTTP(S) and provides a `manifest` file.
Each docupike add-on is a standalone application which can be registered.
The only requirement is that it is reachable via HTTP(S) and provides a `manifest` file.

### Possibilities of an add-on

#### What can an add-on do

An add-on can only interact with docupike through its REST-API. An add-on can implement
a custom frontend in docupike via iframe or integration into the SPA. That means an add-on can, for example,
do the following things:
An add-on can only interact with docupike through its REST API.
An add-on can implement a custom frontend in docupike via iframe or integration into the SPA.
That means an add-on can, for example, do the following things:

- Read/Write/Update/Delete object and category information
- Read/Write/Update/Delete object classes
- Read/Write/Update/Delete classifications
- Implement a custom frontend which will be displayed via iframe or as a part of the SPA
- Read/Write/Update/Delete object and category information
- Read/Write/Update/Delete object classes
- Read/Write/Update/Delete classifications
- Implement a custom frontend which will be displayed via iframe or as a part of the SPA

#### What can an add-on not do

Every docupike add-on is a standalone application which is not necessarily located on the same server. Due to this
strict separation an add-on **can not** modify any docupike files or directly access any code (both front- and backend).
Every docupike add-on is a standalone application which is not necessarily located on the same server.
Due to this strict separation an add-on **can not** modify any docupike files or directly access any code (both front- and backend).
An add-on can thereby not:

- Change the docupike frontend or any HTML, JS or CSS files
- React to internal docupike events
- Extend the docupike REST-API
- Execute docupike (CLI) commands
- Implement custom code or services to the backend
- Change the docupike frontend or any HTML, JS or CSS files
- React to internal docupike events
- Extend the docupike REST-API
- Execute docupike (CLI) commands
- Implement custom code or services to the backend

## Technical add-on architecture

Every docupike add-on is an independent application. The used technology is not limited by docupike, as long as the
application can be reached via HTTP(S) request.
Every docupike add-on is an independent application.
The used technology is not limited by docupike, as long as the application can be reached via HTTP(S) request.

Every add-on application can be viewed as service which will only communicate with docupike via the REST-API. There is
no integration on a filesystem level.
Every add-on application can be viewed as service which will only communicate with docupike via the REST API.
There is no integration on a filesystem level.

Since the add-on is an independent application / service and will only communicate via REST-API with docupike it is technically
possible to use one add-on application for several docupike instances.
Since the add-on is an independent application/service and will only communicate via REST-API with docupike it is technically possible to use one add-on application for several docupike instances.

### Interaction with docupike

Whenever docupike sends a request to the add-on application, it will put specific information like URL, API key and
add-on specific settings into the header. This is done in order to keep the communication stateless.
Whenever docupike sends a request to the add-on application, it will put specific information like URL, API key and add-on specific settings into the header.
This is done in order to keep the communication stateless.

## Structure of an add-on

### Manifest file

Every add-on is required to provide a manifest file. This needs to be a JSON file with some specific data. This file
needs to be accessible to docupike, when the add-on gets registered.
Every add-on is required to provide a manifest file.
This needs to be a JSON file with some specific data. This file needs to be accessible to docupike, when the add-on gets registered.

The manifest file needs be named `addon.json` and has to look like this by default:

Expand All @@ -86,13 +85,13 @@ The manifest file needs be named `addon.json` and has to look like this by defau
}
```

The manifest file needs to be located in the "root" path of the add-on address. For example: when the add-on address is
`127.0.0.1:8000` the manifest file needs to be accessible via `127.0.0.1:8000/addon.json`
The manifest file needs to be located in the "root" path of the add-on address.
For example, when the add-on address is `127.0.0.1:8000` the manifest file needs to be accessible via `127.0.0.1:8000/addon.json`.

#### CMDB structure

The manifest file can be used to implement certain CMDB structures to docupike, when registering and/or updating the
add-on. docupike will keep track of the changes (during update) and synchronize the structure accordingly.
The manifest file can be used to implement certain CMDB structures to docupike, when registering and/or updating the add-on.
docupike will keep track of the changes (during update) and synchronize the structure accordingly.
For this you will need to put a `cmdb` section into your manifest file, like this:

```json
Expand All @@ -110,12 +109,12 @@ For this you will need to put a `cmdb` section into your manifest file, like thi
}
```

Check out [CMDB Structures](/dev/addon/cmdb-structures.html) for further information.
Check out [CMDB Structures](cmdb-structures.md) for further information.

#### Settings

Another important part of the `addon.json` file is the possibility to include add-on specific settings that will be registered into
docupike. These settings (and their values) will then be passed to the add-on via proxy request like the docupike URL and API key.
Another important part of the `addon.json` file is the possibility to include add-on specific settings that will be registered into docupike.
These settings (and their values) will then be passed to the add-on via proxy request like the docupike URL and API key.

Registering settings within the manifest file can look like this:

Expand All @@ -138,33 +137,29 @@ Registering settings within the manifest file can look like this:
}
```

Check out [Settings](/dev/addon/settings.html) for further information.
Check out [Settings](settings.md) for further information.

### Frontend pages

There are two approaches on how to show frontend pages in docupike:

#### Implement a page via SPA

The SPA ("Single Page Application") option can be only used with React. For this approach you will need to register
your components in the manifest file so that docupike can directly access and present them within the docupike UI.
The SPA ("Single Page Application") option can be only used with React.
For this approach you will need to register your components in the manifest file so that docupike can directly access and present them within the docupike UI.

The benefits of this approach are that the React code can make use of docupike internal helpers and interfaces in order to communicate
to our REST-API.
The benefits of this approach are that the React code can make use of docupike internal helpers and interfaces in order to communicate to our REST API.

Check out [Frontend > SPA](/dev/addon/frontend.html#how-to-add-new-frontend-routes) for further information.
Check out [Frontend > SPA](frontend.md#how-to-add-new-frontend-routes) for further information.

#### Implement a page via IFRAME

The IFRAME option can be used if you would like to use your own combination of backend and frontend. In this case
docupike will embed an IFRAME with your add-on application. This solution gives you the most freedom of choice regarding
your technology stack.
The `IFRAME` option can be used if you would like to use your own combination of backend and frontend.
In this case docupike will embed an `IFRAME` with your add-on application.
This solution gives you the most freedom of choice regarding your technology stack.

It does not matter if you use PHP, Python, Node, Java or anything else, as long as your add-on URL responds with a
HTML page that can be displayed inside the docupike frame.
It does not matter if you use PHP, Python, Node, Java or anything else, as long as your add-on URL responds with a HTML page that can be displayed inside the docupike frame.

With this solution you can still communicate to the docupike backend with the help of our REST-API - but you will
need to implement this communication in your own add-on application with the help of the meta data of the proxy request.

Check out [Frontend > SPA](/dev/addon/frontend.html#how-to-add-new-frontend-routes) for further information.
With this solution you can still communicate to the docupike backend with the help of our REST API – but you will need to implement this communication in your own add-on application with the help of the meta data of the proxy request.

Check out [Frontend > SPA](frontend.md#how-to-add-new-frontend-routes) for further information.
2 changes: 1 addition & 1 deletion docs/dev/addon/licensing.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,4 +72,4 @@ Unsufficient license to register add-on.

The same flow also applies to `enable` hook:

![Register/Enable add-ons](/img/dev/addon/licensing-1.png)
![Register/Enable add-ons](../../img/dev/addon/licensing-1.png)
2 changes: 1 addition & 1 deletion docs/ref/version-history.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ lang: en

# Version history

[:material-rss: Subscribe](/releases.atom)
[:material-rss: Subscribe](../releases.atom)

| Version | Date | Release Notes | Changelog |
| ------- | ---------- | ---------------------------------------- | ---------------------------------------- |
Expand Down
16 changes: 8 additions & 8 deletions docs/user/usecases/import-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The way to import existing Data into docupike is to use the CSV Import. Before y

In the object view, you will see the `Import from CSV file` icon in the header menu.

[![Import from CSV file button](/img/screenshots/import-data-via-csv/button-import-csv.png)](/img/screenshots/import-data-via-csv/button-import-csv.png)
[![Import from CSV file button](../../img/screenshots/import-data-via-csv/button-import-csv.png)](../../img/screenshots/import-data-via-csv/button-import-csv.png)

Here we are able to select and upload a valid CSV file. After a successful upload we can continue.

Expand All @@ -23,36 +23,36 @@ Here we are able to select and upload a valid CSV file. After a successful uploa
The second step allows to define if a column header exists in your CSV file. Furthermore, we can specify if our CSV file uses `Semicolon` [;] or `Comma` [,] as separator.
A small preview allows you to review your settings.

[![CSV format](/img/screenshots/import-data-via-csv/csv-format.png)](/img/screenshots/import-data-via-csv/csv-format.png)
[![CSV format](../../img/screenshots/import-data-via-csv/csv-format.png)](../../img/screenshots/import-data-via-csv/csv-format.png)

## Class selection

At the third step we declare the `object class`. Only one class can be selected for each import.

[![Class selection](/img/screenshots/import-data-via-csv/class-selection.png)](/img/screenshots/import-data-via-csv/class-selection.png)
[![Class selection](../../img/screenshots/import-data-via-csv/class-selection.png)](../../img/screenshots/import-data-via-csv/class-selection.png)

## Attribute mapping

During this step each column gets its own row in the mapping. Thus, each row of the CSV file can be linked to an attribute.

[![Attribute mapping](/img/screenshots/import-data-via-csv/attribute-mapping.png)](/img/screenshots/import-data-via-csv/header-mapping.png)
[![Attribute mapping](../../img/screenshots/import-data-via-csv/attribute-mapping.png)](../../img/screenshots/import-data-via-csv/attribute-mapping.png)

After clicking on the `Add` button, the appropriate attribute can selected from the extended dialog menu or its name can be entered directly into the search bar to have suitable attributes suggested.

[![Select a attribute](/img/screenshots/import-data-via-csv/attribute-mapping-title.png)](/img/screenshots/import-data-via-csv/attribute-mapping-title.png)
[![Select a attribute](../../img/screenshots/import-data-via-csv/attribute-mapping-title.png)](../../img/screenshots/import-data-via-csv/attribute-mapping-title.png)

Now you pick the corresponding attribute via the `radio button` and click save to confirm the selection. This way, each column is assigned until all assignments are complete. Assignments can be solved later. Columns without assignment will be ignored during the import.

[![Mapping done](/img/screenshots/import-data-via-csv/attribute-mapping-done.png)](/img/screenshots/import-data-via-csv/attribute-mapping-done.png)
[![Mapping done](../../img/screenshots/import-data-via-csv/attribute-mapping-done.png)](../../img/screenshots/import-data-via-csv/attribute-mapping-done.png)
## Update existing data

Here you can optionally choose if you want to `update` existing objects or only `create new objects`.
We choose `No`.

[![Update data](/img/screenshots/import-data-via-csv/update-data.png)](/img/screenshots/import-data-via-csv/update-data.png)
[![Update data](../../img/screenshots/import-data-via-csv/update-data.png)](../../img/screenshots/import-data-via-csv/update-data.png)

## Preview

The last step displays a `preview` of the import mapping. If everything is in order you can `Start import`. Otherwise you can go back and change the necessary settings.

[![TEXT](/img/screenshots/import-data-via-csv/preview.png)](/img/screenshots/import-data-via-csv/preview.png)
[![TEXT](../../img/screenshots/import-data-via-csv/preview.png)](../../img/screenshots/import-data-via-csv/preview.png)
10 changes: 5 additions & 5 deletions docs/user/usecases/reports.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,21 +11,21 @@ We do that by adding "AND" or "OR" connections.
For this example we are using AND connections.
We want all objects with the class "customer", that have the contract status "active" and the contract end date "earlier than 2024".
So we are going to add those 3 conditions as seen below:
[![TEXT](/img/screenshots/reports/customerconditions.png)](/img/screenshots/reports/customerconditions.png)
[![TEXT](../../img/screenshots/reports/customerconditions.png)](../../img/screenshots/reports/customerconditions.png)

Checking the preview at the bottom, you can see only the name of the customers is being displayed.
To see more than that, you can add the required attributes of the customer.
[![TEXT](/img/screenshots/reports/customerattributes.png)](/img/screenshots/reports/customerattributes.png)
[![TEXT](../../img/screenshots/reports/customerattributes.png)](../../img/screenshots/reports/customerattributes.png)

Now we save the report and open it from the report view.
[![TEXT](/img/screenshots/reports/customerreport.png)](/img/screenshots/reports/customerreport.png)
[![TEXT](../../img/screenshots/reports/customerreport.png)](../../img/screenshots/reports/customerreport.png)

Another example of a report could be the display of server room components like servers, switches, etc.
To do that, we need to add "OR" connections for the classes.
[![TEXT](/img/screenshots/reports/severroomconditions.png)](/img/screenshots/reports/severroomconditions.png)
[![TEXT](../../img/screenshots/reports/severroomconditions.png)](../../img/screenshots/reports/severroomconditions.png)

Next we add the attributes that we want to see from the objects.
[![TEXT](/img/screenshots/reports/serverroomattributes.png)](/img/screenshots/reports/serverroomattributes.png)
[![TEXT](../../img/screenshots/reports/serverroomattributes.png)](../../img/screenshots/reports/serverroomattributes.png)

Now we can display the report from the report view after saving.

Loading

0 comments on commit 54a87eb

Please sign in to comment.