Query for conversations in a space by a member
This topic explains how to query for conversations by member in Agility.
What
I would like to get a detailed list of a member’s Conversations in a space.
How
The following tutorial uses the query.v1 endpoint to obtain Conversation/Expressions data. While there are other approaches, query.v1 is the preferred approach that returns results efficiently in a single query.
The query.v1 endpoint was introduced in Release 13.2, Summer 2013. Please view the About Digital.aiAgility information from the help icon in the menu bar to see if you are on this release or later.
Getting Started
- Have an HTTP Client, or use
<Server Base URI>/http.html. - Obtain an API token, or post directly to the query.v1 endpoint.
Query parameters
from
You can view Conversations on any asset by an author. For this example, we want to find out our own conversations from a space. However, you can build a similar query for Conversations for an asset, Conversations in a Team room etc
For our query, the from is Expression. This means the primary query is about Expression assets.
from: Expression
If our query only has a from parameter, we get a default set of attributes. To return only selected attributes, add a select parameter to your query.
select
To select attributes, you will need to find the system name for the attribute you want to return. Attribute names can be found by querying meta, or meta.v1. To see the attributes available for Expression, run the following query by pasting it into your browser address bar and pressing return.
<Server Base URI>/meta.v1/Expression?xsl=api.xsl
The result will resemble the following, except with many more attributes.
Expression
* Author : Relation to Member — reciprocal of Expressions
* AuthoredAt : Date
* Content : Text
BelongsTo : Relation to Conversation — reciprocal of ContainedExpressions
InReplyTo : Relation to Expression — reciprocal of Replies
Mentions : Multi-Relation to BaseAsset — reciprocal of MentionedInExpressions
AssetState : State
AssetType : AssetType
ChangeComment : Text
ChangeDate : Date
ChangeDateUTC : Date
ChangedBy : Relation to Member
ChangeReason : Text
CreateComment : Text
We can use any of the attributes directly in the select. Let's add Author and Content, Mentions, Replies and Replies Mentions.
from: Expression
select:
- Author.Name
- Content
- Mentions.ID
- Replies.Content
- Replies.Author.Name
- Replies.Mentions.Name
where or filter
If our query does not have a where or filter parameter, the results will include every Conversation or Expression. Since I want Conversations authored by a particular member in a space, I want to filter by Author.Name and ExpressionSpace.Name. And, I do not want to see the replies by this author in the results as an individual conversation. I am filtering the conversations which are having a value in InReplyTo attribute.
from: Expression
select:
- Author.Name
- Content
- Mentions.ID
- Replies.Content
- Replies.Author.Name
- Replies.Mentions.Name
- BelongsTo.ExpressionSpace.Name
where:
BelongsTo.ExpressionSpace.Name: <Space Name>
Author.Name: <Member Name>
InReplyTo: NULL