Экспорт и импорт из MS Project

Библиотека dhtmlxGantt поддерживает экспорт данных из диаграммы Gantt в MS Project, а также импорт данных из MS Project в диаграмму Gantt.

Существует несколько сервисов экспорта, которые можно установить локально на ваш компьютер для экспорта диаграмм Gantt в MS Project. Обратите внимание, что эти сервисы экспорта не входят в комплект поставки Gantt. Подробнее об условиях использования каждого сервиса смотрите в соответствующей статье.

Ограничения по времени

Если процесс экспорта занимает больше 20 секунд, он будет прерван, и вы увидите следующую ошибку:

Error: Timeout trigger 20 seconds

Когда несколько пользователей одновременно экспортируют диаграммы Gantt, общая обработка может занять больше времени. Однако для каждого отдельного запроса пользователя отслеживается время отдельно.

Ограничения на размер запроса

Общий API-эндпоинт https://export.dhtmlx.com/gantt обрабатывает все типы экспорта (exportToPDF, exportToPNG, exportToMSProject и др.) с максимальным размером запроса в 10 МБ.

Также существует отдельный API-эндпоинт https://export.dhtmlx.com/gantt/project специально для сервисов экспорта/импорта MSProject и Primavera P6 (exportToMSProject / importFromMSProject / exportToPrimaveraP6 / importFromPrimaveraP6). Этот эндпоинт позволяет отправлять запросы размером до 40 МБ.

Подробнее об использовании модуля экспорта для MS Project.

Компонент Gantt поддерживает экспорт связей, задач и ресурсов в MS Project.

Чтобы экспортировать данные из диаграммы Gantt в MS Project, выполните следующие шаги:

• Включите плагин export_api через метод plugins для использования онлайн-сервиса экспорта:

gantt.plugins({
    export_api: true
});

<script src="codebase/dhtmlxgantt.js"></script>
<script src="https://export.dhtmlx.com/gantt/api.js"></script>

• Используйте метод exportToMSProject для экспорта данных из вашей диаграммы Gantt.

gantt.exportToMSProject();

Этот метод отправляет запрос на удалённый сервис, который либо сгенерирует XML-файл Project, либо предоставит ссылку для его загрузки.

Related sample:  Export data : MS Project, PrimaveraP6, Excel & iCal

Ответ

Ответ содержит JSON-объект следующей структуры:

{
   data: {},
   config: {},
   resources: [],
   worktimes: []
}

• data — объект данных Gantt. Каждая задача содержит свойства, такие как id, open, parent, progress, start_date, text, resource. Даты представлены в формате строки "%Y-%m-%d %H:%i".
• config — объект конфигурации Gantt, содержащий параметры, извлечённые из project-файла.
• resources — массив объектов ресурсов, каждый из которых содержит свойства {id: string, name:string, type:string}, соответствующих ресурсам из project-файла.
• worktimes — массив объектов, используемых для создания новых календарей. Каждый объект календаря может содержать:
  • id — (необязательно) идентификатор календаря
  • hours — (массив) глобальные рабочие часы, определяющие начало и конец задач
  • dates — (массив), который может включать:
    • Семь дней недели (0 = воскресенье, 6 = суббота), где 1/true — рабочий день, 0/false — выходной
    • Конкретные даты

Настройки экспорта

Метод exportToMSProject() принимает необязательный объект с различными параметрами:

• name — (строка) имя экспортируемого файла (по умолчанию 'gantt.xml').

gantt.exportToMSProject({
    name:'custom.xml'
});

• auto_scheduling — (логический) определяет режим планирования для экспортируемых задач. true — задачи автоматически планируются, false — вручную (по умолчанию).

gantt.exportToMSProject({
    auto_scheduling: false
});

• skip_circular_links — (логический) определяет, будут ли удаляться циклические связи (по умолчанию true).

gantt.exportToMSProject({
    skip_circular_links: false
});

• project — (объект) позволяет задать пользовательские свойства для экспортируемого объекта проекта.

gantt.exportToMSProject({
    project: {
        'Author': 'I am!',
        'MinutesPerDay': function () {
            return gantt.config.hours_per_day * 60;
        }
    }
});

Свойства соответствуют свойствам Project. Поддерживаемые свойства перечислены здесь. Значения могут быть как фиксированными, так и функциями, выполняемыми во время экспорта.

• tasks — (объект) позволяет задать пользовательские свойства для экспортируемых задач.

gantt.exportToMSProject({
   tasks: {
       'StartVariance': function (task) {
           if (task.startVariance)
               return task.startVariance;
           else
               return 0;
       },
       'PercentWorkComplete': function (task) {
           return (task.progress + 0.1);
       },
       'Custom': function (task) {
           return 'Custom value';
       },
       'Custom 2': 'My Custom value'
   }
});

Эти свойства соответствуют свойствам Task, поддерживаемые свойства перечислены здесь. Значения могут быть фиксированными или функциями, вызываемыми для каждой задачи при экспорте.

• data — (объект) позволяет предоставить собственный источник данных для экспортируемой диаграммы Gantt.

const customData = {
    "data": [
        { "id": "10", "text": "Project #5", "start_date": "01-04-2025 00:00", 
            "duration": 3, "order": 10, "progress": 0.4, "open": true, 
            "end_date": "04-04-2025 00:00", "parent": 0 
        },
        { "id": "1", "text": "Task #67", "start_date": "02-04-2025 00:00", 
            "duration": 2, "order": 10, "progress": 0.6, "parent": "10", 
            "end_date": "04-04-2025 00:00" 
        },
        { "id": "2", "text": "Task #89", "start_date": "01-04-2025 00:00", 
            "duration": 2, "order": 20, "progress": 0.6, "parent": "10", 
            "end_date": "03-04-2025 00:00" 
        },
    ],
    "links": [
        { "id": 1, "source": 1, "target": 2, "type": "1" },
    ]
}
 
gantt.exportToMSProject({
    data: customData
});

Related sample:  Gantt. Export custom data

• callback — (функция) для получения URL для скачивания сгенерированного XML-файла. В функцию передаётся JSON-объект со свойством url:

gantt.exportToMSProject({
    callback: function(res){
        alert(res.url);
    }
});

• resources — (массив) для добавления списка ресурсов в файл MS Project.

gantt.exportToMSProject({
  resources: [
    {"id":"1","name":"John","type":"work"},
    {"id":"2","name":"Mike","type":"work"},
    {"id":"3","name":"Anna","type":"work"}
  ]
});

Типы ресурсов могут быть "work", "cost" или "material". Назначения ресурсов указываются через свойство ResourceAssignments в конфигурации задач:

var users = [// ресурсы
  {key:'0', label: "N/A"},
  {key:'1', label: "John"},
  {key:'2', label: "Mike"},
  {key:'3', label: "Anna"}
];
 
gantt.exportToMSProject({
  resources: users
     .filter(function(u){
        if(u.key === '0')//пропустить вариант по умолчанию 
           return false;
        return true;
     })
     .map(function(u){
        return {
           id: u.key,
           name: u.label,
           type: "work"
        };
     }),
  tasks: {
     ResourceAssignments: function(task){          return task.user;                       }                                       }
});

Свойство ResourceAssignments — это функция, которая получает объект задачи и возвращает строку/число либо массив строк/чисел:

tasks: {
    ResourceAssignments: function(task){
        return [task.user, task.office];
    }
}

• server — (строка) указывает API-эндпоинт для запроса экспорта. Используется при запуске локального сервиса экспорта. По умолчанию — https://export.dhtmlx.com/gantt.

gantt.exportToMSProject({
   server:"https://myapp.com/myexport/gantt"
});

Чтобы преобразовать XML- или MPP-файл MS Project, отправьте запрос на сервис экспорта со следующими параметрами:

• URL запроса: https://export.dhtmlx.com/gantt
• Метод запроса: POST
• Content-Type: multipart/form-data

Параметры запроса:

• file — MPP или XML-файл MS Project
• type — "msproject-parse"
• data — (необязательно) JSON-строка с настройками

Пример формы:

<form action="https://export.dhtmlx.com/gantt" method="POST" 
    enctype="multipart/form-data">
    <input type="file" name="file" />
    <input type="hidden" name="type" value="msproject-parse">
    <button type="submit">Get</button>
</form>

Альтернативно вы можете использовать клиентский API, как показано ниже:

gantt.importFromMSProject({
    data: file,
    taskProperties: ["Notes", "Name"],
    callback: function (project) {
        if (project) {
            gantt.clearAll();
            if (project.config.duration_unit) {
                gantt.config.duration_unit = project.config.duration_unit;
            }                    
            gantt.parse(project.data);
        }
     }
});

Здесь file должен быть экземпляром File, содержащим XML или MPP-файл Project.

Ответ

Ответ будет содержать JSON следующей структуры:

{
   data: {},
   config: {},
   resources: [],
   worktime: {}
}

• data — объект данных Gantt. Каждая задача содержит свойства: id, open, parent, progress, start_date, text, resource. Даты представлены строкой в формате "%Y-%m-%d %H:%i".
• config — объект конфигурации Gantt, содержащий параметры, извлечённые из project-файла.
• resources — массив объектов, каждый из которых содержит свойства {id:string, name:string, type:string}, соответствующие ресурсам из project-файла.
• worktime — объект с настройками рабочего времени, взятыми из календаря проекта.

Настройки импорта

Установка единицы измерения длительности

Чтобы указать ожидаемую единицу измерения длительности, в отправляемых на сервер данных можно добавить строку durationUnit ("minute", "hour", "day", "week", "month", "year").

<form action="https://export.dhtmlx.com/gantt" method="POST" 
    enctype="multipart/form-data">
    <input type="file" name="file" />
    <input type="hidden" name="type" value="msproject-parse">
    <input type="hidden" name="data" 
        value="{ \"durationUnit\": \"hour\" }" />
    <button type="submit">Get</button>
</form>

или

gantt.importFromMSProject({
    data: file,
    durationUnit: "hour",
    callback: function(project){}
});

Получение свойств проекта

Чтобы получить поля проекта, в параметре projectProperties можно указать массив нужных полей, который будет отправлен на сервер. Это позволит получить произвольные свойства Project entity в свойство config ответа. Доступные свойства перечислены в документации.

• projectProperties – определяет массив свойств проекта, которые будут включены в ответ.

<form action="https://export.dhtmlx.com/gantt" method="POST" 
    enctype="multipart/form-data">
    <input type="file" name="file" />
    <input type="hidden" name="type" value="msproject-parse">
    <input type="hidden" name="data" 
        value="{ \"projectProperties\": [\"Author\", \"Title\"] }" />
    <button type="submit">Get</button>
</form>

или

gantt.importFromMSProject({
    data: file,
    durationUnit: "hour",
    projectProperties: ["Author", "Title"],
    callback: function(project){
        var config = project.config;
        alert(config.$custom_properties.Author);
    }
});

Получение свойств задач

Чтобы получить поля задач, в параметре taskProperties можно указать массив нужных полей, который будет отправлен на сервер. Это позволяет получить произвольные свойства Task entities. Доступные свойства перечислены в документации.

• taskProperties – определяет массив дополнительных свойств задач для импорта.

<form action="https://export.dhtmlx.com/gantt" method="POST" 
    enctype="multipart/form-data">
    <input type="file" name="file" />
    <input type="hidden" name="type" value="msproject-parse">
    <input type="hidden" name="data" 
        value="{ \"taskProperties\": [\"Contact\", \"Priority\"] }" />
    <button type="submit">Get</button>
</form>

или

gantt.importFromMSProject({
    data: file,
    durationUnit: "hour",
    taskProperties: ["Contact", "Priority"],
    callback: function(project){
        var config = project.config;
        alert(config.$custom_properties.Author);
        gantt.parse(project.data);
    }
});
gantt.attachEvent("onTaskLoading", function(task) {
    if (task.$custom_data) {
        task.contact = task.$custom_data["Contact"];
        task.priority = task.$custom_data["priority"];
        delete task.$custom_data;
    }
    return true;
});

Получение типов задач

Этот способ позволяет определить тип задачи: задачи с пометкой Project имеют свойство Summary: "1", а задачи с пометкой Milestone — свойство Milestone: "1". Импортируя эти свойства, можно соответствующим образом задать тип задачи.

Вызов импорта выглядит так:

gantt.importFromMSProject({
        data: file,
        taskProperties: [
            "Summary",
            "Milestone",
        ],
        callback: function (project) {
            if (project) {
                console.log(project)
                gantt.clearAll();
                if (project.config.duration_unit) {
                    gantt.config.duration_unit = project.config.duration_unit;
                }
                console.log('import: ', project.data);
                gantt.parse(project.data);
            }
        }
    });

Далее типы задач можно скорректировать на основе этих свойств следующим образом:

gantt.attachEvent("onTaskLoading", function (task) {
    if (task.$custom_data) {
        if (task.$custom_data.Summary == "1") {
            task.type = "project";
        }
        if (task.$custom_data.Milestone == "1") {
            task.type = "milestone";
        }
        // delete task.$custom_data;
    }
    return true;
});

Related sample:  Gantt. Import MSP files. Get task type from properties

Существует два конечных API-адреса для сервисов экспорта/импорта MSProject:

• https://export.dhtmlx.com/gantt – основной адрес, обрабатывающий все методы экспорта (exportToPDF, exportToPNG, exportToMSProject, и др.). Максимальный размер запроса — 10 МБ.
• https://export.dhtmlx.com/gantt/project – адрес, предназначенный для сервисов экспорта/импорта MSProject и Primavera P6 (exportToMSProject, importFromMSProject, exportToPrimaveraP6, importFromPrimaveraP6). Максимальный размер запроса: 40 МБ.

Конечный адрес можно указать через свойство server в объекте конфигурации экспорта:

gantt.importFromMSProject({
    server:"https://export.dhtmlx.com/gantt",
    data: file,
    callback: function(project){
       // some logic
    }
});

Если конечный адрес не указан, по умолчанию используется https://export.dhtmlx.com/gantt. Следующий вызов эквивалентен:

gantt.importFromMSProject({
    data: file,
    callback: function(project){
       // some logic
    }
});

Для экспорта или импорта больших проектов, превышающих лимит в 4 МБ, используйте второй адрес:

gantt.importFromMSProject({
    server:"https://export.dhtmlx.com/gantt/project",
    data: file,
    callback: function(project){
       // some logic
    }
});

Этот адрес поддерживает запросы до 40 МБ и предназначен для экспорта и импорта MS Project. Он может использоваться только для экспорта MS Project.

Использование других методов, например gantt.exportToPDF({server:"https://export.dhtmlx.com/gantt/project"}), приведет к ошибке сервера.

Существуют ключевые различия в том, как dhtmlxGantt и MS Project рассчитывают даты, что иногда может приводить к разным результатам.

Эти различия зависят от используемых настроек gantt. Некоторые параметры gantt влияют на результаты вычислений:

1. Преобразование длительности отличается между dhtmlxGantt и MS Project.

Это можно скорректировать, указав HoursPerDay и MinutesPerDay при экспорте в MS Project:

gantt.exportToMSProject({
    project: {
        HoursPerDay: function () {
            return 24;
        },
        MinutesPerDay: function () {
            return 24 * 60;
        }
    }
});

Related sample:  Export to MSProject without the "work_time" settings

2. В проекте может быть отключена настройка work_time:

gantt.config.work_time = false;

Обратите внимание, что даже при отключенных расчетах рабочего времени gantt по-прежнему использует настройки календаря по умолчанию (8 часов в день, рабочая неделя — с понедельника по пятницу). Клиент экспорта всегда отправляет этот календарь MS Project, в результате чего MS Project рассчитывает длительность задач иначе.

В качестве обходного решения можно очистить календарь по умолчанию, чтобы длительности задач рассчитывались одинаково в gantt и MS Project:

gantt.setWorkTime({day:0, hours:[0,24]});
gantt.setWorkTime({day:1, hours:[0,24]});
gantt.setWorkTime({day:2, hours:[0,24]});
gantt.setWorkTime({day:3, hours:[0,24]});
gantt.setWorkTime({day:4, hours:[0,24]});
gantt.setWorkTime({day:5, hours:[0,24]});
gantt.setWorkTime({day:6, hours:[0,24]});

3. Вы можете заметить различия в датах сводных элементов, если gantt.config.duration_unit установлен в "day":

gantt.config.duration_unit = "day";

В этом случае gantt округляет длительности до целых дней, а MS Project показывает дробные значения. Например, длительность проекта может быть 439 дней в gantt, но 438.58 в MS Project.

Решение — переключить duration_unit на часы:

gantt.config.duration_unit = "hour";

Related sample:  Export to MSProject without the "work_time" settings