Teams are an integral part of Cisco Spark, allowing anyone to create a space for your real-life team to discuss projects and make decisions. Teams can be function specific – support, engineering, marketing – or specific to projects, with members from multiple groups collaborating together. Within each Team, you can establish Rooms; these rooms are public to the members of the Team, meaning a member of the Support team (or Engineering team, or Project X team) can join or leave any Room listed as part of that Team, without being invited or added manually. Documentation on using Teams in the Cisco Spark clients can be found at the following links:
- Cisco Spark - Teams
- Getting Started with the Cisco Spark App
- Getting to Know Cisco Spark - the Advanced Guide
Such a vital part of Cisco Spark needs an equally robust representation in the API, and we’re happy to announce the availability of the new /teams and /team resources. In this blog, we’ll walk you through a few of the typical use cases – creating a team and adding members to it, viewing the members of a team, removing a team membership and then deleting a team entirely.
Note that while we will be walking you through the process using the developer portal, you can run all of these requests using your preferred REST client as well.
To start, go to developer.ciscospark.com, click ‘Documentation’ along the top and then the ‘Teams' on the left hand sidebar. Click the ‘Create a Team’ link, which will bring up this page:
As long as Test Mode is set to ON, you can run the Team creation request right from this window – fill in a value for name and then hit the Run button. If it works, you should see a Request and Response that looks like the following:
Now go back to your Cisco Spark client and click the Teams option on the left hand side:
You should see your new Team listed (assuming you’re logged in to the Spark client with the same user you’re using on the developer portal).
We’ll add another team member to the room next – grab the value for the id parameter in the Response and then click the ‘Team Memberships’ link on the left hand sidebar of the developer portal. Click the link ‘Create a Team Membership’, which will bring you to this page.
You should see a total of four Request Parameters – teamId, personId, personEmail, and isModerator. The value for teamId will be the id you copied earlier – add it under ‘Your values’, then add a personId or a personEmail – personId can be retrieved using this people resource (discussed here), but email works just as well. Once you’ve added your new team member, you’ll just need to decide if you want them to be a Moderator or not (note that moderated rooms is a paid feature, so if you’re using a free account’s auth token to test, you won’t be able to set someone as a Moderator) and then hit Run.
If it worked, you should have a 200 OK and a list of parameters like these (the IDs will be real GUIDS):
{
"id": "ID_STRING",
"teamId": " ID_STRING ",
"personId": " ID_STRING ",
"personEmail": "example@cisco.com",
"personDisplayName": "Example Person
"isModerator": true,
"created": "2016-07-06T16:18:01.074Z"
}
Copy that info from your response and save it – we’ll use it again in later examples. If you now go to the Teams option in your Spark Client, select the Team you’re working with and you’ll see the new member in the list under ‘Team Members’.
Next we’ll verify we can see our new team member when we check the Team Memberships. Click the link for ‘List Team Memberships’ on the left sidebar, which will bring you here.
All you need here is the teamId from when you created it – plug it as the value, hit Run and you should see yourself and your new Team Member listed in the results, like so:
{
"items": [
{
"id": "ID_STRING",
"teamId": "ID_STRING",
"personId": "ID_STRING",
"personEmail": "example1@cisco.com",
"personDisplayName": "Example Person 1",
"isModerator": false,
"created": "2016-02-15T21:33:12.175Z"
},
{
"id": "ID_STRING",
"teamId": "ID_STRING",
"personId": "ID_STRING",
"personEmail": "example2@cisco.com",
"personDisplayName": "Example Person 2",
"isModerator": false,
"created": "2016-06-20T16:33:09.132Z"
}
]
}
Last for this walkthrough, we’ll show how to delete a membership and then the team entirely. Both are very straightforward – click the ‘Delete a Team Membership’ link on the left, which will bring you here.
For this, you’ll need the ID for your recently added team member – it’s in the results when you added them to the team, or when you listed the team memberships. Hit the drop down for the membershipId value in the URL listed at the top and paste in the ID value:
Hit Run, confirm you want to actually delete the membership, and if you get a 204 No Content response, the delete worked. You can then go back to your Team in the Spark client, and you’ll see the individual is no longer listed under Team Members.
To remove the Team entirely, go back to the ‘Teams’ link on the left and select ‘Delete a Team’:
All you need for this is the teamID – same one used to view memberships earlier. Add it to the drop down, like you did with deleting the membership earlier, and hit Run. Confirm you really want to delete the Team, and if you get a 204 No Content on the right side, then the delete worked. If you then go back to your Spark client and hit the Teams option, you’ll see the Team you created is now removed from the list.
There are few other options, like updating a Team name, or changing someone to a moderator after they’ve already been added to the Team, but this covers the core of the Teams API and should get you started. If you have any questions, or have any trouble, please reach out to devsupport@ciscospark.com anytime, 24/7/365.
Justin Dupree, Global Manager, Collaboration API Support
