Zammad 6.5 Updates to API Reflected in SDK's

[brianvb]

This is kind of a question but I figured this would most likely fall under a feature request if my understanding is right, so I’m writing it as such.

A few months ago I started developing a custom support solution where I would build into my ministry’s websites a user interface for support that would direct all those to Zammad via the API where people would manage the support requests. That was on Zammad 6.4.X I believe.

Just about 1-2 weeks ago I was ready to go live, and it looks a new version, 6.5, had been released, and the default install using Portainer automatically used this new version. So, I just figured I might as well use the latest version and went with it.

After figuring out how to fix some configuration and websocket issues that I did not have before, I attempted to use by application to find that the search endpoints have changed considerably, as well as the API documentation. Before I was using GET requests for search with query strings like ?query=customer_id:123 but now it looks like I need to make a POST request and create a query condition using JSON in the request body.

So there’s really two major questions I’m trying to figure out here (1) is my understanding right? Looking at the site’s changelog it does seem like I am. (2) Are there plans to update the SDKs / API clients (like this PHP one I am using) and if so is there an expected timeframe by which those will be done.

Title: Updates to SDKs to reflect changes in Zammad API

1. What is your original issue/pain point you want to solve?
   I’m trying to figure out if I will have to re-code my custom solution to connect to the Zammad API or if I’ll be able to use the existing PHP SDK.

2. Which are one or two concrete situations where this problem hurts the most?
   N/A

3. Why is it not solvable with the Zammad standard?
   It can be, just might be some time.

4. What is your expectation/what do you want to achieve?
   I’m trying to figure out if the SDKs will be updated and a timeframe.

[MrGeneration]

I don’t think this is a feature request. If our own SDKs / API Libraries are outdated after the release, then that’s not good at all. Might take time, don’t know the current plans of the devs though.

I believe this is more of a development issue, at least regarding the API stuff. The rest seems to be unrelated to me to be honest.

[brianvb]

Thanks for correctly categorizing my topic. And, yeah, most of what I said was probably unnecessary rambling of just me trying to explain why I’m asking about the new SDK so soon after a release. I’ll keep an eye out, and can just do some slight tweaking to use the SDK as it currently is to make custom requests to the endpoints I need!

[rolfschmidt]

Hi @brian,

I think the main issue is this:

Just about 1-2 weeks ago I was ready to go live, and it looks a new version, 6.5, had been released, and the default install using Portainer automatically used this new version. So, I just figured I might as well use the latest version and went with it.

If you have mandatory developments which are working on your zammad system, you might wanna build a separate testsystem which behaves similar where you can update first and see if your developments are still working and adjust if needed and only update your production if the changes of the major or minor update are handled.

API changes will always happen. They might reduce in the future with graphql but they will happen.

I was using GET requests for search with query strings like ?query=customer_id:123 but now it looks like I need to make a POST request and create a query condition using JSON in the request body.

Please provide a proper example and we will try to help you to adjust your example if it is needed. Maybe you do not even need to change or it is a very minimal change like a missing parameter.

If you mean the /tickets/search api endpoint, then it is still possible via GET:

The PHP SDK is tested and running. It uses a different parameter called ?expand=true and was not affected by the changes we made and still provides the same functionality like before.

There are several ways to call our search endpoints like with full=true/false, expand=true/false, with_total_count=true/false and only_total_count=true/false and they will return different structures.

–

In general of course the stablest way is to use one of the SDKs we provide then that would be the mentioned PHP SDK.

[brianvb]

@rolfschmidt

If you have mandatory developments which are working on your zammad system, you might wanna build a separate testsystem which behaves similar

@rolfschmidt yes, this was mainly a circumstance of odd timing. We have no production environment yet at all. Everything was my local dev work, done on 6.4, then 6.5 was released days before I was going to go live. I could’ve stuck w/6.4 to go to production but figured why not just go with the latest, only to realize unfortunately some of my work was the stuff that breaking changes affected. No one’s fault but my own to decide to go with 6.5. No complaints here, truly!

Thanks for offering to take a look at my code, this isn’t exact, but it gives the gist of what I was doing on version 6.4. In my context, I am trying to get tickets that are by a specific user. We use the same Zammad install to handle requests from our different websites, so we also want to make sure the request is for the website the user is currently on. Perhaps I am not using best practices, and you can give me some hints:

// --- Returns an instance of \ZammadAPIClient\Client configured via a dependency injection container
$client = ZammadHelper::getApiClient(); 

// --- Load the ticket resource
$zammadResource = $client->resource( \ZammadAPIClient\ResourceType::TICKET );

// --- Search for tickets by a customer and a second condition
$response = $zammadResource->search('customer_id:1 AND website:websiteA);

In \ZammadAPIClient\Resource\AbstractResource::search() it currently makes a GET request if I’m understanding correctly.

Now for version 6.5 and with the updated API documentation, it looks like to do a condition-based search I should do a POST request and to include the condition in the request body more like this:

{
    "condition": {
        "ticket.customer_id": {
            "operator": "is",
            "value": 1
        },
        "ticket.website": {
            "operator": "is",
            "value": "websiteA"
        }
    }
}

Since the search() function uses a GET request, I was thinking that I can continue to use the current PHP SDK while changing my code to not use the Ticket resource, but the base client, something like this:

// --- Returns an instance of \ZammadAPIClient\Client configured via a dependency injection container
$client = ZammadHelper::getApiClient();
$response = $client->post(
    'tickets/search',
    [
        "condition": [
            "ticket.customer_id": [
                "operator": "is",
                "value": 1
            ],
            "ticket.website": [
                "operator": "is",
                "value": "websiteA"
            ]
        ]
    ]  
);

Please let me know if you have any insights!

[rolfschmidt]

I would not change anything, your code looks fine. The conditions field is for more complex situations with and/or complexity or when you need specific operators of trigger conditions.

But you are right, it might be make sense that the API clients get more general parameters, maybe. I wasn’t really involved there, but I looks like it is also missing parameters for sorting and ordering (Added: order_by in search function by mostafaqanbaryan · Pull Request #43 · zammad/zammad-api-client-php · GitHub).

[dvanzuijlekom]

@rolfschmidt

There are several ways to call our search endpoints like with full=true/false, expand=true/false, with_total_count=true/false and only_total_count=true/false and they will return different structures.

The with_total_count=true doesn’t seem to work, no count is added to the output with that parameter. Also, that specific parameter is not listed in the API docs, only the only_total_count=true is, which does work as expected.

[MrGeneration]

My impression with 6.5 was, that you will always receive a total asset count on responses, unless you use only_total_count=true which only returns the total count and nothing more.

[dvanzuijlekom]

The total asset count was standard in pre-6.5 versions. In fact, the 6.5 API update broke our monitoring, because we didn’t get an asset count anymore, so we had to change the API query and parsing of the output. This was a bit unexpected for a version which was labelled as a “minor” update.

[brianvb]

@rolfschmidt

I would not change anything, your code looks fine.

Unfortunately, the code does not work. My tests using a GET request and the query param, which was working on the Zammad version 6.4 API , return no results. Here’s what I see in Postman when I attempt to make the request that the old code would have made:

Using a POST request and the request body having the condition property does return the results I would expect:

Perhaps my old code just wasn’t configured in the best way to be able to manage this change. But based on my tests it seems like there is no compatibility between the search API endpoints between the 6.4 version I was using and the 6.5 version that was recently released.

That being said, I did test out my new PHP code above, using the client and its post function directly and not the Zammad Resource object, and it seems to be doing exactly what I need, so there is a fairly simple workaround using the current PHP SDK.

[MrGeneration]

This sounds awfully like a offsync searchindex. Did you rebuilt the index as required with Updating to Zammad 6.5? And is your Elasticsearch working as expected..?

[brianvb]

I have not had Zammad up and running in production yet, so I haven’t had to rebuild any search indexes or anything like that. All of my tests have been run on completely new installations of Zammad with test tickets that I have been submitting.

[MrGeneration]

Right. But rebuilding is mandatory after connecting ES to Zammad.

[brianvb]

I have been setting up fresh installations of Zammad using the suggested docker-compose and Portainer method, and accessing using nginx as a reverse proxy.

Indeed, if there is some type of mandatory rebuilding I have to do then I may have missed that in the installation instructions, or just failed to do it after submitting my test tickets on the fresh installations.

[rolfschmidt]

I agree here with @MrGeneration. Your request example looks good. It seems that your Elasticsearch is not connected properly or that it is off sync.

The rebuild he is talking about is Step 6 here:

Updating Zammad — Zammad System Documentation documentation

[brianvb]

Thank you @rolfschmidt and @MrGeneration - that did allow the GET request to the tickets/search endpoint to give me the same results as I was query format to work!

Now I have a new question, though. I never upgraded Zammad. Each time I ran tests it was on a fresh install of Zammad with test tickets being submitted. Is rebuilding the Elasticsearch index something that I am going to need to run regularly? Using the docker-compose install method, is there a way to tell that a rebuild needs to be done? Or is this a different issue altogether now that the GET search request didn’t work for me on a fresh install?

For now, I will have to stick with the POST body conditions-based request because it seems to consistently work, but it’ll be helpful for me to understand how to properly maintain my Zammad install when it goes to production.