НАЧАЛО РАБОТЫ С API

Для начала работы с PLAN-R API:

• уточните у Вашего системного администратора URL адрес, по которому развернут сервис системы, который предоставляет API, обычно https://your-org.domain/public-api/;
• узнайте уникальный идентификатор пространства, с которым Вы будете взаимодействовать;
• создайте токен доступа;

Проверка доступности сервиса API

Выполните проверку сетевого адреса, на котором расположен API.

$ ping your-org.domain

Pinging your-org.domain [10.10.21.99] with 32 bytes of data:
Reply from 10.10.21.99: bytes=32 time=15ms TTL=57
Reply from 10.10.21.99: bytes=32 time=15ms TTL=57
Reply from 10.10.21.99: bytes=32 time=15ms TTL=57
Reply from 10.10.21.99: bytes=32 time=15ms TTL=57

Ping statistics for 10.10.21.99:
    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 15ms, Maximum = 15ms, Average = 15ms

Выполните проверку URL на котором расположен API.

$ curl https://your-org.domain/public-api/

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                Dload  Upload  Total   Spent    Left  Speed
100   158    0   158    0     0   2166      0 --:--:-- --:--:-- --:--:--  2225

{
    "error":
        {
            "message":"Token isn't exists",
            "details":"Please check that exist Authorization token fo your request",
            "instance":"/public-api/ http method - GET"
        }
}

Получим Ваши первые данные

curl -X 'GET' \
  'https://your-org.domain/public-api/eps' \
  -H 'Authorization: your-api-key' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'x-tenant-id: cc8b0762-f600-4e59-9d0c-190b69113da0'

[
  {
    "id": "cc8b0762-f600-4e59-9d0c-190b69113da0",
    "name": "Your Organization Space Name,
    "parentId": null,
    "sortOrder": null,
    "type": "space",
    "createdBy": null,
    "createdAt": "2024-06-21T15:24:01.758297"
  }
]

Работа со структурой проектов предприятия

Предположим, что Ваше пространство только что создано и в нем нет никаких данных. Получим первоначальное состояние СПП.

curl -X 'GET' \
  'https://your-org.domain/public-api/eps' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

В ответе получим список узлов, содержащихся в СПП, т.к. первоначально ничего кроме пространства не существует, в списке будет только один узел с типом space.

[
  {
    "id": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
    "name": "Ваше предприятие",
    "parentId": null,
    "sortOrder": 0,
    "type": "space",
    "createdBy": "0efee9db-a3ff-4d89-b560-dc000b1eb246",
    "createdAt": "2024-02-27T11:04:25.635368"
  }
]

Структура проектов предприятия в Web клиенте

Давайте создадим в нем структуру Вашего предприятия. Для этого добавим первую группу проектов, указав в качестве родителя существующее пространство. Тип создаваемого узла укажем facility.

curl -X 'POST' \
  'https://your-org.domain/public-api/eps' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "type": "facility",
  "name": "Малоэтажное строительство",
  "parentId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad"
}'

Создадим еще одну группу проектов.

curl -X 'POST' \
  'https://your-org.domain/public-api/eps' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "type": "facility",
  "name": "Строительство промышленных зданий",
  "parentId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad"
}'

Получим новое состояние СПП

curl -X 'GET' \
  'https://your-org.domain/public-api/eps' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

[
  {
    "id": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
    "name": "Ваше предприятие",
    "parentId": null,
    "sortOrder": 0,
    "type": "space",
    "createdBy": "0efee9db-a3ff-4d89-b560-dc000b1eb246",
    "createdAt": "2024-02-27T11:04:25.635368"
  },
  {
    "id": "b60f984c-0088-4d57-992b-853e0fbcbf5e",
    "name": "Строительство промышленных зданий",
    "parentId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
    "sortOrder": 1,
    "type": "facility",
    "createdBy": "0efee9db-a3ff-4d89-b560-dc000b1eb246",
    "createdAt": "2024-06-27T12:22:47.195"
  },
  {
    "id": "df11cea2-effa-419a-bd5f-cd6ce3985fd9",
    "name": "Малоэтажное строительство",
    "parentId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
    "sortOrder": 0,
    "type": "facility",
    "createdBy": "0efee9db-a3ff-4d89-b560-dc000b1eb246",
    "createdAt": "2024-06-27T12:22:33.603"
  }
]

Примечание - структура СПП заполняется согласно модели данных PLAN-R (См. Модель данных)

Структура проектов предприятия в Web клиенте после создания групп проектов

После создания групп проектов добавим в СПП проекты и графики.

curl -X 'POST' \
  'https://your-org.domain/public-api/eps' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "type": "project",
  "name": "Возведение складского комплекса",
  "parentId": "d39ed93d-c3b0-4111-92f4-d489692f4fe4"
}'

{
  "id": "e1a12c3f-0d88-49ed-aab9-fe83f61cdeef",
  "name": "Возведение складского комплекса",
  "parentId": "b60f984c-0088-4d57-992b-853e0fbcbf5e",
  "sortOrder": 0,
  "type": "project",
  "createdBy": "0efee9db-a3ff-4d89-b560-dc000b1eb246",
  "createdAt": "2024-06-27T12:36:56.511"
}

curl -X 'POST' \
  'https://your-org.domain/public-api/eps' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "type": "schedule",
  "name": "График поставки материалов",
  "parentId": "e1a12c3f-0d88-49ed-aab9-fe83f61cdeef"
}'

{
  "id": "54faa898-fbdc-43fe-80e6-3811c2955ffe",
  "name": "График поставки",
  "parentId": "923a4075-6de8-4a1c-a5ee-070604dac07e",
  "sortOrder": 0,
  "type": "schedule",
  "createdBy": "0efee9db-a3ff-4d89-b560-dc000b1eb246",
  "createdAt": "2024-06-27T12:40:36.961"
}

Структура проектов предприятия в Web клиенте после создания проектов и графиков

Сменим название графика на «График строительства»

curl -X 'PUT' \
  'https://your-org.domain/public-api/eps/54faa898-fbdc-43fe-80e6-3811c2955ffe' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "name": "График строительства",
}'

Добавим в график новую версию графика

curl -X 'POST' \
  'https://your-org.domain/public-api/eps' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "type": "version",
  "name": "Актуальная",
  "parentId": "54faa898-fbdc-43fe-80e6-3811c2955ffe"
}'

{
  "id": "9fc1c418-1a9a-48e6-9395-791e0ebd3b99",
  "name": "Актуальная",
  "parentId": "36b60d7c-fba9-4fb6-8d5a-a054f2043827",
  "sortOrder": 0,
  "type": "version",
  "createdBy": "0efee9db-a3ff-4d89-b560-dc000b1eb246",
  "createdAt": "2024-06-27T13:11:03.533"
}

Структура проектов предприятия в Web клиенте после создания проектов, графиков и версий графиков

Работа с атрибутами иерархической структуры работ

Для хранения информации о параметрах работ в ИСР в системе PLAN-R используются атрибуты иерархической структуры работ. Атрибуты привязаны к определенному узлу СПП и наследуются на все нижележащие узлы в иерархии т.е. атрибут, созданный на каком либо проекте, будет доступен на всех графиках этого проекта.

Существует два вида атрибутов:

• Системные - атрибуты изначально присутствующие в системе и привязанные к пространству;
• Пользовательские - атрибуты, создаваемые пользователем, могут быть привязаны к группам проектов, проектам, графикам;

Примечание - типы и назначения атрибутов описаны в документе Модель данных.

Давайте получим список атрибутов для нашего пространства, для этого укажем параметр epsId равным идентификатору пространства.

curl -X 'GET' \
  'https://your-org.domain/public-api/wbs-attributes?epsId=5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

В ответе получим список атрибутов

[
  {
    "id": "0cc9baf7-229b-452d-bc35-40abcf6d57d2",
    "epsId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
    "label": "Шифр",
    "type": "string",
    "directoryId": null,
    "directoryAttributeId": null
  },
  {
    "id": "12519af0-a0d7-4a6b-b9db-3cb40f9df880",
    "epsId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
    "label": "Прогресс",
    "type": "number",
    "directoryId": null,
    "directoryAttributeId": null
  },

  ..........

]

Создадим на пространстве новый пользовательский атрибут типа date. Этот атрибут будет доступен на всех нижележащих узлах СПП.

curl -X 'POST' \
  'https://your-org.domain/public-api/wbs-attributes' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "epsId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
  "label": "Дата выпуска документации",
  "type": "date",
}'

Работа с иерархической структурой работ

Получим иерархическую структуру работ для версии графика.

curl -X 'GET' \
  'https://your-org.domain/public-api/wbs?epsId=bc1da5df-d644-461a-aa54-e60182195898' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

Нам вернется пустой список т.к. мы еще не добавили ни одной работы в версию график.

[]

Для того чтобы создать наши первые работы в ИСР, требуется получить уникальные идентификаторы аттрибутов «Шифр», «Наименование»,«Старт» и «Финиш» для нашей версии графика.

curl -X 'GET' \
  'https://your-org.domain/public-api/wbs-attributes?epsId=bc1da5df-d644-461a-aa54-e60182195898&filter=label in ('Шифр', 'Старт', 'Финиш', 'Наименование')' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

[
    {
        "id": "0cc9baf7-229b-452d-bc35-40abcf6d57d2",
        "epsId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
        "label": "Шифр",
        "type": "string",
        "directoryId": null,
        "directoryAttributeId": null
    },
    {
        "id": "b9a15773-bea1-4038-9a4c-7f7dccc85b52",
        "epsId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
        "label": "Наименование",
        "type": "string",
        "directoryId": null,
        "directoryAttributeId": null
    },
    {
        "id": "cd58507a-dece-47d8-b4a9-690eabad0536",
        "epsId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
        "label": "Финиш",
        "type": "date",
        "directoryId": null,
        "directoryAttributeId": null
    },
    {
        "id": "d347e9d9-cd63-44d1-9091-a3f01232da96",
        "epsId": "5db13376-ba5c-4fd5-ba7f-dc56347956ad",
        "label": "Старт",
        "type": "date",
        "directoryId": null,
        "directoryAttributeId": null
    }
]

Добавим первую работу

curl -X 'POST' \
 'https://your-org.domain/public-api/wbs' \
 -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
 -H 'x-version: 409' \
 -H 'Authorization: your-api-key' \
 -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
 -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
 -d '{
"epsId": "bc1da5df-d644-461a-aa54-e60182195898",
"parentId": "bc1da5df-d644-461a-aa54-e60182195898",
"type": "task",
"code": "S001",
"name": "Выемка грунта для котлована"
}'

{
  "id": "43b87cce-0695-4b57-bcd2-9b3345f9275a",
  "parentId": "bc1da5df-d644-461a-aa54-e60182195898",
  "code": "S001",
  "type": "task",
  "level": 0,
  "indexNumber": 0,
  "sortOrder": 0,
  "values": {
    "0cc9baf7-229b-452d-bc35-40abcf6d57d2": "S001",
    "12519af0-a0d7-4a6b-b9db-3cb40f9df880": 0,
    "30447676-52e9-4f7e-8891-1cce5b4cc029": "5304a040-7b58-4e94-b7b6-d543a6df9291",
    "3dafdd41-566a-4671-b354-f5180d295ec4": 0,
    "6ecddbe3-3b5c-4a3d-96f4-c48ede50ec4a": "not_started",
    "727e66e5-f8c3-4c14-b3cc-ff319d2d153f": "plan-r",
    "85e1278a-00e9-4ea3-9220-190dbb9aa2d9": "atest atest atest@test.ru",
    "ae0bbb2f-6ec0-4893-87bf-1002b2a57130": 5,
    "b34be140-35c4-4833-b7cc-ded3edf50f0d": 40,
    "b9a15773-bea1-4038-9a4c-7f7dccc85b52": "Выемка грунта для котлована",
    "c7e1fba8-2dbd-4a2c-93e2-23d58b010118": 1720015593480,
    "cd58507a-dece-47d8-b4a9-690eabad0536": 1720375200000,
    "d2342704-ae8e-4584-90b0-b61d5bacc400": 40,
    "d347e9d9-cd63-44d1-9091-a3f01232da96": 1719997200000,
    "dfff9bfb-a77b-4c89-af4a-b41c942d126f": "earlier",
    "f8d748cf-53fb-4d14-89c0-f1d2d708d44f": 40
  },
  "criticalPath": false,
  "materialPath": null,
  "curatorAccepted": false
}

Добавим узел ИСР

curl -X 'POST' \
  'https://your-org.domain/public-api/wbs' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "epsId": "bc1da5df-d644-461a-aa54-e60182195898",
  "parentId": "bc1da5df-d644-461a-aa54-e60182195898",
  "type": "work",
  "name": "Строительство фундамента"
}'

{
  "id": "2b73a1f8-833f-488c-9947-7fc1a4b76310",
  "parentId": "bc1da5df-d644-461a-aa54-e60182195898",
  "code": "100",
  "type": "work",
  "level": 0,
  "indexNumber": 1,
  "sortOrder": 1,
  "values": {
    "0cc9baf7-229b-452d-bc35-40abcf6d57d2": "100",
    "727e66e5-f8c3-4c14-b3cc-ff319d2d153f": "plan-r",
    "b9a15773-bea1-4038-9a4c-7f7dccc85b52": "Строительство фундамента"
  },
  "criticalPath": false,
  "materialPath": null,
  "curatorAccepted": false
}

Добавим в узел еще несколько работ

curl -X 'POST' \
  'https://your-org.domain/public-api/wbs' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "epsId": "bc1da5df-d644-461a-aa54-e60182195898",
  "parentId": "2b73a1f8-833f-488c-9947-7fc1a4b76310",
  "type": "task",
  "name": "Установка арматуры"
}'

{
  "id": "90bdc497-b6d0-41cf-a9a9-9621c8bd0732",
  "parentId": "2b73a1f8-833f-488c-9947-7fc1a4b76310",
  "code": "A100",
  "type": "task",
  "level": 1,
  "indexNumber": 2,
  "sortOrder": 0,
  "values": {
    "0cc9baf7-229b-452d-bc35-40abcf6d57d2": "A100",
    "12519af0-a0d7-4a6b-b9db-3cb40f9df880": 0,
    "30447676-52e9-4f7e-8891-1cce5b4cc029": "5304a040-7b58-4e94-b7b6-d543a6df9291",
    "3dafdd41-566a-4671-b354-f5180d295ec4": 0,
    "6ecddbe3-3b5c-4a3d-96f4-c48ede50ec4a": "not_started",
    "727e66e5-f8c3-4c14-b3cc-ff319d2d153f": "plan-r",
    "85e1278a-00e9-4ea3-9220-190dbb9aa2d9": "atest atest atest@test.ru",
    "ae0bbb2f-6ec0-4893-87bf-1002b2a57130": 5,
    "b34be140-35c4-4833-b7cc-ded3edf50f0d": 40,
    "b9a15773-bea1-4038-9a4c-7f7dccc85b52": "Установка арматура",
    "c7e1fba8-2dbd-4a2c-93e2-23d58b010118": 1720016385055,
    "cd58507a-dece-47d8-b4a9-690eabad0536": 1720375200000,
    "cda6b4ec-3d70-4c72-b728-c7af59606612": "100",
    "d2342704-ae8e-4584-90b0-b61d5bacc400": 40,
    "d347e9d9-cd63-44d1-9091-a3f01232da96": 1719997200000,
    "dfff9bfb-a77b-4c89-af4a-b41c942d126f": "earlier",
    "f8d748cf-53fb-4d14-89c0-f1d2d708d44f": 40
  },
  "criticalPath": false,
  "materialPath": "2b73a1f8-833f-488c-9947-7fc1a4b76310",
  "curatorAccepted": false
}

curl -X 'POST' \
  'https://your-org.domain/public-api/wbs' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "epsId": "bc1da5df-d644-461a-aa54-e60182195898",
  "parentId": "2b73a1f8-833f-488c-9947-7fc1a4b76310",
  "type": "task",
  "name": "Заливка бетона"
}'

{
  "id": "2d68dc0b-3877-4ed3-ac1c-9dcfa519df3f",
  "parentId": "2b73a1f8-833f-488c-9947-7fc1a4b76310",
  "code": "A110",
  "type": "task",
  "level": 1,
  "indexNumber": 2,
  "sortOrder": 1,
  "values": {
    "0cc9baf7-229b-452d-bc35-40abcf6d57d2": "A110",
    "12519af0-a0d7-4a6b-b9db-3cb40f9df880": 0,
    "30447676-52e9-4f7e-8891-1cce5b4cc029": "5304a040-7b58-4e94-b7b6-d543a6df9291",
    "3dafdd41-566a-4671-b354-f5180d295ec4": 0,
    "6ecddbe3-3b5c-4a3d-96f4-c48ede50ec4a": "not_started",
    "727e66e5-f8c3-4c14-b3cc-ff319d2d153f": "plan-r",
    "85e1278a-00e9-4ea3-9220-190dbb9aa2d9": "atest atest atest@test.ru",
    "ae0bbb2f-6ec0-4893-87bf-1002b2a57130": 5,
    "b34be140-35c4-4833-b7cc-ded3edf50f0d": 40,
    "b9a15773-bea1-4038-9a4c-7f7dccc85b52": "Заливка бетона",
    "c7e1fba8-2dbd-4a2c-93e2-23d58b010118": 1720016482952,
    "cd58507a-dece-47d8-b4a9-690eabad0536": 1720375200000,
    "cda6b4ec-3d70-4c72-b728-c7af59606612": "100",
    "d2342704-ae8e-4584-90b0-b61d5bacc400": 40,
    "d347e9d9-cd63-44d1-9091-a3f01232da96": 1719997200000,
    "dfff9bfb-a77b-4c89-af4a-b41c942d126f": "earlier",
    "f8d748cf-53fb-4d14-89c0-f1d2d708d44f": 40
  },
  "criticalPath": false,
  "materialPath": "2b73a1f8-833f-488c-9947-7fc1a4b76310",
  "curatorAccepted": false
}

ИСР в Web клиенте