endpoints/pii.js

  4. const pii = {
  5.     /**
  6.      * Personal Idetifying Information
  7.      * @module Pii
  8.      */
  10.     /**
  11.      * List the keys required to access Personally Identifiable Information (PII) for a given identifier. 
  12.      * Exactly one identifier will be accepted. 
  13.      * If the organization contains org-wide Systems Manager users matching the key provided then
  14.      *  there will be an entry with the key "0" containing the applicable keys.
  15.      * PARAMETERS
  16. username
  17. The username of a Systems Manager user
  18. email
  19. The email of a network user account or a Systems Manager device
  20. mac
  21. The MAC of a network client device or a Systems Manager device
  22. serial
  23. The serial of a Systems Manager device
  24. imei
  25. The IMEI of a Systems Manager device
  26.      * @memberof module:Pii
  27.      * @param {string} orgId
  28.      * @param {string} pii 
  29.      * @param {string} value
  30.      * @return { Promise } A promise holding the PII keys
  31.      * @example <caption>Example request</caption>
  32.      * 
  33.      
  34.       
  35.       meraki.getPiiKeys(orgId, pii).then((res) => {
  36.         console.log(res);
  37.       });
  38.      * 
  39.      * @example <caption>Example response</caption>
  40.      * 
  41.     Successful HTTP Status: 200
  42.         {
  43.         [networkId]:{
  44.             "macs":[
  45.             "00:77:00:77:00:77"
  46.             ],
  47.             "emails":[
  48.             "fake@example.com"
  49.             ],
  50.             "usernames":[
  51.             "fakename"
  52.             ],
  53.             "serials":[
  54.             "abcd1234"
  55.             ],
  56.             "imei":[
  57.             990000862471854
  58.             ]
  59.         }
  60.         }
  61.      */
  62.     getPiiKeys(orgId, piiType, value) {
  63.         if (!orgId) {
  64.             return Promise.reject(new Error('The orgId is required'))
  65.         }
  66.         return this.meraki.get(`/organizations/${orgId}/pii/piiKeys?${piiType}=${value}`).then((res) => res.data);
  67.     },
  69.     /**
  70.      * Given a piece of Personally Identifiable Information (PII), return the Systems Manager device ID(s) associated with that identifier. 
  71.      * These device IDs can be used with the Systems Manager API endpoints to retrieve device details. Exactly one identifier will be accepted.
  72.      * @memberof module:Pii
  73.      * @param {string} orgId 
  74.      * @param {string} pii 
  75.      * @param {string} value
  76.      * @return { Promise } A promise holding the device identifier
  77.      * @example <caption>Example request</caption>
  78.      * PARAMETERS
  79.         username
  80.         The username of a Systems Manager user
  81.         email
  82.         The email of a network user account or a Systems Manager device
  83.         mac
  84.         The MAC of a network client device or a Systems Manager device
  85.         serial
  86.         The serial of a Systems Manager device
  87.         imei
  88.         The IMEI of a Systems Manager device
  89.      * 
  90.      * meraki.getSmDevicesForKey(orgId, pii, value).then((res) => {
  91.      *  console.log(res.data);
  92.      * });
  93.      * 
  94.      * @example <caption>Example response</caption>
  95.         {
  96.         [networkId]:["1099541095293", "8348382288234"]
  97.         }
  98.      */
  99.     getSmDevicesForKey(orgId, pii, value) {
  100.         if (!orgId) {
  101.             return Promise.reject(new Error('The orgId is required'))
  102.         }
  103.         if (!pii) {
  104.             return Promise.reject(new Error('The pii type is required: username,email,serial or imei'))
  105.         }
  106.         if (!value) {
  107.             return Promise.reject(new Error('The pii value is required: the username, email, serial or imei'))
  108.         }
  109.         return this.meraki.get(`/organizations/${orgId}/pii/smDevicesForKey?${pii}=${value}`).then((res) => res.data);
  110.     },
  111.     /**
  112.      * Given a piece of Personally Identifiable Information (PII), return the Systems Manager owner ID(s) associated with that identifier.
  113.      *  These owner IDs can be used with the Systems Manager API endpoints to retrieve owner details. Exactly one identifier will be accepted.
  114.      * @memberof module:Pii
  115.      * @param {string} orgId
  116.      * @param {string} pii 
  117.      * @param {string} value
  118.      * @return { Promise } A promise holding the Systems Manager owner ID(s) associated with that identifier.
  119.      * @example <caption>Example request</caption>
  120.      * PARAMETERS
  121.         username
  122.         The username of a Systems Manager user
  123.         email
  124.         The email of a network user account or a Systems Manager device
  125.         mac
  126.         The MAC of a network client device or a Systems Manager device
  127.         serial
  128.         The serial of a Systems Manager device
  129.         imei
  130.         The IMEI of a Systems Manager device
  131.      * 
  132.      * meraki.getSmOwnersForKey(orgId, pii, value).then((res) => {
  133.      *  console.log(res.data);
  134.      * });
  135.      * 
  136.      * @example <caption>Example response</caption>
  137.         {
  138.             [networkId]:["1099541095293"]
  139.         }
  140.      */
  141.     getSmOwnersForKey(orgId, pii, value) {
  142.         if (!orgId) {
  143.             return Promise.reject(new Error('The orgId is required'))
  144.         }
  145.         if (!pii) {
  146.             return Promise.reject(new Error('The pii type is required: username,email,serial or imei'))
  147.         }
  148.         if (!value) {
  149.             return Promise.reject(new Error('The pii value is required: the username, email, serial or imei'))
  150.         }
  151.         const params = Object.keys(key);
  152.         const param = params[0];
  153.         return this.meraki.get(`/organizations/${orgId}/pii/smOwnersForKey?${pii}=${value}`).then((res) => res.data);
  154.     },
  155.     /**
  156.      * List the PII requests for this organization
  157.      * @memberof module:Pii
  158.      * @param {string} orgId 
  159.      * @return { Promise } A promise holding the PII requests for an organization
  160.      * @example <caption>Example request</caption>
  162.      * 
  163.       meraki.getPiiRequests(orgId).then((res) => {
  164.        console.log(res);
  165.       });
  166.      * 
  167.      * @example <caption>Example response</caption>
  168.         [
  169.         {
  170.             "id": "1234",
  171.             "organizationWide": false,
  172.             "networkId": "N_1234",
  173.             "type": "delete",
  174.             "mac": "00:77:00:77:00:77",
  175.             "datasets": "['usage', 'events']",
  176.             "createdAt": 1524692227,
  177.             "completedAt": 1524702227
  178.         }
  179.         ]
  180.      */
  181.     getPiiRequests(orgId) {
  182.         if (!orgId) {
  183.             return Promise.reject(new Error('The orgId is required'))
  184.         }
  185.         return this.meraki.get(`/organizations/${orgId}/pii/requests`).then((res) => res.data);
  186.     },
  188.     /**
  189.      * Return a PII request
  190.      * @memberof module:Pii
  191.      * @param {string} orgId 
  192.      * @param {string} piiId
  193.      * @return { Promise } A promise holding the PII requests for a pii ID
  194.      * @example <caption>Example request</caption>
  196.      * 
  197.         meraki.getPiiRequest(orgId, piiId).then((res) => {
  198.             console.log(res.data);
  199.         });
  200.      * 
  201.      * @example <caption>Example response</caption>
  202.         {
  203.         "id": "1234",
  204.         "organizationWide": false,
  205.         "networkId": "N_1234",
  206.         "type": "delete",
  207.         "mac": "00:77:00:77:00:77",
  208.         "datasets": "['usage', 'events']",
  209.         "createdAt": 1524692227,
  210.         "completedAt": 1524702227
  211.         }
  212.      */
  213.     getPiiRequest(orgId, piiId) {
  214.         if (!orgId) {
  215.             return Promise.reject(new Error('The orgId is required'))
  216.         }
  217.         if (!piiId) {
  218.             return Promise.reject(new Error('The piiId is required'))
  219.         }
  220.         return this.meraki.get(`/organizations/${orgId}/pii/requests/${piiId}`).then((res) => res.data);
  221.     },
  223.     getPiiRequests(orgId) {
  224.         if (!orgId) {
  225.             return Promise.reject(new Error('The orgId is required'))
  226.         }
  227.         return this.meraki.get(`/organizations/${orgId}/pii/requests`).then((res) => res.data);
  228.     },
  230.     /**
  231.      * Submit a new delete or restrict processing PII request
  232.      * 
  233.      * Options
  234. type
  235. One of "delete" or "restrict processing"
  237. datasets
  238. The datasets related to the provided key that should be deleted. Only applies to "delete" requests. The value "all" will be expanded to all datasets applicable to this pii_type.
  240. username
  241. The username of a network log in. Only applies to "delete" requests.
  243. email
  244. The email of a network user account. Only applies to "delete" requests.
  246. mac
  247. The MAC of a network client device. Applies to both "restrict processing" and "delete" requests.
  249. smDeviceId
  250. The sm_device_id of a Systems Manager device. The only way to "restrict processing" or "delete" a Systems Manager device. Must include "device" in the dataset for a "delete" request to destroy the device.
  252. smUserId
  253. The sm_user_id of a Systems Manager user. The only way to "restrict processing" or "delete" a Systems Manager user. Must include "user" in the dataset for a "delete" request to destroy the user.
  254.      * @memberof module:Pii
  255.      * @param {string} orgId 
  256.      * @param {options} options
  257.      * @return { Promise } A promise holding the PII request and status
  258.      * @example <caption>Example request</caption>
  259.     const options = { 
  260.         "type":"delete", 
  261.         "datasets":"["usage","events"]",
  262.         "mac":"00:77:00:77:00:77"
  263.     }
  265.     meraki.submitPiiRequest(orgId, options).then((res) => {
  266.       console.log(res.data);
  267.      });
  268.      * 
  269.      * @example <caption>Example response</caption>
  270.         {
  271.             "id": "1234",
  272.             "organizationWide": false,
  273.             "networkId": "N_1234",
  274.             "type": "delete",
  275.             "mac": "00:77:00:77:00:77",
  276.             "datasets": "['usage', 'events']",
  277.             "status": "in progress"
  278.         }
  279.      */
  280.     submitPiiRequest(orgId, options) {
  281.         if (!orgId) {
  282.             return Promise.reject(new Error('The orgId is required'))
  283.         }
  284.         if (!options) {
  285.             return Promise.reject(new Error('The options are required'))
  286.         }
  287.         return this.meraki.post(`/organizations/${orgId}/pii/requests`,options).then((res) => res.data);
  288.     },
  290.        /**
  291.      * Delete a restrict processing PII request
  292.      * @memberof module:Pii
  293.      * @param {string} orgId 
  294.      * @param {string} piiId
  295.      * @return { Promise } A promise holding the status code, 204 for success
  296.      * @example <caption>Example request</caption>
  297.      * 
  298.      * meraki.deletePiiRequest(orgId).then((res) => {
  299.      *  console.log(res);
  300.      * });
  301.      * 
  302.      * @example <caption>Example response</caption>
  303.         Successful HTTP Status: 204
  304.      */
  305.     deletePiiRequest(orgId, piiId) {
  306.         if (!orgId) {
  307.             return Promise.reject(new Error('The orgId is required'))
  308.         }
  309.         if (!piiId) {
  310.             return Promise.reject(new Error('The piiId is required'))
  311.         }
  312.         return this.meraki.delete(`/organizations/${orgId}/pii/requests/${piiId}`).then((res) => res.data);
  313.     },
  315.    
  316. }
  318. module.exports = pii;