Table of Contents

Altus_API_GetAssignmentByDay - Custom API Documentation

Warning

This API can return large volumes of data and consume high amounts of server resources. Use this API carefully with narrow filters and respect Microsoft Service Protection limits and retry guidance. Failure to do so may cause throttling and failures in other parts of the system.

Overview

Altus_API_GetAssignmentByDay is a Dynamics 365 / Power Apps custom API that returns assignment hours broken down by day for a specified project. It returns hours allocated per resource and/or task within a requested date range. The API is registered as a custom API (typically message name altus_GetAssignmentByDay) and can be called from Power Automate, client scripts, or other plugins.

The API supports two project types:

  • Native Altus projects: schedule data is synthesized from Dynamics task and assignment records.
  • External (imported) projects: schedule data is read directly from an attached Microsoft Project (.mpp) file.

Request

  • Type: POST
  • URI: https://.crm.dynamics.com/api/data/v9.2/sensei_assignmentbyday
  • Headers:
    • Content-Type: application/json

Parameters

Example POST payload:

{
    "projectid": "2beacc65-c52b-f011-8c4d-002248112dcc",
    "start": "2025-12-31T13:30:00.000Z",
    "finish": "2026-06-29T14:30:00.000Z",
    "aggregationType": "resource",
    "resourceids": [],
    "includeRelatedNamedResources": true
}

Required

  • projectid (Guid)
    GUID of the project record to query. The API validates the project exists.

Optional

  • start (DateTime)
    Start date (inclusive). If omitted, no lower bound is applied.
  • finish (DateTime)
    End date (inclusive). If omitted, no upper bound is applied.
    Note: If both start and finish are provided, start must be <= finish, otherwise an InvalidPluginExecutionException is thrown.
  • aggregationType (string)
    How data is grouped (case-insensitive):
    • "resource" → group by Bookable Resource
    • "task" → group by Task
    • "none" → no grouping (default) — one row per resource-task
  • resourceids (string[])
    Array of Bookable Resource GUID strings to filter to. If omitted, all resources are included.
  • taskids (string[])
    Array of Project Task GUID strings to filter to. If omitted, all tasks are included.
  • includeRelatedNamedResources (bool)
    Whether to include assignments linked via named (generic) resources. Default: true if missing.

Data Source Logic

The API automatically determines where to read schedule data:

  1. If the project has an External System Reference:
    • Looks for an attached Microsoft Project (.mpp) file in the project's documents.
    • If found:
      • Standard MPP: reads assignments using MPXJ and maps them to Altus task/resource IDs.
      • Planner MPP: uses additional mappings on the project to align Planner IDs with Altus IDs.
    • If no MPP found: returns an empty dataset.
  2. If no External System Reference (native Altus project):
    • Retrieves tasks/assignments from Dynamics and synthesises daily contours/hours using SyntheticCalculatorService.

After raw assignment-by-day data is retrieved (from either source), the API applies filters:

  • date range (start / finish)
  • resourceids and taskids
  • includeRelatedNamedResources

Finally, results are aggregated according to aggregationType.

Response

JSON Response:

{
    "@odata.context": "https://<host>.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.sensei_assignmentbydayResponse",
    "data": "[<array of stringified response objects - see below]"
}

The API returns a single output parameter:

  • data (string)
    A JSON-serialized array of AssignmentByDayDataResponse objects. Returns [] when no data matches.

Data response example

[
  {
    "G": "group-key-guid-or-empty",
    "T": "task-guid",
    "R": "resource-guid",
    "S": 12.5,
    "A": [
      { "D": "2025-01-01", "H": 8.0 },
      { "D": "2025-01-02", "H": 4.5 }
    ]
  }
]
Edit this page