Experience using Megaplan API

Before that, I had never come across a CRM Megaplan and did not know that it exists. A good friend of mine offered me a side job, said that one of his acquaintances was looking for a programmer to write a small program or script to automate work.
It was said that it is necessary to get data from an API from some system, process it and display it in XLS. I found the proposal interesting, I phoned the customer and made an appointment.

Just want to say that I am in no way affiliated with the Megaplan itself and I am not going to advertise it.

Formulation of the problem

The customer is an enterprise with approximately 50 employees.

Employees, projects and tasks are instituted in CRM.

Employees perform assigned tasks. At the same time in the comments to the task, they indicate the number of hours worked. In addition, the core clock is spent on performing the task (computer time clock).

They are also listed in each task in a separate field.

The customer needs to generate a report in XLS according to data from Megaplan for the specified time period.

For each project, for each task, you need to know how many working hours and “core-hours” were spent.

Those. Costs are grouped first by project, then by task, then by each employee.

A sample report is shown in the figure below.

The customer could not receive such a report using Megaplan. Therefore, it was decided to invite a third-party developer to develop a program / script that will solve the problem.

Deadline: 1 week.
Price: 20 thousand rubles.

The budget is small, the information on the Internet about the experience of using the Megaplan API is even less. I found this article here on Habré, and it was not at all encouraging. It smelled of problems, the money was not much needed, but it was interesting and wanted to help people in their routine. I agreed.

Choosing a scripting language and library for working with Megaplan API

Initially, there was a desire to take Python, read the API documentation and write a script,
which requests all the necessary data from Megaplan by API, processes it and outputs it to XLSX.

However, problems with the API started from the very beginning. It turned out that for each request you need
calculate the value of X-Authorization header by some algorithm.

Those. just learning the API using curl or httpie will fail.

Accordingly, I realized that I need to "cut off the corner" and look for some ready-made library to work with the Megaplan API. I was interested mainly in libraries for Python and Javascript. On github I found the following libraries . Most of them are dead projects, there are still a lot of PHP hacks.

I did not have to choose for a long time, I stopped at the library for the javascript language
megaplanjs .

First, I use javascript every day for the frontend.

Secondly, it was interesting to develop something for the command line on javascript.
Third, I was able to quickly install the library (thanks to npm), copy an example from
documentation and ... my application can already be authenticated in Megaplan and
get a list of projects. Hooray!

Detected problems with Megaplan API

• The problem with the study / study API. For each request, you need to calculate the value of the X-Authorization header by some algorithm. I already wrote about this above.
• API Restriction: API request rate is limited to (50 * N) requests per minute, where N is the number of licenses.
• Paginated data reading. Projects, comments to projects, tasks, comments to tasks need to be received page by page. At the same time, the megaplanjs library was not ready for this and silently returned only the first 50 pieces to me. I had to finish the library myself.
• Extended (custom) task fields. The core clock, which I mentioned above, was the user-defined (custom) field of the task. I could not get them through the API. I had to contact support. There I was suggested an undocumented way to get them. At the same time, I had to make an additional request for each task in order to get the value of this field.
• Error with Task.TimeUpdated. The API has the ability to get a list of tasks that have been updated (updated) after a certain point in time. By the way, there is no way to get updated / changed tasks up to a certain point. So, it turns out that getting the list of tasks updated after the specified time does not work correctly. For example, if a comment was added to the task, which indicates that the employee spent X hours on the task, this does not change the task update time. Therefore, I had to select all tasks through the API and filter them independently by the activity field of the activity - the last activity time by task.

How it ended and the conclusions

I was able to solve the task, but I spent much more time on it than I planned.

This time was not paid, the customer just needed a result. How he is reached, he is not interested.

3 times I turned to the support service. Not immediately, but helped. Thank.

To those developers who are just thinking of doing subj-I, I recommend better assess their risks and allow more time to develop.

Now Megaplan has a new version of API - version 3 (I used version 1, version 2 was not?). I looked at version 3, did not find what I needed (projects, tasks, employees). Version 3 may be just an addition to version 1, not a replacement. I also read that they promised to simplify the work with the API - I will not need to form the X-Authorization header for each request.

I uploaded the source code for my script on github .
If necessary, it can be used as an example to quickly start your application.

All successful development, happy coding!