Questions about using Guru's API to update a Card's verifier
Hey folks, first time caller long time fan :wave: We're in the process of adapting how one of our teams verifies content in Guru to more closely align with our KCS methodology. We've built an MVP where once a card has been added to a custom field in Zendesk and the ticket is submitted, we catch the hook, get the card ID from the Guru URL, and once it passes our validation, use PUT to update the card's verifier. We want to be able to set the verifier of the card as the ticket submitter, verify said card, and set its verification interval to 90 days.
The MVP is functioning as expected but we've hit a roadblock with API credentials. The issue is that AFAIK we don't have a general or admin API token with read/write access. The collection API token would work for our use case, but they're read-only.
As a result, while we can assign the card to the SME who submits the ticket, we can't set the verification status to trusted. Without the ability to do so its purpose is defeated. Any suggestions on resolving or working around this? Can we get a general token with read/write access?
Additionally, while building out the MVP we ran into a couple of issues that we think would be useful feature requests. I've added them to the thread :slightlysmilingface:
Hi @ruairi.murphy , our engineers are still working on the documentation for managing and issuing individual tokens for you to use when changing the verifiers. In the meantime, we are hoping to help with your other questions:
1. *Can we work around having to update the card content when changing the verifier through the API?* You can do a POST call to this url `https://api.getguru.com/api/v1/cards/{cardid}/verifiers/` to change the verifier and that doesn't make a new version of the card.
2. *Why is `Preferred Phase` the object for the card title?* Our original thinking (back when Guru was just the extension :exploding_head:) was that cards could have multiple "phrases" associated with them and one would be designated as the "preferred" one and that'd be used as the title. A basic rule of thumb is that we don't want to make object changes that could break other clients solutions, so that is now the object name.
3. *It doesn't appear to be possible to query team members by email, which would be useful.* Are you looking for cards by user? Or looking to find team members? Either way I think you'd use emails. We never use the 32-digit IDs for users like we use for cards or collections, the unique ID for a user is their email address. We have query language for User Expressions used to filter cards associated for specific users using their emails - example would be `creatorId = ""` cards created by Gary (see query language documentation for more details.)
4. *We're wondering why `dateCreated` is required as part of the `verifier` object?* What API call is this for? Curious why this would be required as well :thinking_face:
5. *SDK?* In Q2, we are focusing on improving our documentation with more endpoints exposed and writing new use cases on our developer page, so unfortunately we are not focusing on any SDK research/build out this quarter.
• Can we work around having to update the card content when changing the verifier through the API?
- Does this also happen when using the API to change the collection or board the card belongs in?
- This is an issue as it will create an unnecessary card version in the Revision History every time a card is updated regardless of whether or not the content itself changes.
• The `Preferred Phase` fires back an error, title needs to be included, which is misleading. Why is `Preferred Phase` the object for the card title?
• It doesn't appear to be possible to query team members by email, which would be useful.
• We're wondering why `dateCreated` is required as part of the `verifier` object?
Hi @ruairi.murphy thanks for posting! We're checking on this and will follow up soon.
Hi Ruairi, fantastic use case going on here with the KCS methodology :raised_hands:. I checked with our engineering team and they think the best way would be to use the user token of the individual you are setting as the verifier (which means you would need to have Admin privileges to issue individual tokens via the API). One of our engineers is working on providing some documentation so we can share this workaround with you.
I am working with one of our engineers on your card versioning question as well, so hopefully I can provide you more details/answers by tomorrow. Sorry for the delay in response - the Token question was quiet the fun riddle for our team :relaxed:
Brilliant, thanks Mary :raised_hands: That makes sense and should be an ideal workaround. I really appreciate the engineers creating some guiding documentation too.
Out of interest, have there been any further developments regarding a timeline or potential release date for the SDK mentioned during your Extending Guru through the API presentation last December?
As someone who's not a dev by trade, it would definitely help me and my team bring a couple of our ideas to fruition. For instance, I intend to leverage your API to build out a custom analytics dashboard, similar to the awesome project <@UNDEN3NBV> presented on :slightlysmilingface:
Hi @ruairi.murphy , our engineers are still working on the documentation for managing and issuing individual tokens for you to use when changing the verifiers. In the meantime, we are hoping to help with your other questions:
1. *Can we work around having to update the card content when changing the verifier through the API?* You can do a POST call to this url `https://api.getguru.com/api/v1/cards/{cardid}/verifiers/` to change the verifier and that doesn't make a new version of the card.
2. *Why is `Preferred Phase` the object for the card title?* Our original thinking (back when Guru was just the extension :exploding_head:) was that cards could have multiple "phrases" associated with them and one would be designated as the "preferred" one and that'd be used as the title. A basic rule of thumb is that we don't want to make object changes that could break other clients solutions, so that is now the object name.
3. *It doesn't appear to be possible to query team members by email, which would be useful.* Are you looking for cards by user? Or looking to find team members? Either way I think you'd use emails. We never use the 32-digit IDs for users like we use for cards or collections, the unique ID for a user is their email address. We have query language for User Expressions used to filter cards associated for specific users using their emails - example would be `creatorId = ""` cards created by Gary (see query language documentation for more details.)
4. *We're wondering why `dateCreated` is required as part of the `verifier` object?* What API call is this for? Curious why this would be required as well :thinking_face:
5. *SDK?* In Q2, we are focusing on improving our documentation with more endpoints exposed and writing new use cases on our developer page, so unfortunately we are not focusing on any SDK research/build out this quarter.
Thanks so much for your detailed response. Apologies for the delay on my end, the joys on traversing timezones.
1. This is interesting! We must have missed it but it didn't seem clearly documented that there's a *card/{card id}/verifiers* endpoint. We're glad it's there, and we can definitely look to migrate to using that instead.
2. That makes total sense, API versioning is not something you want to take lightly :sweat_smile:
3. Honestly, I documented this query early on in building out our solution and I believe it was when we were trying to lookup the card. I can't recall exactly what our use case was for querying by email, but thanks for clarifying. Guru Query language is very interesting though! We think we can possibly use that for the SME groups we're going to create too.
4. We actually don't include the DateCreated as part of the verifier object, the current object that we use in the API request is:
```"verifiers": [
{
"type": "user",
"user": {
"email": "{{email}}"
},
"id": "{{email}}"
}
],```
5. That's unfortunate as it would be really useful, but it makes total sense. Looking forward to seeing it come to fruition.
Hi @ruairi.murphy ! Thanks again for your patience in the API Token management documentation. To help your process of assigning the agent as the verifier and ensuring that the said agent can toggle the new card to trusted, you will need to use individual user tokens for each agent. In order to manage, issue, and assign those individual user tokens, you can find the documentation in this card.
Great project in aligning KCS methodology, so please let me know if you and the team have other questions about our API limits!
Enter your E-mail address. We'll send you an e-mail with instructions to reset your password.