Jens Sorensen
Our nightly integration does a full compare of registered devices in xMatters to ensure key details are kept up to date. We also extract all xM registered devices and load them into our HR system for reporting on global coverage in order to alert teams and employees to critical gaps.
In order to do this with the xmAPI we first call GetPeople but then we have to iterate through each person returned and call {personId}/devices to build the full devices data set which takes a significant amount of time to complete.
Suggestion is to optionally include devices in the GetPeople response and/or provide a method to get all devices. Other suggested approaches?
0
Comments
Please sign in to leave a comment.
Hi Jens,
Thanks for sharing your use case. As you've described, your current solution is the only way to get the list of devices from the system is in two steps.
As far as suggested enhancements, both ways are common approaches that we've employed for other objects in our API. We could enhance the GET /people endpoint parameter called embed to support devices. Additionally, we could add the GET /devices endpoint that would give a paginated list of all devices in the system.
If we were to add the GET /devices endpoint, would you need any parameters to filter the results in any way? Or are you looking for a way to get the complete list of devices despite the device type or status?
Thanks,
Craig
UPDATE - June 3
We have updated the API with two additions:
Checkout the API reference guide
https://help.xmatters.com/xmapi/index.html#get-devices
https://help.xmatters.com/xmapi/index.html#get-people
Thanks for the quick comment. For my own use-case a single GET /devices would accomplish what I need. I can always filter the data once it's returned for what I want. However, others might want to filter on device type or person demographics.
Thanks Jens!
+1 for this.
Currently our Devices workflow is one of our longest running. This would speed things up significantly.
Hi Cory,
Thanks for the feedback :) If you have time could you elaborate more on your workflow to help us better understand your process?
Thanks,
Craig
Of course,
We are using Dell Boomi to make all of our REST calls to the xMatters API. The way we get Device data today is to paginate through every person and build cache with person ids. We then build calls for all the devices for all the people.
This turns into a pretty big workflow. So lets say we have 10k users. Once we have cached every person id, we then need to make 10k calls to get every device in our xMatters instance. This workflow is our second longest running process behind the recipient data extract.
Hi Cory - We're also using Dell Boomi for our xM API integrations and leveraging Boomi caches in probably a similar way. I've broken our scheduled process up into two, the first creates / inactivates people and the second runs after to audit/create missing devices. Email me directly if you're interested in comparing our Boomi xM approaches and processes (email: j5s@qad.com).
Just so that others can learn from your experiences, if you would not mind keeping the discussion in this thread (if possible) we would all appreciate it. Thank you!
Hey Jens, its funny you bring that up. So we never delete a person or device row from our reporting tables. What I've done is replicate the Delete ID functionality that was included in the on-prem xMatters app. Any person or device that had been deleted would have a delete id == device id/pers id. If it was active, then the delete id would be equal to -1.
A rest response with only updated/deleted people and devices would be ideal, but we make it work.
Boomi:
Today we have the Device run as a sub process of People. Once people completes we build a curl for each device and send it one-by-one.
We load everything untouched into stage tables. We do zero within Boomi to identify updated/deleted records. Actually, the delete id is static as -1 into our stage tables. We use Informatica to perform insert/update from our stage tables to our reporting tables.
I am curious about your volume and run times in Boomi, I'll definitely get in touch with you about specifics.
Cory - sorry I missed your last reply, which is why I'm late in responding.
Reaching out to you on something related. Starting Aug 15 and we started getting 503 errors after processing only a few hundred of the GET people/.../devices. Remember we have to iterate through 1950 here. I think the xm web server is getting overwhelmed now.
I had to add a try/catch before making this api call so when getting the 503 error I back-off and wait 30 seconds before retrying. This is only a work around and I have an open case with xM and waiting to hear back. Have you seen any 503 error / capacity issues when calling this service too quickly?
I'll post a few screen shots of our Boomi processes in a separate comment.
For us the limitation in the API is the lack of identifiers for devices. We have two instances on BCM an one ITM and want to update the ITM from BCM however the API can only identify EMAIL and VOICE. So added identifiers that seem to exist already would be very helpful.
Thank You,
Bob, there are a couple of meta-data API calls that you may find helpful:
1. Get Device Types: https://help.xmatters.com/xmapi/index.html?javascript#device-types
Gives the types of devices configured in your instance(s).
and
2. Get Device Names: https://help.xmatters.com/xmapi/index.html?javascript#device-names
Which returns the devices users have or can add to their profile.
Between those two you should have what you need to get and create the appropriate devices between instances.
Hope that helps,
Jordan.
Thank you Jordan, #2 is the ticket. I was thinking that Home Email and Work Email were device types and just not available via API.
I appreciate the tip!
Bob
Cory and Jens, thanks for sharing your process in the forum. It's very informative.
Thanks Bob, glad Jordan could help and point you in the right direction.
Good Morning Craig Gulliver,
I would like to bring up the ability to GET all Devices again. Is this on your 2019 roadmap?
I would also like to bring up a GET All for all the endpoints related to Groups:
1. Group Membership
2. Shift On-Call
3. Shift Membership
These are killing us on performance right now. Groups sub processes run in parallel and still push 2 hours every time they run. Thanks for taking a look.
I second that as well. We have weekly reports that go out and it creates a hundred or so calls rather than just one which slows down the report processing time by quite a bit.
Having the ability to pull all devices (by type) would be ideal.
And I third that as well. The xMatters device sync process is one of my longest running processes. I'd prefer to see the getPeople optionally return all devices, but I'd also take a single call to get all devices too.
Cory/Chance/Jens - Thanks for feedback and the upvotes. We'll certainly look at this enhancement and how it stacks up against other priorities for next year. For now, it's not scheduled or planned in the near future but I have added the enhancement to the list.
Once we get to scheduling the work, I'll provide an update on this thread.
Thanks,
Craig
Thanks Craig, I look forward to it.
Quick Update
We'll be releasing API updates that will make it easier to access user devices at the end of May, targeting 259 release. You see a new endpoint called GET /devices that return a paginated list of devices in the system based on your user level permissions.
Craig - Great to hear & thanks for the update.
Great news Craig, thank you.
We have updated the API with two additions:
Checkout the API reference guide for details:
https://help.xmatters.com/xmapi/index.html#get-devices
https://help.xmatters.com/xmapi/index.html#get-people