File: Readme.pod

package info (click to toggle)
libx12-parser-perl 0.80-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 248 kB
  • ctags: 39
  • sloc: perl: 432; makefile: 5
file content (313 lines) | stat: -rw-r--r-- 12,252 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
=head1 NAME

X12::Parser::Readme - understanding configuration (cf) files 
for X12::Parser

=head2 X12 transactions

ASC X12 standards define commonly used EDI transactions. The
standards define a structure/format for exchange of EDI data.

Each transaction type is called a "transaction set". The smallest
data item in a transaction is called an "element". Groups of related
elements form a data segment. A data element separator separates
the elements within a segment. A segment starts with a element
which is called the segment ID, and ends with a segment terminator.

Logical groups of segments are called loops. There are some segments, 
which are used only to identify the beginning of a loop, these are 
called as control segments. A logical set of loops together form a 
"transaction set".

Similar transaction sets can be lumped together by enclosing them
in data segments that are known as functional group headers and
trailers. Functional groups are grouped together using interchange
control headers and trailers.

=head2 Parsing

Unlike XML/HTML parsers which relies on "<" and ">" tags to
determine start and end of data blocks, X12 transactions rely on
pre-defined values (segment IDs) to indicate start and end of
related data blocks (loops). Developing a parser that would work
for all X12 transactions poses a challenge in this respect, as each
transaction has its own hierarchy of loops and start/end indicators.

This lead to the development of the X12 configuration file (I<cf>)
specification. The cf specification is created to specify details
regarding the blocks/loops and start/end information in a simple
format. Cf files can be created for the different transaction sets.
(see section I<Building a cf file>). 

Now you can parse your X12 data file by invoking the X12::Parser 
specifying the cf file to use. This allows you to parse any X12 
transaction data files just by building the cf file for that
transaction type.

=head2 Cf file specification for X12::Parser

The cf file specifies any transaction in a hierarchical form. It
identifies the loops and segments in a transaction. This information 
is used to parse the transaction file. The L<X12::Parser> uses the 
L<X12::Parser::Cf> module to read the cf file information before parsing 
a transaction file. Since the X12::Parser parses files based on the cf 
file it allows the user to parse different X12 transaction types just 
by using the appropriate cf file. The user can use the cf files that 
are bundled with this package or create new cf files. The cf provided 
with this package is for the HIPAA X12 Ver 4010 X12 transactions.

A cf file has two types of information: I<section> and I<key=value>
pairs. A section contains information in key=value pairs.

=head3 section

Sections are identified by the square brackets ("[" and "]"). Section
represents loops (or logical blocks) in a X12 transaction. The
name of the loop or the block is specified in square brackets. The
section I<[LOOPS]> is mandatory in a configuration file. It consists
only the names of the top level loops instead of key=value pairs.
The X12::Parser::Cf cf file reader starts reading a cf file from the
[LOOPS] section.

=head3 key=value

There are two predefined keys, which are recognized by the Cf
file reader, namely: I<segment> and I<loop>. Segment key is used to
define the segments that are part of the current section/loop. The
loop key is used to define the sub-loops or the child loops for the
current section/loop.

Note: The term section and loop is used interchangeably as a
section in the cf file represents a loop in a X12 transaction.

Within a section, the first key=value pair represents the start of 
the loop. Each section/loop should have atleast one key=value
pair for the X12::Parser to identify the loop in the X12 transaction
file. Although the X12::Parser::Cf modules reads all the key=value
pairs, the X12::Parser uses only the first key=value pair to
identify the loops. The user may specify only the first key=value
pairs for each loop.

Value itself consists of 6 fields separated by I<':'>. All values 
are not currently used.

    key=value1:value2:value3:value4:value5:value6

When parsing a X12 transaction file, the values help the
X12::Parser determine if a segment is the start of a loop.

=over 2

=item value1

value1, is the segment id for a segment in a X12 transaction.
The first key=value pair within a section tells the X12::Parser
how to identify the loop.

=item value2 and value3

In some cases, to identify a loop correctly it is not enough 
to look at the segment id, you need to look at the qualifier too.

value2 and value3 are used to specify this. value2 is used to
specify the position on the segment that the X12::Parser should
look for value3. value3 consists of a COMMA separated list of qualifiers.

=item value4

value4 is a description of the segment. B<(value4 is not currently 
used by Parser)>.

=item value5

value5 indicates if the segment is required or situational. B<(value5 is 
not currently used by Parser)>.

=item value6

value6 indicates the allowable repeat count for the segment. B<(value6 is 
not currently used by Parser)>.

=back

Currently values 1, 2 and 3 are used for parsing the transaction
file. The others may be used in later versions of this package.

=head2 Limitations 

The X12::Parser::Cf module does not do validation of the Cf files. Since the 
goal of the X12::Parser module is to parse X12 files, the X12::Parser::Cf 
module is very minimal. The user should ensure that the cf files 
are appropriate.

Do not put extra spaces after [ ] sections. Do not have leading 
spaces for section name and key=value pairs. Lines with a leading #,
are considered comments.

To validate if X12::Parser::Cf is reading the cf file correctly try 
something like 


    use X12::Parser::Cf;

    my $cf = new X12::Parser::Cf;
    $cf->load("sample.cf");
    $cf->print_tree;

This would print the loop hierarchy. You can validate this to ensure
you have the correct structure.  

=head2 Building a cf file

Lets take the case of building a cf file for Version 004010 of
ANSI ASC X12.85, Health Care Claim Payment/Advice (835) transaction.

=head3 835 transaction

A 835 transaction structure would contain the following loops.

    ISA
    |-- GS
        |-- ST
            |-- 1000A
            |-- 1000B
            |-- 2000
                |-- 2100
                |-- 2110
        |-- SE
    |-- GE
    IEA

The above diagram shows the hierarchy of the loops. The data segments
are not shown.

=head3 Sample cf file

     /-------------------------------------------------\
     | ### start of the configuration file ###         |
 (1) | [LOOPS]                                         |
 (2) | ISA                                             |
     | IEA                                             |
     |                                                 |
     | #--- start of loop details ---#                 |
 (3) | [ISA]                                           |
 (4) | segment=ISA:::Interchange Control Header:R:1    |
 (5) | loop=GS                                         |
     |                                                 |
 (6) | [GS]                                            |
     | segment=GS:::Functional Group Header:R:1        |
     | loop=ST                                         |
     |                                                 |
 (7) | [ST]                                            |
     | segment=ST:1:835:Transaction Set Header:R:1     |
 (8) | loop=1000A                                      |
     | loop=1000B                                      |
     | loop=2000                                       |
     |                                                 |
     | [1000A]                                         |
 (9) | segment=N1:1:PR:Payer Identification:R:1        |
     |                                                 |
     | [1000B]                                         |
     | segment=N1:1:PE:Payee Identification:R:1        |
     |                                                 |
     | [2000]                                          |
     | segment=LX:::Header Number:S:1                  |
     | loop=2100                                       |
     | loop=2110                                       |
     |                                                 |
     | [2100]                                          |
     | segment=CLP:::Claim Payment Information:R:1     |
     |                                                 |
     | [2110]                                          |
     | segment=SVC:::Service Payment Information:S:1   |
     |                                                 |
     | [SE]                                            |
     | segment=SE:::Transaction Set Trailer:R:1        |
     |                                                 |
     | [GE]                                            |
     | segment=GE:::Functional Group Trailer:R:1       |
     |                                                 |
 (3) | [IEA]                                           |
     | segment=IEA:::Interchange Group Trailer:R:1     |
     | ### end of the configuration file ###           |
     \-------------------------------------------------/

=head3 Description

B<(1)> LOOPS section is mandatory. Add the main loops under this section.
Here we have added ISA and IEA loops B<(2)>. These are the top level loops.
The ISA, IEA are interchange group header and trailer segments. But we treat
them as a loop with one segment. And so are GS and GE functional group
header and trailer record.

B<(3)> Create a section for each of the loops mentioned under LOOPS.

B<(4)> Use the segment key to specify how the X12::Parser should determine
the start of the ISA loop. We will explain the fields better when we
come to B<(9)>.
 
B<(5)> Specify the sub-loops for ISA segment. In the above 
example GS is a sub loop for ISA. In there are more than one 
sub loops under ISA specify them too using the loop keyword. 
See B<(8)> how three sub loops are specified.

B<(6)> create a section for all loops specified under section ISA. Here it
is GS. Use the section key and if there are any sub loops use the loop
key to define their values.

Follow the same procedure to define all the loops and sub-loops.
 
B<(9)> Here's a description of the fields of the values for segment.

       segment=N1:1:PR:Payer Identification:R:1
               |  |  |            |         | |
              (a)(b)(c)          (d)       (e)(f)

B<(a)> specify the segment id here. Loop 1000A starts with N1 so specify N1 here.

B<(b)> and B<(c)>, there are cases when the segment id does not uniquely identify a 
loop. For eg. Loop 1000A and 1000B both start with N1 segment id. When parsing 
a transaction file, if the parser encounters a segment starting with N1, it 
needs additional information to decide if it is Loop 1000A or 1000B. This is 
done by specifying the qualifier information in the fields B<(b)> and B<(c)>.

B<(b)> specify the position in the X12 segment where the parser should look for 
the qualifier specified in B<(c)>.

If there are multiple qualifiers which identify a loop, specify all of them in 
position B<(c)> separated by a comma.

B<(d)> This is the description of the segment. You may leave this blank. (*not used)

B<(e)> Specify if the segment is required or situational. (*not used)

B<(f)> Specify the number of times the segment can be repeated (*not used)

The fields B<(d)> B<(e)> and B<(f)> are not used currently, but later releases may 
support these fields.


=head1 SEE ALSO

For details on Transaction sets refer to: National Electronic Data Interchange 
Transaction Set Implementation Guide. Implementation guides are available for all 
the Transaction sets.

L<X12::Parser>, L<X12::Parser::Tree>, L<X12::Parser::Cf>

If you have a mailing list set up for your module, mention it here.

If you have a web site set up for your module, mention it here.

=head1 AUTHOR

Prasad Balan, I<prasad@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright 2009 by Prasad Balan

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut