Fetching Entitlements

retrieve entitlement data using the nue lifecycle management api entitlements define customer access rights and usage limits based on their active assets and subscriptions prerequisites before you begin, ensure you have a valid nue api key with entitlement read permissions customer ids or entitlement numbers for the entitlements you want to retrieve basic understanding of rest apis and json familiarity with entitlement concepts and usage tracking authentication all entitlement retrieval operations require authentication using your nue api key in the nue api key header const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); rest endpoints the nue api provides rest endpoints for flexible entitlement data access // global entitlement endpoints get https //api nue io/entitlements // get all entitlements with pagination get https //api nue io/entitlements/{entitlementnumber} // get a specific entitlement by number // customer scoped entitlement endpoints get https //api nue io/customers/{customerid}/entitlements // get entitlements for a customer get https //api nue io/customers/{customerid}/entitlements/{entitlementnumber} // get a specific entitlement for a customer advanced filtering entitlement endpoints support advanced filtering using query parameters you can filter by any entitlement field except reserved parameters reserved parameters (cannot be used for filtering) customerids , entitlementnumber , includes , page , limit , offset , predicate , history , status dynamic filtering examples // filter by status and customer get https //api nue io/entitlements?customerid=001ks00000dvz1ayad\&quantity>=100 // filter with date ranges and logic operators get https //api nue io/entitlements?startdate>=2024 01 01& predicate=and // customer scoped filtering get https //api nue io/customers/001ks00000dvz1ayad/entitlements?quantity>=100 supported operators equality field=value comparison field>=value , field<=value , field>value , field\<value inequality field!=value , field<>value common status values active , expired , suspended , draft basic entitlement retrieval try it now fetch entitlements → https //api docs nue io/fetch entitlements const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); // fetch all entitlements for a customer const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; const encodedcustomerids = encodeuricomponent(json stringify(customerids)); fetch(`https //api nue io/entitlements?customerids=${encodedcustomerids}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data) { console log(`found ${result data length} entitlements`); result data foreach(entitlement => { console log(`${entitlement entitlementnumber} ${entitlement status}`); console log(`product ${entitlement productid}`); console log(`usage ${entitlement usedquantity || 0}/${entitlement quantity}`); console log(`period ${entitlement startdate} to ${entitlement enddate}`); }); } }) catch(error => console log('error ', error)); fetch entitlements for multiple customers // fetch entitlements for multiple customers const customerids = \[ "d2e04653 ae90 49df a986 134cf64f6d03", "cc5e1f0f 5e14 48cc ab98 9e5b191aa46f" ]; const encodedcustomerids = encodeuricomponent(json stringify(customerids)); fetch(`https //api nue io/entitlements?customerids=${encodedcustomerids}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success') { result data foreach(entitlement => { console log(`${entitlement entitlementnumber} ${entitlement status}`); console log(`customer ${entitlement customerid}`); }); } }) catch(error => console log('error ', error)); filtered entitlement retrieval fetch active entitlements only filter entitlements by their current status const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; const encodedcustomerids = encodeuricomponent(json stringify(customerids)); // fetch only active entitlements const url = `https //api nue io/entitlements?customerids=${encodedcustomerids}\&status=active`; fetch(url, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success') { console log('🟢 active entitlements retrieved'); if (result data && result data length > 0) { result data foreach(entitlement => { console log(`\n📋 ${entitlement name || entitlement entitlementnumber}`); console log(` status ${entitlement status}`); console log(` product ${entitlement productid}`); console log(` capacity ${entitlement quantity}`); console log(` used ${entitlement usedquantity || 0}`); console log(` available ${(entitlement quantity || 0) (entitlement usedquantity || 0)}`); console log(` valid period ${entitlement startdate} to ${entitlement enddate}`); // usage analysis const usagepercent = entitlement quantity > 0 ? ((entitlement usedquantity || 0) / entitlement quantity 100) 0; console log(` usage rate ${usagepercent tofixed(1)}%`); // capacity planning insights if (usagepercent >= 90) { console log(` 🚨 critical near capacity limit`); } else if (usagepercent >= 75) { console log(` ⚠️ warning high usage detected`); } else if (usagepercent >= 50) { console log(` 📊 moderate good utilization`); } else { console log(` ✅ healthy low utilization`); } // time based insights if (entitlement enddate) { const enddate = new date(entitlement enddate); const now = new date(); const daysremaining = math ceil((enddate now) / (1000 60 60 24)); if (daysremaining <= 30) { console log(` 🔔 renewal needed expires in ${daysremaining} days`); } } }); } else { console log('no active entitlements found for this customer'); } } }) catch(error => console log('error ', error)); fetch specific entitlement by number retrieve a specific entitlement using its entitlement number const entitlementnumber = "ent 001234"; const encodedentitlementnumber = encodeuricomponent(entitlementnumber); fetch(`https //api nue io/entitlements?entitlementnumber=${encodedentitlementnumber}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data length > 0) { const entitlement = result data\[0]; console log('🎯 specific entitlement retrieved'); console log(`entitlement number ${entitlement entitlementnumber}`); console log(`name ${entitlement name}`); console log(`status ${entitlement status}`); console log(`customer ${entitlement customerid}`); console log(`product ${entitlement productid}`); console log(`total quantity ${entitlement quantity}`); console log(`used quantity ${entitlement usedquantity || 0}`); console log(`available ${(entitlement quantity || 0) (entitlement usedquantity || 0)}`); console log(`start date ${entitlement startdate}`); console log(`end date ${entitlement enddate}`); console log(`version ${entitlement entitlementversion}`); console log(`billing account ${entitlement billingaccountid}`); // detailed usage analysis if (entitlement quantity > 0) { const usagepercent = ((entitlement usedquantity || 0) / entitlement quantity 100); const remaining = entitlement quantity (entitlement usedquantity || 0); console log(`\n📊 usage analysis `); console log(` utilization ${usagepercent tofixed(1)}%`); console log(` remaining capacity ${remaining} units`); // usage velocity (if we had historical data) if (entitlement startdate) { const startdate = new date(entitlement startdate); const now = new date(); const daysactive = math ceil((now startdate) / (1000 60 60 24)); if (daysactive > 0 && entitlement usedquantity > 0) { const dailyusage = entitlement usedquantity / daysactive; const daystodepletion = remaining / dailyusage; console log(` daily usage rate ${dailyusage tofixed(2)} units/day`); if (daystodepletion > 0) { console log(` estimated depletion ${math ceil(daystodepletion)} days`); if (daystodepletion <= 30) { console log(` 🚨 action required will exceed capacity soon`); } } } } } // time remaining analysis if (entitlement enddate) { const enddate = new date(entitlement enddate); const now = new date(); const daysremaining = math ceil((enddate now) / (1000 60 60 24)); console log(`\n⏰ time analysis `); if (daysremaining > 0) { console log(` days remaining ${daysremaining}`); console log(` expiration date ${entitlement enddate}`); if (daysremaining <= 7) { console log(` 🚨 critical expires within 1 week`); } else if (daysremaining <= 30) { console log(` ⚠️ warning expires within 1 month`); } else if (daysremaining <= 90) { console log(` 📅 notice expires within 3 months`); } } else { console log(` ❌ expired ${math abs(daysremaining)} days ago`); } } } else { console log('entitlement not found'); } }) catch(error => console log('error ', error)); including related data fetch entitlements with product details include product information in the entitlement response const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; const encodedids = encodeuricomponent(json stringify(customerids)); // include product details in the response const urlwithproducts = `https //api nue io/entitlements?customerids=${encodedids}\&includes=product`; fetch(urlwithproducts, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data) { result data foreach(entitlement => { console log(`\n📋 entitlement ${entitlement entitlementnumber}`); console log(` status ${entitlement status}`); console log(` usage ${entitlement usedquantity || 0}/${entitlement quantity}`); // display product information if included if (entitlement product) { console log(`\n 📦 product details `); console log(` name ${entitlement product name}`); console log(` sku ${entitlement product sku}`); console log(` id ${entitlement product id}`); console log(` description ${entitlement product description || 'no description'}`); } // display pricing tags if included if (entitlement pricetags && entitlement pricetags length > 0) { console log(`\n 🏷️ applied price tags `); entitlement pricetags foreach(tag => { console log(` • ${tag name} (${tag code})`); }); } // usage insights with product context if (entitlement product && entitlement quantity > 0) { const usagepercent = ((entitlement usedquantity || 0) / entitlement quantity 100); console log(`\n 📊 ${entitlement product name} usage `); console log(` current ${usagepercent tofixed(1)}% utilized`); console log(` available ${entitlement quantity (entitlement usedquantity || 0)} units`); } }); } }) catch(error => console log('error ', error)); fetch with all available data include all available related data // include all available data types const urlwithall = `https //api nue io/entitlements?customerids=${encodedids}\&includes=product,pricetags`; fetch(urlwithall, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data) { result data foreach(entitlement => { console log(`\n🎯 complete entitlement details ${entitlement entitlementnumber}`); console log(` name ${entitlement name}`); console log(` status ${entitlement status}`); console log(` customer ${entitlement customerid}`); // entitlement capacity console log(`\n 📊 capacity & usage `); console log(` total quantity ${entitlement quantity}`); console log(` used quantity ${entitlement usedquantity || 0}`); console log(` available ${(entitlement quantity || 0) (entitlement usedquantity || 0)}`); const usagepercent = entitlement quantity > 0 ? ((entitlement usedquantity || 0) / entitlement quantity 100) 0; console log(` utilization ${usagepercent tofixed(1)}%`); // product details if (entitlement product) { console log(`\n 📦 product `); console log(` ${entitlement product name} (${entitlement product sku})`); console log(` id ${entitlement product id}`); if (entitlement product description) { console log(` description ${entitlement product description}`); } } // time period console log(`\n 📅 validity period `); console log(` start ${entitlement startdate}`); console log(` end ${entitlement enddate}`); // time analysis if (entitlement enddate) { const enddate = new date(entitlement enddate); const now = new date(); const daysremaining = math ceil((enddate now) / (1000 60 60 24)); if (daysremaining > 0) { console log(` days remaining ${daysremaining}`); } else { console log(` status expired ${math abs(daysremaining)} days ago`); } } // billing information console log(`\n 🧾 billing `); console log(` billing account ${entitlement billingaccountid}`); console log(` order product ${entitlement orderproductid}`); // versioning console log(`\n 🔄 version control `); console log(` version ${entitlement entitlementversion}`); console log(` created ${entitlement createddate}`); console log(` last modified ${entitlement lastmodifieddate}`); // price tags if (entitlement pricetags && entitlement pricetags length > 0) { console log(`\n 🏷️ price tags (${entitlement pricetags length}) `); entitlement pricetags foreach(tag => { console log(` • ${tag name} (${tag code})`); }); } }); } }) catch(error => console log('error ', error)); entitlement history and compliance tracking fetch entitlement history retrieve historical versions of a specific entitlement for compliance and audit async function fetchentitlementhistory(entitlementnumber) { const encodedentitlementnumber = encodeuricomponent(entitlementnumber); const url = `https //api nue io/entitlements?entitlementnumber=${encodedentitlementnumber}\&history=true`; try { const response = await fetch(url, { method 'get', headers myheaders }); const result = await response json(); if (result status === 'success' && result data length > 0) { console log(`📜 entitlement history for ${entitlementnumber}`); console log('=' repeat(60)); // sort by version to show evolution const sortedhistory = result data sort((a, b) => a entitlementversion b entitlementversion); sortedhistory foreach((version, index) => { console log(`\n${index + 1} version ${version entitlementversion}`); console log(` status ${version status}`); console log(` quantity ${version quantity}`); console log(` used ${version usedquantity || 0}`); console log(` period ${version startdate} to ${version enddate}`); console log(` modified ${version lastmodifieddate}`); // compare with previous version if (index > 0) { const previous = sortedhistory\[index 1]; const changes = \[]; if (version status !== previous status) { changes push(`status ${previous status} → ${version status}`); } if (version quantity !== previous quantity) { changes push(`quantity ${previous quantity} → ${version quantity}`); } if ((version usedquantity || 0) !== (previous usedquantity || 0)) { changes push(`used ${previous usedquantity || 0} → ${version usedquantity || 0}`); } if (version enddate !== previous enddate) { changes push(`end date ${previous enddate} → ${version enddate}`); } if (changes length > 0) { console log(` 📊 changes from previous version `); changes foreach(change => console log(` ${change}`)); } } }); // generate compliance insights console log(`\n📋 compliance analysis `); console log(` total versions ${sortedhistory length}`); const firstversion = sortedhistory\[0]; const currentversion = sortedhistory\[sortedhistory length 1]; console log(` original quantity ${firstversion quantity}`); console log(` current quantity ${currentversion quantity}`); console log(` quantity changes ${currentversion quantity firstversion quantity}`); // track usage progression const maxused = math max( sortedhistory map(v => v usedquantity || 0)); console log(` peak usage ${maxused} units`); // compliance status const currentusage = currentversion usedquantity || 0; const iscompliant = currentusage <= currentversion quantity; console log(` current compliance ${iscompliant ? '✅ compliant' '❌ over usage detected'}`); return sortedhistory; } else { console log('no entitlement history found'); return \[]; } } catch (error) { console error('history fetch failed ', error); return \[]; } } // usage example fetchentitlementhistory("ent 001234") then(history => { console log(`compliance audit complete ${history length} versions analyzed`); }); error handling async function safeentitlementfetch(customerids, options = {}) { try { if (!array isarray(customerids) || customerids length === 0) { throw new error('customerids must be a non empty array'); } const encodedids = encodeuricomponent(json stringify(customerids)); let url = `https //api nue io/entitlements?customerids=${encodedids}`; if (options status) url += `\&status=${options status}`; if (options includes) url += `\&includes=${options includes}`; const response = await fetch(url, { method 'get', headers myheaders }); if (!response ok) { throw new error(`http ${response status} ${response statustext}`); } const result = await response json(); if (result status !== 'success') { throw new error(`api error ${result message || 'unknown error'}`); } return { entitlements result data || \[], found result data? length || 0, warnings result warnings || \[] }; } catch (error) { console error('entitlement fetch error ', error); return { entitlements \[], found 0, error error message }; } } query parameters reference parameter type required description customerids array\[string] json encoded array of customer ids entitlementnumber string specific entitlement number to fetch status string no filter by entitlement status includes string no related data to include either customerids or entitlementnumber is required entitlements provide customer access rights and usage limits based on their active assets and subscriptions