What's The Deal with Schedule API? (Dynamics 365 Project Operations)

I had a great time recently getting involved as part of the Microsoft Dynamics ERP User Group, where I presented a session asking (channelling my inner Seinfeld in the process) “What’s the Deal with Schedule API in Dynamics 365 Project Operations?”. Off the back of this session, I wanted to do an accompanying blog post that helps to cover off some of the main topics from my talk and as a resource for anyone interested in diving into this subject again or for the very first time. So without much further ado, let’s jump in to try and answer this question as best as possible.

Schedule API Overview

Schedule API provides developers working with Dynamics 365 Project Operations the only mechanism to automate actions targeting the platform and ensure operations are replicated correctly between Microsoft Dataverse and Project for the web. Rather than using standard Create, Update or Delete actions targeting the core set of Scheduling Tables within Project Operations, developers must instead leverage the Schedule API to carry out these actions. Indeed, this is, in fact, the only supported way we can do this. When we talk about “Scheduling Tables”, we mean any of the following Project Operations table types:

• Project Task (msdyn_projecttask)
• Project Task Dependency (msdyn_projecttaskdependency)
• Resource Assignment (msdyn_resourceassignment)
• Project Bucket (msdyn_projectbucket)
• Project Team Member (msdyn_projectteam)

The Schedule API’s are built using native capabilities that have been available within Microsoft Dataverse for many years, meaning we can call any of the Schedule API’s in the same way we would for any Custom Action or Custom API. With the Schedule API’s, we can carry out the desired automation and programmatic actions we want against Project Operations, using familiar tools and without the need to write a complex integration ourselves that will persist data out into Project for the web.

How It All Works

Because the actions we carry out within Project Operations / Microsoft Dataverse need to be replicated to Project for the web (and vice-versa), Microsoft provides a shared backend service used to process all actions. The following diagram from Microsoft offers an excellent overview of how this backend service works as we target actions against the Schedule API:

As part of this, developers don’t need to handle complex technical logic; instead, we can let the Schedule API do all the heavy lifting for us. 😀

Supported API’s

At the time of writing this post, the Schedule API supports the following actions:

• Creation of new Projects synchronously (via the msdyn_CreateProjectV1 action)
• Creation of new Team Members synchronously (via the msdyn_CreateTeamMemberV1 action)
• Asynchronous Create, Update or Delete actions targeting any of the Scheduling Tables, using the following actions:
  • msdyn_PSSCreateV1
  • msdyn_PSSUpdateV1
  • msdyn_PSSDeleteV1

OperationSets Overview

As the Schedule API’s rely on the backend services mentioned earlier, a mechanism is needed to ensure we can submit these requests and have complete atomicity as part of our transactions. This is provided for as part of OperationSets, a concept worthy of further discussion. In layman’s terms, these provide a wrapper to bundle all our Schedule API requests together. This request is then passed off to the Schedule API to execute the operations we’ve indicated. As such, every request we make to the Schedule API must be included as part of an OperationSet, and we must also link all OperationSets to a Project. We achieve all of this via a two-step process:

• Initialise the OperationSet (via a msdyn_CreateOperationSetV1 request)
• Execute the OperationSet (via a msdyn_ExecuteOperationSetV1 request)

Once we execute our OperationSets, this is then processed asynchronously by the backend Schedule API service; therefore, there can sometimes be a slight delay in processing substantial requests.

We can view the list of OperationSets created within Project Operations by navigating to the appropriate area within the sitemap:

For each row, we can then view details regarding its status, the Project associated with the OperationSet and each request added into the OperationSet:

All of this can be incredibly useful from a debugging and diagnosis standpoint.

Schedule API Usage Scenarios

In a nutshell, any scenario requiring you to automate critical operations targeting Project Operations and, specifically, any scheduling tables will be a good candidate for the Schedule API. This will include situations where, for example, you need to:

• Batch Processing scenarios from external systems into Project Operations.
• Automating the creation of new Projects based on existing template structures.
• Handling complex Work Breakdown Structure’s (WBS’s) that are not easy to define manually in Project Operations.

Working with the Schedule API

Because the Schedule API leverages Dataverse actions, we can work with it in a variety of ways, including:

• Any .NET application, using the official SDK assemblies from Microsoft.
• .NET Dataverse Plug-ins
• JavaScript / TypeScript, via the Dataverse Web API
• Power Automate Cloud Flows via the Perform unbound action action step.

We can also use tools, such as Postman to test operations targeting the Schedule API. Check out my post from my PL-400 blog series, all about working with the Dataverse Web API to understand how we can do this.

To help better understand and work through some of the common ways we can work with the Schedule API, both via C# and Power Automate, check out the demo project on my GitHub repository, which you can download and experiment further with. I’ve included outline instructions on how to work with each sample provided - let me know in the comments below or on GitHub if you have any problems working with either of them.

Gotchas & Limitations

Helpful that the Schedule API may be, there are a couple of things to keep in mind while you are working with it:

• All operations must execute as a fully licensed Project Operations user. This means that using a dedicated Application User account is not supported, as it’s impossible to assign a license to accounts of this type. My recommendation would be to set up a full user account, which you can then utilise as a service account that all automation targeting the Schedule API’s can then run as. Keep in mind that there will be a cost implication for taking the additional license. 😉
• Microsoft restricts certain actions targeting specific columns on each of the scheduling tables. For example, we can’t write any information to a Project Task Actual Start or Actual End columns. Be sure to consult the complete list of unsupported columns to avoid getting caught out during your development work.
• Any operation you execute using the Schedule API will be subject to any platform-level limitations that Project Operations enforces, such as the limit on the number of tasks and resources on a project. Again, ensure you’ve consulted the relevant Microsoft documentation to avoid any unwelcome surprises.

To full the view list of limitations, you can consult the dedicated Microsoft Docs article section devoted to this subject.

Troubleshooting Schedule API Issues

Things can, invariably, go wrong when working the Schedule API. The API’s do a pretty good job of identifying and throwing back any issues in your Operation Set Details as you submit them to the platform (e.g. if you provide a column that’s not supported with the API’s). Still, things can occasionally go wrong as the OperationSets are processed behind the scenes. For when problems occur, we can consult the PSS Error Log (msdyn_psserrorlog) table, which will log any errors that arise alongside the appropriate error code. The information exposed here can be somewhat limited currently, so you may need to escalate each error, along with its CorrelationId, to Microsoft for further investigation.

Additional Resources

Antti Pajunen remains, as always, my go-to person whenever it comes to anything Project Service Automation or Project Operations, and the following posts are particularly recommended. I’m indebted to the first of these in helping to put together the demos in my GitHub repository:

• Dynamics 365 Project Operations: Using Schedule APIs with Power Automate and custom project templates
• D365 Project Operations, Project for the web: Calling Schedule APIs from Power Automate without custom connectors

Another good resource you can turn to, which helps evaluate and understand the expected performance of Schedule API, is the Project Schedule API Performance Benchmarks article, which provides some example execution times for a variety of different request types.

I hope this post has helped remove any doubts or queries you may have had relating to the Schedule API in Dynamics 365 Project Operations. Let me know in the comments below if you have any questions