getUserDetailsFromEmail - How to format the emailAddress for queryParams?

[RichardD]

For /query/getUserDetailsFromEmail

What syntax should be used for specifying the email address please?

Documentation shows:

queryParams

Name Type Attributes Description emailAddress xs:string required once Email Address to search against

Tried the following (as JSON object syntax is used for various other methods) but unfortunately this doesn't seem to work:

 

queryParams = [ { "emailAddress": "foo@bar.com" } ]

Thanks in advance of your kind response.

[Victor]

@RichardD why are you using this, and for what purpose? I can tell you already that it won't give you what you are after, regardless of what you are after, since this is specifically and solely used by routing rule operations. However, we might be able to suggest a more appropriate API if we know what the objective is....

[RichardD]

Thank you.

I wish to get the open calls for a user using getCustomerRequests but I do not have the customerId value.
Was hoping the customerId would be returned by getUserDetailsFromEmail

[Victor]

5 minutes ago, RichardD said:

I wish to get the open calls for a user using getCustomerRequests but I do not have the customerId value.

@RichardD sorry to be a pain, but what do you need the customer open calls/requests for? Reporting? Something else? 

[RichardD]

No worries. We are using getCustomerRequests to display the users open calls in a widget on an self-service portal.
The widget shows the IN/SR number, the summary and a deep link to view the call.

The portal application is moving to a new platform and that platform unfortunately does not hold the unique identifier we used for the customerId in Service Manager.

Is there by chance a way to call getCustomerRequests using the user's email address instead of the customerId?

[Victor]

@RichardD for retrieving the list or requests I recommend https://api.hornbill.com/data/?op=entityBrowseRecords2. I assume you have the customer email address and we want to use that to get the customer/userID to filter the requests?

[RichardD]

5 minutes ago, Victor said:

@RichardD for retrieving the list or requests I recommend https://api.hornbill.com/data/?op=entityBrowseRecords2. I assume you have the customer email address and we want to use that to get the customer/userID to filter the requests?

Yes, filtering by customer email address sounds promising. Thank you.

The call status we would like to return are: status.open, status.new, status.onHold

[Victor]

@RichardD assuming the email address is unique for each customer (which should be I would think) then you can (also) use entityBrowseRecords2 to also retrieve the customer ID - the list of records should only contain one record here.

[RichardD]

@Victor Thank you.

We may make a single request, using the email address as a filter term, and the response would include both the list of open calls and the customer ID?

Or, we should make a request to return the customer ID based on email address filter and then a separate request to return the open calls with the customer ID as the filter?

[Victor]

1 minute ago, RichardD said:

we should make a request to return the customer ID based on email address filter and then a separate request to return the open calls with the customer ID as the filter?

^ This  

[RichardD]

Thank you.

[RichardD]

What is the entity name for a user/customer please?
Or perhaps the simpler question would be, which entity should I be specifying for the entityGetBrowseMetaData request please?
 

Name	Type	Attributes	Description
application	appNameType	optional	Specify the name of the application this operation relates to. If not specified then "system" is assumed.
entity	simpleIdType	required once	The name of the entity you want to query.

I wasn't having any luck trying to invoke https://api.hornbill.com/data/?op=entityGetBrowseMetaData to browse a list.

[Steve Giller]

2 hours ago, RichardD said:

No worries. We are using getCustomerRequests to display the users open calls in a widget on an self-service portal.

If you're displaying a User's Requests on a Self Service portal, would selfserviceGetRequests not be the correct API?
This does exactly that - gets a list of the the signed-in User's Requests ... you then just need to parse the list for Display.

[RichardD]

Thanks @Steve Giller We've done it in the past with getCustomerRequests but in this instance I need to retrieve the open calls for the customer based on their email address rather than the customer ID. I will take a look at selfserviceGetRequests though.

https://api.hornbill.com/apps/com.hornbill.servicemanager/Requests?op=selfserviceGetRequests

[Steve Giller]

3 minutes ago, RichardD said:

in this instance I need to retrieve the open calls for the customer based on their email address rather than the customer ID

I'm struggling to understand the scenario - if they're signed in, you shouldn't really need either.

[RichardD]

On 12/10/2023 at 17:17, Steve Giller said:

I'm struggling to understand the scenario - if they're signed in, you shouldn't really need either.

They are not signed in to Service Manager, they are accessing an internally hosted web application, within which we include a content section that displays their open Service Manager calls.

[RichardD]

On 12/10/2023 at 15:45, RichardD said:

What is the entity name for a user/customer please?
Or perhaps the simpler question would be, which entity should I be specifying for the entityGetBrowseMetaData request please?
 

Name	Type	Attributes	Description
application	appNameType	optional	Specify the name of the application this operation relates to. If not specified then "system" is assumed.
entity	simpleIdType	required once	The name of the entity you want to query.

I wasn't having any luck trying to invoke https://api.hornbill.com/data/?op=entityGetBrowseMetaData to browse a list.

@Victor Where may I find a list of the entity types please?
Getting 'The specified primary entity [Contact] was not found' on the various values I have tried.

[RichardD]

Working my way through search results and found the thread linked below which mentions 'Contact' and entityBrowseRecords2.
Attempting to format the query using xmlmc.AddParam()

xmlmc.AddParam("application", "com.hornbill.core");
xmlmc.AddParam("entity", "Contact");
xmlmc.AddParam("searchFilter", "[ { \"column_name\": \"h_email_1\"" +
                               ", \"column_value\": \"foo@bar.com\"" +
                               ", \"matchType\": \"Exact\" }" +
                               ",{ \"column_name\": \"h_contact_status\"" +
                               ", \"column_value\": \"0\"" +
                               ", \"matchType\": \"Exact\" }]");
xmlmc.AddParam("maxResults", 5);
xmlmc.Invoke("data", "entityBrowseRecords2");

 

[RichardD]

column_name should just be column
column_value should just be value

Still not quite there but feel like I'm getting close.
 

[RichardD]

On 12/10/2023 at 17:17, Steve Giller said:

I'm struggling to understand the scenario - if they're signed in, you shouldn't really need either.

FWIW. It is an optional widget, that users who rarely log calls in Service Manager will likely hide, limiting the requests to the API.
We also use local caching in the web application so it won't be making a request to the API every time they load/refresh our app.

[RichardD]

xmlmc = new XmlmcService(smInstanceOrUrl, smServiceEntryPoint, smWebDavEntryPoint, smApiKey, webProxy);

xmlmc.AddParam("application", "com.hornbill.core");
xmlmc.AddParam("entity", "UserAccount");
var searchFilterParams = new List<XmlmcParam>() {
    new XmlmcParam() { Name = "column", Value = "h_email" },
    new XmlmcParam() { Name = "value", Value= email },
    new XmlmcParam() { Name = "matchType", Value="exact" }
};
// -- TODO ? h_account_status = 0 for current user
xmlmc.AddParam("searchFilter", searchFilterParams);
xmlmc.AddParam("maxResults", 1);
xmlmc.Invoke("data", "entityBrowseRecords2");

var responseUA = xmlmc.GetResponseXMLDocument();
var doc = XDocument.Parse(responseUA.InnerXml);
var userRow = doc.XPathSelectElement("//row");

Thanks again for your help @Victor

The C# code above is retrieving a UserAccount object for the given email address.

I would like to add a second param to the search filter to only include UserAccount objects where the h_account_status = 0

 

I am also having trouble using entityBrowseRecords2 to retrieve Requests (is that the correct entity type?)
I have changed the application param to com.hornbill.servicemanager, or should I be able to target com.hornbill.core for open calls?
I'm getting the following error:
 

Quote

Hornbill.RequestFailureException: 'You need the right 'app.h.searchEntityRecords' to perform this entity operation'

 

[RichardD]

Permissions issue resolved. 

But, I am having trouble constructing an entityBrowseRecords2 search filter collection that matches a user AND one of the request status. If the matchScope is "any", the response understandably includes Requests matching the user AND matching any of the three specified status. A matchScope of "all" will not work as Requests will only match one status.

xmlmc.AddParam("application", "com.hornbill.servicemanager");
xmlmc.AddParam("entity", "Requests");

xmlmc.AddParam("matchScope", "any"); // -- need 'any' for the status filters but 'all' for user + status

xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
    new XmlmcParam() { Name = "column", Value = "h_fk_user_id" },
    new XmlmcParam() { Name = "value", Value= svcMgrUAID },
    new XmlmcParam() { Name = "matchType", Value="exact" }
});
xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
    new XmlmcParam() { Name = "column", Value = "h_status" },
    new XmlmcParam() { Name = "value", Value="status.onHold" },
    new XmlmcParam() { Name = "matchType", Value="exact" }
});
xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
    new XmlmcParam() { Name = "column", Value = "h_status" },
    new XmlmcParam() { Name = "value", Value="status.new" },
    new XmlmcParam() { Name = "matchType", Value="exact" }
});
xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
    new XmlmcParam() { Name = "column", Value = "h_status" },
    new XmlmcParam() { Name = "value", Value="status.open" },
    new XmlmcParam() { Name = "matchType", Value="exact" }
});

xmlmc.AddParam("orderBy", new List<XmlmcParam>() {
    new XmlmcParam() { Name = "column", Value = "h_datelogged" },
    new XmlmcParam() { Name = "direction", Value="descending" }
});
xmlmc.AddParam("maxResults", 10); // -- limit to ten
xmlmc.Invoke("data", "entityBrowseRecords2");

 

[RichardD]

@Steve G Thought it best to post in this thread, rather than the Python topic you kindly replied to me in previously.

https://docs.hornbill.com/esp-api/services/data/entityBrowseRecords2/index

Quote

Multiple values for the same column are always treated as a separate sub-criteria and ‘any’ value will match regardless of this setting.

If I'm not misunderstanding, shouldn't "all" work for me as the matchScope as I'm searching against multiple columns with my three 'h_status' column searchFilter params being treated as a sub-criteria with 'any' value matching?

[RichardD]

My apologies. The "all" matchScope is working.
Coincidentally, every user I tested my code against had a single call.
When I added "status.closed" as another searchFilter the request returned 10.

Thanks again for your help.

[RichardD]

@Victor @Steve G

Hi. I now need to also filter the Requests based on the service id.

I have tried h_service_id and h_fk_service_id without success.

I do not have access to the Entity Explorer, so would you be able to let me know the column name, please?

xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
     new XmlmcParam() { Name = "column", Value = "h_service_id" },
     new XmlmcParam() { Name = "value", Value="1" },
    new XmlmcParam() { Name = "matchType", Value="exact" }
});

For the benefit of anyone else stumbling on this thread, that might wish to wildcard filter Requests based on the Team ID the calls are assigned to, the following search filter worked well for me... where, for example, we had team IDs of "ABC/team1", "ABC/team2" and "DEF/team1" and we want to only include the ABCs.

xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
    new XmlmcParam() { Name = "column", Value = "h_fk_team_id" },
    new XmlmcParam() { Name = "value", Value="ABC/" },
    new XmlmcParam() { Name = "matchType", Value="wildcard" }
});