Get the on-call user

rest-api
questions

(Andrew Striletskyi) #1

Hello everyone. How to get On-Call user via REST API (for some schedule) . With this query

https://test.pagerduty.com/api/v1/schedules/id/users

I get all users in schedule. But I want to get on-call user


(Jay Chiarella) #2

Hi Andrew,

I suggest to use our REST API v2 so that you can use the GET /oncalls endpoint. You can add a schedule ID as a parameter to the API call so that you can get the on-call user for the specified schedule.

Here is the documentation on this endpoint: https://v2.developer.pagerduty.com/v2/page/api-reference#!/On-Calls/get_oncalls

I hope this helps, but let me know if you have further questions.

Cheers,

Jay


(Nathan Falk) #3

I am doing something like this for my team by querying the schedule to find out who is on call right now, like this:

/schedules/<schedule_id>?since=<time_now>&until=<time_now>&overflow=true

Our team has multiple schedules and could have multiple people on call at the same time, so I send this query for each of our schedules to find out all of the users on call now.

Also, this is part of a more general program that might obtain the schedule for a day, a week, or a custom time interval, and so the above query can be modified just by changing the values for “since” and “until”.

Thanks,

Nate


(Simon Fiddaman) #4

+1 for Get the on-call user linked from @jay2 - this is what I do for our Slack bot; because I’m answering a specific question “who is on-call for this team”, I have a set of configs pre-defined which are used to generate the answers; basically I call /oncalls and use the schedule_ids and escaltion_policy_ids filters to get the correct response (as we use levels in our Escalation Policies and I want to target a specific level of the EP.


(Ladislav Prskavec) #5

Some problem I have to filter escalation level on bot side. I’m missing filtering by teams_ids[] that will be useful if you have 100+ teams as our PD.


(Simon Fiddaman) #6

Here’s an excerpt of the core part of my oncall bot.

Basically you give it a simple configuration with a list of escalation_policy_ids, schedule_ids and optionally a single Live Call Routing number (lcr) which it’ll use to determine first which user is on call for that EP/Schedule combination and choose the first one (the break at the end of the loop).

If you have an LCR defined, that’s all you need - if not, you must make a second call to get the user details including their contact_methods (to extract the phone number). This could be skipped if you just wanted to know who they are, or adjusted to display whatever attribute you’re interested in.

    from pdpyras import APISession

    def main(schedule_ids, escalation_policy_ids, lcr=None):
        '''
        Poll for a single oncall, based on a schedule id and escalation policy id
        The use of both Schedule and Escalation Policy limits scope
        In the event that multiple results are returned, the first result is provided
        Generally speaking, at the first esclation level where these schedule(s) are mentioned,
        there should be only one active on-call, regardless of time of day. 
        The expectation is that a level with split day/night responsibility will not overlap.
        '''
        
        oncalls = api.iter_all(
            'oncalls', # method
            {
                #"include[]": "users", # including users doesn't give us the contact details
                "schedule_ids[]": schedule_ids,
                "escalation_policy_ids[]": escalation_policy_ids
            } #params
        )

        if oncalls:
            for oncall in oncalls:
                # If we have a Live Call Routing number configured, just display it here
                if lcr:
                    ## directly print the result
                    # schedule - Live Call Routing: +xx xxxxxx,,x User Name until yyyy-mm-ddThh:mm:ssZ
                    print(u'`{}` - Live Call Routing: `{}` {} until {}'.format(
                        oncall.get('schedule').get('summary'),
                        lcr,
                        oncall.get('user').get('summary'),
                        oncall.get('end')
                    ))

                # We don't have an LCR configured, so find the user's phone number(s)
                else:
                    response = api.request(
                        'get', # requests type
                        '/users/{}'.format(oncall.get('user').get('id')), # get single user
                        params={"include[]": "contact_methods"} # include contact _details_
                    )
                    # prepare an empty phone list to populate - there could be more than one
                    phone = {}
                    if response.ok:
                        user = response.json()['user']
                        # loop through all of the contact methods, looking for phone numbers
                        for contact_method in user.get('contact_methods'):
                            # add phone numbers in the constructed format to the `phone` list
                            if 'phone' in contact_method['type']:
                                phone[contact_method.get('label')] = u'`{}: +{} {}`'.format(
                                    contact_method.get('label'),
                                    contact_method.get('country_code'),
                                    contact_method.get('address'))
                    # if no `contact_methods` of type `phone`
                    if not phone:
                        phone['EMPTY'] = 'NO PHONE ENTRIES FOUND'
                    
                    ## print the result
                    # schedule - user name - Work: +xx xxxxxx, Mobile: +xx xxxxxx until yyyy-mm-ddThh:mm:ssZ
                    print(u'`{}` {} - {} until {}'.format(
                        oncall.get('schedule').get('summary'),
                        oncall.get('user').get('summary'),
                        ', '.join(phone.values()),
                        oncall.get('end')
                        )
                    )

                break

        else:
            logging.critical('No oncalls returned')

(Simon Fiddaman) #7

note: this uses https://pagerduty.github.io/pdpyras/


(system) #8