Easy Guide

[senorlocksmith]

Has anyone made a guide that is easy to follow. I am just wanting to learn how to implement this gem and get started with EDI parsing, generation and processing. I know this might sound absurd since I know EDI is very difficult, but I am hopeful that there might be a decent quick start guide or tutorial out there. Even if its just how to install, and get started attaching or something of the sort. Any help is much appreciated. Thank you!

[kputnam]

Hi @senorlocksmith,

No we don't have something like that yet. I would love to accept a PR from someone that comes up with one! The closest thing we have are the examples in README.md, the documents in doc/, and the example code in examples/ and notes/.

To anyone interested, there are a few topics that come up often enough we all would benefit from a quick start guide or tutorial.

• Reading documents from files
• Extracting information from documents
• Generating documents programmatically
• Writing documents to files
• Creating a new transaction set grammar
• Modifying an existing grammar
• Testing the correctness of your grammar

Some of this is documented already, but it's narrowly focused and has too much detailed to use for beginners. The information in Navigating.md, Generating.md, and Transcribing.md could be made more accessible with a getting started guide.

@senorlocksmith, if you are willing to work on it I'll be glad to offer guidance and accept your PR. This is a good idea and is long overdue.

[senorlocksmith]

@kputnam Thanks for the fast reply!

I am not a seasoned or classically trained programmer. I have been teaching myself how to program rails for a little while but following simple guides and youtube tutorials. I might be overreaching when it comes to trying to put together something of this nature, however then again I might be fit for this coming from a novice.

When reading those documents they are far from comprehensible by myself which is why I found this repo very difficult to understand.

I have made a few simple apps (local hosted) for simple data entry and using repos like Devise and the like. You tell me if I am way over my head here.

[kputnam]

Hi again @senorlocksmith,

I don't know if you'll be in over your head, but I do think you'll figure it out with enough time. I think most people have little to no experience with X12, so the terminology is a big hurdle to clear. I've done my best to remain consistent with the X12 terminology and not make up my own.

The other potentially unfamiliar aspect is the way the API works. Some ideas are borrowed from other languages like Scala and Haskell, so people familiar with those languages will have an easier time. I'm sure by now some other Ruby libraries have also borrowed some of these ideas, and in fact even the Ruby standard library has borrowed some in the years since I started this project (#tap and #flat_map and #then). But the overwhelming majority of Ruby code isn't written in that style.

If you have time, I think you would improve your skills a lot by working out how to use the library. But if you have a deadline approaching or don't have the time, it might take too long. Either way, feel free to ask questions and I'll do my best to help.

[adriand]

Hey @kputnam if I were to take a crack at this, would you still be up for reviewing, answering questions, etc.? I'm using this library in a new project and I feel like writing this guide would help me wrap my head around some things. That said, things have been a little quiet in this repository lately. I don't want to write it and submit a PR that doesn't get merged. ;) Let me know what you think!

[kputnam]

Hi @adriand, that would be wonderful. Yes I'll be happy to review and merge.

[adriand]

Okay @kputnam I have started sketching this out. I do have a couple of questions off the top (not sure whether you are okay with me going back and forth in this thread with questions, or whether you would prefer an alternate means of communication, in which case, LMK). My questions relate to the correct way to provide segment and element definitions that do not exist in the gem or that you want to override because the gem's versions are either incorrect or incomplete.

For example, I am working on a standard for the 5010 204, which does not exist in the gem (the 4010 204 is in there). I have figured out how to register my own 204:

      config.transaction_set.customize do |x|
        x.register("005010", "SM", "204") { Edi::FiftyTen::Standards::SM204 }
      end

However, the majority of the segments in the 5010 204 do not exist in the gem, and these segments include a great many elements that don't exist either. I am currently defining these in my project in files that look like the following:

# frozen_string_literal: true

require "stupidedi"

module Edi
  module FiftyTen
    module SegmentDefs
      include Stupidedi::Versions::FiftyTen::SegmentDefs

      s = Stupidedi::Schema
      e = Edi::FiftyTen::ElementDefs
      r = Stupidedi::Versions::FiftyTen::ElementReqs

      AT5 = s::SegmentDef.build(:AT5,
      "Bill of Lading Handling Requirements",
      "To identify Bill of Lading handling and service requirements",
      e::E152.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 3/Max 1,
      e::E560.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 10/Max 1,
      e::E153.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 30/Max 1,
      e::E355.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 2/Max 1,
      e::E408.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 4/Max 1,
      e::E408.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 4/Max 1,
      Stupidedi::Versions::FiftyTen::SyntaxNotes::E.build(1, 3),
      Stupidedi::Versions::FiftyTen::SyntaxNotes::E.build(2, 3),
      Stupidedi::Versions::FiftyTen::SyntaxNotes::C.build(5, 4),
      Stupidedi::Versions::FiftyTen::SyntaxNotes::C.build(6, 4)
    )

    AT8 = s::SegmentDef.build(:AT8,
      "Shipment Weight, Packaging and Quantity Data",
      "To specify shipment details in terms of weight, and quantity of handling units",
      e::E187.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 2/Max 1,
      e::E188.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 1/Max 1,
      e::E81.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 10/Max 1,
      e::E80.simple_use(r::Optional, s::RepeatCount.bounded(1)), # Min 7/Max 1,
      e::E80.simple_use(r::Optional, s::RepeatCount.bounded(1)), # Min 7/Max 1,
      e::E184.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 1/Max 1,
      e::E183.simple_use(r::Relational, s::RepeatCount.bounded(1)), # Min 8/Max 1,
      Stupidedi::Versions::FiftyTen::SyntaxNotes::P.build(6, 7)
    )

And then in my 204 standard, I am using them:

# frozen_string_literal: true

require "stupidedi"

module Edi
  module FiftyTen
    module Standards
      b = Stupidedi::TransactionSets::Builder
      d = Stupidedi::Schema
      r = Stupidedi::Versions::FiftyTen::SegmentReqs

      # point this at OUR segment defs, which should
      # have included the new one we made
      s = Edi::FiftyTen::SegmentDefs

Is this the correct method? I note that there are customize methods for interchanges, functional groups, etc., in the gem, but I did not see anything related to segment or element definitions.

[kputnam]

Hi @adriand, yep that's correct. You can use customize to wire different transaction sets in, but if you need to customize the transaction set itself, there's no "surgical" way to do this. In the worst case, you'll need to start by defining elements, then work up to segments, then finally defining the transaction set.