API Call - com.hornbill.servicemanager/Requests?op=getCustomerRequests

[Joshua T M]

Hi All,

 

Would you be able to let me know the expected attributes for the parameters of the API call below -

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

 

i.e. Should the Customer ID just be passed as a number, What format should the "Query String" be..? etc.

Can you also double check the optional parameters are indeed optional and the order is correct?

[James Ainsworth]

Hi @Joshua T M

I'm afraid that I don't have a great deal of knowledge in this area, but I would say that the requests can have two types of customers - contacts or users.  While the ID of contacts is numerical, the users can be alphanumeric.  On the Request table, the field that holds the customer ID is a varchar so I'm assuming that it should be passed as a string.

I hope that helps.

Regards,

James

[Joshua T M]

Hi @James Ainsworth, 

 

Unfortunately I require more information, we need to effectively know what we should be passing for each of the parameters as the documentation doesn't show any types and unfortunately as we have found in the past not all fields are "optional".

 

If someone could create a basic example that is known to work and return the relevant JSON we would have a better understanding. Would one of your team be able to provide this?

[ArmandoDM]

Hi @Joshua T M

the params are all in string format.
Only 'queryName' and 'resultType' are required, and their possible values are as per documentation.

About the other params:

queryString: deprecated
userId: ID of request's owner
customerId: ID of the request's customer (as James mentioned, this can be numeric or alphanumeric depending on the customer type - contact or user)
statusFilter: the request status, as specified in the documentation
requestType: additional request type, on top of Incidents and Service Requests

For example:

  <queryName>getCustomersRequests</queryName>
  <resultType>allData</resultType>
  <userId>joshuatm</userId>
  <customerId>armandodm</customerId>
  <rowstart>0</rowstart>
  <limit>10</limit>
  <statusFilter>status.open</statusFilter>
  <statusFilter>status.new</statusFilter>
  <requestType>Change Request</requestType>

will return the first 10 requests (rowstart=0, limit=10) where:

joshuatm is the owner, 
AND
armandodm is the customer
AND
the status of the request is open OR new
AND
the request type is Incident OR Service Request OR Change Request

The list of requests are returned in JSON format as shown in the image

 

I hope that helps

Regards

Armando

[jeffgleed]

Thanks for the info. I have got to admit that the API documentation is quite hard to use so I have another related question. I want to get a single request record by reference. Initially I trued to use (what I though was obvious) getRequestRecord. Whilst this works, the format of the data is wildly different than the getCustomerRequests i.e. it includes a load of low level stuff and omits quite a lot of the textual information of use the end user. I can't see an obvious way of getting a request in the same (or similar) format to that returned by getCustomerRequests. Can anyone suggest how to do this? I did attempt to use the queryString but, as you mention, it's deprecated and it's completely not documented so it's pretty useless anyway.  

[Victor]

@jeffgleed just to confirm... are you looking for documentation/information about Hornbill or Supportworks products?

[jeffgleed]

Both, we currently use SW but may be upgrading at some point to Hornbill. We are building a REST API  to hide complexity and to make the upgrade from our existing API client apps more straightforward.

[Victor]

@jeffgleed ah, ok, just to make sure the advice provided is relevant (i.e. regarding Hormnill APIs)

[jeffgleed]

I am obviously missing something important:

I am using the Sandbox. If I login to Hornbill as GrahamC and list all the Requests for John Brown (by typing John Brown into the search box) it returns 12 items with each of them showing 'John Brown' under the customer name colum and no owner.

IF I then run the following API

            xmlmcService.AddParam("queryName", "getCustomersRequests");
            xmlmcService.AddParam("resultType", "allData");
            xmlmcService.AddParam("customerId", "johnb");
            xmlmcService.AddParam("limit", "200");
            xmlmcService.Invoke("apps/com.hornbill.servicemanager/Requests", "getCustomerRequests");

I get 15 requests returned. The first 12 are the same ones as showin in the user interface. I have no idea what the final 3 are. Also, johnb comes back as the user id (despite being blank in the UI) but no customer id is returned. Can someone explain what is being returned please?

[{"h_pk_reference":"IN00000251","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":{"@raw":"2017-06-27 16:17:05","#text":"2017-06-27 17:17:05"},"h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:07302090-aeca-44ec-a9f5-e7ed17ddc339","h_datelastmodified":{"@raw":"2017-06-27 16:17:04","#text":"2017-06-27 17:17:04"}},{"h_pk_reference":"IN00000263","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":{"@raw":"2017-08-22 16:17:05","#text":"2017-08-22 17:17:05"},"h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:5c9ca14a-a9b8-4590-bad3-255502ae68be","h_datelastmodified":{"@raw":"2017-08-22 16:17:05","#text":"2017-08-22 17:17:05"}},{"h_pk_reference":"IN00000290","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":"2017-12-12 17:17:06","h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:58c28827-6a59-4859-b8ab-1533acb69e09","h_datelastmodified":"2017-12-12 17:17:06"},{"h_pk_reference":"IN00000302","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":"2018-02-06 17:17:08","h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:f19db3a3-f7a6-4531-bce3-7f5360882d40","h_datelastmodified":"2018-02-06 17:17:08"},{"h_pk_reference":"IN00000317","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":{"@raw":"2018-04-03 16:17:03","#text":"2018-04-03 17:17:03"},"h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:3f19706c-7d86-43cb-955e-08170a191e26","h_datelastmodified":{"@raw":"2018-04-03 16:17:03","#text":"2018-04-03 17:17:03"}},{"h_pk_reference":"IN00000324","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":{"@raw":"2018-05-29 16:17:02","#text":"2018-05-29 17:17:02"},"h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:eacf2d9b-89af-427d-98bc-6d38d37d6fcd","h_datelastmodified":{"@raw":"2018-05-29 16:17:02","#text":"2018-05-29 17:17:02"}},{"h_pk_reference":"IN00000368","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":{"@raw":"2018-07-24 16:17:03","#text":"2018-07-24 17:17:03"},"h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:6586f617-3f3d-414f-9187-24dcf890ac95","h_datelastmodified":{"@raw":"2018-07-24 16:17:03","#text":"2018-07-24 17:17:03"}},{"h_pk_reference":"IN00000380","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":{"@raw":"2018-09-18 16:17:06","#text":"2018-09-18 17:17:06"},"h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:8ec76aa1-11e7-491a-8c27-509444dd3d87","h_datelastmodified":{"@raw":"2018-09-18 16:17:05","#text":"2018-09-18 17:17:05"}},{"h_pk_reference":"IN00000420","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":"2018-11-13 17:17:33","h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:25c797e9-43ae-4ef8-a603-29f3b1fe34d3","h_datelastmodified":"2018-11-13 17:17:33"},{"h_pk_reference":"IN00000453","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":"2019-01-08 17:17:04","h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:8eea6559-3c62-4aca-a7d4-e15e63625fb1","h_datelastmodified":"2019-01-08 17:17:03"},{"h_pk_reference":"IN00000488","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":"2019-03-05 17:17:04","h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:c5b5f4b1-e9a2-4776-802f-ccf118eb6bc1","h_datelastmodified":"2019-03-05 17:17:04"},{"h_pk_reference":"IN00000517","h_summary":"Lync Issues","h_description":"Lync Issue, See question section for more info","h_fk_user_id":"johnb","h_requesttype":"Incident","h_status":"status.open","h_datelogged":{"@raw":"2019-04-30 16:17:01","#text":"2019-04-30 17:17:01"},"h_fk_priorityname":"Low","h_activity_stream_id":"urn:buzz:activityStream:145eadec-f09f-4e6d-9c7c-3a0d178cfc4d","h_datelastmodified":{"@raw":"2019-04-30 16:17:01","#text":"2019-04-30 17:17:01"}},{"h_pk_reference":"SR00000442","h_summary":"Dental Care Query","h_fk_user_id":"johnb","h_ownerid":"annab","h_requesttype":"Service Request","h_status":"status.open","h_datelogged":"2018-12-19 17:40:59","h_activity_stream_id":"urn:buzz:activityStream:80268f85-48bc-4e4e-ab2a-af6d35d35fe3","h_datelastmodified":"2018-12-19 17:40:59","customer_name":"Anna Bishop","icon":"42/0000000047"},{"h_pk_reference":"SR00000477","h_summary":"Dental Care Query","h_fk_user_id":"johnb","h_ownerid":"annab","h_requesttype":"Service Request","h_status":"status.open","h_datelogged":"2019-02-13 17:41:00","h_activity_stream_id":"urn:buzz:activityStream:a9d11b1c-d549-453b-8f42-5b5f0ac0d276","h_datelastmodified":"2019-02-13 17:41:00","customer_name":"Anna Bishop","icon":"42/0000000047"},{"h_pk_reference":"SR00000506","h_summary":"Dental Care Query","h_fk_user_id":"johnb","h_ownerid":"Leea","h_requesttype":"Service Request","h_status":"status.open","h_datelogged":{"@raw":"2019-04-10 16:40:55","#text":"2019-04-10 17:40:55"},"h_activity_stream_id":"urn:buzz:activityStream:05e70012-e58c-4308-9a18-2e27ee239f2c","h_datelastmodified":{"@raw":"2019-04-10 16:40:55","#text":"2019-04-10 17:40:55"},"customer_name":"Lee Alders","icon":"39/0000000072"}]

[Victor]

7 minutes ago, jeffgleed said:

typing John Brown into the search box

Searching is not using the getCustomersRequests API, is using (iirc) entitySearch API (https://api.hornbill.com/data/?op=entitySearch)

Look in the browser dev console when you perform the search in the UI, it should tell you which APIs are invoked...

[jeffgleed]

Ok .. I have run the application whilst debugging in Chrome. When I list all Requests (the sandbox currently has 291 with 253 open). This triggers a call to smGetRequests with the following request payload

<methodCall service="apps/com.hornbill.servicemanager/Requests" method="smGetRequests" trace="user/com.hornbill.servicemanager" csrf_token="a333f2bdcec0fc8b77409a78ec9013223701b0cb"><params><typeEquals>Incident</typeEquals><typeEquals>Service Request</typeEquals><typeEquals>Change Request</typeEquals><typeEquals>Problem</typeEquals><typeEquals>Known Error</typeEquals><typeEquals>Release</typeEquals><statusEquals>status.resolved</statusEquals><statusNotEquals>status.closed</statusNotEquals><serviceEquals>153</serviceEquals><serviceEquals>23</serviceEquals><serviceEquals>5</serviceEquals><serviceEquals>20</serviceEquals><serviceEquals>101</serviceEquals><serviceEquals>19</serviceEquals><serviceEquals>186</serviceEquals><serviceEquals>12</serviceEquals><serviceEquals>193</serviceEquals><serviceEquals>62</serviceEquals><serviceEquals>132</serviceEquals><serviceEquals>25</serviceEquals><serviceEquals>14</serviceEquals><serviceEquals>184</serviceEquals><serviceEquals>15</serviceEquals><serviceEquals>16</serviceEquals><serviceEquals>96</serviceEquals><serviceEquals>139</serviceEquals><serviceEquals>125</serviceEquals><serviceEquals>21</serviceEquals><serviceEquals>22</serviceEquals><textFilter>%</textFilter><rowstart>0</rowstart><limit>100</limit><optgroupBy>none</optgroupBy><orderByColumn>h_datelogged</orderByColumn><orderByDirection>descending</orderByDirection></params></methodCall>

If I try to run it from my application using the API key attached to Graham C (The same user I logged in with) I get ....

<?xml version=\"1.0\" encoding=\"utf-8\"?><methodCallResult status=\"ok\"><params><count>0.000000</count><exception>You do not have the rights to view the selected request types.</exception></params><flowCodeDebugState><step>61c615fc-56f0-4f9b-9a2b-3a28fc86c823</step><executionId>a316f04e-bec8-4929-9639-973a2301ccd9</executionId></flowCodeDebugState></methodCallResult>

This seems at odds with your previous comment taht the GUI uses entitySearch. Was this just a mistake or am I still not calling the right thing. Also, I seem to be unable to access the data via the API even though I can run the call when loged into Hornbill.

Regards

Jeff

 

[Victor]

OK, so I don't remember correctly, global searching for requests is not using entitySerach API (this is used elsewhere). So:

Searching requests using Global search:

This is using the searchRequests API:

<methodCall service="apps/com.hornbill.servicemanager/Requests" method="searchRequests" csrf_token="f11107d57b2d3979e5d70a5c90b9e8f85ccb96e0">
  <params>
    <searchQuery>12345</searchQuery>
    <resultsFromRow>0</resultsFromRow>
    <resultsToRow>9</resultsToRow>
  </params>
</methodCall>

The smGetRequests runs as you noticed when accessing requests list. However, the API payload depends on what Home view has been set for the user.

I am not sure and can't say why running smGetRequests API with the payload you posted returns that message. For me, it works fine when testing it from here (same instance, same user, same payload)....  

 

But perhaps we can approach this from a different angle... What exactly are you trying to achieve using APIs?  

[jeffgleed]

Thanks, yeah that sounds sensible ...

We are developing a new AI based conversational (Chatbot type) application which provides information for users on a wide range of applications (about 70 ... of which Supportworks/Hornbill is just one). From the support application perspective we want to be able to:

• Get a list of call raised/owned by a specific user (in a nice concise form) .
• Same thing for a single call ref
• Create a new call to be owned by the user but actioned by the Chatbot application.
• Cancel a call by call ref
• Update the status of a call by call ref. 

The new Chatbot is intended to be the primary interface for all our applications and, if required, should be able to automatically setup a support call (as if it were going to be actioned by a real person), perform the action (via any of our applications) and close the call when the action has been completed. The plan is to abstract to this application outside of any single 3rd party product so we do not become dependent on it for all time. The Chatbot is heavily based on Microsoft Cognitive AI services and has already been subject to considerable investment. The decision on whether to purchase any 3rd party applications will be heavily dependent on our ability to access it's data via this Chatbot.

Hope that all makes sense.

[Victor]

@jeffgleed ah, ok, yes makes sense and I do have a better understanding where you are aiming at... In a nutshell, everything you mentioned on the dotted list can be achieved by either using APIs directly or by using the Hornbill iBridge mechanism (to a certain extent). Usually these scenarios are part of the discussions taking place during Switch On activities and this would benefit a conversation with a Product Specialist to scope this more precisely to ensure that a) you receive all the information you need and b) get insight into other aspects and functionality that you might not be necessarily aware that would help you with this integration. I understand your organisation is considering undergoing a Switch On trial, may I suggest this being discussed then?

It might also be the case that you are building a proof of concept right now in which case we will try to assist you on individual queries but we won't be able to have a wider conversation on forums regarding your integration  

But back to your queries:

Get a list of call raised/owned by a specific user

IMO, the best API to use for this would be entitySearch (https://api.hornbill.com/data/?op=entitySearch). The challenge here is obviously constructing the payload as this is one of the least friendly APIs. The issue using any of the Request type APIs is the inherent limitations built in these APIS as they are designed for a certain purpose in Hornbill. For example, smGetRequests purpose is, as mention in the documentation, to "return the total request count matching the supplied filter criteria and a limited number of request results". As such is not best suited to return ALL requests using certain criteria (it may but it also may not)

Same thing for a single call ref

I am sticking to entities here and would say best to use here is entityGetRecord (https://api.hornbill.com/data/?op=entityGetRecord). Again, not a friendly API so we would need to work on how the payload looks like.

Create a new call to be owned by the user but actioned by the Chatbot application

You can have the Chatbot app invoke any APIs that actions on a request, for example, the "log" APIS and update, assign, resolveRequest, etc.

Cancel a call by call ref

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

Update the status of a call by call ref

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

 

Obviously, this is a very high-level overview and advice but my main intention is to show that it can be done and point to some areas where one can look into 

[jeffgleed]

Ok cool .. As you guessed we are trying to put together a POC now. The REST API I have written uses a plug-in model so we should be able to switch between SupportWorks and Hornbill ESP should we need to. I am just trying to get both the plug-ins working which is not as straightforwards as I had hoped!

Some help creating the queries would be appreciated e.g. an example call for entitySearch which returns all calls for the customer_id="johnb" and the ability to filter by status would be good. I can't find anything in the forums or via Google. I assume the format of the searchQuery would be something like customer_id:"johnb" but I can't really even guess what the parameters for entity would be.

Thanks for the help

Jeff

 

[Victor]

Actually, the search query is not that is the name of a built-in query... I'll try and find the one that you need. The entity, on the other hand, is rather simple as it is: "Requests". They are easy to miss in the documentation but they are right there

So basically any bolded section like the one I highlighted is an entity. Requests is an entity and can be found further down the page  

[jeffgleed]

Ok I missed that. If there are built in queries that would be excellent.

 

[jeffgleed]

I was having a play around with the Hornbill ESP web site and I noticed that, if I create a custom View it runs some simpler code:

<methodCall service="apps/com.hornbill.servicemanager/Requests" method="smGetRequests" trace="user/com.hornbill.servicemanager" csrf_token="a333f2bdcec0fc8b77409a78ec9013223701b0cb">
    <params>
        <customerEquals>johnb</customerEquals>
        <rowstart>0</rowstart>
        <limit>100</limit>
        <optgroupBy>none</optgroupBy>
        <orderByColumn>h_datelogged</orderByColumn>
        <orderByDirection>descending</orderByDirection>
    </params>
</methodCall>

Unfortunartely, if I try and execute the request I get  the following:

<methodCall service="apps/com.hornbill.servicemanager/Requests" method="smGetRequests" trace="user/com.hornbill.servicemanager" csrf_token="a333f2bdcec0fc8b77409a78ec9013223701b0cb">
    <params>
        <customerEquals>johnb</customerEquals>
        <rowstart>0</rowstart>
        <limit>100</limit>
        <optgroupBy>none</optgroupBy>
        <orderByColumn>h_datelogged</orderByColumn>
        <orderByDirection>descending</orderByDirection>
    </params>
</methodCall>

Which seems odd to me as I am using the API Key associated with the system administrator. I seem to be ab;le to make almost any other API call, just not this one! Would getting this one working give me what I want as it seems pretty flexible?

 

 

 

[SamS]

Hi @jeffgleed,

It appears that you have accidentally copied the request XML instead of the response XML.

If your result is the following, then no results are being returned:

<methodCallResult status="ok">
  	<flowCodeDebugState>
		<step>...</step>
		<executionId>...</executionId>
	</flowCodeDebugState>
</methodCallResult>

If you want to verify this, then just drop the "customerEquals" element to return 100 rows.

If you have a permissions error, you might need to ensure your system administrator account has "Service Manager" and "Service Desk Admin" Security Roles.