Skip to content
Snippets Groups Projects
Select Git revision
  • main default protected
1 result
History
Forked from an inaccessible project.
frischler's avatar
Wrapping up the last makros where it was not yet clear how to handle them.
frischler authored
c870ed36
Name Last commit Last update
.gitignore
README.md
config.py
main.py
makro_handlers.py
page_mapper.py
print_report.py
x_wiki_api.py
README.md

XWiki Makro Migration Tools

The XWiki Makro Migration Tools are scripts to help migrate the outstanding makros. With these tools you can

  • list pages and what makros they have,
  • list makros and their occurences,
  • list all variations of makros,
  • overwrite page contents to get rid of trouble-causing makros, or to refactor them.

The tools are using the XWiki REST API.

Prerequisites

The script requires Python 3 as well as the python libraries lxml and beautifulsoup4:

pip install lxml beautifulsoup4

Usage

main.py is the script to use.

Show usage:

python main.py

Show a report of all makros, in which pages they occur, etc.:

python main.py report

Do a dry run migration of a makro. Suggested to do that before doing an actual migration:

# in this example the 'protokoll' and 'layout' makro.
python main.py migrate-dry-run protokoll layout

Migrate a makro:

# in this example the 'protokoll' and 'layout' makro.
python main.py migrate protokoll layout

Do a dry run migration of a makro. Suggested to do that before doing an actual migration: # in this example the 'protokoll' and 'layout' makro. python main.py migrate-dry-run protokoll layout

Migrate a makro: # in this example the 'protokoll' and 'layout' makro. python main.py migrate protokoll layout"""

How makros are being treaded

725x mention

already worked with initial migration.

370x layout-cell

Will be removed. See layout.

290x layout-section

Will be removed. See layout.

208x protokoll

Transform to a table. So this

{{protokoll Desc="Plenum" LstMembers="XWiki.lambda,XWiki.neonet" NumMembers="7" Date="09.10.2018" Writer="XWiki.againstreality" atlassian-macro-output-type="INLINE"}}

becomes

Protokoll:
|Anwesende (ehem. LstMembers)|{{mention reference="XWiki.lambda" style="FULL_NAME"/}}{{mention reference="XWiki.neonet" style="FULL_NAME"/}}
|Anwesend|7
|Beschreibung|Plenum
|Datum|09.10.2018
|Protokollant|{{mention reference="XWiki.againstreality" style="FULL_NAME"/}}

177x task

See task-list

135x code

already worked with initial migration.

95x view-file

Replace with a simple link to the attachement: [[attach:<file name>]]. We mostly used this makro for PDFs. And the pdf makro is only for XWiki Pro. So we don't loose much.

92x layout

XWiki does not have layouting such as Confluence has with its sections. There might be some plugin, but they don't seem heavily used. Because of that, and because most of the pages using layouts are not heavily utilizing on them, the layout makros are removed.

77x task-list

Replace task and task-list with todo, combined with ul lists to keep task hierachy. Meaning the following ...

{{task-list}}
    {{task id="1" status="incomplete"}}
        Umstellung mit Krea absprechen
        {{task-list}}
            {{task id="14" status="complete"}}
                (Krea hat jetzt einen eigenen Server.)
            {{/task}}
        {{/task-list}}
    {{/task}}
{{/task-list}}

... becomes this ...

* {{todo status="open"}}
    Umstellung mit Krea absprechen
  {{/todo}}
** {{todo status="resolved"}}
     (Krea hat jetzt einen eigenen Server.)
   {{/todo}}

50x expand

🖐️ Should be covered by hand. (Done) Since there is no equivalent makro, expand will be removed. This needs to be done by hand because the headings inside this makro don't yet fit with the overall headings hierachy. The pages affected are:

44x info

already worked with initial migration.

37x children

already worked with initial migration.

37x inventar

Transform to a table. So this

{{inventar Desc="Labornetzteil" Liable="XWiki.lambda,XWiki.neonet" Position="Büro" Bought="2018" Image="Labornetzteil.jpg" Name="PeakTech 6040A" atlassian-macro-output-type="INLINE"}}

becomes

Inventar 'PeakTech 6040A':
|Beschreibung|Labornetzteil
|Bild|[[image:Labornetzteil.jpg]]
|Verantwortlich|{{mention reference="XWiki.lambda" style="FULL_NAME"/}}{{mention reference="XWiki.neonet" style="FULL_NAME"/}}
|Wann gekauft|2018
|Wo|Büro

32x note

note becomes info.

31x toc

already worked with initial migration.

31x velocity

already worked with initial migration.

19x example

already worked with initial migration.

17x vortrag < next migration from here

{{vortrag SpeakersPlain="ridcully, Maze" Title="GSM/WLAN-Sicherheit, Google, Datenerfassung/~~schutz" Host="Anwaltsverein Frankfurt am Main e.V." Speakers="XWiki.kventil" Date="09.06.2010" Place="Frankfurt/Main" atlassian-macro-output-type="INLINE"}}

becomes

Vortrag 'GSM/WLAN-Sicherheit, Google, Datenerfassung/~~schutz':

|Datum|09.06.2010
|Host|Anwaltsverein Frankfurt am Main e.V.
|Ort|Frankfurt/Main
|Vortragende|{{mention reference="XWiki.kventil" style="FULL_NAME"/}}
|Vortragende (SpeakersPlain)|ridcully, Maze

14x confluence_attachments

Replace with the attachementGalleryPicker makro. Unfortunately, all attributes of the original makro will be removed, since there doesn't exist equivalent attributes in the new makro. These attributes are: 'patterns', 'sortBy', 'sortOrder', 'upload'. Because of them being removed, some attachement lists might show different content than they did before. An example of that is the Patchfelder / Portbelegung page – the only page utilizing the 'patterns' attribute.

11x panel

panel becomes info.

11x tip

tip becomes info.

11x confluence_gallery

Replace with the gallery makro. Unfortunately, all attributes of the original makro will be removed, since there doesn't exist equivalent attributes in the new makro. These attributes are: 'columns', 'exclude', 'reverse', 'sort', 'title'. Technically, we could use velocity scripting makros to add these functionality by Javascript, but that

  • requires the admin team to allow you to add and alter scripting makros, or
  • requires the original authors of the affected pages to allow you to add and alter scripting makros, which both
  • would make other users to have the same problems as you have when altering the scripts again.

Given the few pages that are actually affected, it's more trouble than it's worth.

8x warning

already worked with initial migration.

8x contentbylabel

Will be removed, since we have no proper replacement for it.

8x include

Removed. No idea what it did anyway.

7x widget

{{widget url="http://www.youtube.com/watch?v=3V1PwpoDqzM&feature=related"/}} becomes [[http:~~/~~/www.youtube.com/watch?v=3V1PwpoDqzM&amp;feature=related&gt;&gt;http://www.youtube.com/watch?v=3V1PwpoDqzM&amp;feature=related]]

7x box

already worked with initial migration.

6x drawio

{{drawio border="true" viewerToolbar="true" fitWindow="false" diagramName="Partitionierung neuer Host" revision="2"/}} becomes [[image:Partitionierung neuer Host.png]]

6x recently-updated

Will be removed, since we have no proper replacement for it.

6x contributors

Will be removed, since we have no proper replacement for it.

6x time

{{time datetime="2021-02-01"/}} becomes 2021-02-01

6x html

already worked with initial migration.

4x success

already worked with initial migration.

4x chart

already worked with initial migration.

4x documentTree

already worked with initial migration.

3x viewpdf

Replace with a simple link to the attachement: [[attach:<file name>]]. See view-file.

3x create-from-template

Will be removed, since we have no proper replacement for it.

3x content-report-table

Will be removed, since we have no proper replacement for it.

3x displayIcon

already worked with initial migration.

3x section

Will be removed, since they are not really used for anything except for adding a border to a section.

2x asset

🖐️ should be handled by hand. (Done) Formatting looks quirky. Adjusting these two by hand is way faster.

2x userlister

Will be removed, since we have no proper replacement for it.

2x notifications

already worked with initial migration.

2x excerpt-include

🖐️ should be handled by hand. Is entangled with excerpt. (Done) This makro was for including parts of one page into another. Due to the rare usage, this was removed. A link to the other page is enough.

2x excerpt

🖐️ should be handled byhand. Is entangled with excerpt-include. (Done) This makro was for including parts of one page into another. Due to the rare usage, this was removed. A link to the other page is enough.

2x cheese

Will be replaced with a 🧀.

2x multimedia

🖐️ should be handled by hand. (Done) Just made attach out of them.

1x popular-labels

Will be removed, since we have no proper replacement for it.

1x activity

already worked with initial migration.

1x diagram

already worked with initial migration.

1x tasks-report-macro

Will be removed, since we have no proper replacement for it.

1x pagetreesearch

Will be removed, since we have no proper replacement for it.

1x error

already worked with initial migration.

1x gallery

already worked with initial migration.

1x livesearch

Will be removed, since we have no proper replacement for it.

1x status

🖐️ should be handled by hand. (Done) Changed to info makro.

1x translation

❔ ... cannot even change that page.

Some technical/nice-to-know stuff

Caching

The script caches all pages contents (excluding attachments and images). Therefore, running the script multiple times will not cause more traffic. When you overwrite a pages content, the cache will be overwritten, too.

Overwriting a pages content

The following code snipped shows how you could overwrite a pages content:

api = CachedXWikiApi(Config())

username = input("Enter your username: ")
password = getpass.getpass("Enter your password: ")

api.login(username, password)

# getting the page for a specific REST url.
xml = api.get_page_xml("https://wiki.cccwi.de/xwiki/rest/wikis/xwiki/spaces/testseite123/pages/WebHome")
page: Page = page_mapper.map_to_page(page_rest_url, xml))

# adding something to the content.
new_content = page.content + " and more text."

# writing the new content.
api.write_page_content(page.rest_url, new_content)

Example output of the current main script:

found cache for https://wiki.cccwi.de/xwiki/rest/wikis/xwiki/spaces
found cache for https://wiki.cccwi.de/xwiki/rest/wikis/xwiki/spaces/Administration/pages/WebHome
found cache for https://wiki.cccwi.de/xwiki/rest/wikis/xwiki/spaces/Administration/spaces/Accounts/pages/WebHome
...
following makros where found per page:
    id: xwiki:Administration.WebHome
    rest_url: https://wiki.cccwi.de/xwiki/rest/wikis/xwiki/spaces/Administration/pages/WebHome
    web_url: https://wiki.cccwi.de/xwiki/bin/view/Administration/
    makros: ['activity', 'children', 'popular-labels']

    id: xwiki:Administration.Accounts.WebHome
    rest_url: https://wiki.cccwi.de/xwiki/rest/wikis/xwiki/spaces/Administration/spaces/Accounts/pages/WebHome
    web_url: https://wiki.cccwi.de/xwiki/bin/view/Administration/Accounts/
    makros: ['mention']

    id: xwiki:Administration.Admin-Doku (war\: Dokumentation).WebHome
    rest_url: https://wiki.cccwi.de/xwiki/rest/wikis/xwiki/spaces/Administration/spaces/Admin-Doku%20(war:%20Dokumentation)/pages/WebHome
    web_url: https://wiki.cccwi.de/xwiki/bin/view/Administration/Admin-Doku%20%28war%3A%20Dokumentation%29/
    makros: ['children', 'layout-cell', 'layout-section', 'note']
...
all found makros:
    723x mention
    370x layout-cell
    290x layout-section
...
all makro variations:
    makro 'children'
		found attributes: ['all', 'sort', 'reverse']
        {{children all="true" sort="title" reverse="true"/}}
        {{children all="true"/}}
        {{children all="true" style="h3" sort="title" reverse="true"/}}

    makro 'popular-labels'
		found attributes: ['count']
        {{popular-labels count="10"/}}

    makro 'activity':
		found attributes: ['spaces']
        {{activity spaces="Administration"/}}
...
...