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<item type="…">
2  <properties>
3    <title>…</title>
4    <description><![CDATA[Lorem ipsum description]]></description>
5  </properties>
6</item>

Dates

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

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

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

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

Users

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

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

The author of a version can also be specified:

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

Permissions

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

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