API : Change Log List
Introduction
This request will return the list of changes performed on a customer, a section or a specific item.
Request
| URL | https://api.telecomx.dk/log/changelog/customer/CUSTOMER_ID |
| https://api.telecomx.dk/log/changelog/customer/CUSTOMER_ID/SECTION |
| https://api.telecomx.dk/log/changelog/customer/CUSTOMER_ID/SECTION/ITEM_ID |
| Method | GET |
| Access level | VIEWER, MANAGER or OWNER if looking up for own customer
RESELLER if customer belongs to the reseller or a subreseller
RESELLER_ADMIN for any customer and system wide sections |
| Query | offset | [optional] Index of the first log event to return, default 0. |
| limit | [optional] The number of log events to return, default 100, min 1, max 500. |
| includeData | [optional] If true, the full item as it looked like when it was created or before it was updated or deleted, is included. |
| includeEmployees | [optional] If true an additional array is returned with all the employees who has caused the events listed, so that it is easy to put a name/e-mail on who caused the event to happen. |
| version | [optional] Which version of the endpoint to use. Defaults to 1 |
| includeChanges | [optional] [version 2] Whether to include the changes between change logs or not. Requires a SECTION - without one every entry's changes come back empty. |
| filter | [optional] [version 2] Free-text filter matched against the item's name / search values (and the number itself for Numbers). Requires a SECTION; ignored when an ITEM_ID is given. |
| sortBy | [optional] [version 2] Sort by property. Currently only allows 'when' |
| orderBy | [optional] [version 2] Order by property. Allowed values are “ASC” and “DESC”. Defaults to “ASC”. |
| what | [optional] [version 2] Filters logs based on what sort of action it is (the 'what'-property on each log). Allowed values are CREATE, UPDATE, DELETE, OTHER. |
| Params | CUSTOMER_ID | Id of the customer the events happened on. If it happened in a non-customer section, then this must be set to 'SYSTEM'. |
| SECTION | [optional] Name of the section the events happened in. Valid sections are listed below (case-sensitive). If not included, then all events on the customer is included in the response. |
| ITEM_ID | [optional] Id of an item, e.g. to list only events on a given sip account, this would be the id of the sip account. |
| Valid section names |
| CurrentInvoices | Customers | DeletedMvnoAccounts |
| Employees | MvnoAccounts | Dsls |
| Fibers | Numbers | Portings |
| Products | MvnoSims | |
| SipAccounts | PbxDialplans | SipPhones |
| PbxMusicOnHold | PbxAudios | PbxSettings |
| HumanTasks | IpTvDevices | |
Query examples
https://api.telecomx.dk/log/changelog/customer/1234567890ABCDEF12345678
https://api.telecomx.dk/log/changelog/customer/1234567890ABCDEF12345678/Employees
https://api.telecomx.dk/log/changelog/customer/1234567890ABCDEF12345678/Employees/1234567890ABCDEF12345678
https://api.telecomx.dk/log/changelog/customer/1234567890ABCDEF12345678/Employees?offset=10&limit=20&includeData=true&includeEmployees=true
https://api.telecomx.dk/log/changelog/customer/SYSTEM/Employees?offset=10&limit=20&includeData=true&includeEmployees=true
https://api.telecomx.dk/log/changelog/customer/SYSTEM/Employees/1234567890ABCDEF12345678?offset=10&limit=20&includeData=true&includeEmployees=true
Response
Version 1
| JSON object |
| offset | Index of the first event returned. |
| limit | Number of events to return. Note that the actual number of events returned may be lower. |
| total | Number of events that can be returned when offset and limit is not considered. This is to be used for paging through the data. |
| log | Array of changelog events, see definition below |
| employees | Only present when includeEmployees=true: array of employees who caused the listed events, each with _id, name and emailAddress |
| Log object (JSON) |
| _id | Id | Unique event id. |
| employee | Id | Id of the employee who caused the event, null if caused by the system. |
| when | Date | Date and time the event took place. |
| where | String | Name of the section where the event happened. See list above of valid section names |
| what | String | Type of event: CREATE, UPDATE, DELETE or OTHER. |
| description | String | Optional description of what happened, human-readable english language. |
| data | Object | If includeData query argument is set, then the data object is included. This is the item as it looked like at creation (if what=CREATE) or how the item looked like before it was updated or deleted (what=UPDATE or DELETE). |
Version 2
| JSON object |
| offset | Index of the first event returned. |
| limit | Number of events to return. Note that the actual number of events returned may be lower. |
| total | Number of events that can be returned when offset and limit is not considered. This is to be used for paging through the data. |
| log | Array of changelog events, see definition below |
| Log object (JSON) - if version=2 |
| _id | Id | Unique event id. |
| employee | Id | Id of the employee who caused the event. Null when caused by the system - and, when includeEmployees=true, also when the consumer may not see who caused the change. |
| employeeName | String | Only present when includeEmployees=true: name of the employee who caused the event. 'System' when the system made the event, 'Administrator' when the consumer may not see the name. |
| when | Date | Date and time the event took place. |
| where | String | Name of the section where the event happened. See list above of valid section names |
| what | String | Type of event: CREATE, UPDATE, DELETE or OTHER. |
| description | String | Optional description of what happened, human-readable english language. |
| changes | Change[] | Only computed when includeChanges=true and a SECTION is given: per-field diff from this UPDATE entry to the next-newer UPDATE of the same item. Empty otherwise. |
| changes[].key | String | Name of key, e.g ratePlan, name, notes. |
| changes[].oldValue | any | Old value, before update |
| changes[].oldDisplayValue | any | Old display value, e.g the name of the rate plan being changed, and not just an ID. |
| changes[].newValue | any | New value, after update |
| changes[].newDisplayValue | any | New display value, e.g the name of the rate plan being changed, and not just an ID. |
| data | Object | If includeData query argument is set, then the data object is included. This is the item as it looked like at creation (if what=CREATE) or how the item looked like before it was updated or deleted (what=UPDATE or DELETE). |
| impersonatedBy | Id | Only present when includeEmployees=true and the consumer is RESELLER_ADMIN or higher: id of the impersonator, if the user was impersonated. |
| impersonatedByName | String | Only present when includeEmployees=true and the consumer is RESELLER_ADMIN or higher: name of the impersonator. |
| impersonatedBySystem | Boolean | If the user was impersonated by the system, e.g a scheduled job is performed on the user's behalf. |
Note that properties holding no value may be omitted from the object.
Example - normal (v1)
{
"offset": 10,
"limit": 25,
"total": 243,
"log": [
{
"_id": "1234567890ABCDEF12345678",
"employee": "1234574890ABCDEF12345678",
"when": "2014-01-01T12:34:56.123Z",
"where": "Employees",
"what": "UPDATE",
"description": "Password has been reset"
}
]
}
Example - normal (version 2)
{
"offset": 10,
"limit": 25,
"total": 243,
"log": [
{
"_id": "1234567890ABCDEF12345678",
"employee": "1234574890ABCDEF12345678",
"employeeName": "Jens Mogensen",
"when": "2014-01-01T12:34:56.123Z",
"where": "Employees",
"what": "UPDATE",
"description": "Password has been reset",
"changes": []
},
{
"_id": "5234567890ABCDEF12345678",
"employee": null,
"employeeName": "Administrator",
"when": "2014-01-01T13:15:42.401Z",
"where": "Employees",
"what": "UPDATE",
"changes": [
{
"key": "ratePlan",
"oldValue": "1234567890ABCD1324657890",
"oldDisplayValue": "Basic Tale",
"newValue": "1234657980ABCD1324567980",
"newDisplayValue": "Fri tale, 5 gb data"
}
]
},
{
"_id": "6234567890ABCDEF12345678",
"employee": null,
"employeeName": "System",
"when": "2014-01-01T14:50:00.565Z",
"where": "Employees",
"what": "UPDATE",
"changes": [
{
"key": "newRatePlan",
"oldValue": null,
"oldDisplayValue": "N/A",
"newValue": "1234567980ABCD1324567980",
"newDisplayValue": "Mobil datakort 100gb"
}
]
}
]
}
Errors
| Error code | Message | Description |
| 403 | access_denied | Insufficient access level |
| 403 | customer | The SYSTEM scope requires RESELLER_ADMIN or higher. |
| 422 | customer | Customer is invalid. |
| 422 | section | Section is invalid. |
| 500 | internal_error | <Unspecified> |
