A new extension point in fulfillment - order code

23 views
Skip to first unread message

jkon...@soldevelo.com

unread,
Sep 12, 2017, 8:13:57 AM9/12/17
to OpenLMIS Dev
Hi all,

It is critical for Malawi to have order numbers that are easy to transfer from one document to another since they will be used in reference documentation. We decided that the best approach would be to have an extension point in fulfillment service that will be used for generating order codes. The default implementation would be left intact and we would provide a custom one with codes that are easy to transcribe (e.g. ORD-0000-1720). Does that sound good?

Regards,
Jakub

Josh Zamor

unread,
Sep 12, 2017, 6:28:38 PM9/12/17
to jkon...@soldevelo.com, OpenLMIS Dev
Hi Jakub,

Last I heard, which was as early as last week, Malawi wasn’t sure if this extension point was going to be prioritized for the 3.2.1 release (which is scheduled for the end of September here).  Has the priority changed and Malawi desires this to be in the 3.2.1 release?

I like the idea of order numbers that are easier to transcribe, personally.  For the technical committee though, our goal is to dive in deeper than just the high level description.  We need to see details.

To get into the details on the extension point I’d propose the following:

  • Create a JIRA Issue for the user-story (…simpler order number so that it may be easily transcribed…).
  • Attach a design document (google docs) or link to a wiki page with a technical proposal for the extension point:
    • Code reference to where this extension strategy is to be used.  i.e. where in the Fulfillment service is the code that uses the created order number? It should be a GitHub link to the line of code where we think the extension point would be used (not where it’d be defined).
    • Code the interface that extension point will be.  Doesn’t have to be a PR, it can just be a snippet of Java in the document for the interface.
    • Describe in words the different spring beans that will implement the extensions/strategy:  one is the hard to read UUID of the order, the second is the easier to transcribe Order #.
    • See the example (3rd bullet point) that’s been published:  Extension point (Java interface), extension (Spring Bean), Extension’s published through Maven, published extension side-car (Docker image), configuration to choose which extension is to be used (Docker Compose).
  • Mention if any UI extensions would be involved.

Lets get those details up here ASAP if we’re going to try to make the 3.2.1 release.  Honestly it’s already a bit short notice, as that release needs to be stable and released in just over 2 weeks.  I’m a little skeptical it’s possible so close to this release frankly.

The last thing I’ll mention is that this is of course something the product committee would be interested in - easier to transcribe order numbers sounds pretty universally desirable (so long as global uniqueness is maintained).

Best,
Josh



SolDevelo Sp. z o.o. [LLC] / www.soldevelo.com
Al. Zwycięstwa 96/98, 81-451, Gdynia, Poland
Phone: +48 58 782 45 40 / Fax: +48 58 782 45 41

--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/bb76a227-fcf8-4f29-9a77-c5862b60a7d6%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Mary Jo Kochendorfer

unread,
Sep 12, 2017, 7:38:43 PM9/12/17
to Josh Zamor, jkon...@soldevelo.com, OpenLMIS Dev, OpenLMIS Product Committee

Hello Jakub,


I wanted to raise that this may be a globally applicable feature. In https://openlmis.atlassian.net/browse/OLMIS-401 we decided to use the UUID because with system integrations we would want to use the UUID. However, has you point out it is challenging for print-outs or when a manual transcribing process is followed (copying the Order Number to another paper form).  


As Josh mentions, please create a JIRA ticket with the story that supports the configuration of the order number. Once created, I believe the PC would find this feature globally applicable and the PC can review. It may be easier to build out the feature versus using an extension point.


In terms of releases, we are planning to wait one more sprint for the 3.2.1 release so we'd have time to write up the ticket and complete it prior to the release.


Thanks,

Mary Jo



From: openlm...@googlegroups.com <openlm...@googlegroups.com> on behalf of Josh Zamor <josh....@villagereach.org>
Sent: Tuesday, September 12, 2017 3:28:36 PM
To: jkon...@soldevelo.com
Cc: OpenLMIS Dev
Subject: Re: [openlmis-dev] A new extension point in fulfillment - order code
 

Sebastian Brudziński

unread,
Sep 13, 2017, 8:33:07 AM9/13/17
to openlm...@googlegroups.com

Hi.


yes, this is a priority for Malawi and we need to incorporate this feature as soon as possible.


Josh, I'm quite surprised to see all those requirements we must meet in order to implement a simple extension point and an extension module. Wasn't the initial idea of the extension points to have a simple way for implementations to alter behavior of certain parts of the logic, mostly on their own? Last time we spoke about the workflow for implementations to implement ext point/module, my impression was that exposing an extension point was meant to be conisdered a trivial (non-controversial) change that can be submitted to core's code pretty much anytime (since it's just a refactor of some piece of a code to reside in a spring bean). Has anything changed since then or did I not understand what the workflow for providing an extension point is? If implementing an extension point requires implementations to provide the detailed use case, technical design, interface code, explanation of the approach and getting an approval from the product committee and technical committee, I'm afraid we may not see any extension point implemented in OpenLMIS v3. Perhaps we could revisit the workflow at the next technical committee call?

Please don't get me wrong - the Malawi team can of course provide all of this if it seems necessary. The above is really a concern for new/outside implementations. If we are to discourage forking, we are not doing it right (or at all) at the moment.


Mary Jo, thanks for your response. If this is something that is globally applicable this would make things easier for us. When do you think you would be able to get PC feedback on it? As I mentioned this is a high priority change for us, therefore knowing whether we will be implementing it directly in core or via extension point is crucial for us.


Best regards,
Sebastian.


For more options, visit https://groups.google.com/d/optout.

--

Sebastian Brudziński
Software Developer / Team Leader
sbrud...@soldevelo.com

Josh Zamor

unread,
Sep 13, 2017, 3:16:05 PM9/13/17
to Sebastian Brudziński, openlm...@googlegroups.com
Thanks for the feedback Sebastian.  I understand the confusion, and I think I understand some of your concern about effort.

First on the extension trivialness.  When we said we desired for it to be trivial, it’s true that we want the process from ideation through implementation to be as trivial as possible.  Moreover though we wanted any debate of whether an extension point should exist to be as minimal as possible.  Put another way, there should rarely be any debate about the usefulness to an implementation, only that it doesn’t break existing functionality.  After that comes the effort to switch out code in a non-forking manner, which if we have an idea on how to make easier, it would be universally welcome.

Given that we’re here on the technical forum discussing an extension point, let me go over the list of things I proposed a little more succinctly:
  • a user story - surely this exists already?
  • a github link
  • a java interface, like this: https://github.com/OpenLMIS/openlmis-example/blob/master/src/main/java/org/openlmis/example/extension/point/OrderQuantity.java - 3 lines of code
  • a description of what the two spring beans would be.  It can be as simple as saying that we need one Spring Bean named “UUIDOrderNumberImpl” and another named “Base64OrderNumberImpl” (if you’re thinking Base64 representation) with short english descriptions of what each one does.  
  • Finally I called out that the extension point mechanism has elements of publishing (Maven oriented and Docker Image) and configuration in deploying the Reference Distro to choose which extension is used.  All of which has tooling and examples, yet lets make sure we’re not forgetting about it - you’ll need it for this to work.

I don’t feel this effort is undue - it’s the basic pieces of a design, and it’ll be needed anyways for communication and documentation.  I’m simply encouraging we do this sooner rather than later.

As for timing, I’m encouraging the Malawi team to prioritize this now, so that we may discuss the extension point and provide feedback early.  If this ends up as an undiscussed pull request with only two weeks to go before the release, I will recommend that the PR does not make it in that release if there’s any question at all as to its stability or conformance to our conventions.  That automatic “no” would be in everyone’s best interest if we’ve learned anything from the trouble we had with the contributed “Rejected status”, batch approval or reporting service.  We need to communicate, and we need to give ourselves time to evaluate and plan.  Otherwise as you know, our experience is that things that can’t be allowed to break, do.

Clearly this is small enough and likely universally desirable enough to just incorporate into the product in the normal way:  a jira issue with the user story and then an agreement on what the “human readable” part details will be. If so lets just discuss that:  are you thinking Base64 or perhaps Base85 encoding?  Some other encoding?

Best,
Josh 



Paweł Gesek

unread,
Sep 13, 2017, 4:38:05 PM9/13/17
to Josh Zamor, Sebastian Brudziński, openlm...@googlegroups.com
Personally I would trim this discussion just to the interface and information where it will be used. I believe we should assume the current implementation is left intact and becomes the implementation of the said interface that is used by default. I also feel we already have enough of a user story already - easier to read order numbers.

We don't need worry about what the imeplementers bean does or how they name it - we won't have any control over them. We might ask to fish for a potential contribution, but it shouldn't block the extension point.

This talk about extension points reminds me of when I made a request to the Spring framework itself in the exact same vein (https://jira.spring.io/browse/SPR-14100). They implemented it the same day I reported it, no questions asked. Funny enough, I never used it, since I was stuck with some old Spring version, but I hope someone else benefited from it - I'm thinking this should be our thinking as well. Even if we introduce a certain new order number implementation to core, I think we should still consider marking this an extension point in the process - for the benefit of those that come after us. Just my two cents.

Regards,
Paweł

To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.
To post to this group, send email to openlmis-dev@googlegroups.com.
-- 
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.
To post to this group, send email to openlmis-dev@googlegroups.com.
-- 
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.
To post to this group, send email to openlmis-dev@googlegroups.com.

-- 
Sebastian Brudziński
Software Developer / Team Leader 
sbrud...@soldevelo.com


SolDevelo Sp. z o.o. [LLC] / www.soldevelo.com
Al. Zwycięstwa 96/98, 81-451, Gdynia, Poland
Phone: +48 58 782 45 40 / Fax: +48 58 782 45 41

-- 
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.
To post to this group, send email to openlmis-dev@googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.

To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/977FDE21-A302-4A0D-87B1-EB0A14C03D49%40villagereach.org.

For more options, visit https://groups.google.com/d/optout.



--

Paweł Gesek
 Technical Project Manager
pge...@soldevelo.com / +48 690 020 875

Josh Zamor

unread,
Sep 13, 2017, 5:09:10 PM9/13/17
to Paweł Gesek, Sebastian Brudziński, openlm...@googlegroups.com
I agree that the most important piece to communicate is the interface (3 lines of code), and where it’s used (the github link).  If there is uncertainty of how you’ll create a more human readable code and therefore what you’ll call that bean, then you can just note that it’s unknown.

I also feel we already have enough of a user story already - easier to read order numbers.

Great.  Team Malawi, post the link to the ticket.  Don’t make everyone go find it.

Best,
Josh

Jakub Kondrat

unread,
Sep 14, 2017, 8:06:44 AM9/14/17
to openlm...@googlegroups.com

Hi Josh,

A user story can be found here:

https://openlmis.atlassian.net/browse/MW-475

Regarding our bean that would implement the extension: I was thinking that Base36 with 6 characters would be good - it's short and case insensitive which would make it easier for people writing them down. I believe it has around 2 billion combinations, so we could additionally check for its uniqueness in that extension point. Base36OrderCodeGenerator?

I went ahead and created the proposed extension point (not much overhead since we already had the code in example service). It can be found on order-code-extension branch. Here's the interface:

https://github.com/OpenLMIS/openlmis-fulfillment/blob/42bf19aa4c92f4f407c1acaeedaf056ce70ee24f/src/main/java/org/openlmis/fulfillment/extension/point/OrderCodeGenerator.java#L24

And here's the code that uses the created order number:

https://github.com/OpenLMIS/openlmis-fulfillment/blob/42bf19aa4c92f4f407c1acaeedaf056ce70ee24f/src/main/java/org/openlmis/fulfillment/web/OrderController.java#L364

I also modified the ExtensionManager a little so that when it has no configuration entry it looks for a bean with given class - as a result I could run fulfillment service without any additional docker images (openlmis-fulfillment-extensions?) and it still used the default implementation.

-Jakub
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.

To post to this group, send email to openlm...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Jakub Kondrat
Software Developer
jkon...@soldevelo.com

SolDevelo Sp. z o. o. [LLC]
Office: +48 58 782 45 40 / Fax: +48 58 782 45 41 Al. Zwycięstwa 96/98 81-451, Gdynia
http://www.soldevelo.com

Place of registration: Regional Court for the City of Gdansk KRS: 0000332728, TAX ID: PL5862240331, REGON: 220828585, Share capital: 60,000.00 PLN

Josh Zamor

unread,
Sep 15, 2017, 2:59:41 AM9/15/17
to Jakub Kondrat, openlm...@googlegroups.com
Thank you Jakub,

This is exactly what we need.

We had an all day meeting today so I haven’t had any time, however I have a quick observation:

- Currently your extension point is defined to take a DTO as a parameter.  I think this makes more sense to define this in the context of the domain, the Order.  Let the Order be the class that is responsible for the id and the code, and pass the appropriate order number generation implementation to the Order.

Base 36 at first look sounds like a good fit.

Best,
Josh


Josh Zamor

unread,
Sep 15, 2017, 5:36:41 PM9/15/17
to Jakub Kondrat, openlm...@googlegroups.com
So that everyone may follow this, this has turned into a pull request which now has a design discussion occurring there:  https://github.com/OpenLMIS/openlmis-fulfillment/pull/11

Best,
Josh
Reply all
Reply to author
Forward
0 new messages