M365 Integration - Done

functional specification 1\ introduction 1 1 purpose this document outlines the functional requirements and specifications for integrating microsoft 365 (m365), azure active directory (azure ad / entra id), and related services (intune, teams, sharepoint, onedrive, windows 365) tenants with the commandit platform via gdap the integration aims to provide msps with centralized read only visibility into m365/azure ad configurations, security posture, user activity, licensing, enriched user profiles (including all relevant standard and custom attributes ), intune devices ( including detailed properties ), enterprise applications/app registrations , azure ad role assignments (including pim) , teams structure, sharepoint/onedrive sites/permissions, enabling efficient monitoring, reporting, and billing reconciliation across multiple client tenants via authorized delegated access 1 2 scope in scope secure authentication/authorization via gdap for read access configuration for msp partner id and client tenant integrations guidance on required read only gdap roles scheduled synchronization of key data points (users incl extended/mailbox/custom attributes, all group types, licenses, security settings, unified audit logs, intune devices/software/properties, policy status, dirsync status, litigation hold status, user directory status, teams/channels, sharepoint sites/items/permissions, onedrive usage, enterprise apps/service principals, app role assignments, azure ad role definitions/assignments, pim assignments, key mailbox settings, etc ) handling of deleted objects reported via sync by updating status mapping synced data to commandit entities mechanism for manual override of specific synced user fields synchronization and augmentation of intune managed device details (including windows 365 cloud pcs) robust logic to prevent duplicate inventory records matching/pairing logic for intune/agent devices handling of unmatched intune devices monitoring m365/azure ad security configurations (read only) generating alerts based on detected events/changes/configurations providing data views and reports based on synchronized information storing data necessary to analyze historical access questions (optional/future) synchronization of sharepoint/onedrive permission states (complex) out of scope all write actions from commandit back to m365/azure ad/intune bi directional synchronization sync is one way m365 > commandit real time event streaming gdap relationship management agent deployment via intune windows 365 provisioning policy/gateway configuration management deep synchronization of all possible graph api data points; focus is on operationally relevant data for msps 1 3 goals provide a single pane of glass for m365/azure ad/intune/teams/sharepoint/onedrive info via gdap (read only) automate data collection for assessments, compliance, billing, and enriched inventory (devices, users, apps, roles) enable proactive alerting based on collected data reduce manual data gathering effort enhance visibility (user activity incl permission changes via logs, licenses, security, device state, directory sync health, user profiles, teams/sites/items/permissions, onedrive usage, app registrations, role assignments) prevent duplicate records via intelligent pairing/merging allow administrators authoritative control over specific user attributes within commandit provide the data necessary to answer historical point in time access questions 2\ architecture overview leverages microsoft graph api for read operations managed via integrationinstances ('microsoft365') authentication via oauth 2 0 (secure application model + gdap) scheduled background jobs for read synchronization device pairing logic integrated into device sync upsert logic with data source prioritization and sync override checks implemented for user attributes and device component inventory delta queries for users/groups read operations per tenant throttling management and error handling for read operations 3\ msp setup & configuration 3 1 application registration (one time) commandit multi tenant app in commandit azure tenant defines necessary delegated read only graph api permissions (scopes include user read all, group read all, groupmember read all, auditlog read all, devicemanagementmanageddevices read all, devicemanagementapps read all, devicemanagementconfiguration read all, securityevents read all, servicehealth read all, directory read all, policy read all, identityriskevent read all, sites read all, files read all, application read all, approleassignment readwrite all (or read), rolemanagement read directory, privilegedaccess read all, mailboxsettings read confirm minimum required set ) 3 2 storing msp microsoft partner id manual entry into organizations microsoft partner id 3 3 managing integrations ui to manage 'microsoft365' integrationinstances requires client org link and client tenant id provides clear guidance on required read only gdap roles (e g , global reader, security reader, intune administrator, application administrator (read access), privileged role administrator (read access), exchange administrator (read access) confirm minimum roles ) includes api connection test mechanism 4\ client setup & configuration (gdap relationship) authorization relies on msp establishing gdap relationship with client via partner center msp must request specific read only azure ad roles based on commandit's documented requirements client admin must approve the gdap request and roles 5\ backend data synchronization & operations 5 1 sync job architecture periodic background jobs per active 'microsoft365' integrationinstance authenticates using gdap delegated flow logs permission errors clearly 5 2 api calls & data mapping (read sync m365 > commandit) (logic respects users sync overrides before updating commandit) organization details get /organization > integrationinstances users get /users/delta (use $select for required properties) map core attributes to azureadusers map extended attributes (job title, phones, office location, mailbox settings including litigation hold , custom extensions) into the azureadusers extended attributes and the dedicated azureadusers litigation hold enabled field link and populate users/userphonenumbers (respecting overrides) handle @removed users > set directory status='softdeleted' groups get /groups/delta sync all types map attributes to azureadgroups handle @removed groups group members get /groups/{id}/members/delta > azureadgroupmemberships (track history) licenses (assigned) get /users/{id}/licensedetails > saasuserassignments secure score get /security/securescores, /security/securescorecontrolprofiles > securescorehistory, securescorecontrols intune policies (definitions) get /devicemanagement/devicecompliancepolicies, /devicemanagement/deviceconfigurationpolicies > intunecompliancepolicies, intuneconfigurationprofiles intune device policy status get /devicemanagement/manageddevices/{id}/devicecompliancepolicystates (or similar) > intunedevicepolicystatus audit logs get /auditlogs/directoryaudits and/or /security/auditlog/queries include sharepoint, teams, exchange etc > m365auditlog sign in logs get /auditlogs/signins > azureadsigninlog ( requires p1/p2 ) risky sign ins get /identityprotection/riskdetections > azureadriskysigninevents ( requires p2 ) conditional access policies get /identity/conditionalaccess/policies > azureadconditionalaccesspolicies ( requires p1/p2 ) service health get /admin/serviceannouncement/healthoverviews, /issues > m365servicehealthissues intune managed devices get /devicemanagement/manageddevices (select more properties like enrollmenttype, managementagent, macs, compliancestate) > used for device pairing (5 4) & augmentation of devices records (incl configuration jsonb) intune software inventory get /devicemanagement/manageddevices/{id}/detectedapps > used for deduplication logic (5 6) targeting devicesoftware directory synchronization status get /directory/onpremisessynchronization > update integrationinstances deleted items periodically query get /directory/deleteditems/microsoft graph user > update azureadusers directory status microsoft teams get /groups/{id}/team > microsoftteams team channels get /teams/{team id}/channels (and /allchannels) > teamchannels table sharepoint sites get /sites?search= > sharepointsites sharepoint/onedrive items (files/folders) get /drives/ /children (recursive) > sharepointitems table sharepoint/onedrive permissions (current state) get /drives/ /permissions (recursive/targeted) > sharepointpermissions table (complex/high volume) enterprise apps / service principals get /serviceprincipals (delta available?) > azureadappserviceprincipals get /applications (delta available?) > azureadapplications app role assignments get /serviceprincipals/{id}/approleassignedto > azureadapproleassignments azure ad role definitions get /directoryroles or /directoryroletemplates > azureadroledefinitions table azure ad role assignments (active) get /rolemanagement/directory/roleassignments or /directoryroles/{id}/members > azureadroleassignments table pim assignments (eligible/active) get /identitygovernance/privilegedaccess/group/assignmentschedules (and similar for roles) > pimroleassignments table (requires pim permissions) 5 3 error handling & throttling implement robust error handling, logging permission failures implement retry after header handling and exponential backoff per tenant utilize json batching 5 4 device pairing and augmentation logic 5 4 1 intune > commandit pairing match on intune id > serial > hostname+mfg/model > fingerprint (if feasible) augment matched record 5 4 2 commandit agent > intune pairing check existing link > match on serial > hostname+mfg/model > fingerprint (if feasible) update agent record with intune id if matched 5 4 3 data augmentation intelligently merge data, prioritizing agent for operational details, intune for management context/gaps update sync source 5 5 handling unmatched devices intune devices not automatically paired get status = 'pendingmatch' ui lists pending devices for msp admin review options "match to existing device", "confirm as new device", "ignore/exclude" 5 6 data synchronization and deduplication logic implement upsert strategy with intelligent matching for shared data points (software, hardware, disks, nics) use last seen source field to track updates apply data source prioritization rules (e g , prefer agent for install path, prefer intune for compliance state) respect users sync overrides flags during user attribute updates 6\ configuration monitoring periodic jobs query graph api using gdap context for specific settings comparison logic runs against compliancerules results stored (azureadtenantsecuritypolicy, devicecomplianceresults) deviations trigger alerts depends on sufficient gdap roles 7\ security considerations secure storage of msp application credentials clear guidance on minimum necessary read only gdap roles log all sync activities, errors, pairing actions, data upsert/merge actions, and configuration checks in auditlog 8\ data mapping summary this table outlines the primary mapping between microsoft graph api endpoints/objects and the target commandit schema tables where the synchronized data will be stored graph api object/endpoint key properties synced commandit table(s) key commandit columns notes get /organization id, verifieddomains, displayname, technicalnotificationmails integrationinstances tenant id, primary domain, name por id not reliably available via graph/gdap get /users/delta id, userprincipalname, displayname, givenname, surname, mail, accountenabled, signinactivity, onpremisessyncenabled, usertype, jobtitle, officelocation, businessphones, mobilephone, manager azureadusers, users, userphonenumbers azure object id, user principal name, display name, first name, last name, email address, account enabled, last sign in date time, on premises sync enabled, user type, extended attributes (for jobtitle, officelocation etc ), manager user id respects sync overrides links users/azureadusers get /users/{id}/mailboxsettings litigationholdenabled, automaticrepliessetting, etc azureadusers litigation hold enabled, extended attributes requires mailboxsettings permissions get /users/{id}/licensedetails skuid saasuserassignments (via products) user id, product id requires mapping sku id to commandit product get /groups/delta id, displayname, description, grouptypes, mailenabled, securityenabled, membershiprule azureadgroups azure object id, display name, description, group types, mail enabled, security enabled, membership rule details syncs all group types get /groups/{id}/members/delta id, @odata type azureadgroupmemberships group azure object id, member azure object id, member type, is active, last seen timestamp, removed timestamp tracks history get /security/securescores currentscore, maxscore, createddatetime securescorehistory current score, max score, score date get /security/securescorecontrolprofiles controlname, score, maxscore, status, controlcategory securescorecontrols control name, current score, max score, status, category get /devicemanagement/devicecompliancepolicies id, displayname, description, platform, version intunecompliancepolicies intune policy id, name, description, platform, version get /devicemanagement/deviceconfigurationpolicies id, displayname, description, platform, version intuneconfigurationprofiles intune profile id, name, description, platform, version /devicemanagement/ /devicecompliancepolicystates policyid, state, platformtype, settingstates intunedevicepolicystatus device id, policy type, policy id, compliance state, last reported timestamp, details links to device and policy tables /auditlogs/directoryaudits, /security/auditlog/queries activitydatetime, user, activitydisplayname, result, target, ipaddress, details m365auditlog timestamp, user id, activity, item type, item id, site url, source ip, details must include sharepoint, teams, exchange etc workloads get /auditlogs/signins createddatetime, userprincipalname, appdisplayname, ipaddress, location, devicedetail, status, conditionalaccessstatus azureadsigninlog timestamp, user principal name, application, ip address, location info, device info, status code, failure reason, ca status requires p1/p2 get /identityprotection/riskdetections userprincipalname, detecteddatetime, risktype, risklevel, riskstate, ipaddress, location azureadriskysigninevents user principal name, detection timestamp, risk type, risk level, risk state, ip address, location info requires p2 get /identity/conditionalaccess/policies id, displayname, state, conditions, grantcontrols, sessioncontrols azureadconditionalaccesspolicies policy id, name, state, configuration details requires p1/p2 stores details in jsonb get /admin/serviceannouncement/issues id, title, classification, status, service, startdatetime, enddatetime, impactdescription m365servicehealthissues issue id, service name, status, title, start time utc, end time utc, description get /devicemanagement/manageddevices id, devicename, serialnumber, manufacturer, model, osversion, userprincipalname, lastsyncdatetime, isencrypted, iscompliant devices (via pairing/augmentation logic) intune device id, name, serial number, manufacturer id, model number, os version, primary contact user id, intune last checkin at, configuration augments agent data get /devicemanagement/ /detectedapps displayname, version, publisher devicesoftware (via upsert logic) display name, version, publisher, last seen source merges with agent data get /directory/onpremisessynchronization serviceaccount, lastsynctimestamp, status details integrationinstances directory sync service account, last directory sync time utc, directory sync status get /directory/deleteditems/ id azureadusers directory status sets status to 'softdeleted' get /groups/{id}/team id, displayname, description, visibility microsoftteams team id, display name, description, visibility, archived status links to azureadgroups get /teams/{team id}/channels id, displayname, description, channeltype, weburl teamchannels channel id, team id, display name, description, channel type, web url get /sites?search= id, name, weburl, sitecollection hostname sharepointsites site id, name, url, hostname, storage quota, storage usage get /drives/ /children id, name, file, folder, size, parentreference id sharepointitems item id, drive id, site id, name, item type, size bytes, parent item id recursive sync needed get /drives/ /permissions id, grantedtov2, roles, link, invitation sharepointpermissions permission id, item id, drive id, site id, granted to type, granted to id, roles, link type, link scope complex/high volume get /serviceprincipals id, appid, displayname, serviceprincipaltype azureadappserviceprincipals service principal id, app id, display name, service principal type get /applications id, appid, displayname azureadapplications application id, app id, display name get /serviceprincipals/{id}/approleassignedto principalid, approleid, resourceid azureadapproleassignments assignment id, principal id, app role id, resource id get /directoryroles, /directoryroletemplates id, displayname, description, rolepermissions azureadroledefinitions role definition id, display name, description, role permissions get /rolemanagement/ /roleassignments id, roledefinitionid, principalid, directoryscopeid azureadroleassignments assignment id, role definition id, principal id, principal type, scope get /identitygovernance/ /assignmentschedules id, roledefinitionid, principalid, scheduleinfo pimroleassignments pim assignment id, role definition id, principal id, assignment type, assignment state, start date time, end date time requires pim permissions 9\ future considerations implement delta queries where supported (incl service principals, apps, roles, sites, items?) explore webhook subscriptions for near real time event ingestion re evaluate adding specific write capabilities based on msp demand and security review enhance fingerprinting methods for device pairing refine data source prioritization rules for upsert logic develop application level logic/reporting to answer historical access questions by correlating m365auditlog events with permission/membership snapshots backend development tasks this document outlines the detailed backend tasks required to implement the microsoft 365 / azure ad integration as specified in m365 integration spec v1 (v3 1 read only gdap focus), assuming a typescript environment, postgresql database access via an orm (e g , prisma/typeorm), and use of @azure/msal node or similar for authentication phase 1 core setup & configuration backend task 1 1 implement/verify schema migrations context ensure the database structure precisely matches the final agreed upon schema for all m365/azure ad/intune related tables action create or verify database migration scripts (using the chosen migration tool) for all tables listed in the previous version of this task list (e g , integrationinstances, azureadusers, azureadgroups, azureadgroupmemberships, saasuserassignments, securescorehistory, securescorecontrols, intune , m365auditlog, azureadsigninlog, azureadriskysigninevents, azureadconditionalaccesspolicies, m365servicehealthissues, microsoftteams, teamchannels, sharepointsites, sharepointitems, sharepointpermissions, azureadapplications, azureadappserviceprincipals, azureadapproleassignments, azureadroledefinitions, azureadroleassignments, pimroleassignments, plus fields added to devices, users, organizations) output database schema matching the specification, including all columns, types, constraints, indexes, and comments success criteria migrations run successfully; schema introspection confirms all tables/fields/constraints/indexes exist as defined unit test(s) typically verified by running migrations against a test database and using schema introspection tools or orm validation, rather than traditional unit tests ensure rollback scripts function correctly task 1 2 manage msp partner id context allow msp admins to store their microsoft partner id for por checking logic action implement backend api endpoints (e g , get /api/organizations/self, put /api/organizations/self) allowing authenticated msp admins to view and update the microsoft partner id field on their own organizations record include input validation input msp org id (from auth context), microsoft partner id string output updated organizations record schema interaction organizations (read/update microsoft partner id) success criteria msp admin can successfully view and save their partner id via the api unit test(s) test get endpoint returns correct microsoft partner id for the authenticated msp org test put endpoint successfully updates microsoft partner id with valid input test put endpoint rejects invalid input formats (if validation rules exist) test authorization ensure only authorized admins for the msp org can call put task 1 3 manage m365 integration instances context provide the backend api for managing connections to client m365 tenants action implement backend restful api endpoints (crud) for integrationinstances where integration type = 'microsoft365' include endpoints for create, list (for org), get details, update (name, is enabled, sync toggles), delete logic link securely to credentials (task 1 4) validate inputs (e g , valid tenant id format) enforce authorization (user must have rights to manage integrations for the specified orgid) schema interaction integrationinstances (crud) success criteria api endpoints function correctly according to openapi/swagger definition; data is persisted accurately; authorization enforced unit test(s) test post creates a new record with correct integration type, org id, tenant id, and default status test get (list) returns only instances for the specified orgid test get (details) returns the correct instance test put updates specified fields (name, is enabled, configuration) correctly test delete removes the instance test authorization checks for all endpoints test validation for inputs like tenant id task 1 4 secure credential storage context securely store sensitive oauth refresh tokens needed for gdap authentication action implement the chosen secure storage strategy (e g , linking integrationinstances to credentials table with encryption, or integrating with external vault) implement strict access control to retrieval functions schema interaction integrationinstances, credentials (or external vault api) success criteria refresh tokens are stored securely (encrypted at rest); retrieval is strictly controlled and audited; mechanism links tokens to specific integrationinstances unit test(s) test secure storage function encrypts data correctly test secure retrieval function decrypts data correctly only for authorized internal services test linking mechanism between integrationinstances and stored credential/token test access control ensure unauthorized components cannot retrieve credentials test audit logging for credential access/storage (if applicable) phase 2 authentication & authorization (gdap via sam) task 2 1 gdap token acquisition service context central service to handle acquiring graph api access tokens using the gdap delegated flow action create typescript service (gdaptokenservice) using @azure/msal node implement getaccesstoken(clienttenantid string) logic retrieves msp app credentials & partner service account refresh token (task 1 4), requests token targeting clienttenantid authority using refresh token grant handle caching/refresh (task 2 2) input client tenant id output valid graph api access token libraries @azure/msal node success criteria service reliably returns valid access tokens; handles token refresh transparently unit test(s) mock msal successful token acquisition using refresh token; verify correct access token is returned mock msal expired access token scenario; verify refresh logic is triggered and new token returned mock msal refresh token failure; verify appropriate error is thrown/logged verify correct authority url (including client tenant id) is used in token requests verify correct scopes are requested (e g , https //graph microsoft com/ default) task 2 2 token management & caching context optimize token acquisition and handle expiry action integrate caching (e g , node cache, redis) into gdaptokenservice cache access tokens keyed by clienttenantid respect expires on implement auto refresh logic before expiry log events/errors success criteria token requests are served from cache; expired tokens are refreshed; errors logged unit test(s) test token retrieval hits cache when token is valid test token retrieval triggers refresh when token is expired or near expiry test cache invalidation logic (e g , on authentication errors) task 2 3 api connection test endpoint context allow users to verify integration setup and gdap permissions action implement backend api endpoint post /api/integrationinstances/{instanceid}/test logic retrieves instanceid calls gdaptokenservice getaccesstoken() if successful, makes a simple graph api call (e g , get /organization via task 3 2 wrapper) checks api response output json { success boolean, message string } detailing success or specific failure reason (auth failed, permission denied for basic read) success criteria endpoint accurately reflects ability to get token and make basic graph call via gdap unit test(s) mock successful token acquisition and successful get /organization; verify response is { success true, } mock failed token acquisition; verify response is { success false, message 'authentication failed ' } mock successful token acquisition but failed get /organization (403 forbidden); verify response is { success false, message 'permission denied ' } phase 3 sync job framework & core directory sync (read) task 3 1 sync job scheduler & queue context manage background synchronization tasks reliably and scalably action implement scheduler (e g , node cron) and queue (e g , bullmq) queue jobs per tenant update integrationinstances status/timestamps/errors implement concurrency limits and retry logic libraries node cron, bullmq (or alternatives) success criteria jobs scheduled; queue processes jobs; status/timestamps updated unit test(s) test job scheduling adds jobs to the queue correctly test queue worker picks up and processes jobs test retry logic on simulated job failure test integrationinstances status updates correctly on job start/success/failure task 3 2 graph api client wrapper context create a reusable client for graph api interactions action develop typescript class (graphapiclient) takes gdaptokenservice & clienttenantid provides methods (get, getwithpagination, getdelta) handles token injection, pagination (@odata nextlink), basic error parsing, throttling handling (detect 429, retry after, backoff) success criteria wrapper simplifies calls; handles auth, pagination, errors, throttling unit test(s) mock successful api call; verify data returned mock paginated api response; verify wrapper correctly follows @odata nextlink mock 429 response with retry after; verify wrapper waits and retries mock 429 response without retry after; verify exponential backoff is applied mock 403/401 errors; verify appropriate exceptions are thrown task 3 3 user synchronization context keep commandit user data aligned with azure ad action create sync job task logic logic use task 3 2 wrapper fetch get /users/delta (select core + custom props) fetch /mailboxsettings handle @removed > update directory status upsert azureadusers (map core, map extended/mailbox to extended attributes/litigation hold enabled) link/update users/userphonenumbers, checking sync overrides store $deltatoken output updated db tables stored $deltatoken logs schema integrationinstances, azureadusers, users, userphonenumbers success criteria data reflects azure ad state (respecting overrides); delta sync works unit test(s) (as described in previous thought block create, update, override check, delete handling, pagination, error handling, delta token storage) task 3 4 group synchronization context keep commandit group data aligned with azure ad action create sync job task fetch get /groups/delta handle @removed upsert azureadgroups (map types/flags) store $deltatoken schema azureadgroups, integrationinstances success criteria azureadgroups reflects azure ad groups accurately unit test(s) test create, update, delete scenarios via delta verify mapping of grouptypes, mailenabled, securityenabled test delta token handling task 3 5 group membership synchronization context keep group memberships accurate and track history action create sync job task fetch get /groups/{id}/members/delta handle added members (upsert azureadgroupmemberships, set is active=true, update last seen timestamp) handle removed members (update existing record is active=false, set removed timestamp) schema azureadgroupmemberships success criteria table accurately reflects current membership and flags inactive ones with timestamps unit test(s) test adding a member test removing a member (verify is active false, removed timestamp set) test re adding a member (verify is active true, removed timestamp nullified, last seen timestamp updated) task 3 6 license synchronization context track m365 license assignments action create sync job task fetch /users/{id}/licensedetails map skuid to products upsert saasuserassignments handle removals schema saasuserassignments, products, azureadusers success criteria saasuserassignments accurately reflects assignments unit test(s) test assigning a license test removing a license test handling unknown skus (log error or create placeholder product?) task 3 7 directory sync status synchronization context provide visibility into aad connect health action create sync job task fetch /directory/onpremisessynchronization update integrationinstances fields schema integrationinstances success criteria fields updated correctly unit test(s) mock api response; verify correct fields on integrationinstances are updated task 3 8 deleted items check context ensure soft deleted users are flagged; handle hard deletes action create periodic sync job task fetch /directory/deleteditems/microsoft graph user update azureadusers directory status='softdeleted' handle users disappearing from this endpoint schema azureadusers success criteria status updated correctly; hard deletes handled per policy unit test(s) test finding a user in deleted items updates status test user disappearing from deleted items triggers expected action (e g , record deletion) phase 4 security & compliance data sync (read) task 4 1 secure score sync create sync job task fetch /security/securescores & /security/securescorecontrolprofiles populate securescorehistory & securescorecontrols handle pagination/history unit test(s) verify data insertion/update into both tables test handling of historical score entries task 4 2 risky sign in sync create sync job task fetch /identityprotection/riskdetections populate azureadriskysigninevents handle pagination/date filtering unit test(s) verify data insertion test date filtering logic test mapping of risk levels/types task 4 3 ca policy sync create sync job task fetch /identity/conditionalaccess/policies populate azureadconditionalaccesspolicies (store details in jsonb) handle pagination unit test(s) verify data insertion verify complex policy structure stored correctly in jsonb task 4 4 audit log sync create sync job task fetch unified audit logs (via /security/auditlog/queries or /auditlogs/directoryaudits), ensure sp/teams/exo/aad included implement pagination, date filtering, checkpointing map to m365auditlog unit test(s) verify data insertion test pagination logic test checkpointing (only fetching new logs) verify parsing of different workload event types task 4 5 sign in log sync create sync job task fetch /auditlogs/signins populate azureadsigninlog implement pagination/filtering unit test(s) verify data insertion test pagination and date filtering verify mapping of status codes, location, device info task 4 6 implement service health sync create sync job task fetch /admin/serviceannouncement/healthoverviews & /admin/serviceannouncement/issues populate/update m365servicehealthissues handle pagination unit test(s) verify data insertion/update for service status and active issues test mapping of issue details phase 5 intune data sync (read) task 5 1 intune device sync create sync job task fetch /devicemanagement/manageddevices (select properties) pass results to device pairing logic (task 6 1) unit test(s) verify api call construction with $select verify data is passed correctly to the pairing service task 5 2 intune policy definition sync create sync job task fetch /devicemanagement/ policies populate intunecompliancepolicies & intuneconfigurationprofiles unit test(s) verify data insertion/update for both policy types test handling of different platform types task 5 3 intune policy status sync create sync job task fetch device policy statuses (e g , /manageddevices/{id}/devicecompliancepolicystates) populate intunedevicepolicystatus unit test(s) verify data insertion/update, linking correctly to devices and policy tables test mapping of different compliance/config states task 5 4 intune software inventory sync create sync job task fetch /manageddevices/{id}/detectedapps pass results to deduplication logic (task 6 4) unit test(s) verify api call construction verify data is passed correctly to the upsert service phase 6 device & component synchronization logic task 6 1 implement device pairing logic (intune > commandit) develop typescript function/service implement matching algorithm (intuneid > serial > host+mfg/model > fingerprint) implement db updates/inserts for devices table (status, sync source, intune device id) unit test(s) test matching logic for each step (match on intuneid, match on serial only, etc ) test creation of 'pendingmatch' record test update of existing record test fingerprinting logic (if implemented) task 6 2 implement device pairing logic (commandit agent > intune) develop typescript function/service called during agent check in implement matching logic against intune sourced devices update agent's devices record with intune device id unit test(s) test matching logic called from agent check in context test successful update of intune device id on agent's record test scenario where no match is found task 6 3 implement data augmentation logic define and implement rules (typescript service) for merging agent and intune data onto devices record, prioritizing sources update sync source unit test(s) test various merge scenarios (e g , intune provides serial, agent provides os details; agent provides newer os version) verify sync source is updated correctly task 6 4 implement component upsert logic develop generic or specific typescript functions/services for upserting data into devicesoftware, physicaldisks, etc implement matching, data prioritization rules, update last seen source/last updated at unit test(s) for each component type (e g , software) test inserting new record from agent test inserting new record from intune test updating existing agent record with intune data (verify merge rules) test updating existing intune record with agent data verify last seen source updates correctly phase 7 handling unmatched devices task 7 1 backend api list pending devices implement get /api/devices?status=pendingmatch\&org id= endpoint using orm queries add filtering/pagination unit test(s) test endpoint returns correct list based on status and org id test authorization task 7 2 backend api match/confirm/ignore actions implement backend logic for post /match, patch /confirm, post /ignore update devices status/links or exclusion list log actions in auditlog unit test(s) test 'match' action correctly links intune id and updates status test 'confirm' action updates status test 'ignore' action prevents device from reappearing in pending list on next sync test audit logging for each action phase 8 sharepoint, onedrive, teams sync (read) task 8 1 implement teams sync fetch /groups/{id}/team populate microsoftteams unit test(s) verify data insertion/update into microsoftteams, linking correctly to azureadgroups task 8 2 implement team channel sync fetch /teams/{team id}/channels populate teamchannels unit test(s) verify data insertion/update into teamchannels, linking correctly to microsoftteams task 8 3 implement sharepoint site sync fetch /sites populate sharepointsites handle pagination unit test(s) verify data insertion/update into sharepointsites test handling of different site types task 8 4 implement onedrive usage sync fetch /users/{id}/drive populate useronedrivestatus unit test(s) verify data insertion/update into useronedrivestatus, linking correctly to azureadusers task 8 5 implement sp/od item sync implement recursive fetch of /drives/ /children populate sharepointitems handle pagination/throttling unit test(s) test recursive fetching logic verify data insertion/update for files and folders test parent linking test handling of large folders/pagination task 8 6 implement sp/od permission sync implement fetch of /drives/ /permissions populate sharepointpermissions handle complexity/volume/throttling (lower priority) unit test(s) verify data insertion/update for different permission types (user, group, link) test mapping of roles test handling of inherited vs direct permissions phase 9 identity governance data sync (read) task 9 1 implement enterprise app/sp sync fetch /serviceprincipals, /applications populate azureadappserviceprincipals, azureadapplications handle delta if available unit test(s) verify data insertion/update for both tables task 9 2 implement app role assignment sync fetch /serviceprincipals/{id}/approleassignedto populate azureadapproleassignments unit test(s) verify data insertion/update, linking correctly to sps and principals task 9 3 implement azure ad role definition sync fetch /directoryroles or /directoryroletemplates populate azureadroledefinitions unit test(s) verify data insertion/update for built in and custom roles task 9 4 implement azure ad role assignment sync fetch /rolemanagement/directory/roleassignments populate azureadroleassignments unit test(s) verify data insertion/update, linking correctly to roles and principals task 9 5 implement pim assignment sync fetch /identitygovernance/privilegedaccess/ /assignmentschedules populate pimroleassignments handle required permissions unit test(s) verify data insertion/update for both eligible and active assignments test parsing of schedule info phase 10 configuration monitoring & alerting task 10 1 configuration check engine develop scheduled service/job reads compliancerules targeting m365 configs queries graph api via wrapper unit test(s) test engine correctly identifies applicable rules and queries the right graph api endpoints based on rule definition task 10 2 comparison logic implement comparison between fetched state and compliancerules check logic data unit test(s) test comparison logic for different data types and operators defined in rules task 10 3 compliance result logging create/update devicecomplianceresults based on outcomes unit test(s) verify devicecomplianceresults records are created/updated correctly with status ('compliant', 'noncompliant') task 10 4 alerting integration develop logic evaluating results/logs based on alertprocessingrules and creating alerts unit test(s) test rule evaluation triggers alerts correctly based on non compliant results or specific log patterns phase 11 cross cutting concerns task 11 1 centralized audit logging implement standardized logging service/decorator used by all modules performing actions or syncs ensure detailed context is logged to auditlog unit test(s) verify key actions (sync start/end, errors, pairing, merge) generate appropriate auditlog entries task 11 2 error handling framework define standard error types implement consistent try/catch blocks, error logging (to integrationinstances and potentially centralized logging), and integration with queue retry logic unit test(s) test various error conditions (api errors, db errors, unexpected data) and verify they are handled gracefully and logged correctly task 11 3 throttling implementation implement and test throttling handling (retry after, backoff) in the graph client wrapper (task 3 2) add monitoring for frequent throttling unit test(s) mock 429 responses; verify client wrapper waits and retries correctly task 11 4 security implementation implement secure fetching/handling of credentials/tokens (task 1 4, task 2 1) perform code reviews focusing on security ensure api calls respect least privilege based on gdap roles unit test(s) test credential storage/retrieval security code reviews are primary verification