My first attempt at managing Syncplicity with Alexa Skill, while rather crude, it was a success in dipping my toe into the waters of the API ocean and so I decided to see what I could achieve next.
Syncplicity with Alexa
Listing and counting the users, groups and policies within my Syncplicity account had been a fairly simple task using straightforward API calls. This time, I wanted to plunge in a little deeper by cross-referencing information from different APIs. So, rather than just ask about users or groups, I’d try finding out such things as what groups does a user belongs to and which users are members of a group.
Working out the API calls
I started by trying to find out the groups that a user belongs to. Looking at the Syncplicity APIs, there already exists an API for this name, “Get groups which include a user.” A perfect start!
I read the documentation and it only works if you pass it the user’s GUID. Hmmm, so I can’t just pass along a user name. Thinking about it, I guess it’s possible that there might be two “Claudio Tinnirello’s or two “John Doe’s, in the account so using a unique ID to pinpoint the exact user makes sense. Luckily, my prior use of the “Get users” API returned this unique GUID along with the first name and last name.
My flow for this seems to be: 1) make an API call to get the user’s GUID; 2) make the API call to get the groups for that user’s GUID.
I wondered if this would be like finding out the users in a group? Looking at those APIs, there’s an API named “Get members of a group” and, yes, it also required a unique GUID for the group so this is turning out to be very similar.
The flow for this variation seems to be: 1) make an API call to get the group GUID; 2) make the API call to get the members of that group’s GUID.
Ok, now that I’ve got the API calls worked out, how do I get Alexa to perform these tasks?
Working out the dialogue for Alexa
Calling an API from a script, or program is simple in that you can just run the script or program, and see the results. Naming that script something like “list_a_user’s_groups.sh” and passing it arguments, such as the username, seems to be fairly standard practice and it works because you can supply the arguments by typing them exactly as you need them to be.
For example, I could run my script by typing “list_a_user’s_groups.sh firstname.lastname@example.org” and the script would understand what email@example.com is. But how do you achieve this using only your voice with Alexa?
Alexa has an amazing grasp of language and names, but technical items, such as email addresses or GUIDs, are not things that come naturally when uttered verbally. In my head, I imagine the conversation that I’m about to have: “Alexa, ask My Administrator to list the groups that see Tinnirello at sign Axway dot com belongs to.” Hmmm, doesn’t exactly roll off the tongue.
Obviously, I need to rethink this in terms of a conversation with Alexa.
Amazon’s developer portal gives some great guidance for designing conversations for Alexa Skills. After reading those guides, I decided to let Alexa guide me rather than trying to make her understand technical terms. If I can give her the gist of what I’m trying to achieve, then she can guide me to completion.
I started by asking Alexa to perform the task and then design the conversation so she would ask me to confirm more details using questions that could be answered with a “yes” or “no.”
My conversation flow would be something like this:
- “Alexa, ask My Administrator to list a user’s groups.”
- “OK, would you like to hear Adam’s groups?”
- “OK, would you like to hear Betty’s groups?”
- “OK, would you like to hear Claudio’s groups?”
- “Yes, please.”
- “Claudio belongs to the following groups: API Group, Customer Success, Geeks, and US Cloud Storage Group. Would you like me to repeat that?”
- “No thanks.”
- “OK, would you like to hear Deborah’s groups?”
- “OK, goodbye.”
By looping through the list of users, Alexa can prompt me for a “yes” or “no.” This has got to be so much easier than trying to pronounce uncommon names, such as my own, and hoping that Alexa understands correctly!
I can implement other command words, such as “stop” or “exit,” besides reacting to the “yes/no” replies. I’m already envisioning navigation command words such as “skip 5,” “go back 10,” or even “start at letter K” but let’s hold off on those until I get the simple “yes” and “no” navigation working.
I’ll use the same conversation flow for asking about the members of a group so, once I have “list a user’s groups” working, I can reuse this flow wherever I need it.
Using My Administrator Skill
Here goes. “Alexa, ask My Administrator to list a user’s groups.” Alexa replies by listing the users, using first and last names, and then asking me if I’d like to hear the groups that they belong to.
Brilliant! I reply in the affirmative and Alexa proceeds to read out loud the groups that this user belongs to. No matter how obscure or unusual the group name is, Alexa does her best to pronounce it which, honestly, is much better than asking me to do it. When I reply in the negative, Alexa moves on to the next user. This interaction continues until I ask Alexa to stop.
So far, so good
So far, so good! Now let’s try the other way around. “Alexa, ask My Administrator to list a group’s members.” Alexa replies by listing the groups then asking me if I’d like to hear the users that belong to that group. Very nice! I reply in the affirmative and Alexa proceeds to read out loud the users that belong to this group. She reads out the first and last names and, if no first and last name exists, she’ll read out their email address instead. When I reply in the negative, Alexa moves on to the next group. This interaction continues until I ask Alexa to stop.
Just like the first time, these two new API calls also provide text feedback to the Alexa App in the form of “cards” that appear in the “Activity” section. Alexa’s replies to the above conversations appear in the Alexa App so I can easily refer to the App to see an audit trail of all the output from my conversation. How very handy!
Once again, I’m pleasantly surprised at how easy it can be to manage my Syncplicity account using Alexa.
I see the potential to go further and start actively managing Syncplicity. Rather than just reading back to me the status of my users and groups, I envision the ability to add, remove and update users and groups. Adding might be an issue as I’ll have to pronounce user and group names in such a way that Alexa understands and doesn’t auto-correct for me.
“Alexa, ask My Administrator to create a group called BU123.” “OK, I’ve created a group called Bee You Won To Three.” Yikes! However, tasks such as disabling or deleting should be easy as Alexa can read back the user or group name to me and then ask for confirmation before performing the action.
Not bad. I still haven’t added a “welcome” and “help” option to this Alexa Skill but I like where it’s going.
Learn more about Syncplicity by Axway, a visionary file sharing platform.