Documents

Documents and their history can be imported. There are still limitations though. Here are the list of unsupported features:

  • Export/import metadata in project

  • Export/import item’s metadata

  • Export/import wiki documents

  • Export/import link versions

  • Export/import approval tables

  • Export/import locked document

Basic XML syntax

<project>
  <services>
    <service shortname="plugin_docman" enabled="true" />
    ...
  </services>

  ...

  <docman>
    <item type="folder">
      <properties>
        <title><![CDATA[Project Documentation]]></title>
      </properties>
      <item type="folder">
        <properties>
          <title><![CDATA[My subfolder]]></title>
        </properties>
        <item type="embeddedfile">
          <properties>
            <title><![CDATA[My embedded file]]></title>
          </properties>
          <versions>
            <version>
              <filename><![CDATA[file]]></filename>
              <filetype><![CDATA[text/html]]></filetype>
              <filesize><![CDATA[11]]></filesize>
              <content><![CDATA[documents/content-213.bin]]></content>
            </version>
          </versions>
        </item>
        <item type="empty">
          <properties>
            <title><![CDATA[My empty document]]></title>
          </properties>
        </item>
        <item type="link">
          <properties>
            <title><![CDATA[My link]]></title>
          </properties>
          <url><![CDATA[https://tuleap.org]]></url>
        </item>
        <item type="file">
          <properties>
            <title><![CDATA[My file]]></title>
          </properties>
          <versions>
            <version>
              <filename><![CDATA[button.gif]]></filename>
              <filetype><![CDATA[image/gif]]></filetype>
              <filesize><![CDATA[1312544]]></filesize>
              <content><![CDATA[documents/content-212.bin]]></content>
            </version>
            <version>
              <filename><![CDATA[button-v2.png]]></filename>
              <filetype><![CDATA[image/png]]></filetype>
              <filesize><![CDATA[799789]]></filesize>
              <content><![CDATA[documents/content-214.bin]]></content>
            </version>
          </versions>
        </item>
      </item>
    </item>
  </docman>

Note:

  • the item <docman> must contain only one element: a folder item (the root folder).

  • Files (and embedded files) versions have a tag <content> which reference a file located in the archive.

  • unless specified (see below) the owner of items will be the current user who is importing the project.

  • unless specified (see below) the creation/update date of items will be the date of import.

  • unless specified (see below) the permissions of items will inherit from the parent.

Description

The optional description can be specified in the properties of the item:

1
2
3
4
5
6
<item type="…">
  <properties>
    <title>…</title>
    <description><![CDATA[Lorem ipsum description]]></description>
  </properties>
</item>

Dates

You can specify the original creation date and update date in the properties of the item:

1
2
3
4
5
6
7
<item type="…">
  <properties>
    <title>…</title>
    <create_date format="ISO8601"><![CDATA[2018-03-10T10:38:55+01:00]]></create_date>
    <update_date format="ISO8601"><![CDATA[2020-02-18T11:30:03+01:00]]></update_date>
  </properties>
</item>

You can also specify the creation date of a specific version of a file or embedded file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<item type="file">
  <properties>
    <title>…</title>
  </properties>
  <versions>
    <version>
      <filename><![CDATA[button.gif]]></filename>
      <filetype><![CDATA[image/gif]]></filetype>
      <filesize><![CDATA[1312544]]></filesize>
      <date format="ISO8601"><![CDATA[2020-02-13T14:32:37+01:00]]></date>
      <content><![CDATA[documents/content-212.bin]]></content>
    </version>
    <version>
      <filename><![CDATA[button-v2.png]]></filename>
      <filetype><![CDATA[image/png]]></filetype>
      <filesize><![CDATA[799789]]></filesize>
      <date format="ISO8601"><![CDATA[2020-02-13T14:59:55+01:00]]></date>
      <content><![CDATA[documents/content-214.bin]]></content>
    </version>
  </versions>
</item>

Users

The owner of the item can be specified in its properties:

1
2
3
4
5
6
<item type="…">
  <properties>
    <title>…</title>
    <owner format="ldap">102</owner>
  </properties>
</item>

The author of a version can also be specified:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<item type="file">
  <properties>
    <title>…</title>
  </properties>
  <versions>
    <version>
      <filename><![CDATA[button.gif]]></filename>
      <filetype><![CDATA[image/gif]]></filetype>
      <filesize><![CDATA[1312544]]></filesize>
      <author format="ldap">102</author>
      <content><![CDATA[documents/content-212.bin]]></content>
    </version>
    <version>
      <filename><![CDATA[button-v2.png]]></filename>
      <filetype><![CDATA[image/png]]></filetype>
      <filesize><![CDATA[799789]]></filesize>
      <author format="ldap">102</author>
      <content><![CDATA[documents/content-214.bin]]></content>
    </version>
  </versions>
</item>

Note

See Users management for more details of user format.

Labels & Changelog

The label or changelog of an item version can be specified:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
<item type="file">
  <properties>
    <title>…</title>
  </properties>
  <versions>
    <version>
      <filename><![CDATA[button.gif]]></filename>
      <filetype><![CDATA[image/gif]]></filetype>
      <filesize><![CDATA[1312544]]></filesize>
      <label><![CDATA[The label]]></label>
      <content><![CDATA[documents/content-212.bin]]></content>
    </version>
    <version>
      <filename><![CDATA[button-v2.png]]></filename>
      <filetype><![CDATA[image/png]]></filetype>
      <filesize><![CDATA[799789]]></filesize>
      <label><![CDATA[Another label]]></label>
      <label><![CDATA[A changelog]]></label>
      <content><![CDATA[documents/content-214.bin]]></content>
    </version>
  </versions>
</item>

Permissions

Each item can define its permissions read, write, and manage.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<item type="…">
  <properties>
    <title>…</title>
  </properties>
  <permissions>
    <permission type="PLUGIN_DOCMAN_READ" ugroup="UGROUP_REGISTERED"/>
    <permission type="PLUGIN_DOCMAN_WRITE" ugroup="UGROUP_PROJECT_ADMIN"/>
    <permission type="PLUGIN_DOCMAN_WRITE" ugroup="Developers"/>
  </permissions>
</item>