Adding a supervisor to multiple groups through the xMatters REST API

Question 

Is there a way to add a supervisor to several groups at once? For example when a new supervisor is hired and needs to be added to several groups, or if a high-level executive wants to access to a number of groups in the system.

Answer

You can add a supervisor, or supervisors to multiple groups through the xMatters REST API and any third-party software that can use scripts to pull data from a .csv file. The following instructions are written for Postman, but might be applicable to other third-party software.

Warning: This bulk upload overwrites all existing supervisors for the specified groups. If you’re adding a new supervisor to a group that already has multiple supervisors, you must include the IDs of all existing supervisors. If you don't, your new supervisors are added, but the existing ones are removed.

Here’s how to add a new supervisor to multiple groups. First we'll need to get the supervisor IDs and group IDs into files.

  1. Get the supervisor UUIDs and save them to a text file. You can find UUIDs by either:
    • Finding the user on the Users page in the Web User Interface. Click the Profile tab, then the API button.UUID_get.png

    • Through the API using GET/people?firstName=<name>&lastName=<name>
  2. Open the spreadsheet program of your choice. If you’d like to keep a record of the group names (which is optional, but helpful) title Column A Group Name, and Column B groupID. You can title the columns whatever you’d like but ensure the title for group IDs does not contain spaces.

    mceclip2.png
  3. Get the UUIDs of the groups using GET /groups?search=<group_name>&fields=NAME and paste them into the groupID column of the spreadsheet.
  4. Save the spreadsheet as a .csv file in an easy-to-find location.

The files are ready, now let's set up Postman to read the files and use the xMatters REST API to modify your system.

  1. Open Postman and create a new POST command for your URL. For example: https://<your-company>.xmatters.com/api/xm/1/groups

    mceclip3.png

  2. In the Authentication tab, set the Type to “Basic Auth” and enter your credentials.

    mceclip4.png

  3. In the Body tab, select the Text type of JSON and add the following code into the body. Remember, if the group already has more than one supervisor listed and you want to keep those supervisors, you’ll need to include their UUIDs as well as the new supervisor's. If you only add the new supervisor, the existing supervisors will be removed. Here's what the code looks like if you're adding a new supervisor to a group and removing all existing supervisors:
    {
     "id": "{{data}}",
     "recipientType": "GROUP",
     "supervisors":
      [
       "438e9245-b32d-445f-916bd3e07932c892"
      ]
    }

    Here’s what it would look like for a group with two existing supervisors where a new one is added:

    {
     "id": "{{data}}",
     "recipientType": "GROUP",
     "supervisors":
      [
       "438e9245-b32d-445f-916bd3e07932c892"
       "b2341d69-8b83-4660-b8c8-f2e728f675f9"
       "a2e6b439-3396-4580-8793-1565b64d417f"
      ]
    }
  4.  Go to the Pre-Request Script tab and add the following code. Remember to replace {groupID} with the title of the column in your .csv file.
    var data = {};
    data = "{{groupID}}";

    //Optional parameters to speed up the request
    //data.recipientType = "GROUP";
    //data.recipientType = "DEVICE";

    //This is a postman function to set an environment variable to be passed in as the body.
    pm.environment.set("data",data);
    console.log("Data", JSON.stringify(data));

    mceclip6.png

  5. In the Tests tab, add the following code.
    let jsonData = JSON.parse(responseBody);

    tests['Member added to roster Successfully: ' + jsonData.id];
    postman.setEnvironmentVariable('memberUUID', jsonData.id);
    mceclip7.png

  6. Select Save As to save the script. Give it a name and save in an easy to find location.

    mceclip8.png

Now that we've set up all the files, let's run the scripts to add the supervisor to the groups.

  1. Click Runner from the top menu.

    mceclip9.png

  2. In the Runner window, navigate to the location of your saved script.

    mceclip10.png
  3. In the Data field, click Select File to navigate to the location of your .csv file. Ensure Data File Type is set to “text/csv”.

       mceclip11.png

  4. Click Run to run the script on the .csv file of groups.

When Postman finishes processing the file, check your groups have the correct supervisors listed either using the Web user interface, or the xMatters REST API.

 

   

 

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.