sendEntityTemplateMessage: Dude, where's my template?

[Stuart Riddell]

Hi folks,

I'm trying to use sendEntityTemplateMessage to send an automated email to a customer.  The problem is translating the template URL into something that the_template_value will accept.

 

xmlmc.AddParam("application", "com.hornbill.servicemanager")
xmlmc.AddParam("entity", "Request")
xmlmc.AddParam("recordId", Reference)

xmlmc.AddParam("template", the_template_value)

 

I've seen too many  "Failed to get template" messages to continue.

The documentation doesn't help: 

• The path to the the template you wish to use to base the e-mail message on. You can specify either a relative path which will look for the template in the folder of the mailbox from which you are sending this message, or you can specify a fully-qualified path by starting with the "/" character which will locate the template from the absolute location from /dav/.

 

The templates don't appear to be stored in any mailbox folder, since we can use them in emails from either the live or training mailboxes without any issue.

Without any documentation explaining where /dav/ exists in relation to the /email/, I've not been able to find a suitable option.

 

 

So how do I convert the link below from the Hornbill Administrator into a link that sendEntityTemplateMessage will accept.

https://admin.hornbill.com/{InstanceID}/email/templates/com.hornbill.servicemanager/Requests/Service-IncidentUpdate-External/

 

[Victor]

@Stuart Riddell have you tried "Service-IncidentUpdate-External" as the value for the template param?

EDIT: that would be the template ID in the screenshot above

[Victor]

Also, the value for the entity param is incorrect:

xmlmc.AddParam("entity", "Request")

This needs to be:

xmlmc.AddParam("entity", "Requests")

If you tried the template ID before and it failed with "Failed to get template" messages this is most likely due to the incorrect entity value.

[Victor]

You also need the mailbox param if you use sendEntityTemplateMessage

[Stuart Riddell]

Hi Victor,

 

It was the "Request" vs "Requests" that was the issue, so thanks for spotting that.

 

It's sent the email but not added it to the request's timeline as I would have expected.  I'm passing in the request's h_pk_reference .  Is this correct for the recordId?   Or should it be the h_activity_stream_id or something else?

 

I'd left out the mailbox and other optional parameters for clarity in the original post.

[Victor]

4 hours ago, Stuart Riddell said:

It's sent the email but not added it to the request's timeline as I would have expected.  I'm passing in the request's h_pk_reference .  Is this correct for the recordId?   Or should it be the h_activity_stream_id or something else?

Mmmm... no, it won't do anything else but to send the email. I can sort of see why you would think it would do more (like add this to the request timeline). I'll try explain below what's and how's. The correct value for the record ID, if the entity used is "Requests" is the request reference, so you have the correct value there.

If you look at https://api.hornbill.com/ you notice a list of Services. Each of these services have their own list of APIs. One to mention specifically is the "apps" service which contains basically application APIs, like Service Manager APIs or Board Manager APIs. All application APIs will make use of other services APIs (like mail or data) to achieve a certain functionality. I'll give you an example: 

https://api.hornbill.com/apps/com.hornbill.servicemanager/Requests?op=smSendMessage. This API is the one used when an analyst/user sends an email from a request (using the Email action on a request). To achieve its functionality, this Service Manager application API will make use of the following "other" services APIs, as follows:

1. Invoke queryExec which is a Data Service API - this retrieves request data.
2. Invoke sharedMailboxGetInfo which is a MailAdmin Service API - this retrieves mailbox data.
3. Invoke sendMessage which is a Mail Service API - this sends the email (the params for this API call are a combination of input params for smSendMessage - the "parent API" - and values from Step 1 and 2).
4. Invoke entityUpdateRecord which is a Data Service API - this stores some request data re the email that was sent.
5. Invoke updateReqTimeline which is another Service Manager application API - this creates the timeline entry on that request for this operation (sending the email).

This is not a complete list of all the operations that happen as part of smSendMessage API, is just a summary as an example of how the application API works. You will notice that Step 5 is using another application API (updateReqTimeline) which can be made of similar subsequent operations, same way smSendMessage does. If you like, you can look at the application APIs like a collection of subsequent APIs (which can include other subsequent application APIs). Very similar concept to how a business process/workflow engine is designed to work in Hornbill.

The "non application" APIs  (e.g. Data Service, Mail Service, etc.) are basically providing functionality for the application API. As such they don't have the concept of a specific application (e.g. Service Manager app) but the concept of an app. They don't "know" Service Manager exists, as an app, they only know that apps (as a concept or object) exists. Because of this they won't be able to perform app specific operations.

Example: sendEntityTemplateMessage being a Mail Service API cannot perform an app specific (Service Manager) operation like updating the request timeline. The request and its timeline are objects that are specific to Service Manager app, there is no other app that uses the request object (entity) and only app (Service Manager) specific APIs can work with these objects. I hope this explains why sendEntityTemplateMessage in itself cannot perform the request timeline update.

The sendEntityTemplateMessage input param: recordID. As you noticed, when sending an email for a request, the correct value for this param is the request reference. You notice the name of the param is recordID, and this naming is intentional. As described above, because the sendEntityTemplateMessage is a Mail Service API, it provides functionality for any app that needs to use it. Because of this the input params intended for apps need to be generic. If we were to name the param as "requestReference" instead of "recordID" then this would have not been meaningful for other apps using this API (like Project Manager or Supplier Manager). So the sendEntityTemplateMessage does make use of the request reference (via recordID) but it does not specifically know is a request reference. sendEntityTemplateMessage will use the recordID to retrieve entity data that would be used to populate values for the email template variables.

In conclusion, to send an email and update a request timeline you need to make use of multiple APIs. For example updateReqTimeline.

Now, I would like to know, if you can share, what are you using these APIs for, what are you trying to achieve/implement?

As you can see, we have a collection of APIs, different services and some are more suited to be used for certain integrations than others. Is also the aspect that certain APIs are designed for a specific purpose, and is not advisable to use them for a different purpose. For example smGetRequests is designed specifically for the request list view but in essence it retrieves a list of requests, one can use it to retrieve requests but might not work as one would think/expect since it will be used outside its context/purpose (the request list view).