getUserProfileAssets (apps/com.hornbill.servicemanager/Asset)

[RichardD]

Has the getUserProfileAssets method been deprecated?

Browsing https://docs.hornbill.com/ this morning and wasn't able to find it mentioned.

[Gerry]

@RichardD

The official position is, if the API is not published on https://docs.hornbill.com/ then its not available for use, and, more importantly is not stable, meaning its subject to change at any time, without prior notice, or any steps to take care of compatibility issues with existing use.  Right that all sounds very harsh...  but the truth is, we are in transition when it comes to APi's and the Hornbill.

Our original strategy was to document and publish *ALL* API's, and over the last 10 years that list has grown to 1000's of them. Not only do we create (reasonably well documented) API's at the platform level, we also create many API's at the application level, and over the last 10 years that has led to a number of problems

* Many API's that are published are not generally useful to customers, creating a "cannot see the wood for the trees" problem. 

* The focus of our API creation has been to support our own development efforts around front ends, administration and integrations, customer access to API's has typically made use of a very small subset of API's. 

* Documentation ranges from acceptable to very poor.  Many API's used for supporting front end UI functionality have ended up using strings to store/load complex JSON structures that are basically not documentable.

The scale of our API's along with a need for *much much better* customer facing documentation has led us to a point where we need to create a different set of API's for customers. A smaller, much more well defined, stable and importantly well documented, high quality API's, and thats been part of what we have been working towards.  To that end, what is now documented on docs.hornbill.com is our current take on what API's we feel need to be customer facing.  All other API's that were there before are *currently* still available to be called, they are just not documented.    However, it is important to note that, ultimately if the API is not documented in https://docs.hornbill.com/ then its probably a good idea to assume that you are using an unsupported API, which, is very likely to change, break or even disappear completely from the system, without prior notice from us, and without any contignecy for backwards compatibility or alternatives.  Which will mean it will simply stop working, and if that happens, our support team will look at the documentation, and if its not available, there will be no immediate fix.  That is not going to happen over night, but there is a strong possibility it will happen in the future.  

We are in the somewhat bizarre position today that, if we need to change, or depreciate some API's in support of our work in our own product, we cannot because we had no idea who was using these API's, this is crazy given the vast majority of API's are only ever used by us, so, we should be free to change them in order to improve the product.  So there is a very strong need for use to be able to both commit to a stable set of API's for our customers to use, and API's that we can use/change/evolve as we see fit, knowing we will not be impacting our customers use of API's

If the specific API you are talking about (getUserProfileAssets) is something you feel should be customer facing, then there is no problem proposing that, we would need to run that through our internal team/process to make sure there is no other reasons why it should not be added as a customer API, and on the back of that, I will raise that question internally for you. Can you tell me what you use this particular API for?

As part of our overall documentation effort at Hornbill, the aim is to drive up the quality of our documentation considerably, and the API documentation is a big part of that effort.  Internally we will be publishing a "Customer Facing API Quality Standard" which will mandate our developers meet a certain standard before making API's generally available to customers.  By standard I mean, using correct data types, documenting each input/out parameter properly, setting appropriate security controls, providing an examples for use of the API etc... and of course, for the API's that are documented/published, we have quite a lot of retrospective work to do in this regard.  

The end game is, our customer accessible API's will be completely independent of our internal API's, we are working on significant changes and architectural improvements to our API infrastructure that will help facilitate this transition. 

Hope that helps

Gerry

 

[ChrisDee]

Hi, when we were onboarded onto Service Manager we required a self-service device audit facility. This was not available in Service Manager and we were advised by Hornbill to create our own facility using the Service Manager APIs. We currently use around half a dozen API methods.

This has been running successfully for around 3 three years. As of 05:30 yesterday morning the method 'getUserProfileAssets' now returns an error:

/apps/com.hornbill.servicemanager/entities/Asset/fc_modules/sm_asset_helper.js(5745): error X1001: Uncaught TypeError: Cannot read property 'length' of undefined

Can you confirm whether this is a service outage and will be looked at and hopefully resolved (we have an incident logged), or given the 'official position' no action will be taken your end to resolve please?

Happy to look to future options, but just need to know whether current service can be restored.

[CraigP]

Thanks for the info Gerry.

We use getUserProfileAssets too. I'm troubleshooting a different issue this morning and noticed this doesn't seem to be working anymore (it's returning "Uncaught TypeError: Cannot read property 'length' of undefined"). Happy to replace it with an API that is deemed more appropriate to be customer facing, but the Asset page seems to be quite sparce in this regard. What is the suggested way to script the retrieval of a user's assigned assets?

[GJ06]

 Hi @Gerry, Thanks for the comprehensive update. Was their any comms that went out prior to the API's being chopped? I attended the HUG last week, the pace of change spoken about was both exciting and terrifying. feedback shared by some was that we can't seem to get our head around where we find out your change schedule and comms for this kind of work. I don't have time to watch the forum that regularly, can a heads up on this sort of thing be delivered via email or a Harry Hornbill notification for admin users?

[Gerry]

@GJ06

No unfortunately not, that is one of the problems we are trying to solve.  In all honesty we have no idea which customers are using which API's, we have done out best to determine this from the logs and other sources of information we have, but its not so simple to determine, this is because the API catalog customer have been using, is the same APi catalog as we are using internally.  This change is about making those two seperate things.  Technically, the API's currently. although not documented anymore, will still work today unimpeded, but the basic aim is, if the API is not earmarked for customer use, its not appearing in the new documentation, and the legacy dev documentation that was previously published to api.hornbill.com has been removed. 

We are not proactively seeking to break things, but as I said, we have no absolute way of knowing exavtly what API's customers are using, we ourselves are trying to make that determination. 

It is critical we make this change if we are to provide a stable set of APIs for customers, that are of high quality, well documented, and properly supported from an availability point of view.  The above problem reported by both @ChrisDee and @CraigP is a perfect example of this.  The API ( getUserProfileAssets ) appears to be broken, almost certainly because something changed and this API did not have test/validation in our test automation.  In our current approach all API's are equal, what we are putting in place is, specific API's that are customer facing will be treated with a much higher priority, will have more testing applied and will be objectively more stable as a result. 

@ChrisDee @CraigP in relation to the getUserProfileAssets API, this seems from the error message to be a defect that we have inadvertently introduced, this specific problem is not as a result of the API architecture change, there seems to be a simple software defect.  I will ensure a defect is raised against this and it gets fixed ASAP, this ought to be something we can simply hotfix, in relatively short order I would expect. 

The question as to weather this API should be promoted to a customer-facing API is still open, for now it will continue to work.  On the face of it, looking at the API spec it does not pass our Quality Requirements in terms of being properly documented because we are exposing an undocumented JSON structure via an xs:string property type.  As I mentioned above, its not our goal to mess things up for customers, so we need to provide a more definitive answer to this for you.  In the mean time, we will fix the API so it will once again work as it was previously, and I will raise this API with the dev team who can make a further determination as to the status of this API.

@ChrisDee Thanks for providing the explanation around the Device Audit facility, I am not sure I understand what that is in detail, but I will pass onto the Service Manager product team to look into this, to see if this is something that we should be including in Self-Service rather than you having to roll your own, or, if not, we should be providing you with the requsite APIs you need to DIY this as you have done. 

Thanks
Gerry 

[ChrisDee]

Hi @Gerry, could you provide a likely timescale for fixing the getUserProfileAssets method please? I will be chased later in the week for an update on it.

[Gerry]

@ChrisDee

I believe this should already been fixed, I am sure I seen a hotfix go out for this.  Is it still not working for you?

 

Gerry

[CraigP]

I can confirm getUserProfileAssets seems to be working again for us. Thanks for getting it sorted!

[ChrisDee]

@Gerry, yes it's working again now. Thanks for your help.

[Gerry]

No problem all, our apologies for that, I am not exactly sure what caused the problem, I expect we missed in testing.   Please do keep in mind though that this API is not currently flagged as a customer-facing API and from the looks of the API signature the API does not meet our own guidelines to meet the requirements of being a customer-facing API becuase there are undocumented JSON strings/structures emitted from this API, these JSON structures are generally not ridgid and are subject to change at any time, which means this API can also change at any time. 

Gerry

[samwoo]

Hi @Gerry,

Is there somewhere we can request for a customer-facing API? (maybe a subsection of this forum?) or should we just use this section of the forums?

For example, I cannot seem to find any customer-facing APIs on docs.hornbill.com that will allow returning a list of all Shared Users (returning the username, optionally also returning the email address) against a single asset.

There is an API for capturing this, but it's on the old API documentation so probably unsupported?

[Gerry]

@samwoo

You can just use these forums.  Just put into the right forum so right dev team get it.  For the most part you are either going to be requesting a platform or Service Manager API.  For the shared user example above that will be a Service Manager feature request.  You can generally determine that based on what Doc you would expect the API to be documented in. 

 

Quote

There is an API for capturing this, but it's on the old API documentation so probably unsupported?

For now, all old API's will continue to work, the caviat here is, at some point they will stop working because of the API infrastrcuture changes we are making. At some point in the future the API endpoints will also be changing - we will communicate this early with plenty of notice so no need to worry about it now.  In essence the current endpoints will be used excluseivly for our front-end applications.  There will be a newly created API endpoint which is dedicated for customer consumption, when this happens, two major changes will kick in. 

* Only the API's documented on docs.hornbill.com will be accessible on that new endpoint
* The existing endpoint will no longer work with API keys, only interactive sessions will work, and the only way to create an interactive session will be from our apps, and not accessible by API users
* The new API endpoint will only work with API keys. 
* The old API documentation is going to be taken out of service/will no longer be available (thats happening quite soon)

There is still some months to go here, so if you are using some of the old API's they will contine to operate, but, they may change or disappear without any prior notice as this development effort continues. 

Gerry

[samwoo]

Thanks @Gerry

2 hours ago, Gerry said:

There is still some months to go here, so if you are using some of the old API's they will contine to operate, but, they may change or disappear without any prior notice as this development effort continues. 

This is why I think we should be raising these on the forums so you know what is being used and whether or an alternative one could be developed, I guess.

[Gerry]

@samwoo

it would certainly be helpful for us to understand generally what customers are using the API's for, so yes, please ask.  We are keen to understand not only what  API's you use but what you use them for, that might give us better insights into how we might better produce useful customer-facing API's

Gerry

 

[samwoo]

Hi @Gerry,

You may have already seen in the Thread, that I have requested for some new supported API's.

I do, however, have another question. With any supported API's, even ones that are requested and implemented, are there potential for these to be added in the future to be used in Workflows as a Hornbill Automation node as well? 

For example, for the API's I have requested (related to Shared Users against Assets), I don't think there is any equivalent Hornbill Automations for these, but I think it would certainly be useful to include in the Workflow so we can utilize Hornbill more.

As of current, I know it's risky, but I do use the HTTP iBridge to run some of these, but it would be good if there could be a way to run Automations for single assets by passing an Asset ID into them, instead of using the nodes that applies to all assets (or by type) that are linked to the Request.

Thanks,

Samuel

[Gerry]

@samwoo

Quote

I do, however, have another question. With any supported API's, even ones that are requested and implemented, are there potential for these to be added in the future to be used in Workflows as a Hornbill Automation node as well? 

Good question Sam.  The basic answer is no, one does not automatically get you the other, but, if the function is present and working as required, for example, lets say there is an automation presented in the BPM for performing an action, and there is a reason why that would be a good idea to also have that as an API then that may make it easier to implement, especially if the logic behind the function is complex. 

However, generally speaking, the request for an addtional function in the BPM and an addtional API are really treated as two seperate requirements, in both bases we are asking why its needed, how relevant is it in that domain (BPM, API etc...) and all that stuff. 

Historically we have been very bad at just adding stuff, even if it only aids one customer, and in many cases now, as the systems scale and size has grown this approach has come back to bite us because we needed to change things that were incompatible, or we had forgotten about that variation, or many complaints of how complicated the system is, too many API's, too many options, not enough documentation, examples, guidance etc... All fair criticisms and something we are very keen to do something about.  The changes to the API's, documentation, getting the Academy up and running and many other initiatives are all components of allowing our platform to continue to gorw, while at the same time making things simpler, more consumable, better documented etc...

So when we look at requirements from customers, from the sales field and in the compatative landscape we have a much more inquisative mind being applied to thore requests.  Just knowing what someone would like is no longer enough to get stuff added to the product, we need to understand not only what, but why its needed, how does it fit into the bigger picture, and we need to consider if there are better/alternative ways to achieve the same thing.... etc...

Hopefully that sheds a little light and answers your question. 

 

Gerry 



 

[samwoo]

Thanks @Gerry, I appreciate the response