Experience using Megaplan API

Before that, I had never encountered 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 the work.
It was said that you need to get API data from some system, process it and output it to XLS. The proposal seemed interesting to me, I phoned the Customer and made an appointment.

I want to say right away that I have nothing to do with Megaplan itself and I am not going to advertise it.

Formulation of the problem

Customer - an enterprise with approximately 50 employees.

Employees, projects and tasks are established in CRM.

Employees perform assigned tasks. Moreover, in the comments to the task, they indicate the number of hours worked. In addition, a core-clock (machine time clock) is spent on a task.

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

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

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

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

A sample report is presented in the figure below.

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

Duration: 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 did not cause optimism at all. It smelled of problems, the money was not much needed, but it was interesting and I wanted to help people in their routine. I agreed.

Choosing a scripting language and library for working with the Megaplan API

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

However, problems with the API started from the very beginning. It turned out that for each request it is necessary to
calculate the value of the X-Authorization header according to some algorithm.

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

Accordingly, I realized that I needed to "cut the corner" and look for some ready-made library for working with the Megaplan API. I was mainly interested in the libraries for Python and Javascript. On github, I found the following libraries . Most of them are dead projects, there are many more "crafts" in PHP.

I didn’t have to choose for a long time, I stopped at the library for the javascript
megaplanjs language .

Firstly, I use javascript every day for the frontend.

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

Detected Issues with Megaplan API

• The problem with learning / exploring the API. For each request, you need to calculate the value of the X-Authorization header according to some algorithm. I already wrote about this above.
• API limitation: The frequency of API requests is limited to (50 * N) requests per minute, where N is the number of licenses.
• Page reading data. Projects, project comments, tasks, task comments must 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.
• Advanced (custom) task fields. The clock core, of which I spoke above, was the user-defined (custom) field of the task. I could not get them through the API. I had to contact support. They told me an undocumented way to get them. At the same time, I had to make an additional request for each task 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 tasks updated / changed until a certain point. So, it turns out that getting a list of tasks updated after the specified time does not work correctly. For example, if a comment was added to the task stating that the employee spent X hours on the task, this does not lead to a change in the update time of the task. Therefore, I had to select all the tasks through the API and filter them myself by the field of the activity task - the time of the last activity for the task.

How it ended and conclusions

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

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

3 times I contacted the support service. Not immediately, but helped. Thanks.

For developers who are just thinking of doing subj, I recommend that they better assess their risks and spend more time developing.

Now Megaplan has a new version of the 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). Maybe version 3 is just an addition to version 1, not a replacement. I also read that they promised to simplify the work with the API - there will be no need to create an X-Authorization header for each request .

I posted the source code of my script on github .
If necessary, you can use it as an example to quickly start your application.

Good luck to everyone, happy coding!