This logic was moved to ObjectMapperConfigurer. The JsonSerializer now just wraps the data in a standard structure then calls ObjectMapper

This file has the meaningful change. I tried to add verbose docstrings explaining the behaviour and why everything here is needed.

I didn't actually end up using this component. I can remove it (and the changes to MapperComponentResolver) if that would make things clearer, but I figure this will be useful at some point so I left it in. It lets us do stuff like:

X xEntity = new X(...)
XDto xDto = smartMapper.map(xEntity, XDto)

which will automatically resolve the mapper to use for converting from X to XDto and call it.

this is one of the main advantages of the new implementation. Not only does it automatically handle serializing the object, but it automatically serializes each field as well. So the ProductSimpleDto will also get serialized automatically (and if ProductSimpleDto was still implementing ResponesBodyFormattable, it would have used that method to serialize it).

an example of how we can include transient getter methods as fields in the JSON response using @JsonProperty

these checks on ALREADY_SEEN_OBJECTS and MAX_JSON_DEPTH weren't required to get this working, but as I was developing this I hit a few infinite loops/stack overflow errors due to some misconfigurations I had. I fixed those cases but I figured I'd leave these checks in for protection.

These checks are exactly what scare me about this solution.

1. I think I mentioned this somewhere else, but the default max depth seems super deep unless there's more to this than I'm understanding. And I know it's warding off the worst-case scenario (infinite loop), but what are the performance implications for letting the serializer do a kinda infinite loop here e.g. an expensive getter somewhere in the nested object graph that gets invoked on every nested objected. Naive example, but it could happen.

2. In general, I actually want serialization to fail pretty loudly (e.g. StackOverflowError) if it means we're doing something wrong (serializing deeply nested domain objects unnecessarily) or being lazy (not implementing a DTO).

But if we do need to keep the handle circular reference logic, we should log.warn/error'ing those so we can watch those pile up and make that the signal to map a particular domain to a DTO.

With that said, I would prefer to disable the Hibernate module and make us intentionally map from domain to DTO.

I think that's an important point, so I want to pause to let that sink in. We don't need to flesh out and implement the entire DTO class hierarchy right now. We just need to implement the DTOs that we want to expose the resources via the API right now. I understand there are core classes like (Location, Person, User) that require us to flesh out more than just the cycle count classes, but I think we could get away with most of those being "short" references. In fact, (although I'm not advocating for this), but it seems you could use @JsonIdentify (discussed below) to create simple short DTO versions of all the core domain classes just to get that out of the way.

From my perspective, if we go the DTO-always route instead of the DTO-plus-fallback-to-wrapper route, we don't need this wrapper class at all. In fact, I don't think we would want to handle circular references ourselves anway. Instead we'd want the DTO layer to be mapped properly so that we explicitly prevent circular references and we want Jackson to be loud when we do it wrong. This should be possible by either referencing the "shorter" DTOs that explicitly short-circuit the nested objects or through Jackson config.

Aside: I did some cursory research into the Jackson mechanisms that are used for the circular references and found the following.

• Use @JsonIdentityInfo to handle circular references by rendering the full object once and the the ID only
  • https://stackoverflow.com/questions/37302816/how-to-use-jsonidentityinfo-with-circular-references
  • https://share.google/aimode/siqaRyiTN6K4eREx8
• Use @JsonManagedReference or @JsonBackReference to omit foward and back references
  • (https://share.google/aimode/siqaRyiTN6K4eREx8)
• Use @JsonIgnore to leave the property off altoghether (not sure what case this would be used for since we have control of the DTO)

Honorable Mentions for generally useful features we need to look into and document as we move forward:

• @JsonAutoDetect - actually, it seems all of our DTO classes should use this annotation to opt-in (so this probably needs to be moved
• @JsonIdentityReference - just the id, ma'am. nothing but the id. this one should actually move to the list above.
• @JsonView - tag fields with view classes (Summary, Detail) and serialize with a chosen view. i think this is probably close to what i was think re: different representations of the same object (OBPIH-2649)
• JsonFilter + FilterProvider - holy shit, runtime include/exclude. that's dope.
• JsonSerialize - point to a custom serializier

Holy shit, there's so much more in Jackson than I expected!!! I'm starting to really lean into the idea of building this DTO layer and using Jackson. **I know some of the comments here are critical, bordering on harsh, but I want to make it clear that I think this is the right direction. ** @ewaterman

None of the Jackson top three mechanisms help us with the Hibernate serialization problem since our domains do not (and will not) be configured to serialize via Jackson config placed on the domain class (at least that's my opinion today). I could change my mind on that but I think the map domain to DTO is the safer and more correct route.

Note: The will not is emphatic for the same reasons we're building the DTO layer in the first place:

• property visibilty - we should control what properties we expose
• Hibernate - we don't want to deal with lazy loading,
• circular references (
• security (we haven't even discussed the cases where certain roles/users should not see a given property)

By the way, there's been a set of PRs and tickets I had on my mind since I first started to review the original object mapper PR. I found one ticket that mentioned the DTO layer and a bunch of PRs. There are probably other OBPIH tickets that include constraints, requirements, conventions but I'll have to do that look up later.

@kchelstowski created a ticket to advocate for this back in 2023 (https://pihemr.atlassian.net/browse/OBPIH-5993). Back then I was expecting us to move to the Grails @resource mechanism to map domains to REST resources, so I was ok with using domain and command classes to define and expose properties for the API resource. But that wasn't necessarily going to solve some of the issues we had around representing and serializing objects via the API.

• different representations of the same domain class
• hiding properties based on role
• hiding properties that should not be exposed publicly
• avoid circular references

So I want to acknowledge that I think @kchelstowski was right about introducing the DTO layer and this PR by @ewaterman is a sensible first step towards implementing that vision (particularly the adoption of Jackson and it's configurability and extensibility).

Aside: For years, I have been thinking about creating an Architecture Decision Record to keep track of the decisions we're making here (and elsewhere), scoped very narrowly to what we're actually deciding. So I'm going to create that repository now.

In our case here there would likely be multiple ADRs

• ADR-0001 - Canonical API serialization mechanism (with decision to adopt Jackson as our default serialization framework, but name the existing approach as well as other approaches i.e. MapStruct, @Resource, etc)
• ADR-0002 - Create a DTO layer to act as the default representation of resources exposed via API, webhook payloads, file exports, etc. Need to discuss all of the constraints and requirements for this. Don't need to solve them all right now.
• There are probably a dozen more ADRs to draft here, so I'll try to

To do that I want to make sure we capture all of the aforementioned (and unnamed) requirements, constraints, conventions from PRs and tickets over the years. It doesn't have to be exhaustive, but we should make sure that the adoption of Jackson will either solve the problem or not get in our way when we try to tackle the problem in the future. A good future problem to solve would be the "hide properties based on role", so doing a discovery on that might be a next step of the ADR.

I had Claude pull up all of the discussions we've had in pull requests re: the "DTO layer" over the years. Here are those discussions, grouped by PR, each link with a one-line summary. I want to extract all of the "requirements" and "conventions" that were brought up so we can create a

PR #4435 — OBPIH-6015 (Dec 2023 – Jan 2024) · your foundational DTO-layer position
r1437926214 (2023-12-29) — Don't add a DTO layer without a requirement; revert to a default toJson() on ProductSupplier unless there's a compelling reason.
r1437927243 (2023-12-29) — Follow existing conventions or invest in "v2"; your recommended convention: Map toJson() on the domain, marshaller in Bootstrap, BaseDomainApiController, and separate controller actions for list/search.
r1449813011 (2024-01-12) — Prefer toJson() returning a map; don't litter the code with DTOs if you might refactor to JSON views later; offered the JSON-views path as a "give it a shot" option.
r1449817169 (2024-01-12) — On LazyInitializationException: suggested testing by having toJson() reach into an association not loaded by the criteria query — i.e., you flagged the lazy-loading serialization risk two years ago.
PR #5976 — OBLS-781 Bulk APIs (June 2026) · recent, a specific DTO
r3418092959 (2026-06-16) — Suggested returning the saved/validated objects, or a DTO that wraps them and renders to JSON.
r3422157231 (2026-06-16) — Disliked returning "a list of maps with an arbitrary shape" and magic strings ("ok"/"error"); proposed a concrete UpsertResult DTO with UpsertStatus/UpsertAction enums.
r3422171203 (2026-06-16) — Sketched the method signatures returning UpsertResult / List.
r3422183403 (2026-06-16) — Allowed keeping the current shape for now, but noted you may want a separate DTO class to wrap the list of UpsertResult.
(The later #5976 comments — r3455901632, r3464270929, r3464282636 — are about the two-session/transaction-proxy and product-availability-refresh issue, not the DTO layer.)

PR #5968 — OBPIH-7867 Start a receipt (June 2026) · tangential, API response shape
r3396565077 (2026-06-11) — On 201 responses: you favor returning a Location header (HTTP-spec compliant) and having the client fetch, but noted you were overruled on the stock-movement APIs since the object is almost always needed immediately.

I want to reiterate that the serializer wrapper is not for supporting hibernate. We support hibernate via the config line:

objectMapper.registerModule(new Hibernate5Module())

So if we want to not support hibernate, all we do is remove that line.

The serializer wrapper is what allows ResponseBodyFormattable and ResponseMapper to work. Even if we remove hibernate serialization support, I still expect both of those to be used in combination with a DTO if we need to customize the serialization logic beyond what Jackson offers. They are enhancements to the built in serialization logic.

So even if we disable hibernate, we still need the serializer wrapper.

The serializer wrapper also adds the circular dependency and max depth checks. I like having these checks because by default the ObjectMapper will keep serializing until you stack overflow, which I do not want to happen on prod. I can definitely change the logic there to complain loudly with a helpful error message if we hit some invalid max depth (I reduced it to 25), but I want to be extra sure that we don't bring down prod with some misconfigured DTO serialization that we didn't catch during testing for whatever reason.

I do think we'd benefit from standardizing our approach to serialization (what annotations to use and when, when to introduce ResponseBodyFormattable or a ResponseMapper) and having consideration for things like dynamically hiding fields based on user role. That would be a good follow up discovery. I suspect the latter can be supported via an additional hook in on this serialization wrapper (another reason to keep it around).

But wouldn't keeping this enabled be a good indication that we didn't flesh out our API model well enough? This error is a signal to developers to get their shit together, no? It also makes sure our API is completely backed by DTOs, which is what I think we're trying to do here.

I don't remember exactly why I needed this. I figured that it'd be pretty difficult to unintentionally create a DTO that has no fields, and even if we did we'd likely notice right away that the API response is empty

Yeah if we're going to commit to Jackson and DTO for some APIs, I think we need to commit for all. The existing APIs with toJson() marshallers should continue to work (correct?) therefore we don't really need backwards compatibility, we just need to slowly migrate to Jackson + DTO for everything over time.

yes this is only going to affect new APIs that extend BaseController so we could say that we ALWAYS require a DTO. As I mention in a previous comment though, it might make using this logic a headache (at least at first) because we'd need to create a bunch of DTO classes for our entities just to have it be able to properly serialize something

Given that this would only be applicable for the controllers that would extend the BaseController, I would be restrictive and force us not to serialize domains if possible.

I tried disabling serializing Hibernate entities but it's already a mess for cycle count since it doesn't use DTOs very often. I can keep this restriction if we really want it, but it's going to balloon this PR somewhat because I'll need to add a bunch of new dtos (or at least have the domains implement asResponseBody). Honestly I'd rather just allow Hibernate entities for now but make a goal for us to move away from it. Not allowing domains will make it harder to integrate existing APIs with the BaseController

thoughts?

Sorry just getting back to this tonight. As I mentioned above in the ObjectMapperConfig comments, I would love to disable Hibernate because "make a goal for us to move away from it" is usually something we're usually good at. Once it's in place, we can use the "fixme later" excuse. If we take a hardline here, I think it'll be better for us in the future, even if it adds cost upfront. We're pretty good dealing with upfront cost because we have inertia in the moment.

So I think I would prefer the asResponseBody approach (which I assume could just call the toJson on the domain class right)? So it's not really add much more.

Another issue that I've had trouble articulating has to do with asResponseBody() and ResponseBodyFormattable. I haven't quite figured out how to solve it, but response body is very specific to web requests.

However, what I think we're trying to do is add a transport-agnostic method of serializing/deserializing objects, whether we render to or ingest from json, csv, xml, etc. At least that's my hope for what we're trying to accomplish. Whereas "repsonse body" makes this 💯 about the lifecycle of an API request. I want this serialization solution to handle rendering an API response, preparing a webhook payload, exporting a file, or producing an integration message that can be sent to a Kafka queue or SFTP server.

On top of that this same framework should be cabaple of handling deserialization without any changes to the object mapper. In other words, it should work bi-directionally. That might just be something we deal with later, but I don't want it to be too much of afterthought.

The problem with having a single, transport-agnostic serialization method is that different formats need to be structured differently. JSON and XML support complex nested data structures but CSV and XLS do not. The data must be flat for CSVs and XLS because it is just rows and columns.

Take a look at ResponseMapper. I was trying to split out the cases in a way that is agnostic of the underlying format. I ended up with:

• asResponseBody for JSON and XML -> maybe "asHierarchicalData"?
• asExportRow for CSV and XLS -> maybe "asBulkDataRow" or "asTabularRow"?

What would be the consequence of restricting this to none? And what would we need to do in order to counter it? Adding the JsonProperty annotation to all fields? In our toJson we're explicitly including / excluding properties. Here it seems like we'll be including any property in the DTO. I'm not saying we shouldn't include them all, just want to know the behavior so we can make the appropriate choice. For me, I'd rather have the implicit behavior of including everything. But there's definitely maybe going to be a case where we need to include a property in the DTO for context, but don't want to include it in the JSON response.

yes by default all fields are included and you'd annotate a field with @JsonIgnore if you want to exclude it.

If we did the opposite and by default exclude all fields, you'd need @JsonProperty on all fields you want to include

I agree with the idea and respect the nauanced reason for the different between this policy and the one on fields. Playing devil's advocate I think if we're including the fields by default, then at least getters fit into that implictly included set. At least for me, every getter is a transient property. Booleans also fall into that for me. The nuance is that including getters is a potential performance issue so we need to be careful and thoughtful about what to include. I don't necessarily security plays into this at all, but I could be wrong.

Again, not advocating for one over the other. As much as I like opinionated solutions (i think implicit property inclusion falls into that category), I would be ok taking the opposite (explicit) approach for API response bodies.

One additional caveat (might be instructive for the policy below) is that the explicit getter / property inclusion potentially avoids breaking changes because we inadvertantly exposed a property we didn't mean to.

There's a case for restricting access to everything and and applying annotations in the DTO layer.

objectMapper.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.NONE)

I assume this would allow us to use @JsonAutoDetect for when we really do want to go the implicit route. I know that breaks for the domains but I would argue we should not try to serialize the Hibernate domains at all. Which is a vote for getting rid of the Hibernate module and enabling fail on empty beans.

That'll force us to create DTOs for everything that needs to be exposed via the API and make good decisions on what properties get exposed.

including getters is a potential performance issue so we need to be careful and thoughtful about what to include

this is the strongest argument to not include them IMO. It's very easy to make a db query in a getter method and so I want us to be explicit about the getter methods that we actually want to include

we should not try to serialize the Hibernate domains at all

I agree but we already do this a lot in the app. I didn't want to force a dev to make a bunch of new DTOs for existing domains just to get their API serializing properly. I imagine it'd disincentivize using this flow since the existing serialization does support entities. I figured this was the path of least resistence

There's a case for restricting access to everything and and applying annotations in the DTO layer.

I'd be potentially open to this idea

How does the mechanism of PropertyAccessor work to determine if something is a getter? Does it check if a method name (getter) starts with get*? If it doesn't, I'm worried that it can treat all the class methods as getters and try to include any methods without arguments in the serialization?

yeah it checks if the method name starts with get* or is*. But the way I have it configured now is that it always ignores methods and only serializes fields

Whoa. This is both awesome and terrifying. I think this deserves a tech huddle.

yeah we can discuss. For the record, we're already doing this. I just moved the logic from JsonSerializer.serializeObject to here.

New classes shouldn't use toJson. ResponseBodyFormattable or a response mapper is better. I only included toJson to support preexisting dtos that do it that way.

I like the idea of a config property, but this is potentially a bad idea. If you're going 50 levels deep, something went wrong. I would argue that giving someone the ability to configure the app to go any deeper would potentially cause more harm than good.

Does it prevent the circular dependency? E.G. receipt has receiptItems returned, but receiptItem returns receipt in its DTO, so we end up with an infinite loop? I think Grails' converter did a great job in that, and it potentially cut the dependency to include only id for a child, that would potentially return the parent again and again.

I remember there were some jackson's annotations that needed to be added both sides, to determine which one is the child and which one is the parent, to avoid that problem. Probably @JsonManagedReference and @JsonBackReference

The problem with @JsonManagedReference and @JsonBackReference is that the @JsonBackReference is essentially always excluded when serializing.

What this should do is as you describe. See handleCircularReference. It detects that we've already seen the object and so sticks only its id in (or if it doesn't have an id it calls toString on it). So it should behave like the Grails converter

I'll be honest, I would be in favor of getting rid of this JSON serializer layer if the cost was "we need to create more DTOs".

it's not about having more DTOs. It's about hooking our DTO/entity -> Map conversion logic (which is the toJson() or asResponseBody() methods) into the ObjectMapper.

My point was that this is trying to solve the problem of we don't have enough DTOs to cover all of the APIs, so we need something to bridge the gap with the existing domain classes. I am arguing that we should only use the jackson-powered object mapper with the DTO layer and not try to make it work with the marshallers and asResponseBody() methods.

So the "More DTO" point was just a comment on how we get from where we are (mixed serialization) to where we want to be (a single serialization approach using Jackson). Each API controller will need to be migrated or we just leave the existing controllers alone for the time being. Any new API uses the Jackson approach. In either case, the objective should be Everything that goes out over the wire needs a DTO which means we need to add more DTOs.

I'll be honest. This thing scares me. So question: Does this go away if/when we migrate away from the other two solutions?

what other solutions? I get that this config is intimidating (it was for me too at first) but essentially all this is doing is allowing us to hook in custom serialization logic that triggers before the default ObjectMapper logic.

And the custom logic is automatically calling any toJson(). asResponseBody() methods that a DTO has

what other solutions?

I'm just talking about the existing serialization solutions we use:

• ObjectMarshaller + toJson()
• ResponseBodyFormattable

I get that this config is intimidating (it was for me too at first) but essentially all this is doing is allowing us to hook in custom serialization logic that triggers before the default ObjectMapper logic.

It's not that it's intimitading. It's just seems like a workaround. And it seems like it's only necessary because we cannot implement your ideal approach across the board (DTO+Jackson). This is not a criticism, it's a reality we have to deal with because we have existing serialization solutions in use. So now we now need to add a wrapper in order to make sure it all works happily together. This is only problematic because implementing this workaround (instead of the ideal solution of DTO+Jackson) leads me to believe it has the potential for harm.

Another way to frame this: If we started from scratch with DTO+Jackson for the entire API, would this class be necessary? If the new APIs are using just the DTO+Jackson approach do we need our own serialization wrapper class. The answer might still be yes. But if this wrapper is necessary even with DTO+Jackson+sensible config solution then I would double-down and say maybe this isn't the right solution.

I think I understand the point of this class ... it's to ease our burden / bridge the gap between where we are (using a mix of serialization approaches) vs the ideal (Jackson-based serialization). But, if we're going down this route of rewiring serialization across the board, I don't actually want to ease the burden with workarounds and wrappers because that's potentially where all the bugs will be coming from. It's possible that this PR nails all of the issues we might encounter (re: circular dependency, explicit vs implicit properties and getters, Hibernate issues, how are exceptions handled - fail silently vs exception).

But if it doesn't we're potentially going to be chasing our tailing to debug/troubleshoot issues we didn't anticipate, applying more and more workarounds, and getting to a place where we're further from a more consistent, stable, and maintainable solution.

I don't mean to be a curmudgeon. I say all this having seen how complicated serialization becomes through the OpenMRS sync project (maybe we can ask @mseaton to see what he thinks).

If we started from scratch with DTO+Jackson for the entire API, would this class be necessary?

It is not necessary to get Jackson working but it is not a work around. We don't need it to support existing structures. I'm trying to enhance the Jackson objectmapper with additional functionality.

There are two main enhancements that I want to support:

1. auto-serializing when we have a ResponseMapper component for a DTO
2. auto-serializing when we have a DTO that implements ResponseBodyFormattable

Both of these solutions are new, and this serialization wrapper class adds support for those enhancements. With this class, when serializing a DTO, this wrapper allows Jackson to invoke the ResponseMapper associated with that DTO, or call that DTO's asResponseBody method if it implements ResponseBodyFormattable.

In most cases we should not need 1 or 2. We can just use Jackson annotations and that is enough. The enhancements I added are meant to add additional functionality that allows us to easily define custom, more complicated serialization behaviour.

For example, if you need to call into some component when converting to json, the way we do it now is statically access that component inside the DTO's toJson method using Holders.grailsApplication.mainContext.getBean(X), which feels really hacky. If instead you define a ResponseMapper you can do it like this:

@Component
class XMapper implements ResponseMapper<X> {

    MessageLocalizer messageLocalizer
    SomeComponent someComponent

    @Override
    Map<String, Object> asResponseBody(X source) {
        return [
            field1: messageLocalizer.localize("x.y.z", [source.field1])
            field2: someComponent.doSomething(source.field2)
        ]
    }
}

which keeps the logic out of the DTO, letting it be a simple wrapper on fields.

So if we serialize X to json, thanks to the logic in OpenBoxesBeanSerializerModifier, Jackson will know to call XMapper.asResponseBody.

And similarly, if we want to customize the serialization process beyond what Jackson supports but we don't want to bother creating a whole ResponseMapper component we can use ResponseBodyFormattable:

@Component
class X implements ResponseBodyFormattable {

    String field1
    String field2

    @Override
    Map<String, Object> asResponseBody() {
        return [
            field1: field1,
            field2: field2,
            somethingElse: field1 + field2,
        ]
    }
}

And again thanks to the logic in OpenBoxesBeanSerializerModifier, if we serialize X to json, Jackson will know to call its asResponseBody() method.

(That's not the greatest example because you can still use Jackson annotations to solve it, but hopefully you get the idea.)

But if you didn't need to do either of the above and just want to serialize the fields of X as they are, then all you need to do is:

class X {
    String field1
    String field2
}

and Jackson will serialize that to:

{
    "field1": "a",
    "field2": "b",
}

So no this OpenBoxesBeanSerializerModifier is not required to support Jackson. I need it to support using ResponseMapper and ResponseBodyFormattable as custom serialization methods, which I created for the sake of convenience for devs when they need more custom serialization behaviour than what Jackson alone can support.

How does the mechanism of PropertyAccessor work to determine if something is a getter? Does it check if a method name (getter) starts with get*? If it doesn't, I'm worried that it can treat all the class methods as getters and try to include any methods without arguments in the serialization?

Given that this would only be applicable for the controllers that would extend the BaseController, I would be restrictive and force us not to serialize domains if possible.

Does it prevent the circular dependency? E.G. receipt has receiptItems returned, but receiptItem returns receipt in its DTO, so we end up with an infinite loop? I think Grails' converter did a great job in that, and it potentially cut the dependency to include only id for a child, that would potentially return the parent again and again.

I remember there were some jackson's annotations that needed to be added both sides, to determine which one is the child and which one is the parent, to avoid that problem. Probably @JsonManagedReference and @JsonBackReference

I remember you saying we don't have to define the asResponseBody anymore for DTO. Where does this asResponseBody come from now? How does the flow work?

we still support implmenting a ResponseMapper or extending ResponseBodyFormattable if you need to customize the serialization for a DTO.

For example you can have:

class SomeDto implements ResponseBodyFormattable {
    String field
  
    @Override
    Map<String, Object> asResponseBody() {
        return [
                field: field,
        ]
    }
}

but because all you're doing in the above is serializing all the fields as they are, you don't actually need to do this and can just do:

class SomeDto {
    String field
}

and it'll do the equivalent of the first version.

But if you want to customize the serialization in a non-standard way or if you just want to be explicit about it, you can still implement ResponseBodyFormattable and define the asResponseBody() method.

The main goal of the PR is to avoid the need for the boilerplate in the case where you're not doing anything custom with it.

It'd make sense to still implement ResponseBodyFormattable if you were doing something like the following:

class SomeDto implements ResponseBodyFormattable {
    String field
    String field2
  
    @Override
    Map<String, Object> asResponseBody() {
        return [
                newField: field + field2,
        ]
    }
}

because you're customizing the response JSON in a non-standard way

why did it need its own "Mapper"? I haven't seen that before

is it because we serialize the domain, and we don't have a DTO for the CycleCountCandidate?

the ResponseMapper it's primarily to break the serialization logic out into its own component for the case where we need it to depend on other components.

In this case we don't depend on other components so we don't strictly need a dedicated ResponseMapper (we could have just had CycleCountCandidate implement ResponseBodyFormattable), but I broke it out because the logic here was getting long, and because I eventually want to use asExportRow as well once we support the new exporter flow