71. EPMO Open Source Coordination Office Redaction File Detail Report

Produced by Araxis Merge on 9/24/2019 1:38:01 PM Eastern Daylight Time. See www.araxis.com for information about Merge. This report uses XHTML and CSS2, and is best viewed with a modern standards-compliant browser. For optimum results when printing this report, use landscape orientation and enable printing of background images and colours in your browser.

71.1 Files compared

#	Location	File	Last Modified
1	PCL-5_v1_build_8.zip\v1_build 8\Unredacted\spp_mha_web-development.zip\spp_mha_web-development\Docs\vistalink	vistalink_1_6_sm.doc	Wed Jul 31 17:35:31 2019 UTC
2	PCL-5_v1_build_8.zip\v1_build 8\Unredacted\spp_mha_web-development.zip\spp_mha_web-development\Docs\vistalink	vistalink_1_6_sm.doc	Tue Sep 24 17:09:02 2019 UTC

71.2 Comparison summary

Description	Between Files 1 and 2
Description	Text Blocks	Lines
Unchanged	14	3782
Changed	13	29
Inserted	1	1
Removed	0	0

71.3 Comparison options

Whitespace
Character case	Differences in character case are significant
Line endings	Differences in line endings (`CR` and `LF` characters) are ignored
CR/LF characters	Not shown in the comparison detail

71.4 Active regular expressions

No regular expressions were active.

71.5 Comparison detail

1
2	VISTALINK
3	SYSTEM MAN AGEMENT GU IDE
4	Version 1. 6
5	December 2 010
6	Department of Vetera ns Affairs
7	Office of Informatio n and Tech nology
8	Product De velopment
9	Revision H istory
10	DateDescri ptionAutho r12/03/10V istALink V ersion 1.6 release.P roduct Dev elopment S ervices Se curity Pro gram VistA Link devel opment tea m.
11	Albany, NY OIFO:
12	Developer— Mike Kilma de
13	Developer— Liz Defiba ugh
14	Bay Pines, FL OIFO:
15	Developmen t Manager— Charles Sw artz
16	Tester—Jas on Woodyar d
17	Oakland, C A OIFO:
18	Developer— Kyle Clark e
19	SQA—Gurbir Singh
20	Technical Writer—Sus an Strack0 5/2006Init ial VistAL ink Versio n 1.5 rele ase.Jim Al exander, t echnical w riter
21	Dawn Clark , project managerTab le i. Revi sion Histo ry
22	Contents
23	iiRevision History
24
25
26	iiiContent s
27
28
29	viiFigures
30
31
32	viiiTables
33
34
35	ixOrientat ion
36
37
38	ixTerminol ogy
39
40
41	xText Conv entions
42
43
44	xiiWebLogi c Systems
45
46
47	1-11.
48	Introducti on
49
50
51	1-11.1.
52	VistALink 1.6 Overvi ew
53
54
55	1-11.2.
56	WebLogic U pdates Pro ject
57
58
59	2-12.
60	Deploying VistALink Adapters o n J2EE
61
62
63	2-12.1.
64	RAR Overvi ew
65
66
67	2-22.1.1.
68	Summary of RAR Chang es Since P revious Ve rsion
69
70
71	2-32.2.
72	Creating a RAR
73
74
75	2-32.2.1.
76	Exploded 1 .6 RAR Lay out, Produ ction Syst ems
77
78
79	2-32.2.2.
80	Exploded 1 .6 RAR Lay out, Non-P roduction Systems
81
82
83	2-32.2.3.
84	1.6 Deploy ment Descr iptor: ra. xml
85
86
87	2-52.2.4.
88	1.6 Deploy ment Descr iptor: web logic ra.x ml
89
90
91	2-82.2.5.
92	Steps to C reate a 1. 6 RAR
93
94
95	2-82.3.
96	VistALink Connector Configurat ion File
97
98
99	2-92.3.1.
100	Connector Entry Form at
101
102
103	2-92.3.2.
104	Connector Settings
105
106
107	2-102.3.3.
108	Advanced C onnector S ettings
109
110
111	2-102.3.4.
112	File-Wide Setting: e ncryptionS coped
113
114
115	2-112.3.5.
116	Obsolete S ettings
117
118
119	2-112.4.
120	Deploying J2EE Share d Librarie s for Vist ALink (Pro duction Sy stems Only )
121
122
123	2-112.5.
124	Deploying a RAR
125
126
127	2-122.6.
128	Updating A lready-Dep loyed Adap ters
129
130
131	2-132.7.
132	DNS Update s and Vist ALink Adap ters
133
134
135	2-142.8.
136	Pool Size Management /Tuning
137
138
139	3-13.
140	Configurin g log4j Lo gging
141
142
143	3-13.1.
144	log4j Conf iguration Overview
145
146
147	3-13.2.
148	Configurin g log4J
149
150
151	3-23.2.1.
152	Alternativ e Approach
153
154
155	3-23.3.
156	Sample log 4j Configu ration Fil es
157
158
159	3-33.4.
160	VistALink Core log4j Categorie s
161
162
163	4-14.
164	Institutio n Mapping
165
166
167	4-14.1.
168	Managing t he Mapping
169
170
171	4-14.1.1.
172	PrimarySta tion Attri bute (Vist ALink Conf iguration File)
173
174
175	4-14.1.2.
176	How the Ma pping Is I nitialized
177
178
179	4-24.1.3.
180	Viewing th e Current Mapping
181
182
183	4-24.1.4.
184	Updating I nstitution Mappings
185
186
187	4-24.1.5.
188	How Applic ations Use Instituti on Mapping s
189
190
191	4-24.2.
192	Troublesho oting Inst itution Ma pping Issu es
193
194
195	4-24.2.1.
196	Out-of-Syn ch Configu ration Fil es on Mult iple Physi cal Server s
197
198
199	4-24.2.2.
200	Connector Station an d M System Mismatch
201
202
203	4-34.2.3.
204	JNDI Name Configurat ion Mismat ch
205
206
207	4-34.2.4.
208	Mappings w ith Undepl oyed Conne ctors (Sto pped or De leted)
209
210
211	4-34.3.
212	Pluggable Institutio n Mapping Rules
213
214
215	5-15.
216	The VistAL ink Admini stration C onsole
217
218
219	5-15.1.
220	Overview
221
222
223	5-15.2.
224	Monitor Ro le Restric tions
225
226
227	5-15.3.
228	Accessing the VistAL ink Admini stration C onsole
229
230
231	5-15.3.1.
232	VistALink Administra tion Conso le as Stan dalone Web Applicati on
233
234
235	5-25.3.2.
236	VistALink Administra tion Conso le as WebL ogic Conso le Extensi on
237
238
239	5-35.4.
240	Monitoring Connector Status
241
242
243	5-35.4.1.
244	Adapter Li st/Summary
245
246
247	5-45.4.2.
248	Adapter De tail
249
250
251	5-65.4.3.
252	Monitoring Instituti on Mapping
253
254
255	5-75.5.
256	Configurat ion Editor
257
258
259	5-75.5.1.
260	About the Configurat ion File
261
262
263	5-85.5.2.
264	How to Pro pagate Con figuration Changes t o Other Se rvers
265
266
267	5-85.5.3.
268	Viewing an d Editing Connector Properties
269
270
271	5-95.5.3.1 .
272	JNDI Namin g Recommen dations
273
274
275	5-95.5.4.
276	Encryption of Access /Verify Co des
277
278
279	5-105.5.4. 1.
280	Modifying Access/Ver ify Codes Outside of Configura tion Edito r
281
282
283	5-105.5.4. 2.
284	Encrypt Un encrypted Entries Fe ature
285
286
287	5-105.5.4. 3.
288	Changing t he Encrypt ion Type
289
290
291	6-16.
292	Monitoring VistALink via JMX a nd MBeans
293
294
295	6-16.1.
296	Overview
297
298
299	6-16.2.
300	VistALink MBeans
301
302
303	6-16.2.1.
304	VistaLinkC onnector M Bean
305
306
307	6-36.2.2.
308	VistaLinkI nstitution Mapping MB ean
309
310
311	6-36.3.
312	VistALink MBean Secu rity
313
314
315	7-17.
316	M Server M anagement
317
318
319	7-17.1.
320	Overview
321
322
323	7-17.2.
324	Finding Us er Process es with th e Connecti on Manager
325
326
327	7-27.3.
328	Finding Vi stALink Pr ocesses wi thout the Connection Manager
329
330
331	7-27.3.1.
332	VMS System s
333
334
335	7-27.3.2.
336	Non-VMS Sy stems
337
338
339	7-37.4.
340	Listener M anagement
341
342
343	7-37.4.1.
344	Listener M anagement for Caché/ VMS System s
345
346
347	7-37.4.2.
348	Listener M anagement for Caché/ NT Systems
349
350
351	7-37.4.3.
352	Listener M anagement for DSM/VM S Systems
353
354
355	7-37.5.
356	M Listener Site Para meters Fil e
357
358
359	7-37.5.1.
360	Site Param eters for All System Types
361
362
363	7-47.5.2.
364	Site Param eters for Windows Sy stems
365
366
367	8-18.
368	Security
369
370
371	8-18.1.
372	J2EE Syste m Manager Security T asks for V istALink
373
374
375	8-18.2.
376	M System M anager Sec urity Task s for Vist ALink
377
378
379	8-18.3.
380	VistALink' s J2SE Sec urity Mode l
381
382
383	8-28.4.
384	VistALink' s J2EE Sec urity Mode l
385
386
387	8-28.4.1.
388	Connector Proxy User (J2EE)
389
390
391	8-28.4.2.
392	J2EE Re-au thenticati on Mechani sms for En d-Users
393
394
395	8-48.5.
396	RPC Securi ty (B-Type Option)
397
398
399	8-48.6.
400	Creating C onnector P roxy Users for J2EE Systems
401
402
403	8-48.6.1.
404	Security C aution
405
406
407	8-58.6.2.
408	Creating t he "Connec tor Proxy User"
409
410
411	8-58.7.
412	Additional Security Issues (J2 SE Mode)
413
414
415	8-58.7.1.
416	Authentica tion in Cl ient/Serve r Mode
417
418
419	8-58.7.2.
420	CCOW-Based Single Si gn-on
421
422
423	8-68.7.3.
424	Kernel Aut o Sign-on
425
426
427	8-68.7.4.
428	Sensitivit y of VistA Link-Logge d Data
429
430
431	9-19.
432	Troublesho oting Vist ALink 1.6
433
434
435	9-19.1.
436	Overview
437
438
439	9-19.2.
440	Symptoms a nd Possibl e Solution s
441
442
443	9-19.2.1.
444	Connection Attempt t o Bad List ener Addre ss/Port
445
446
447	9-29.2.2.
448	Connection Attempt t o RPC Brok er Listene r
449
450
451	9-29.2.3.
452	Invalid Co nnector Pr oxy Creden tials
453
454
455	9-39.2.4.
456	Connector Proxy Expi red Verify Code
457
458
459	9-39.2.5.
460	Sporadic S ocket Time outs
461
462
463	9-49.2.6.
464	Connection Pool Capa city Excee ded
465
466
467	9-49.2.7.
468	ClassCastE xception
469
470
471	9-59.2.8.
472	Configurat ion File C onfusion
473
474
475	9-59.2.9.
476	Reauthenti cation (En d-User Ide ntificatio n) Failure
477
478
479	9-69.2.10.
480	Division M ismatch
481
482
483	9-69.2.11.
484	Failure to Authorize RPC (B-Ty pe Option)
485
486
487	9-69.2.12.
488	M-Side Err or Returne d to J2EE
489
490
491	9-69.2.13.
492	Abrupt Dis connects ( M-Side Err ors)
493
494
495	9-79.2.14.
496	J2SE Conne ction Atte mpt to 1.0 Listener
497
498
499	9-79.3.
500	Analyzing VistALink Errors in the M Erro r Trap
501
502
503	9-79.3.1.
504	XOBSTR Var iable
505
506
507	9-89.3.2.
508	XWBTIP Var iable
509
510
511	9-89.3.3.
512	XOBLASTR V ariable (M Request T imestamp)
513
514
515	9-89.4.
516	Analyzing VistALink Java Excep tions
517
518
519	9-89.5.
520	Section 50 8 Complian ce: Differ entiate Fo cus on Cha nge Verify Code Chec k Box
521
522
523	1Appendix A: Listene r Manageme nt for Cac he/NT Sys tems
524	Appendix A -
525
526	1Creating/ Editing Li stener Con figuration s
527	Appendix A -
528
529	2Starting All Config ured Liste ners
530	Appendix A -
531
532	2Starting a Single U nconfigure d Listener
533	Appendix A -
534
535	2Stopping a Configur ed or Unco nfigured L istener
536	Appendix A -
537
538	3Schedulin g Listener Startup a t System S tartup
539	Appendix A -
540
541	1Appendix B: Listene r Manageme nt for DSM /VMS Syste ms
542	Appendix B -
543
544	1Setting U p an OpenV MS User Ac count
545	Appendix B -
546
547	1Setting U p a Home D irectory f or the Vis tALink Han dler Accou nt
548	Appendix B -
549
550	1Creating a DCL Logi n Command Procedure for the Vi stALink Ha ndler
551	Appendix B -
552
553	2Sample DC L Login Co mmand Proc edure
554	Appendix B -
555
556	2Setting U p and Enab ling the T CP/IP Serv ice
557	Appendix B -
558
559	3Obtaining an Availa ble Listen er Port (f or Alpha/V MS systems only)
560	Appendix B -
561
562	3Creating the TCP/IP Service
563	Appendix B -
564
565	4Enabling and Saving the Servi ce
566	Appendix B -
567
568	4Access Co ntrol List ACL Issue s
569	Appendix B -
570
571	5Controlli ng the Num ber of Log Files
572	Appendix B -
573
574	6Disabling New Conne ctions
575	Appendix B -
576
577	6Terminati ng All Con nections a nd Prevent ing New On es
578	Appendix B -
579
580	1Glossary
581	Glossary-
582
583
584
585	Figures
586	2-4Figure 2‑1. 1.6 D eployment Descriptor Template (ra.xml)
587
588
589	2-7Figure 2‑2. 1.6 D eployment Descriptor Template (weblogic ra.xml)
590
591
592	2-9Figure 2‑3. VistA Link Confi guration F ile Format Example
593
594
595	3-2Figure 3‑1. Sampl e log4j co nfiguratio n files
596
597
598	3-3Figure 3‑2. Log4j configura tion file example
599
600
601	4-1Figure 4‑1. Insti tution Map ping Assoc iation in VistALink Configurat ion File
602
603
604	5-2Figure 5‑1. Stand alone Vist ALink 1.6 Administra tion Conso le
605
606
607	5-3Figure 5‑2. VistA Link Admin istration Console: A ccess via link in na vigation t ree and ta b in domai n tab set
608
609
610	5-4Figure 5‑3. Conne ctor Summa ry List
611
612
613	5-5Figure 5‑4. Conne ctor Detai l, 1 of 2
614
615
616	5-6Figure 5‑5. Conne ctor Detai l, 2 of 2
617
618
619	5-7Figure 5‑6. Confi guration E ditor Main Interface
620
621
622	5-9Figure 5‑7. Editi ng a Conne ctor Entry
623
624
625	5-11Figure 5‑8. Chan ging the e ncryption type -- co nfirmation page
626
627
628	7-1Figure 7‑1. Using the Conne ction Mana ger
629
630
631	7-2Figure 7‑3. Use t he DCL com mand SHOW SYSTEM /PR OC=VL to d isplay all VistALink processes
632
633
634	7-3Figure 7‑4. Edit VistALink related si te paramet ers
635
636
637	7-4Figure 7‑5. Edit site param eters for Windows sy stems
638
639
640	9-7Figure 9‑1. M Err or Trap
641
642
643	1Figure A‑ 1. Foundat ions Manag er Interfa ce (Cache΄ Systems)
644	Appendix A -
645
646	1Figure A‑ 2. Create or edit li stener con figuration entries
647	Appendix A -
648
649	3Figure A‑ 3. Automat ically Sta rting List ener(s) on TaskMan R estart
650	Appendix A -
651
652	2Figure B‑ 1. Sample DCL Login Command Pr ocedure
653	Appendix B -
654
655	3Figure B‑ 2. Obtaini ng an avai lable list ener port (for Alpha /VMS syste ms only)
656	Appendix B -
657
658	3Figure B‑ 3. Creatin g the TCP/ IP Service
659	Appendix B -
660
661	4Figure B‑ 4. Enablin g and savi ng the TCP /IP servic e
662	Appendix B -
663
664	5Figure B‑ 5. Access Control Li st
665	Appendix B -
666
667
668
669	Tables
670	iiTable i. Revision History
671
672
673	6-3Table 6 ‑1. VistaL inkConnect or MBean A ttributes
674
675
676	6-3Table 6 ‑2. VistaL inkInstitu tionMappin g MBean At tributes
677
678
679	7-2Table 7 ‑2. Connec tion Manag er actions and defin itions
680
681
682	7-6Table 7 ‑6. Founda tions Site Parameter file fiel d definiti ons
683
684
685	8-3Table 8 ‑1. Connec tion Speci fication C lass and C redentials
686
687
688	2Table A‑1 . Listener Configura tion Entri es Descrip tion Table
689	Appendix A -
690
691
692
693	Orientatio n
694	XE "Orient ation"
695	This Syste m Manageme nt Guide i s intended for use i n conjunct ion with t he VistALi nk softwar e. It outl ines the d etails of VistALink- related so ftware and gives gui delines on how the s oftware is used with in Healthe Vet-Vetera ns Health Informatio n Systems and Techno logy Archi tecture (V istA).
696	The intend ed audienc e of this manual is all key st akeholders . The prim ary stakeh older is t he Product Developme nt Securit y Program team. Addi tional sta keholders include:
697	HealtheVet -VistA app lication d evelopers of Web-bas ed applica tions in t he WebLogi c 9.2 and 10.x Appli cation Ser ver enviro nment.
698	Informatio n Resource Managemen t (IRM) an d Informat ion Securi ty Officer s (ISOs) a t Veterans Affairs M edical Cen ters (VAMC s) respons ible for c omputer ma nagement a nd system security.
699	Product Su pport (PS) .
700	VA facilit y personne l who will be using HealtheVet -VistA Web -based app lications running in the WebLo gic 9.2 an d 10.x App lication S erver envi ronment.
701	Document O verview
702	This manua l provides informati on on the management of VistAL ink resour ce adapter s and serv ers. It co ntains det ailed info rmation on :
703	Deploying VistALink on Java 2 Enterprise Edition ( J2EE) Serv ers
704	J2EE Loggi ng
705	VistALink’ s Institut ion Mappin g
706	The VistAL ink admini stration c onsole
707	Monitoring Adapters
708	M listener managemen t
709	VistALink security
710	Troublesho oting
711	Its intend ed audienc e includes server ad ministrato rs and IRM Informati on Technol ogy (IT) s pecialists at VA fac ilities, a s well as developers of Java a pplication s requirin g communic ation with VistA/M.
712	Generally, the insta llation an d maintena nce instru ctions pre sented her e assume t he use of Windows as the clien t operatin g system. Where appr opriate, s eparate st eps are di splayed fo r Linux.
713	Terminolog y
714	The term r esource ad apter is o ften short ened in th is guide t o "adapter ," and is also used interchang eably with the term connector.
715	Text Conve ntions
716	File names and direc tory names are set o ff from ot her text u sing bold font (e.g. , config.x ml). Bold is also us ed to indi cate GUI e lements, s uch as tab , field, a nd button names (e.g ., "press Delete").
717	All caps a re used to indicate M routine and option names (e. g., XMINET ). All cap s used ins ide angle brackets i ndicate fi le names t o be suppl ied by the user. Exa mple:
718	<JAVA_HOM E>\bin\jav a -Dlog4j. configurat ion=file:/ //c:/local Configs/my log4j.xml
719	Names for Java objec ts, method s, and var iables are indicated by Courie r font. Sn apshots of computer displays a lso appear in Courie r, surroun ded by a b order:
720	Select Ins tallation Option: LO AD a Distr ibution
721	Enter a Ho st File: X OB_1_6.KID
722	In these e xamples, t he respons e that the user ente rs at a pr ompt appea rs in bold font:
723	Enter the Device you want to p rint the I nstall mes sages.
724	You can qu eue the in stall by e nter a 'Q' at the de vice promp t.
725	Enter a '^ ' to abort the insta ll.
726	DEVICE: HO ME// <Ente r> TELNET PORT
727	Boldface t ext is als o used in code and d eployment descriptor samples t o indicate lines of particular interest, discussed in the pr eceding te xt:
728	<?xml vers ion="1.0"? >
729	<weblogic- connector xmlns="htt p://www.be a.com/ns/w eblogic/90 " xmlns:xs i=http://w ww.w3.org/ 2001/XMLSc hema-insta nce xsi:sc hemaLocati on="http:/ /www.bea.c om/ns/webl ogic/90 ht tp://www.b ea.com/ns/ weblogic/9 0/weblogic -ra.xsd">
730
731	<!-- For n ew ADAPTER -level jnd i-name, re commend us ing value of connect ion instan ce JNDI na me, append ed with Ad apter -->
732
733	<jndi-name >vlj/testc onnectorAd apter</jnd i-name>
734
735	<enable-gl obal-acces s-to-class es>true</e nable-glob al-access- to-classes >
736	The follow ing symbol s appear t hroughout the docume ntation to alert the reader to special i nformation or condit ions.
737	SymbolDesc riptionUse d to infor m the read er of gene ral inform ation and references to additi onal readi ng materia l, includi ng online informatio n. Used to caution t he reader to take sp ecial noti ce of crit ical infor mation.Add itional Re sources
738	VistALink Web Site
739	The VistAL ink websit e summariz es VistALi nk archite cture and functional ity and pr esents sta tus update s:
740	http:// URL /vistalink /.
741	VistALink Documentat ion Set
742	The follow ing is the VistALink 1.6 end-u ser docume ntation se t:
743	VistALink 1.6 Instal lation Gui de: Provi des detail ed instruc tions for setting up , installi ng, and co nfiguring the VistAL ink listen er on Vist A/M server s and the VistALink resource a dapter on J2EE appli cation ser vers. Its intended a udience in cludes ser ver admini strators, IRM IT spe cialists, and Java a pplication developer s.
744	VistALink 1.6 System Managemen t Guide (t his manual ): Contain s detailed informati on on syst em managem ent for Vi stALink ad apters and M listene rs.
745	VistALink 1.6 Develo per Guide: Contains detailed i nformation about wor kstation s etup, re-a uthenticat ion, insti tution map ping, exec uting requ ests, Vist ALink exce ptions, Fo undations Library ut ilities, a nd other t opics pert aining to writing co de that us es VistALi nk.
746	VistALink 1.6 Releas e Notes: L ists all n ew feature s included in the re lease.
747	VistALink end-user d ocumentati on can be downloaded from the VA Softwar e Document Library ( VDL) Web s iteXE "VHA Software Document L ibrary (VD L):Home Pa ge Web Add ress"
748
749	XE "Web Pa ges:VHA So ftware Doc ument Libr ary (VDL): Home Page Web Addres s"
750
751	XE "Home P ages:VHA S oftware Do cument Lib rary (VDL) :Home Page Web Addre ss"
752
753	XE "URLs:V HA Softwar e Document Library ( VDL):Home Page Web A ddress":
754	URL
755	VistALink end-user d ocumentati on and sof tware can be downloa ded from a ny of the anonymous. software d irectories on the Of fice of In formation Field Offi ce (OIFO) File Trans fer Protoc ol (FTP) d ownload si tesxe "EPS Anonymous Directori es":XE "EV S Anonymou s Director ies":
756	Albany OIF O
757	URL
758	Hines OIFO
759	URL
760	Salt Lake City OIFO
761	URL
762	Preferred Method
763	URL
764	The docume ntation is made avai lable onli ne in Micr osoft Word format an d Adobe Ac robat Port able Docum ent Format (PDF). Th e PDF docu ments must be read u sing the A dobe Acrob at Reader (i.e., ACR OREAD.EXE) , which is freely di stributed by Adobe S ystems Inc orporated at the fol lowing Web addressXE "Adobe:Ho me Page We b Address"
765
766	XE "Web Pa ges:Adobe Home Page Web Addres s"
767
768	XE "Home P ages:Adobe Home Page Web Addre ss"
769
770	XE "URLs:A dobe Home Page Web A ddress":
771	http://www .adobe.com /
772	WebLogic S ystems
773	At the cur rent time, VistALink 1.6 has b een tested and is su pported on WebLogic Server 9.2 and 10.x, only. Web Logic prod uct docume ntation ca n be found at the fo llowing we bsite:
774	http://edo cs.bea.com /.
775	DISCLAIMER : The appe arance of any extern al hyperli nk referen ces in thi s manual d oes not co nstitute e ndorsement by the De partment o f Veterans Affairs ( VA) of thi s Web site or the in formation, products, or servic es contain ed therein . The VA d oes not ex ercise any editorial control o ver the in formation you may fi nd at thes e location s. Such li nks are pr ovided and are consi stent with the state d purpose of this VA Intranet Service.In troduction
776	VistALink 1.6 Overvi ew
777	The VistAL ink resour ce adapter is a tran sport laye r that pro vides comm unication between He altheVet-V istA Java applicatio ns and Vis tA/M serve rs, in bot h client-s erver and n-tier env ironments. It allows Java appl ications t o execute remote pro cedure cal ls (RPCs) on the Vis tA/M syste m and retr ieve resul ts, synchr onously. V istALink i s also ref erred to a s "VistALi nk J2M."
778	VistALink 1.6 consis ts of Java -side adap ter librar ies and an M-side li stener:
779	The adapte r librarie s use the J2EE Conne ctor Archi tecture (J 2CA 1.5) s pecificati on to inte grate Java applicati ons with l egacy syst ems.
780	The M list ener proce ss receive s and proc esses requ ests from client app lications.
781	WebLogic U pdates Pro ject
782	In support of the De partment o f Veterans Affairs I nformation Technolog y applicat ion Modern ization ef fort, the three appl ications V istALink, Fat-client Kernel Au thenticati on and Aut horization (FatKAAT) , and Kern el Authent ication an d Authoriz ation for the Java 2 Enterpris e Edition (KAAJEE) h ave been d eveloped. Based on t he directi on of the Technical Review Mod el (TRM) a nd in orde r to suppo rt applica tions that upgrade t o the new WebLogic S erver vers ions 9.2 a nd 10.x, t his projec t is requi red. The s cope of th e project is to upgr ade these three appl ications t o work wit h the WebL ogic Serve r versions 9.2 and 1 0.x.
783	Deploying VistALink Adapters o n J2EE
784	RAR Overvi ew
785	On J2EE sy stems, J2C A-complian t adapters , such as VistALink, are deplo yed in res ource adap ter archiv e (RAR) fi les. RAR f iles are a nalogous t o Enterpri se Archive (EAR) fil es and Web Archive ( WAR) files , except t hat they a re exclusi vely for r esource ad apters (J2 CA connect ors).
786	NOTE: Orac le (former ly known a s BEA) rec ommends th at RARs be deployed in explode d format.D eployment characteri stics of V istALink R ARs runnin g in WebLo gic domain s:
787	VistALink adapters a re meant t o be deplo yed as sta ndalone J2 CA adapter s, e.g., i ndependent of indivi dual J2EE applicatio ns.
788	For a J2EE applicati on to use a VistALin k adapter, the adapt er must be running i n the same JVM as th e J2EE app lication.
789	If a J2EE applicatio n using Vi stALink is targeted to multipl e WebLogic servers, so must th e VistALin k adapter( s) it is u sing.
790	A single V istALink a dapter dep loyment ca n target m ultiple We bLogic ser vers in a domain.
791	A VistALin k adapter runs indiv idually on each serv er it is t argeted to ; it is no t aware of itself ru nning on o ther serve rs in the domain.
792	There are no cluster -aware fea tures or c onfigurati on setting s for stan dalone J2C A adapters such as V istALink i n WebLogic . In parti cular, the re is no:
793	failover a cross serv ers
794	load-balan cing acros s servers
795	The config urable set tings for deployment of any Vi stALink ad apter are contained in the fol lowing loc ations:
796	weblogic-r a.xml: con tains WebL ogic-speci fic deploy ment descr iptor conf iguration settings ( such as in itial and maximum po ol sizes) and JNDI-r elated pro perties th at must be modified for each a dapter, to distingui sh one ada pter from another in JDNI.
797	VistALink configurat ion file: contains V istALink-s pecific co nfiguratio n settings , such as access and verify co des for th e connecto r proxy us er. The Vi stALink co nfiguratio n file con tains sett ings for a ll deploye d VistALin k connecto rs. It is in a singl e location on a give n server, in a folde r that the deployer places on the server 's classpa th.
798	NOTE: With the deplo yment desc riptor tem plates pro vided with VistALink 1.6, in m ost case t he ra.xml deployment descripto r does not need to b e modified .Summary o f RAR Chan ges Since Previous V ersion
799	vljFoundat ionsLib an d vljConne ctor jars: New versi ons provid e a J2CA 1 .5 complia nt adapter implement ation.
800	Deployment Descripto r Changes: The forma t of both the ra.xml and weblo gic-ra.xml descripto rs is diff erent. Exi sting adap ters' depl oyment des criptors n eed to be updated. U sing the p rovided sa mple/templ ate descri ptors, onl y weblogic -ra.xml wi ll need to be modifi ed when cr eating a V istALink R AR:
801	META-INF/r a.xml: The template version pr ovided in the VistAL ink distri bution is updated to be J2CA 1 .5 complia nt. In mos t cases, i t no longe r needs an y further editing wh en creatin g a RAR.
802	META-INF/w eblogic-ra .xml: The template v ersion pro vided in t he VistALi nk distrib ution is u pdated to be J2CA 1. 5 complian t. It must be edited for each RAR deploy ed.
803	META-INF/M ANIFEST.MF : The temp late versi on provide d in the V istALink d istributio n is updat ed to supp ort use of J2EE Shar ed Librari es by RARs .
804	lib/saxpat h.jar, lib /jaxen-cor e.jar, and lib/jaxen -dom.jar a re no long er needed in the RAR as their functional ity has be en replace d by the X Path imple mentation introduced in Java 5 .
805	lib/xbean. jar no lon ger needed in the RA R since an implement ation of X ML Beans i s included in WebLog ic 9/10
806	Linked ada pters (lin k-ref mech anism) no longer sup ported for VistALink 1.6 adapt ers
807	Developmen t System C lassloadin g: Automat ic classlo ading of a ll jars in RAR is no w supporte d by WebLo gic 9.x/10 . Library jars inclu ded in RAR no longer need to b e manually added to the server classpath .
808	Production System Cl assloading : Oracle r ecommends removing a ll jars fr om RARs on productio n systems, and deplo ying them as J2EE sh ared libra ries inste ad (to red uce resour ce consump tion – rep lacement f or resourc e-saving a spect of t he 8.1 lin k-ref mech anism). Wh en deploye d as J2EE shared lib raries, th e jars sup porting Vi stALink RA Rs no long er need to be manual ly added t o the serv er classpa th.
809	NOTE: Vist aLink 1.6 is upgrade d to be a J2CA 1.5-c ompliant a dapter, an d runs in WebLogic 9 .x and 10. The previ ous versio n of VistA Link (1.5) implement ed the J2C A 1.0 stan dard, and runs in We bLogic 8.1 .Creating a RAR
810	Exploded 1 .6 RAR Lay out, Produ ction Syst ems
811	The recomm ended cont ents of an exploded VistALink RAR folder , for prod uction sys tems, are:
812	(root)
813	empty
814	META-INF\
815	- MANIFEST .MF (conta ins inform ation need ed to use J2EE Share d Librarie s)
816
817	- ra.xml ( J2EE stand ard Deploy ment Descr iptor)
818
819	- weblogic -ra.xml (W LS-specifi c Deployme nt Descrip tor)
820	The app-J2 EE\Rar-Pro d-Template directory in the Vi stALink di stribution zip provi des an exp loded RAR in this st ructure.
821	NOTE: On p roduction systems, O racle reco mmends tha t the supp orting lib raries (JA R files) b e deployed as J2EE s hared libr aries to m inimize th e consumpt ion of ser ver resour ces (hence the recom mended exp loded RAR for a prod uction sys tem contai ns only de ployment d escriptors ).Exploded 1.6 RAR L ayout, Non -Productio n Systems
822	The recomm ended cont ents of an exploded VistALink RAR folder , for non- production systems, are:
823	(root)
824	Main VistA Link libra ries:
825
826
827	- vljConne ctor-1.6.0 .jar
828
829
830	- vljFound ationsLib- 1.6.0.jar
831	lib\
832	Supporting libraries :
833
834
835	- log4j-1. 2.13.jar
836	META-INF\
837	- MANIFEST .MF (a req uired RAR artifact)
838
839	- ra.xml ( J2EE stand ard Deploy ment Descr iptor)
840
841	- weblogic -ra.xml (W LS-specifi c Deployme nt Descrip tor)
842	The app-J2 EE\Rar-Dev -Template directory in the Vis tALink dis tribution zip provid es an expl oded RAR i n this str ucture.
843	NOTE: Libr aries cont ained in R ARs are au tomaticall y loaded o nto a high -level cla ssloaders, and are t hus availa ble to oth er deploye d applicat ions (EARS , WARs, et c) running in the sa me Java Vi rtual Mach ine (JVM). 1.6 Deploy ment Descr iptor: ra. xml
844	A template ra.xml ve rsion is p rovided in the VistA Link distr ibution zi p file, in each of t he example rar folde rs. It has been upda ted to be compatible with 1.5 of the J2C A specific ation.
845	In most ca ses, you c an copy th is templat e ra.xml d eployment descriptor as-is fro m the Vist ALink exam ple RAR fo r all your RARs, wit h no furth er need to edit it.
846	<?xml vers ion="1.0" encoding=" UTF-8"?>
847	<connector xmlns="ht tp://java. sun.com/xm l/ns/j2ee" xmlns:xsi ="http://w ww.w3.org/ 2001/XMLSc hema-insta nce" xsi:s chemaLocat ion="http: //java.sun .com/xml/n s/j2ee htt p://java.s un.com/xml /ns/j2ee/c onnector_1 _5.xsd" ve rsion="1.5 ">
848	<descript ion>J2M Vi stALink ad apter that allows RP C executio n from Jav a/J2EE to
849	M/VistA< /descripti on>
850	<display- name>Vista LinkAdapte r</display -name>
851	<vendor-n ame>Founda tions</ven dor-name>
852	<eis-type >VistA</ei s-type>
853	<resource adapter-ve rsion>1.6< /resourcea dapter-ver sion>
854	<!-- NOTE : In VistA Link v1.6, deployed in WebLogi c, in most cases thi s
855	VistAL ink-distri buted ra.x ml file do es NOT req uire any e dits/chang es. Instea d,
856	all ed its/change s should b e made in weblogic-r a.xml. -->
857	<resource adapter>
858	<resourc eadapter-c lass>gov.v a.med.vist alink.adap ter.spi.Vi staLinkRes ourceAdapt er</resour ceadapter- class>
859	<outboun d-resource adapter>
860	<connec tion-defin ition>
861	<manag edconnecti onfactory- class>gov. va.med.vis talink.ada pter.spi.V istaLinkMa nagedConne ctionFacto ry</manage dconnectio nfactory-c lass>
862	<confi g-property >
863	<desc ription>pl aceholder property f or connect orJndiName whose pre sence allo ws overrid ing in web logic-ra.x ml</descri ption>
864	<!-- NOTE: On W ebLogic, w ith VistAL ink v1.6, DON'T edit the ra.xm l
865	conn ectorJndiN ame value. INSTEAD, edit the w eblogic-ra .xml conne ction inst ance
866	conn ectorJndiN ame proper ty. It ove rrides thi s one! -->
867	<conf ig-propert y-name>con nectorJndi Name</conf ig-propert y-name>
868	<conf ig-propert y-type>jav a.lang.Str ing</confi g-property -type>
869	<conf ig-propert y-value>vl jPlacehold er</config -property- value>
870	</conf ig-propert y>
871	<conne ctionfacto ry-interfa ce>javax.r esource.cc i.Connecti onFactory< /connectio nfactory-i nterface>
872	<conne ctionfacto ry-impl-cl ass>gov.va .med.vista link.adapt er.cci.Vis taLinkConn ectionFact ory</conne ctionfacto ry-impl-cl ass>
873	<conne ction-inte rface>java x.resource .cci.Conne ction</con nection-in terface>
874	<conne ction-impl -class>gov .va.med.vi stalink.ad apter.cci. VistaLinkC onnection< /connectio n-impl-cla ss>
875	</conne ction-defi nition>
876	<transa ction-supp ort>NoTran saction</t ransaction -support>
877	<reauth entication -support>f alse</reau thenticati on-support >
878	</outbou nd-resourc eadapter>
879	</resourc eadapter>
880	</connecto r>
881	Figure 2‑1 . 1.6 Depl oyment Des criptor Te mplate (ra .xml)
882	1.6 Deploy ment Descr iptor: web logic ra.x ml
883	The locati on of the provided, template w eblogic-ra .xml deplo yment desc riptor is also the M ETA-INF su bfolder in side the a dapter RAR file (pac kaged or e xploded). The VistAL ink zip di stribution provides example ad apters wit h pre-conf igured ra. xml and we blogic-ra. xml files.
884	Unlike the ra.xml de ployment d escriptor, you will need to ed it the web logic-ra.x ml descrip tor with u nique valu es for eac h RAR you deploy. Th e key prop erties to modify are :
885	PropertyVa luejndi-na me (top/ad apter-leve l)Name sho uld be uni que across all adapt ers.
886	This is a NEW proper ty since t he previou s version of VistALi nk.
887	Needs to b e DIFFEREN T than the value of jndi-name used for t he connect ion instan ce. Recomm end settin g to the v alue of th e connecti on-instanc e jndi-nam e, appende d with "Ad apter", e. g., "vlj/S iouxFalls4 38Adapter" .jndi-name (connecti on-instanc e)Name sho uld be uni que across all adapt ers.
888	The value of this pr operty is the JNDI l ookup stri ng that ap plications will use to retriev e the adap ter, e.g., "vlj/Siou xFalls438" .
889	Recommend the JNDI n ame be alp hanumeric, also OK t o include the charac ters: - _ / ( ) [ ] connectorJ ndiName (v alue)Set t o the same value as the connec tion-insta nce jndi-n ame.Exampl e:
890	<?xml vers ion="1.0"? >
891	<weblogic- connector xmlns="htt p://www.be a.com/ns/w eblogic/90 " xmlns:xs i="http:// www.w3.org /2001/XMLS chema-inst ance" xsi: schemaLoca tion="http ://www.bea .com/ns/we blogic/90
892	http://www .bea.com/n s/weblogic /90/weblog ic-ra.xsd" >
893	<!-- War ning: The order the elements a ppear in c omplex ele ments is u sually imp ortant. It is a good idea to v alidate an d test the weblogic- ra.xml doc ument befo re committ ing. -->
894	<!-- For new ADAPT ER-level j ndi-name, recommend using valu e of conne ction inst ance JNDI name, appe nded with "Adapter" -->
895	<jndi-na me>vlj/Sio uxFalls438 Adapter</j ndi-name>
896	<enable- global-acc ess-to-cla sses>true< /enable-gl obal-acces s-to-class es>
897	<outboun d-resource -adapter>
898	<conne ction-defi nition-gro up>
899	<con nection-fa ctory-inte rface>java x.resource .cci.Conne ctionFacto ry</connec tion-facto ry-interfa ce>
900	<def ault-conne ction-prop erties>
901	<p ool-params >
902	<initial-c apacity>1< /initial-c apacity>
903	<max-capac ity>5</max -capacity>
904	<capacity- increment> 1</capacit y-incremen t>
905	<shrinking -enabled>t rue</shrin king-enabl ed>
906	<shrink-fr equency-se conds>1800 </shrink-f requency-s econds>
907	<highest-n um-waiters >214748364 7</highest -num-waite rs>
908	<connectio n-creation -retry-fre quency-sec onds>30</c onnection- creation-r etry-frequ ency-secon ds>
909	<connectio n-reserve- timeout-se conds>0</c onnection- reserve-ti meout-seco nds>
910	<test-freq uency-seco nds>3600</ test-frequ ency-secon ds>
911	<profile-h arvest-fre quency-sec onds>30</p rofile-har vest-frequ ency-secon ds>
912	<ignore-in -use-conne ctions-ena bled>false </ignore-i n-use-conn ections-en abled>
913	<match-con nections-s upported>t rue</match -connectio ns-support ed>
914	</ pool-param s>
915	<t ransaction -support>N oTransacti on</transa ction-supp ort>
916	<r eauthentic ation-supp ort>false< /reauthent ication-su pport>
917	</de fault-conn ection-pro perties>
918	<con nection-in stance>
919	<d escription >This is t he connect ion and JN DI name th at applica tions
920	will be ac cessing.</ descriptio n>
921	<j ndi-name>v lj/SiouxFa lls438</jn di-name>
922	<c onnection- properties >
923	<propertie s>
924	<propert y>
925	<!-- c onnectorJn diName val ue should be the sam e value as
926	c onnection instance j ndi-name a few lines above -->
927	<name> connectorJ ndiName</n ame>
928	<value >vlj/Sioux Falls438</ value>
929	</proper ty>
930	</properti es>
931	</ connection -propertie s>
932	</co nnection-i nstance>
933	</conn ection-def inition-gr oup>
934	</outbou nd-resourc e-adapter>
935	</weblogic -connector >
936	Figure 2‑2 . 1.6 Depl oyment Des criptor Te mplate (we blogic ra. xml)
937	Steps to C reate a 1. 6 RAR
938	Create a f older, in a file loc ation acce ssible on the admin server, fo r the new RAR. Name the folder in a way that easil y identifi es the ada pter, sinc e the fold er name wi ll become the deploy ed adapter name in W ebLogic.
939	Copy the f iles neede d for the new RAR fr om the Vis tALink zip distribut ion to the new RAR f older:
940	Production Systems: Copy the c ontents of the app-J 2EE\Rar-Pr od-Templat e folder f rom the Vi stALink zi p distribu tion to th e new RAR folder.
941	Non-produc tion syste ms: Copy t he content s of the a pp-J2EE\Ra r-Dev-Temp late folde r from the VistALink zip distr ibution to the new R AR folder.
942	Edit the w eblogic-ra .xml deplo yment desc riptor in the new RA R, to have the appro priate JND I names.
943	VistALink Connector Configurat ion File
944	VistALink- specific r esource ad apter (con nector) se ttings are stored in a separat e, host-fi le-system- based conn ector conf iguration file, name d gov.va.m ed.vistali nk.connect orConfig.x ml. You ca n edit thi s file man ually or u sing the C onfigurati on Editor (see the s ection "Co nfiguratio n Editor") .
945	The rules for the Vi stALink co nfiguratio n file are :
946	The file m ust be nam ed "gov.va .med.vista link.conne ctorConfig .xml".
947	The file m ust be pla ced in a f older that is on the ‘java’ cl asspath of the JVM o f each Web Logic serv er instanc e deployin g VistALin k connecto rs.
948	Because th e gov.va.m ed.vistali nk.connect orConfig.x ml file ho lds login credential s for acce ssing VA V istA syste ms, it mus t be prote cted. On L inux syste ms, access to the fo lder conta ining the file shoul d be restr icted to t he account or group under whic h WebLogic runs. Acc ess to the host file system sh ould be pr otected on all J2EE systems.
949	When the s erver depl oys a Vist ALink conn ector, the connector does the following:
950	Gets the c onnectorJn diName pro perty valu e from web logic-ra.x ml deploym ent descri ptor.
951	Loads gov. va.med.vis talink.con nectorConf ig.xml, vi a the serv er ‘java’ classpath.
952	Looks in t he VistALi nk configu ration fil e for a <c onnector> entry with a matchin g jndiName attribute .
953	Uses the s ettings fr om the mat ching entr y (ip, por t, access- code, veri fy-code, e tc.) to co nfigure th e connecto r.
954	NOTE: Alth ough you c an manuall y edit the VistALink configura tion file, a Configu ration Edi tor UI is provided a s part of the VistAL ink consol e (see the "
955	Configurat ion Editor
956	." section in the Vi staLink Ad ministrati on Console chapter.) Connector Entry Form at
957	The VistAL ink config uration fi le should contain on e <connect or> entry per connec tor module /adapter t hat you wi ll deploy to your J2 EE server. Each entr y should h ave a uniq ue jndiNam e. Each <c onnector> entry desc ribes the characteri stics of t he M liste ner that a particula r connecto r module/a dapter wil l connect to.
958	The follow ing exampl e shows th e format o f the Vist ALink conf iguration file (with a configu ration of a single l istener):
959	<?xml vers ion="1.0" encoding=" UTF-8"?>
960	<connector s encrypti onScoped=" false"
961	xmlns:xsi= "http://ww w.w3.org/2 001/XMLSch ema-instan ce"
962	xsi:noName spaceSchem aLocation= "connector Config.xsd "
963	xmlns="URL "
964	>
965	<connec tor
966	jndi Name="vlj/ SiouxFalls 438"
967	prim aryStation ="438"
968	ip=" URL"
969	port ="8000"
970	acce ss-code="j oe.123"
971	veri fy-code="e bony.432"
972	time out="30"
973	alwa ys-use-def ault-as-mi n="false"
974	enab led="true"
975	/>
976	</connecto rs>
977	Figure 2‑3 . VistALin k Configur ation File Format Ex ample
978	Connector Settings
979	The config uration fi le should contain on e or more <connector > elements (entries) inside th e top-leve l <connect ors> eleme nt.
980	The basic settings f or each <c onnector> entry are as follows :
981	jndiName ( required): Uniquely identifies each entr y. Should be the sam e JNDI nam e as you w ill specif y in the w eblogic-ra .xml descr iptor for your conne ctor. This setting i s also use d to creat e the JNDI half of t he mapping s between station nu mbers and connector JNDI names .
982	NOTE: The value must start wit h an alpha numeric ch aracter, a nd followi ng that ca n contain only alpha numeric pl us the fol lowing pun ctuation c haracters: - _ / ( ) [ ]primar yStation ( required): Station n umber of t he M/Kerne l system c onnected t o. VistALi nk’s insti tution map ping funct ionality m aps this s tation num ber to the connector 's JNDI na me, so the applicati on can ret rieve the connector by the sta tion numbe r. This en try is che cked again st the DEF AULT INSTI TUTION fie ld (#217) of the KER NEL SYSTEM PARAMETER S file (#8 989.3) at runtime, w hen connec tions are made.
983	ip (requir ed): IP ad dress of t he M VistA Link liste ner to con nect to (e ither nume ric or mne monic).
984	port (requ ired): Por t of the M VistALink listener to connect to.
985	access-cod e and veri fy-code (r equired): The access and verif y code cre dentials f or the con nector pro xy user to connect t o the M Vi stALink li stener.
986	NOTE: When entering access and verify co des direct ly in the config fil e (not usi ng the con figuration editor), if the cod es contain the follo wing speci al charact ers, they need to be entered a s follows:
987	special ch ar ente r as
988	< <
989	& &amp ;
990	" &quo t;
991	' &apo s;
992	or alterna tively, us e the conf iguration editor.enc rypted (op tional): t rue \| fals e. When th e access/v erify code s are encr ypted by V istALink, this attri bute is se t to true. If you ne ed to manu ally (outs ide the co nfiguratio n editor) update the access / verify cod e, however , set "enc rypted" to false so that VistA Link will know the a ccess/veri fy code is not encry pted.
993	enabled (r equired): true \| fal se. If fal se, the co nnector wi ll not dep loy. Use t his attrib ute primar ily to ret ain inacti ve configu rations in your conf iguration file.
994	timeout (o ptional): Sets the d efault spa n of time in seconds socket wi ll wait fo r response from M (e .g., waiti ng for an RPC to exe cute) and after whic h connecti on is auto matically terminated .
995	Advanced C onnector S ettings
996	always-use -default-a s-min: If true, the default ti meout will be the lo west timeo ut value a llowed for this conn ector; it will overr ide any pr ogrammatic ally speci fied lower value set by an app lication.
997	timestamp: When a co nnector en try is edi ted, the c onfigurati on editor automatica lly stamps the entry with a ti mestamp.
998	File-Wide Setting: e ncryptionS coped
999	encryption Scoped: Th is attribu te should not be edi ted direct ly, and in stead shou ld be modi fied only when using the VistA Link admin istration console to modify th e encrypti on type fo r all conf iguration file entri es. The fi le-wide <c onnectors> attribute "encrypti onScoped" reflects w hether ent ries have been encry pted with domain-sco ped encryp tion or no t. If doma in scoped, the domai n name is included i n the encr yption, ma king it di fficult to use encry pted value s on other WebLogic domains.
1000	Obsolete S ettings
1001	primarySta tionSuffix : This att ribute has been elim inated. An y primary station nu mbers requ iring an a lpha suffi x, should instead be entered a s part of the "prima ryStation" attribute , i.e., pr imaryStati on="200M". Note: If VA institu tion rules are being used, onl y 200-seri es (Austin Informati on Technol ogy Center ) station numbers ca n have alp ha suffixe s for the primary st ation numb er.
1002	Deploying J2EE Share d Librarie s for Vist ALink (Pro duction Sy stems Only )
1003	REF: To mi nimize the consumpti on of serv er resourc es, Oracle recommend s that sup porting li braries fo r RARs sho uld be dep loyed as J 2EE Shared Libraries , on produ ction syst ems.On pro duction sy stems only , prior to deploying any VistA Link RARs, you shoul d install the follow ing jars a s J2EE sha red librar ies:
1004	Jar NameJ2 EE Shared Library De ployment N amevljConn ector-1.6. 0.jarvljCo nnector(1. 6,1.6)vljF oundations Lib-1.6.0. jarvljFoun dationsLib (1.6,1.6)l og4j-1.2.1 3.jarlog4j -1To deplo y a jar as a shared library (P roduction Systems):
1005	Place the jar in a f older loca tion acces sible on t he admin s erver.
1006	Log on to the WebLog ic console .
1007	Select Loc k & Edit s o you can modify the domain co nfiguratio n.
1008	Navigate t o the Depl oyments pa ge.
1009	Click Inst all. Navig ate to the jar, sele ct it and click Next .
1010	Choose the server(s) to target . Choose a ll servers that you will be de ploying Vi stALink RA Rs on, and click Nex t.
1011	Leave the Name value as-is, an d click Fi nish.
1012	Click Acti vate Chang es to comp lete the d eployment.
1013	Deploying a RAR
1014	For each M system yo u want you r J2EE sys tem to con nect to, y ou need to create an d deploy a separate VistALink RAR (explo ded or pac kaged). Ea ch RAR con tains two deployment descripto rs, ra.xml and weblo gic-ra.xml . These ne ed to be c onfigured with the u nique sett ings that describe h ow the ada pter shoul d be deplo yed on the J2EE syst em and how it should connect t o a specif ic M syste m.
1015	To deploy a new Vist ALink adap ter:
1016	If you are deploying to a prod uction sys tem, ensur e that you have depl oyed the n ecessary s upporting libraries for VistAL ink as J2E E Shared L ibraries b efore proc eeding any further.
1017	Create the RAR (see Creating a RAR secti on above).
1018	Add an ent ry in the gov.va.med .vistalink .connector Config.xml file for the new ad apter, on all server s that the connector will be d eployed on . Its jndi Name attri bute shoul d match th e values u sed in web logic-ra.x ml in the <connectio n-instance > section, for <jndi -name> and connector JndiName ( see VistAL ink Connec tor Config uration Fi le section above).
1019	Propagate the update d gov.va.m ed.vistali nk.connect orConfig.x ml file to all serve rs in the domain hos ting VistA Link adapa ters.
1020	Use WebLog ic to targ et and dep loy the ne w RAR to o ne or more servers.
1021	Verify tha t the new adapter is working c orrectly o n each tar geted serv er, using the VistAL ink admini stration c onsole (se e The Vist ALink Admi nistration Console
1022	for more informatio n).
1023	Even thoug h the adap ter may de ploy succe ssfully fr om WebLogi c's point of view, t he test fo r configur ation comp letion is whether th e adapter can succes sfully con nect to th e M system .
1024	Updating A lready-Dep loyed Adap ters
1025	If you upd ate an ada pter setti ng in the VistALink configurat ion file, weblogic-r a.xml, or ra.xml, yo u do not n eed to bou nce the se rver to ac tivate the changed s etting. It is suffic ient to up date the a dapter in the WebLog ic console to make t he changed setting(s ) active.
1026	NOTE: Whil e the adap ter is bei ng updated , it may b e briefly unavailabl e to appli cations.To update an adapter:
1027	Log on to the WebLog ic console .
1028	Select Loc k & Edit s o you can modify the domain co nfiguratio n.
1029	Navigate t o the Depl oyments pa ge.
1030	Select the adapter t o update a nd click U pdate. Com plete the steps nece ssary to f inish the update.
1031	Click Acti vate Chang es.
1032	Verify tha t the adap ter state is Active.
1033	Verify tha t the upda ted adapte r is worki ng correct ly using t he VistALi nk adminis tration co nsole (see "The Vist ALink Admi nistration Console" section fo r more inf ormation).
1034	DNS Update s and Vist ALink Adap ters
1035	If the val ue of the "Ip" prope rty used t o configur e a VistAL ink 1.6 ad apter's de stination M system i s a domain name, the n DNS upda tes to the IP addres s correspo nding to t hat DNS na me can be received d ynamically /automatic ally by th e adapter, with a fe w caveats. This is a change fr om previou s versions of VistAL ink. The c aveats are :
1036
1037	The JVM's "cache for ever" sett ing may fo rce DNS lo okup cachi ng at the JVM level. For VistA Link adapt ers to rec eive DNS u pdates dyn amically, the JVM mu st be conf igured to turn off D NS caching . Otherwis e, the JVM will reso lve the DN S name onc e, at depl oyment, an d cache th at name un til the ne xt time th e JVM rest arts.
1038	This setti ng is usua lly contro lled by th e "network address.ca che.ttl" J VM propert y in the j ava.securi ty file, i n the lib/ security s ubdirector y of the J RE used fo r WebLogic . For exam ple:
1039	# The Java -level nam elookup ca che policy for succe ssful look ups:
1040	#
1041	# any nega tive value : caching forever
1042	# any posi tive value : the numb er of seco nds to cac he an addr ess for
1043	# zero: do not cache
1044	#
1045	# default value is f orever (FO REVER). Fo r security reasons, this
1046	# caching is made fo rever when a securit y manager is set.
1047	#
1048	# NOTE: se tting this to anythi ng other t han the de fault valu e can
1049	# ha ve serious security implicatio ns. Do not set it un less
1050	# yo u are sure you are n ot exposed to DNS sp oofing att ack.
1051	#
1052	# networka ddress.cac he.ttl=-1
1053	In order t o disable JVM-level DNS cachin g, the "ne tworkaddre ss.cache.t tl" proper ty must be uncomment ed for the JRE used by WebLogi c, for all servers i n the doma in, and se t to some value of 0 or greate r.
1054	NOTE: The "Java Home " value ma y need to be explici tly set in the "Conf iguration \| Server S tart" page for each server in the domain (use the WebLogic c onsole), i n order fo r the chan ge in java .security to be pick ed up.NOTE : Assuming servers r unning Vis tALink are running i nside a se cure intra net, the s ecurity ri sk of disa bling DNS caching is low (if a n organiza tion is us ing DNS at all to dy namically update int ernal IP a ddresses, then it ha s presumab ly already evaluated the risk to be acce ptable.)Ex isting con nections i n the conn ection poo l remain c onnected t o previous destinati on. If the DNS is up dated, exi sting open connectio ns to the previous D NS-resolve d system w ill remain until tho se connect ions close . The M-si de "J2EE C onnection Timeout" s etting in the M-side VistALink site para meters fil e determin es life of inactive connection s. Since t he current recommend ed value i s 1 day, e ven inacti ve connect ions could stay open to the fo rmer desti nation for quite som e time, an d if conne ctions are used, the y could st ay open ev en longer.
1055
1056	Some strat egies to e nsure exis ting conne ctions are terminate d when DNS is change d for the M system i nclude:
1057	If the M s ystem at t he old add ress is sh ut down, a ll open co nnections are termin ated autom atically.
1058	If the M s ystem mana ger kills all existi ng VistALi nk connect ions, this will remo ve any old connectio ns from po ol (if won 't disrupt service t o remainin g VistALin k clients, if any).
1059	On the J2E E side, if the J2EE system man ager 1) st ops the ad apter, and 2) update s the adap ter, this will shut down the p ool and al l old conn ections.
1060	Pool Size Management /Tuning
1061	Pool size management is a key factor in enhancing VistALink’ s performa nce on a J 2EE server (and mini mizing its impact on M servers ). It is c ostly to h ave either too many unused ope n connecti ons or not enough fo r incoming requests. Connectio n pool siz ing will b e part of the art of system tu ning in a HealtheVet -VistA env ironment.
1062	On the Web Logic serv er, you ca n use the WebLogic c onsole and the weblo gic-ra.xml deploymen t descript or to cont rol the ch aracterist ics of the connectio n pool for each depl oyed resou rce adapte r.
1063	Key settin gs include :
1064	Initial Ca pacity: T he number of connect ions to cr eate for t he connect ion pool. Pool creat ion happen s on initi al deploym ent and on server st artup. Hig her number s for this setting c an add add itional ti me to the server sta rtup proce ss.
1065	Max Capaci ty: The h igh point of expansi on for the connectio n pool. Yo u may want to set th is based o n the high est load y ou can pla ce on the M system y ou are con nected to (potential work as w ell as lic ense slot usage). On the J2EE side, if a ll connect ions are i n use and the Max Ca pacity set ting is r eached, ap plications requestin g a connec tion will be thrown a Resource Exception.
1066	Shrinking Enabled an d Shrink F requency S econds: T his allows pools to shrink whe n the numb er of requ ests has s lowed down and creat ed connect ions are i nactive fo r a given set of tim e. Enablin g shrinkin g is recom mended in most cases , to reduc e the numb er of inac tive conne ctions usi ng license slots on M systems.
1067	Configurin g log4j Lo gging
1068	The VistAL ink Java c ode base h as been in strumented with log4 j logging statements . log4j is an open-s ource logg ing packag e distribu ted under the Apache Software license.
1069	It can be helpful in debugging and troub leshooting to review the outpu t informat ion contai ned in the log files produced at runtime . System a dministrat ors can co nfigure lo g4j to log either Vi stALink er rors only or VistALi nk errors with debug informati on.
1070	REF: Learn more abou t the log4 j tool at: http://l ogging.apa che.org/lo g4j/docs/ .log4j Con figuration Overview
1071	A log4j co nfiguratio n file con tains:
1072	appender e ntry(s): C onfigurati on entries describin g the dest inations f or logging informati on
1073	logger ent ry(s): Con figuration entries d escribing the level specific i nformation will be l ogged. Log gers are t ypically o rganized b y Java pac kage and c lass name.
1074	The config uration fi le is used by log4j to set up a JVM-wide logging c onfigurati on. Becaus e this con figuration spans app lications, HealtheVe t-VistA ap plications do not co ntrol logg ing config urations i ndividuall y. Instead , a single log4j con figuration file must be set up with the logging co nfiguratio n for all HealtheVet -VistA app lications running on a particu lar JVM.
1075	Configurin g log4J
1076	Currently, we recomm end the fo llowing st eps for co nfiguring log4j:
1077	Create a s ingle file named "lo g4j.xml" t o hold the loggers a nd appende rs for all HealtheVe t-VistA ap plications on your J 2EE system .
1078	Add in all the appen der elemen ts require d to set u p as many logging de stinations as you ne ed for you r system.
1079	Add in all the logge r elements required to configu re logging for your HealtheVet -VistA app lications running on your serv er. (VistA Link provi des a list of availa ble logger s, which y ou can use to config ure loggin g coming f rom VistAL ink classe s.)
1080	Place this file in a HealtheVe t-VistA co nfiguratio n folder o n your J2E E server J VM classpa ths.
1081	The purpos e of the f older is t o hold con figuration files for all Healt heVet-Vist A applicat ions, incl uding Vist ALink.
1082	If you per form steps 1-4 above , log4j wi ll find th e log4j.xm l file on your serve r classpat hs, and wi ll be able to establ ish a JVM- wide log4j logging c onfigurati on for all applicati ons runnin g in the J VM.
1083	Alternativ e Approach
1084	Alternativ ely, you c an place a log4j con figuration file on t he file sy stem and p ass its na me and loc ation as t he log4j.c onfigurati on system property t o the JVM at startup . This fil e does not need to b e on the J VM classpa th.
1085	The follow ing exampl e shows ho w to start a JVM wit h a log4j configurat ion stored in a non- log4j.xml file, in a folder th at is not on the ser ver classp ath:
1086	<JAVA_HOME >\bin\java -Dlog4j.c onfigurati on=file:// /c:/localC onfigs/myl og4j.xml
1087	Sample log 4j Configu ration Fil es
1088	To create the log4j configurat ion file, the system administr ator can d o one of t he followi ng:
1089	Use the in formation above to a dd to an o verall log 4j configu ration fil e
1090	Copy one o f the samp le log4j c onfigurati on files p rovided in the VistA Link distr ibution zi p file or
1091	Just copy some of th e logger e lements in the sampl e files.
1092	The sample log4j con figuration files can be locate d in the l og4j direc tory insid e the Vist ALink dist ribution z ip file. T here are t wo sample log4j conf iguration files:
1093	File NameD escription log4jSampl eJ2EEConfi g.xmlExamp le configu ration for a J2EE sy stem, turn ing DEBUG- level logg ing on for VistALink classes o f interest on a J2EE system.
1094	Note: Turn ing on ‘de bug’ level can adver sely affec t system p erformance .log4jSamp leJ2SEConf ig.xmlExam ple config uration fo r a J2SE ( Java clien t-M server ) applicat ion, turni ng DEBUG-l evel loggi ng on for VistALink classes of interest for client /server ap plications .Figure 3‑ 1. Sample log4j conf iguration files
1095	The follow ing is a s imple log file examp le with on e appender element, two logger elements and a root logger, r educed fro m "log4jSa mpleJ2EECo nfig.xml":
1096	<?xml vers ion="1.0" encoding=" UTF-8" ?>
1097	<!DOCTYPE log4j:conf iguration SYSTEM "lo g4j.dtd">
1098	<log4j:con figuration xmlns:log 4j="http:/ /jakarta.a pache.org/ log4j/">
1099	<!-- APP ENDERS -->
1100	<appende r name="ve rboseDaily RollingFil eAppender" class="or g.apache.l og4j.Daily RollingFil eAppender" >
1101	<param name="Fil e" value=" /YOURLOGDI R/vlj.log" />
1102	<param name="Dat ePattern" value="'.' yyyy-MM-dd "/>
1103	<layou t class="o rg.apache. log4j.Patt ernLayout" >
1104	<para m name="Co nversionPa ttern" val ue="%-4r % d{ISO8601} [%t] %-5p %C:%M:%L - %m%n"/>
1105	</layo ut>
1106	</append er>
1107	<!-- LOG GERS -->
1108	<!-- DEB UG-level l oggers for VistaLink packages, override ROOT logge r level
1109	in production , usually turn on DE BUG level logging fo r troubles hooting sp ecific pro blems only -->
1110	<logger name="gov. va.med.vis talink.ada pter.spi.V istaLinkMa nagedConne ctionFacto ry" additi vity="fals e" >
1111	<l evel value ="debug" / >
1112	<appe nder-ref r ef="verbos eDailyRoll ingFileApp ender"/>
1113	</logger >
1114	<logger name="gov. va.med.vis talink.ada pter.spi.V istaLinkMa nagedConne ction" add itivity="f alse" >
1115	<l evel value ="debug" / >
1116	<appe nder-ref r ef="verbos eDailyRoll ingFileApp ender"/>
1117	</logger >
1118	<!-- ROO T level lo gger: usua lly good t o log all ERROR-leve l entries regardless of source -->
1119	<root>
1120	<l evel value ="error" / >
1121	<appe nder-ref r ef="verbos eDailyRoll ingFileApp ender"/>
1122	</root>
1123	</log4j:co nfiguratio n>
1124	Figure 3‑2 . Log4j co nfiguratio n file exa mple
1125	VistALink Core log4j Categorie s
1126	VistALink core log4j categorie s are docu mented in the spread sheet prov ided in th e log4j su bdirectory of the Vi stALink di stribution file.
1127	To obtain a full log 4j logger category n ame for a given pack age and cl ass, conca tenate the package w ith the cl ass. For e xample, th e logger f or: gov.va .med.vista link.adapt er.spi (pa ckage) and VistaLink ManagedCon nection (c lass) is g ov.va.med. vistalink. adapter.sp i.VistaLin kManagedCo nnection.
1128	Each logge r category provides a descript ion and no tes the su pported lo gger level s (e.g., D EBUG and E RROR). You can then use the lo gger categ ory name(s ) to set u p loggers in your lo g4j config uration fi les to log informati on from sp ecific par ts of the VistALink package, a s needed.
1129	Institutio n Mapping
1130	Applicatio ns using V istALink n eed the ab ility to s elect the resource a dapter (co nnector) t o execute a remote p rocedure c all (RPC) on a given M system. On the J2 EE side, t he way to retrieve a connector is with a Java Nami ng and Dir ectory Int erface (JN DI) name. The instit ution, sta tion, and division n umber are the pieces of inform ation an a pplication is likely to have t o identify an M syst em it want s to conne ct to. App lications should not have to h ard-code c onnector J NDI names; in most c ases they should get the appro priate con nector usi ng a stati on number.
1131	Managing t he Mapping
1132	PrimarySta tion Attri bute (Vist ALink Conf iguration File)
1133	The primar yStation a ttribute f or connect or entries in VistAL ink's conf iguration file provi de the map ping betwe en connect or JNDI na mes and Vi stA statio n numbers. The (requ ired) prim aryStation attribute of the <c onnector> element li nks a part icular con nector (id entified b y its JNDI name) wit h a partic ular stati on number.
1134	In the fol lowing con figuration file exam ple, stati on number "11000" (a nd its des cendants " 11000A," "110000B," etc.) are mapped to the JNDI name "vlj/ testconnec tor":
1135	<?xml vers ion="1.0" encoding=" UTF-8"?>
1136	<connector s encrypti onScoped=" false"
1137	xmlns:xsi= "http://ww w.w3.org/2 001/XMLSch ema-instan ce"
1138	xsi:noName spaceSchem aLocation= "connector Config.xsd "
1139	xmlns="htt p:// URL /vistalink /adapter/c onfig"
1140	>
1141	<connec tor
1142	jndi Name="vlj/ testconnec tor"
1143	prim aryStation ="11000"
1144	ip="test. URL " port=" PORT " access-c ode="joe.1 23" verify -code="ebo ny.432" ti meout="30" always-us e-default- as-min="fa lse" enabl ed="true"
1145	/>
1146	</connecto rs>
1147	Figure 4‑1 . Institut ion Mappin g Associat ion in Vis tALink Con figuration File
1148	Assuming t he above c onnector i s deployed on a give n server, when an ap plication asks for t he JNDI na me for the connector for stati on 11000A, it will b e returned the strin g "vlj/tes tconnector ."
1149	How the Ma pping Is I nitialized
1150	Institutio n mapping is per JVM in-memory cache, ba sed on the settings configured by the ad ministrato r in the V istALink c onfigurati on file. I t is initi alized whe n the firs t connecto r is deplo yed to a g iven serve r. The map pings for each conne ctor are a dded in wh en each co nnector de ploys. If multiple s ervers hav e connecto rs deploye d, each se rver has i ts own cop y/version of the in- memory cac he.
1151	Viewing th e Current Mapping
1152	To view th e current set of ins titution-t o-station number map pings on a ny server, use the V istALink a dministrat ion consol e on your WebLogic a dministrat ion server (if deplo yed). For more infor mation see Monitorin g Institut ion Mappin g in the s ection The VistALink Administr ation Cons ole.
1153	Updating I nstitution Mappings
1154	Mappings a re loaded automatica lly for a connector whenever t he connect or is depl oyed. If a previous connector has been m apped to t he same st ation numb er, a "las t one in w ins" strat egy is emp loyed, and a warning -level log ger entry is logged.
1155	Mappings a re marked for remova l when a c onnector i s undeploy ed. The ac tual remov al of the mappings d oes not ha ppen until garbage c ollection runs on th e server. If garbage collectio n has not run and a mapping is used to r etrieve th e JNDI nam e of an un deployed c onnector, the attemp t to use o f the conn ector will fail at t he point t he applica tion attem pts to ret rieve the connection factory f rom JNDI. If garbage collectio n has run, the attem pt to use of the con nector wil l fail whe n no JNDI name can b e returned for the g iven stati on number.
1156	How Applic ations Use Instituti on Mapping s
1157	Applicatio ns are pro vided with an Applic ation Prog ram Interf ace (API) to retriev e a connec tor's JNDI name, bas ed on a st ation numb er. For mo re informa tion, see the VistAL ink 1.6 De veloper Gu ide.
1158	Troublesho oting Inst itution Ma pping Issu es
1159	Out-of-Syn ch Configu ration Fil es on Mult iple Physi cal Server s
1160	The VistAL ink config uration fi le (gov.va .med.vista link.conne ctorConfig .xml) must be access ible on th e JVM clas spath of e ach server with depl oyed VistA Link conne ctors. Bec ause separ ate copies of the Vi stALink co nfiguratio n file can exist for separate physical s ervers, it is possib le that th ese copies may not b e identica l. The pri maryStatio n attribut es, on whi ch the ins titution m apping is based, may be differ ent.
1161	It is the responsibi lity of th e system a dministrat or to keep separate physical c opies of t he VistALi nk configu ration fil e synchron ized.
1162	Connector Station an d M System Mismatch
1163	The primar yStation a ttribute i s used to create the mappings that appli cations us e to retri eve the co nnector. I t is alway s possible to miscon figure a c onnector, associatin g it with the wrong station nu mber. Stat ion mismat ch checkin g is emplo yed to cat ch such co nfiguratio n errors.
1164	When VistA Link conne cts to an M system, the primar yStation a ttribute o f the conn ector is p assed to M . It is th en checked against t he DEFAULT INSTITUTI ON field ( #217) of t he KERNEL SYSTEM PAR AMETERS fi le (#8989. 3). If it doesn't ma tch, the c onnection is rejecte d, and a S ecurityPri maryStatio nMismatchE xception i s returned to the ap plication.
1165	The system administr ator shoul d monitor the VistAL ink admini stration c onsole and log files for indic ators of r ejected co nnections due to pri mary stati on mismatc hes.
1166	JNDI Name Configurat ion Mismat ch
1167	The jndiNa me attribu te in the VistALink configurat ion file i s used to associate a station number wit h a partic ular conne ctor. Howe ver, the J NDI name u nder which WLS deplo ys the con nector com es from th e <jndi-na me> elemen t in the w eblogic-ra .xml file. If these two values don't mat ch, the ma pping will not refle ct the cor rect JNDI name for t he connect or.
1168	Runtime ch ecking val idates whe ther these values ar e the same . If they are not, a ttempts to use the c onnector w ill return a VistaLi nkResource Exception to the app lication. In additio n, the Vis tALink adm inistratio n console will displ ay a warni ng if it s ees these values do not match for a give n connecto r.
1169	The two JN DI setting s are in t he weblogi c-ra.xml d eployment descriptor and the g ov.va.med. vistalink. connectorC onfig.xml file. When these set tings are out of syn ch, the re sult shoul d be an un usable con nection (o utright fa ilure), ra ther than an incorre ctly route d connecti on, which is harder to diagnos e.
1170	The system administr ator shoul d monitor the VistAL ink admini stration c onsole and log files for indic ators of r ejected co nnections due to JND I name mis matches.
1171	Mappings w ith Undepl oyed Conne ctors (Sto pped or De leted)
1172	Mappings a re marked for remova l when a c onnector i s undeploy ed. Howeve r, the act ual remova l of the m appings do es not hap pen until garbage co llection r uns on the server.
1173	If a conne ctor has b een undepl oyed and g arbage col lection ha s not yet run, the a ttempted u se of the connector will fail at the poi nt the app lication a ttempts to retrieve the connec tion facto ry from JN DI. If gar bage colle ction has run, the a ttempted u se of the connector will fail when no JN DI name ca n be retur ned for th e given st ation numb er. In bot h cases, t he attempt to use th e undeploy ed connect or will fa il.
1174	Pluggable Institutio n Mapping Rules
1175	NOTE: This section i s of inter est primar ily to non -VA users of VistALi nk.The imp lementatio n of insti tution map ping used on the J2E E side of VistALink contains r ules with several VA -specific assumption s, in part icular:
1176	Legal stat ion number s in VA ca n be 3 dig its or 5+ digits wit h one exce ption (see nursing h omes below ).
1177	For statio n numbers assigned t o the Aust in Informa tion Techn ology Cent er (AITC) only: If a station n umber has an alpha s uffix, e.g . "200A", the numeri c portion must be "2 00"
1178	For nursin g homes: I f a numeri c station number is 4 digits, the 4th di git must b e a "9"
1179	In order t o facilita te use of VistALink outside of VA, the i mplementat ion of the se VA rule s has been placed in to a plugg able Prima ryStationR ules imple mentation. By defaul t, the VA- specific i mplementat ion of the station n umber rule s is used when worki ng with st ation numb ers on the J2EE side . However, to have V istALink u se a diffe rent rule implementa tion in pl ace of the default V A-specific one:
1180	A new impl ementation of the IP rimaryStat ionRules i nterface m ust be pro vided, and
1181	The packag e/classnam e of the n ew impleme ntation mu st be pass ed in a -D JVM argum ent, "gov. va.med.vis talink.pri mary-stati on-rules-c lass". E.g ., pass -D gov.va.med .vistalink .primary-s tation-rul es-class=o rg.test.Pr imaryStati onRulesTes t
1182	REF: For m ore inform ation on i mplementin g a non-VA -specific institutio n rules cl ass, see t he Develop er's Guide .The VistA Link Admin istration Console
1183	Overview
1184	The VistAL ink admini stration c onsole run s in two m odes depen ding on in stallation : either a s an exten sion in th e WebLogic console, or as a st andalone W eb applica tion. In b oth cases, the VistA Link admin istration console ru ns on the administra tion serve r for a gi ven WebLog ic configu ration. It provides the follow ing functi onality:
1185	Monitor Co nnector St atus (per server)
1186	Connector summary li st with he alth indic ators, sta tus
1187	Connector detail, in cluding a live call to M syste m
1188	Institutio n mapping associatio n list
1189	Configurat ion Editor (admin se rver only)
1190	Edit conn ector conf igurations in VistaL ink connec tor config uration fi le
1191	Monitor Ro le Restric tions
1192	WebLogic’s console s upports fo ur roles: Administra tors, Depl oyers, Ope rators and Monitors. The 1.6 V istALink a dministrat ion consol e restrict s users in the Monit ors role t o read-onl y access. Users in t he Monitor s role can monitor c onnector s tatus, but are restr icted from using the Configura tion Edito r.
1193	NOTE: To s upport acc ess by use rs in the Monitors r ole, the s ystem admi nistrator currently needs to e xplicitly declare th e "Listen Address" a ttribute i n the WebL ogic domai n configur ation, for each serv er in the domain. Ot herwise a JMX remoti ng call th at is need ed, fails, under Mon itor privi leges alon e. Accessi ng the Vis tALink Adm inistratio n Console
1194	VistALink Administra tion Conso le as Stan dalone Web Applicati on
1195	If install ed as a st andalone W eb applica tion, you can access it at the following URL:
1196	http://<ad min server >:<port>/v lconsole
1197	You’ll be prompted f or a user name and p assword. U se the sam e credenti als as you would use to login to the Web Logic admi nistration console. From that point on, the standa lone VistA Link conso le applica tion will look almos t identica l to the c onsole ext ension plu g-in versi on (except it will n ot have th e WebLogic console c ontent dis played on the left a nd top.).
1198
1199	Figure 5‑1 . Standalo ne VistALi nk 1.6 Adm inistratio n Console
1200	NOTE: On W ebLogic 10 .3, the Vi stALink ad ministrati on console works bes t when ins talled as a standalo ne applica tion.VistA Link Admin istration Console as WebLogic Console Ex tension
1201	If install ed as an e xtension i n the WebL ogic conso le, access the VistA Link conso le extensi on as part of the ma in WebLogi c console. Within th e WebLogic console, the VistAL ink consol e extensio n can be f ound in tw o location s:
1202	As a tab ( ‘VistALink J2M’) in the WebLog ic console ’s domain page
1203	As a link (‘VistALin k J2M’) in the WebLo gic consol e’s naviga tion tree, under ‘En vironment’
1204	NOTE: On W ebLogic 10 , only the tab in th e WebLogic console’s domain pa ge may be available. The link in the con sole’s nav igation tr ee may not be displa yed.Figure 5‑2 shows two ways to access the VistAL ink admini stration c onsole whe n installe d as a Web Logic cons ole extens ion.
1205
1206	Figure 5‑2 . VistALin k Administ ration Con sole: Acce ss via lin k in navig ation tree and tab i n domain t ab set
1207	Monitoring Connector Status
1208	To monitor connector status, p ick a serv er in your domain fr om the lis t of serve rs on the main VistA Link Admin istration console pa ge. You ca n then mon itor vario us attribu tes of the VistALink adapter(s ) deployed on that s erver.
1209	Adapter Li st/Summary
1210	On the fir st page af ter select ing a serv er, Figure 5‑3, you’ ll be show n a list o f VistALin k adapters on the se rver, incl uding heal th indicat ors and ot her summar y informat ion for ea ch:
1211	Deployed J NDI Name: The JNDI n ame under which the adapter ha s been dep loyed and made avail able to ot her applic ations
1212	JNDI Misma tch: Indi cates that the JNDI name used to look up the conne ctor setti ngs in the VistALink configura tion file (from the “connector JndiName” custom pro perty valu e in weblo gic-ra.xml ) does not match the deployed JNDI name used by th e containe r to deplo y the conn ector, whi ch could i ndicate a misconfigu red connec tor.
1213	Health Ind icators/Fa ilure Coun ts:
1214	Conn Socke t: The nu mber of ti mes, since deploymen t or serve r re-start , that an attempt to create a physical c onnection to the M s ystem has failed.
1215	Conn Auth: The numb er of time s, since d eployment or server restart, t hat the co nnector ha s attempte d and fail ed to log on to the M system w ith the co nnector us er access/ verify cod e.
1216	Prod Misma tch: The number of times sinc e deployme nt or serv er restart that the connector has attemp ted to log on to the M system and found a mismatch between t he Product ion settin gs for the M system and the J2 EE server' s JVM. On the J2EE s erver, thi s setting is control led via th e gov.va.m ed.environ ment.produ ction JVM argument.
1217	Div Mismat ch: The n umber of R PC request s since de ployment o r server r estart tha t have fai led becaus e the divi sion speci fied in th e RPC requ est is not legal for the re-au thenticati on user. A large num ber of div ision mism atches may indicate a misconfi gured JNDI -to-instit ution mapp ing for th e connecto r in quest ion.
1218	Re-Auth: The number of times since depl oyment or server res tart that re-authent ication ha s failed w hen attemp ting to ex ecute RPCs on behalf of users. A large n umber of f ailures ma y indicate a misconf igured JND I-to-insti tution map ping for t he connect or in ques tion.
1219	M System I nfo: The I P address and port u sed to con nect to th e M system configure d for the adapter.
1220	Deployment State: Th e deployme nt state o f the adap ter on the J2EE syst em.
1221
1222	Figure 5‑3 . Connecto r Summary List
1223	Adapter De tail
1224	If you cli ck on the “Deployed JNDI Name” link for any adapte r on the s ummary pag e, you’ll access a d etail page , Figure 5 ‑4 and Fig ure 5‑5, w ith more i nformation for the c onnector:
1225	WebLogic-s pecific co nfiguratio n informat ion
1226	VistALink- specific c onfigurati on informa tion
1227	including institutio n mappings associate d with the connector
1228	Health mon itoring in dicators
1229	Performanc e monitori ng indicat ors
1230	Live VistA Link M/Vis tA Server Query, inc luding (fr om M):
1231	M VistALin k version
1232	“Connector Proxy” us er name fr om the New Person fi le
1233	UCI/volume /box-volum e pair of the M acco unt
1234	Domain, In stitution and Test/P roduction setting of the M acc ount
1235	Introducto ry Text (f or visual confirmati on of corr ect system )
1236	NOTE: When the detai l page is loaded for any conne ctor, a "l ive" call is made to the M sys tem. The r esults pro vide an ea sy way to get a pict ure of the M system connected to, and ma y also hel p verify w hether a c onnector i s reaching the inten ded M syst em.
1237	Figure 5‑4 . Connecto r Detail, 1 of 2
1238
1239	Figure 5‑5 . Connecto r Detail, 2 of 2
1240	Monitoring Instituti on Mapping
1241	Click on “ Institutio n Mapping” to displa y the curr ent set of instituti on mapping associati ons on the selected server. Fo r example:
1242	Station #
1243	JNDI Name
1244	11000
1245	vlj/testc onnector
1246	11001
1247	vlj/testc onnector1
1248	11002
1249	vlj/testc onnector2
1250	The curren t mappings for the s elected se rver are l isted in a table. Yo u can use this infor mation to monitor an d verify t he current , live ins titution m appings on your serv er(s).
1251
1252	NOTE: Appl ications t ypically r etrieve an adapter b y using th e station #. The act ual adapte r returned to the ap plication is determi ned by wha t JNDI nam e is mappe d to the r equested s tation #. The list o f mappings is genera ted (and m odified) w hen each a dapter’s c onfigurati on is load ed during adapter de ployment, update, or server st artup.Conf iguration Editor
1253	The VistAL ink admini stration c onsole inc ludes the Configurat ion Editor , for edit ing the Vi stALink co nfiguratio n file sto ring infor mation abo ut each Vi stALink ad apter/conn ector, Fig ure 5‑6.
1254	NOTE: User s that are in the Mo nitor role (and not a Deployer , Operator or Admini strator) a re disallo wed from u sing the c onfigurati on editor.
1255	Figure 5‑6 . Configur ation Edit or Main In terface
1256	About the Configurat ion File
1257	The config uration fi le contain s addition al propert ies needed to define a VistALi nk adapter beyond th ose in the deploymen t descript ors (ra.xm l and webl ogic-ra.xm l).
1258	The Config uration Ed itor loads the confi guration f ile from t he admin s erver clas spath. If a file nam ed "gov.va .med.vista link.conne ctorConfig .xml" is f ound in a folder on the admin server cla sspath, th e Configur ation Edit or loads t he content s of this file autom atically. When chang es are mad e and save d, they ar e saved to this file as well, on the adm in server only.
1259	NOTE: The main page of the Con figuration Editor di splays the physical file locat ion of the VistaLink connector configura tion file that it is using, on the admin server.Co nfiguratio n files mu st conform to the sc hema file connectorC onfig.xsd, provided with the V istALink 1 .6 distrib ution. For more info rmation ab out the Vi stALink co nfiguratio n file, se e the sect ion, "Vist ALink Conn ector Conf iguration File."
1260	How to Pro pagate Con figuration Changes t o Other Se rvers
1261	A copy of the config uration fi le must be available on the cl asspath of all serve rs in a do main that have deplo yed VistAL ink adapte rs. Change s made by the Config uration Ed itor, howe ver, are m ade to the copy of t he file on the physi cal file s ystem of t he admin s erver only .
1262	Multiple S erver, Mul tiple Mach ine Domain : In order to update the per-s erver Vist ALink conf iguration files for other phys ical serve rs in your domain (i .e., manag ed servers ), you mus t manually copy/prop agate the edited fil e from the admin ser ver to a l ocation on the class path of th e particul ar server.
1263	Multiple S erver, Sin gle Machin e Domain: Because al l of the s ervers in this type of domain reside on the same p hysical ma chine, it is possibl e to confi gure all o f their cl asspaths t o contain the same f older, hol ding a sin gle copy o f the Vist ALink conf iguration file. In s uch cases, no furthe r propagat ion of the configura tion file is require d.
1264	Single Ser ver Domain : In a sin gle server WebLogic domain, on e server i s both the admin ser ver and th e server o n which co nnectors a nd applica tions are deployed. No further propagati on of the configurat ion file b eyond the admin serv er is requ ired.
1265	Viewing an d Editing Connector Properties
1266	Users can view and e dit connec tor proper ties by se lecting on e of the c onnectors (hyperlink ed) from t he connect or list. T he Configu ration Edi tor will t hen displa y the conn ector’s pr operties, Figure 5‑7 .
1267
1268	Figure 5‑7 . Editing a Connecto r Entry
1269	After edit ing the fi le, you ca n save the changes b y clicking the Submi t button.
1270	For a desc ription of the vario us propert ies in a c onnector c onfigurati on, see th e earlier section in the Deplo ying VistA Link on J2 EE chapter , "VistALi nk Connect or Configu ration Fil e."
1271	JNDI Namin g Recommen dations
1272	When namin g adapters and editi ng connect or entries , we recom mend that you begin all connec tor JNDI n ames with a common J NDI subcon text name, i.e., "vl j/", follo wed by a m eaningful name to sp ecifically identify the adapte r, i.e., " vlj/Salem6 58".
1273	The Config uration Ed itor permi ts the fol lowing pun ctuation c haracters as part of the JNDI name (the first lett er of the JNDI name must be al phanumeric , however) : - _ / \ ( ) [ ]
1274	Encryption of Access /Verify Co des
1275	Encryption of the ac cess and v erify code adds an a dditional level of s ecurity to protect c onnector p roxy user credential s. The pro perties ar e encrypte d when you :
1276	Save chang e when you edit an e xisting co nnector, o r add a ne w connecto r
1277	Select “En crypt Unen crypted En tries” on the main C onfigurati on Editor page (only shown if there are unencrypte d entries in the fil e)
1278	When a con nector con figuration is loaded by a depl oyed adapt er on a gi ven system
1279	The main p age of the Configura tion Edito r displays the numbe r of unenc rypted con nector ent ries, if a ny.
1280	Modifying Access/Ver ify Codes Outside of Configura tion Edito r
1281	If necessa ry, the ac cess and v erify code can be mo dified out side the C onfigurati on Editor, and store d in clear text. Whe n doing th is, set th e optional encrypted attribute to "false ". Then th e next tim e any of t he encrypt ion-trigge ring event above hap pen for th e connecto r entry, t he access and verify codes wil l be encry pted and t he encrypt ed attribu te set to "true".
1282	Encrypt Un encrypted Entries Fe ature
1283	If any une ncrypted e ntries are present i n the conf iguration file, a 'E ncrypt Une ncrypted E ntries' bu tton is di splayed. C hoosing th is will al low you to encrypt a ll unencry pted entri es present in the fi le.
1284	Changing t he Encrypt ion Type
1285	The encryp tion type reflects w hether ent ries have been encry pted with domain-sco ped encryp tion or no t. If doma in scoped, the domai n name is included i n the encr yption, ma king it di fficult to use encry pted value s on other WebLogic domains. C onfigurati on files f rom before 1.6 do no t have dom ain-scoped encryptio n.
1286	To change the encryp tion type, select Ch ange Encry ption Type on the ma in Configu ration Edi tor page, Figure 5‑8 .
1287
1288	Figure 5‑8 . Changing the encry ption type -- confir mation pag e
1289	Monitoring VistALink via JMX a nd MBeans
1290	Overview
1291	Java Manag ement eXte nsions (JM X) is the Java-stand ard mechan ism for ma king appli cations ma nageable, including providing monitoring capabilit ies. Appli cations (a nd the app lication s erver itse lf) supply a variety of MBeans . Through JMX, attri butes on t he MBeans can be mon itored, an d operatio ns invoked , both loc ally insid e a JVM an d remotely from outs ide the JV M.
1292	A variety of built-i n and thir d-party ut ilities an d applicat ions suppo rt the use of JMX to access MB ean attrib utes and o perations, including :
1293	third-part y JMX cons oles
1294	third-part y monitori ng applica tions
1295	scripting tools such as WebLog ic Scripti ng Tool (W LST) and w lshell
1296	the WebLog ic console itself, w hich is bu ilt around JMX and M Beans
1297	VistALink MBeans
1298	VistALink provides t wo MBean t ypes that can be mon itored:
1299	VistaLinkC onnector M Bean
1300	Deployed: One instan ce per JVM , per depl oyed VistA Link adapt er
1301	MBean Type : VistaLin kConnector
1302	VistaLinkC onnector A ttributeTy peDescript ionCfgIpAd dressjava. lang.Strin gIP addres s from Vis tALink con figuration file used for this connector. CfgPortint port from VistALink configurat ion file u sed for th is connect orCfgTimeo utlongtime out from V istALink c onfigurati on file us ed for thi s connecto rCfgTimeou tAlwaysUse DefaultAsM inbooleanw hether a l ower timeo ut can be set by app lications than the c onfigured timeout, f rom VistAL ink config uration fi le used fo r this con nectorCont ainerMBean Namejavax. management .
1303	ObjectName System-spe cific Obje ctName of connector' s connecto r MBean li nked to th is VistALi nk MBeanDe ploymentSt atejava.la ng.Stringt he current deploymen t state of the conne ctor (plat form-speci fic string )
1304	Throws: ja va.rmi.Rem oteExcepti on - throw n if unabl e returns this infor mation (ob tained fro m another MBean)Dist inguishedI dentifierl ongunique, internall y managed distinguis hed identi fier for t he VistALi nk connect orEisTypej ava.lang.S tringthe E ISType of the connec tor (for V istALink c onnectors, should al ways be 'V istA')
1305	Throws: ja va.rmi.Rem oteExcepti on - throw n if unabl e returns this infor mation (ob tained fro m another MBean)Hlth Connection AuthFailur eCountlong number of connector proxy auth entication failures for this c onnector, since last system st artup or d eploymentH lthConnect ionFailure Countlongn umber of T CP-level c onnection failures f or this co nnector, s ince last system sta rtup or de ploymentHl thDivision MismatchCo untlongnum ber of mis matches be tween conn ector prim aryStation setting a nd target M system's primary s tation, si nce last s ystem star tup or dep loymentHlt hIdentityF ailureCoun tlongnumbe r of re-au thenticati on identif ication fa ilures (fa ilure to m atch reque sted DUZ, Applicatio n Proxy or VPID on M system), since last system st artup or d eploymentH lthProduct ionMismatc hCountlong number of mismatches between J 2EE server 's and M s erver's pr oduction s etting, si nce last s ystem star tup or dep loymentJnd iNameActua ljava.lang .Stringthe JNDI name used to r egister th e connecto r in the J NDI tree o f the serv erJndiName CustomProp java.lang. Stringthe value of t he connect orJndiName custom ra .xml prope rtyPerfCre ateConnect ionHandleA vgMillisdo ubleThe am ount of ti me it take s for a Vi staLink ma naged conn ection to create a n ew connect ion handle for the u nderlying physical c onnection represente d by the M anagedConn ection ins tance; thi s connecti on handle is used by the appli cation cod e to refer to the un derlying p hysical co nnectionPe rfMatchMan agedConnec tionAvgMil lisdoubleT he amount of time it takes for the Vista Link conne ction fact ory to eit her a) mat ch a conne ction requ est with a n existing connectio n in pool of managed connectio ns, or b) determine that no su ch match e xistsQuery MappedInst itutionsja va.lang.St ring[]a fo rmatted st ring array listing t he institu tions curr ently mapp ed to this connector QueryMSyst emMapjava. util.Mapre turns a Ma p containi ng a set o f string k eys and va lues obtai ned from c alling the M system. QueryMSyst emReportja va.lang.St ring[]a fo rmatted st ring array report re presenting a set of properties and value s obtained from call ing the M systemVend orSpecific Properties java.util. Mapa Map c ontaining vendor-spe cific prop erties and values
1306	Throws: ja va.rmi.Rem oteExcepti on - throw n if unabl e returns this infor mation (ob tained fro m other MB eans)Table 6‑1. Vist aLinkConne ctor MBean Attribute s
1307	VistaLinkI nstitution Mapping MB ean
1308	Deployed: One instan ce per JVM where Vis tALink Con nectors ar e Deployed
1309	Type: Vist aLinkInsti tutionMapp ing
1310	Attribute NameTypeAt tributeIns titutionMa ppingsjava .util.MapA Map conta ining stri ng keys (s tation num bers) and string val ues (JNDI names) rep resenting the curren t institut ion mappin g associat ions on th is JVM.Tab le 6‑2. Vi staLinkIns titutionMa pping MBea n Attribut es
1311	VistALink MBean Secu rity
1312	By default , in WebLo gic 9/10 d omains, cu stomer-sup plied MBea ns such as those pro vided by V istALink a re secured as follow s:
1313	attributes : anyone w ho can aut henticate to the dom ain can ac cess
1314	operations : must pos sess admin istrator r ole to inv oke
1315	All VistAL ink MBean informatio n access i s implemen ted as att ributes.
1316	M Server M anagement
1317	Overview
1318	Because Vi stALink co nnectors a re deploye d on J2EE servers, m uch of the managemen t workload for VistA Link focus es on the J2EE serve r. However , the Vist ALink list ener (the portion of VistALink that resi des on the M server) must also be manage d.
1319	In some ca ses, the s ame system manager m ay be resp onsible fo r managing both the J2EE and M portions of VistALi nk. In man y cases, h owever, th e two side s will be managed by different system ma nagers, in separate computing facilities .
1320	Finding Us er Process es with th e Connecti on Manager
1321	The Connec tion Manag er (new wi th VistALi nk 1.6) tr acks all a ctive Vist ALink conn ections on the curre nt M syste m, display s the indi vidual pro cesses, an d gives yo u the opti on to eith er kill a selected V istALink c onnection, or all Vi stALink co nnections. The Conne ction Mana ger could be useful during sof tware inst allations, for examp le, where it might b e desirabl e to get a ll VistALi nk process es off of the system .
1322
1323	In multi-n ode M envi ronments, the M node you run t he Connect ion Manage r on shoul d be on th e same nod e as the V istALink c onnections are runni ng on, as started by the VistA Link liste ner(s).
1324	Main scree n capture:
1325	VL/J2M Con nection Ma nager Feb 21, 20 08@11:33:1 4 Page: 1 of 1
1326	Job Se lection Cr iteria (ma tches: 4)
1327	Box-V olume Pair : ROU:CACH E2
1328	Current Namespace : VL-HEAD
1329	Routine : XOBVSKT
1330	Job State : READ :: Job is rea ding from a device.
1331	Entry PID D evice:Clie nt IP Commen t
1332	1 175 6 \| TCP\|8016\|1 756:10.6.2 1.65 User=* KILMADE,JO E
1333	2 175 7 \| TCP\|8016\|1 757:10.6.2 1.65 User=* KILMADE,JO E
1334	3 117 69 \| TCP\|8016\|1 1769:10.6. 17.157 User=* KILMADE,JO E
1335	4 117 70 \| TCP\|8016\|1 1770:10.6. 17.157 User=* KILMADE,JO E
1336
1337
1338
1339
1340	* Connecto r Proxy Us er
1341	TA Termin ate All RE Refres h
1342	TP Termin ate PID SS System Status
1343	Select Act ion:Quit//
1344	Figure 7‑1 . Using th e Connecti on Manager
1345	ActionDesc riptionTA (Terminate All)Kills all VistA Link conne ctionsTP ( Terminate PID)Kills a selected VistALink connectio nRE (Refre sh)Refresh es/updates the list of connect ionsSS (Sy stem Statu s)Displays a list of all proce sses runni ng on the system (no t just Vis tALink one s)Table 7‑ 2. Connect ion Manage r actions and defini tions
1346	Finding Vi stALink Pr ocesses wi thout the Connection Manager
1347	VMS System s
1348	On VMS sys tems, the listener f or any act ive VistAL ink connec tion is ty pically co nfigured t o be launc hed via VM S TCP Serv ices. Vist ALink sets the VMS p rocess nam e to "VLin k_XXXXXXXX ", where " XXXXXXXX" is the val ue of the M $J conve rted to he x.
1349	This makes it easier to find w hich VMS p rocesses a re associa ted with V istALink, and with w hich M job as well. You can us e the DCL command SH OW SYSTEM /PROC=VL t o display all VistAL ink proces ses. For e xample:
1350	core$ show sys /proc =VL* <RET>
1351	OpenVMS V7 .3-2 on n ode ISC1A4 1-MAR-2 005 10:19: 47.64 Upt ime 146 1 0:17:35
1352	Pid P rocess Nam e State Pri I/O CPU Page flts Pages
1353	20F9B10B V LINK_BG187 7 HIB 11 179 0 0 0:00:00.01 202 184 N
1354	20F9F90C V Link_20F9F 90C LEF 11 211 0 0 0:00:00.11 4186 852 S
1355	20FA190D V LINK_BG189 1 HIB 11 172 0 0 0:00:00.04 202 184 N
1356	20F9890E V Link_20F98 90E LEF 10 211 0 0 0:00:00.10 4310 865 S
1357	20F9C90F V LINK_BG191 0 HIB 11 172 0 0 0:00:00.01 202 184 N
1358	20F9C910 V Link_20F9C 910 LEF 10 211 0 0 0:00:00.09 4231 852 S
1359	core$
1360	Figure 7‑3 . Use the DCL comman d SHOW SYS TEM /PROC= VL to disp lay all Vi stALink pr ocesses
1361	Non-VMS Sy stems
1362	To list Vi stALink pr ocesses on non-VMS s ystems (e. g. Caché o n Windows) , you can look for p rocesses t hat are fr equently i n the XOBV SKT routin e; these p rocesses a re VistALi nk listene rs. (Howev er, when R PCs are in voked, the routine l isted will be differ ent.)
1363	Listener M anagement
1364	Listener M anagement for Caché/ VMS System s
1365	See the se ction "Lis tener Mana gement for Caché/VMS " in Chapt er 2 ("Vis tA/M Serve r Installa tion Proce dures") of the VistA Link 1.6 I nstallatio n Guide.
1366	Listener M anagement for Caché/ NT Systems
1367	See Append ix A, "Lis tener Mana gement for Caché/NT Systems."
1368	Listener M anagement for DSM/VM S Systems
1369	See Append ix B, "Lis tener Mana gement for DSM/VMS S ystems."
1370	M Listener Site Para meters Fil e
1371	The FOUNDA TIONS SITE PARAMETER S file (#1 8.01) is u sed to con trol liste ner settin gs for all implement ations (Ca ché and DS M, on VMS and Window s). It con tains one entry; the ".01" fie ld is a po inter to t he DOMAIN file (#4.2 ). When Vi stALink is installed , the inst all proces s creates this entry and assig ns the pro per Domain Name usin g the DOMA IN file.
1372	The site p arameters in this to p-level en try pertai n to Found ations and VistALink . Currentl y, all the parameter s in this file are r elated to VistALink and listen er configu ration. As more Foun dations to ols are in troduced, non-VistAL ink-relate d paramete rs will be added.
1373	NOTE: As p art of the VistALink installat ion for Ca ché system s, a liste ner config uration na med 'DEFAU LT' was cr eated for port 8000. To edit th e site par ameters, u se the Sit e Paramete rs action in the Fou ndations m enu.
1374	Site Param eters for All System Types
1375	To edit Vi stALink re lated site parameter s, use the Site Para meters act ion:
1376	HEARTBEAT RATE: 180/ / <Enter>
1377	LATENCY DE LTA: 180// <Enter>
1378	J2EE CONNE CTION TIME OUT: 60480 0//
1379	J2EE REAUT HENTICATIO N TIMEOUT: 3600//
1380	Figure 7‑4 . Edit Vis tALink rel ated site parameters
1381	Site Param eters for Windows Sy stems
1382	When the l istener ru ns in M (r ather than via VMS T CP Service s), you sh ould make an entry i n the Vist ALink LIST ENER CONFI GURATION f ile for ea ch set of listeners that you p lan to run on your s ystem. Aft er adding a listener configura tion, you need to as sociate th at configu ration wit h any BOX- VOLUME whe re the new configura tion is ap propriate.
1383	Note that the follow ing portio n of the d ialog is n ot present ed to a DS M system u ser:
1384	Select BOX -VOLUME PA IR: ROU:CA CHE//
1385	BOX-VOLU ME PAIR: R OU:CACHE// <Enter>
1386	DEFAULT CONFIGURAT ION: DEFAU LT// <Ente r>
1387	Select BOX -VOLUME PA IR:
1388	Figure 7‑5 . Edit sit e paramete rs for Win dows syste ms
1389	It is irre levant on Caché /VMS as well, if the lis tener is s tarted via VMS TCP S ervices.
1390	As part of this acti on, you ar e asked to select a Box-Volume Pair entr y. Then, w ithin each Box-Volum e Pair ent ry (repres enting the volume se t and syst em on whic h the list ener shoul d run), yo u can set the defaul t listener configura tion to be automatic ally start ed as part of the ex ecution of the XOBV LISTENER S TARTUP opt ion. Also, the Start Box actio n uses thi s default listener c onfigurati on.
1391	The table below defi nes the Fo undations Site Param eter file fields.
1392	FieldDescr iptionHear tbeat Rate This field indicates the rate (in second s) of the VistALink heartbeat message or iginating from a cli ent. If th ere is no activity o n the conn ection for the speci fied amoun t of time, the clien t will sen d a system heartbeat message.
1393	The client , as part of the ini tial conne ction prot ocol, retr ieves this value. As a result, the clien t and the M server a re always synchroniz ed regardi ng the hea rtbeat rat e.Latency DeltaThis field indi cates the number of seconds to add to th e HEARTBEA T RATE whe n calculat ing the in itial time out value for the Vi stALink li stener.
1394	The client and the M server ar e synchron ized regar ding the H EARTBEAT R ATE. This latency pa rameter al lows the s ite to fin e-tune the timeout v alue. The site can t o take int o account any networ k slowness or other factors th at may del ay the arr ival of th e system h eartbeat m essage fro m the clie nt.J2EE Co nnection T imeoutThis field ind icates the number of seconds t hat a Vist ALink conn ection fro m J2EE to M should b e allowed to remain connected when inact ive, befor e M drops the connec tion.
1395	It is reco mmended th at the J2E E CONNECTI ON TIMEOUT parameter be set re latively h igh, e.g., 1 day (86 400 second s). A high setting i s recommen ded becaus e all the major appl ication se rver imple mentations have more robust me chanisms f or control ling conne ction pool s.
1396	The site s hould use the tools/ mechanisms supplied by the app lication s erver impl ementation to contro l how the connection pool size grows and shrinks.J 2EE Re-aut henticatio n TimeoutT his new pa rameter in dicates th e number o f seconds between 18 0 and 3600 (inclusi ve) before a re-auth enticated connection is consid ered expir ed and mus t go throu gh the re- authentica tion proce ss again. (default: 600 secs).
1397	Rules:
1398	If a conne ction in t he applica tion serve r's pool i s not reus ed by a pa rticular r e-authenti cated user before th is timeout limit is reached, t he re-auth entication is consid ered expir ed.
1399	If the tim eout is re ached, the re-authen tication p rocess is performed again even if the sa me user us es the con nection.
1400	If the sam e connecti on is used again by the re-aut henticated user befo re the tim eout is re ached, the session i s consider ed re-auth enticated for these number of seconds mo ving forwa rd. (i.e. the timeou t clock is reset)
1401	If a diffe rent user gains acce ss to the connection , the connectio n is immed iately con sidered no t re-authe nticated, and the re -authentic ation proc ess is per formed.
1402	Example of Re-authen tication E xpiration:
1403	User gains access an d uses a c onnection from the p ool at 4:0 0pm
1404	User signs off and g oes home, along with most of t he site st aff
1405	After 4:00 pm, user file maint enance is performed and the us er's profi le is chan ged. For e xample, th e user's F ILE MANAGE R ACCESS C ODE [DUZ(0 )] is chan ged.
1406	User signs back on t he next mo rning at 8 am
1407	Since ther e is very little act ivity from 4:00-8 am , the conn ection has not been re-used by another u ser and is still ass ociated wi th 4:00 us er
1408	Since time out has pa ssed, re-a uthenticat ion has ex pired
1409	Re-authent ication pr ocess occu rs for the user
1410	Re-authent ication pr ocess rese ts DUZ(0) appropriat ely to the new value .Box-Volum e Pair(For M-based l isteners o nly)
1411	This field indicates the BOX-V OLUME pair for the e ntry.
1412	The XOBV L ISTENER ST ARTUP opti on uses th is field t o find the configura tion that should be used to st artup Vist ALink list eners for the BOX-VO LUME pair.
1413	Note: This informati on is pres ented to b oth VMS an d NT Cache ΄ users, b ut not to DSM users. However, it is igno red if lis teners are started v ia the VMS TCP Servi ce.Default Configura tion(For M -based lis teners onl y)
1414	This field indicates the defau lt startup listener configurat ion for th e BOX-VOLU ME PAIR en try.
1415	The XOBV L ISTENER ST ARTUP opti on uses th is field t o retrieve the corre ct listene r configur ation from the VISTA LINK LISTE NER CONFIG URATIONS f ile (#18.0 3).
1416	The inform ation in t he configu ration is then used to startup the indic ated VistA Link liste ners on th e desired ports.
1417	Note: This informati on is not presented to a DSM s ystem user .Table 7‑6 . Foundati ons Site P arameter f ile field definition s
1418	Security
1419	J2EE Syste m Manager Security T asks for V istALink
1420	The primar y J2EE sys tem manage r tasks fo r ensuring VistALink security are:
1421	Safeguardi ng the acc ess/verify codes tha t M system managers provide to configure connector s with.
1422	These acce ss/verify codes are for "conne ctor proxy " users, a nd must be kept conf idential. The level of system access the y provide to the M s ystem is s ignificant .
1423	Ensuring t hat connec tors are p roperly co nfigured t o reach th e appropri ate M syst ems.
1424	This is do ne primari ly through the VistA Link confi guration f ile (gov.v a.med.vist alink.conn ectorConfi g.xml) and by making sure that connector s are mapp ed to the appropriat e VA stati on number, IP, and P ort.
1425	M System M anager Sec urity Task s for Vist ALink
1426	The primar y M system manager t asks for e nsuring se curity for VistALink are:
1427	Creating c onnector p roxy users for J2EE systems co nnecting t o your M s ystem
1428	Securely c ommunicati ng connect or proxy c redentials (access a nd verify codes) to authorized J2EE syst em manager s, who use them to c onfigure t heir J2EE systems to access yo ur M syste m.
1429	VistALink' s J2SE Sec urity Mode l
1430	For J2SE c lients ope rating in client/ser ver mode w ith VistA, the VistA Link secur ity model is as foll ows:
1431	A persiste nt connect ion is cre ated betwe en the Jav a client a nd the M s erver. Act ions canno t be perfo rmed until the DUZ a rray has b een create d on the M side, act ing as pro of of end- user ident ity.
1432	To create the DUZ ar ray, the J ava client prompts t he user fo r access/v erify code s, divisio n (as need ed), and n ew verify code (as n eeded), an d submits this infor mation to Kernel sec urity.
1433	If the cre dentials a re valid, the DUZ ar ray is cre ated.
1434	From that point on, the client can issue RPC reque sts to the M server. Authoriza tions are checked th rough the normal RPC authoriza tion call, based on the conten ts of the DUZ array. If author ized, the RPC is exe cuted and results ar e returned . Because this is a persistent connectio n, the DUZ array "pe rsists" be tween call s. Because the conne ction is n ot used by or availa ble to oth er clients , it does not need t o be repro ved each t ime.
1435	VistALink' s J2EE Sec urity Mode l
1436	The securi ty modes f or J2EE an d J2SE are different . In J2EE n-tier mod e, the con nections a re pooled on the J2E E server a nd are reu sed betwee n differen t users. T here are t wo levels of securit y.
1437	The first security l evel is th e authenti cation for the conne ction itse lf. It is implemente d similarl y to the c lient/serv er-mode me chanism de scribed in the previ ous sectio n:
1438	The app se rver/conne ctor is co nfigured b y the app server adm inistrator with the access/ver ify code o f an M use r. The M u ser must b e marked a s a "conne ction prox y" user. ( In J2EE mo de, only u sers whose Kernel ac count is m arked as " connection proxy" ca n have con nections e stablished on their behalf.)
1439	If the cre dentials a re valid, a J2EE con nection is establish ed.
1440	The J2EE s erver plac es the con nection in a connect ion pool, for use by J2EE appl ications r unning on the J2EE s erver.
1441	In the J2C A specific ation, the second le vel of sec urity is a process c alled re-a uthenticat ion. Here, the end-u ser identi ty informa tion is pa ssed from the callin g applicat ion to Vis tALink via a J2CA co nnection s pec. The r e-authenti cation ste ps are as follows:
1442	When a J2E E applicat ion obtain s a connec tion from the J2EE s erver's po ol of conn ections, i t passes i dentity in formation about the end-user t o VistALin k via a J2 CA "connec tion spec. "
1443	VistALink (on the J2 EE side) p asses the identity ( DUZ, VPID, or applic ation prox y name) do wn to M.
1444	Via a "cha in of trus t," VistAL ink (on th e M side) trusts tha t the call ing J2EE a pplication has authe nticated t he identit y of the e nd-user (v ia FatKAAT , KAAJEE, etc.).
1445	VistALink (on the M side) perf orms a lig htweight s ecurity co ntext swit ch to the identity o f the spec ified end- user. RPCs are then executed u nder the D UZ of the end-user, and normal RPC secur ity is app lied.
1446	RPCs conti nue to exe cute under the ident ity of the specified end-user until the connection is "close d" (return ed to the pool) by t he J2EE ap plication.
1447	Connector Proxy User (J2EE)
1448	The M serv er’s prima ry gatekee per for co ntrolling J2EE/VistA Link acces s to M is the connec tor proxy user. This is a spec ial user c lass in th e Kernel N EW PERSON file (#200 ). Only J2 EE connect ors config ured with credential s for "con nection pr oxy" Kerne l users ca n connect to an M Vi stALink li stener. On ce a conne ction is e stablished through a connectio n proxy us er, J2EE a pplication s on that J2EE serve r can exec ute a vari ety of RPC s on the M server un der a vari ety of end -user iden tities.
1449	J2EE Re-au thenticati on Mechani sms for En d-Users
1450	Once a con nection is establish ed from J2 EE to M vi a a connec tor proxy user, Vist ALink empl oys a proc ess called re-authen tication, which runs RPCs unde r the iden tity of an actual en d-user.
1451	Whenever a n applicat ion uses a connectio n to execu te a reque st, re-aut henticatio n makes a lightweigh t security context s witch from the conne ctor proxy user iden tity to ac tual end-u ser identi ties. This switch is performed for the f ollowing r easons:
1452	Connection s are pool ed for use by multip le end-use rs on the applicatio n server
1453	Most RPCs need to ru n in the c ontext of specific K ernel/M en d-users
1454	NOTE: It i s preferab le that a connector proxy user have no p rivileges. The VistAL ink re-aut henticatio n architec ture assum es that th e identity of the en d-user has already b een authen ticated (v erified) b y the call ing applic ation. The refore Vis tALink doe s not atte mpt to aut henticate the end-us er’s ident ity. To do so would be difficu lt for an M system, given the variety of client me chanisms t hrough whi ch end-use rs could b e accessin g any J2EE applicati on. (There is also t he possibi lity that an end-use r might no t even hav e an accou nt on a gi ven M syst em – in th is case, a special " applicatio n proxy" u ser accoun t could be used inst ead.)
1455	Instead of authentic ating the end-user’s identity, VistALink does the following to re-auth enticate t he end use r:
1456	Trusts tha t the conn ecting app lication h as authent icated the end-user, relying o n the chai n of trust establish ed through the conne ctor proxy user
1457	Verifies t hat it can match the end-user identity p assed by t he request ing applic ation to a n identity on the M system
1458	Checks whe ther the i dentified M account is authori zed to per form the r equested a ction
1459	When retri eving a Vi stALink co nnection f rom a conn ection fac tory, the applicatio n supplies end-user credential s as part of the con nection sp ecificatio n. These c redentials are used to switch security c ontext on the M side . This re- authentica tion proce ss establi shes the c orrect end -user envi ronment on the M ser ver (VPID, Applicati on Proxy, etc.) for the durati on of the time that the connec tion is in use.
1460	To link id entities, the applic ation sele cts one co nnection s pecificati on from th e followin g, to retr ieve a con nection:
1461	Connection Specifica tion class Credential sVistaLink DuzConnect ionSpecKno wn DUZ val ue, plus s tation num berVistaLi nkVpidConn ectionSpec Known VPID value, pl us station numberVis taLinkAppP roxyConnec tionSpecAp plication Proxy name , plus sta tion numbe rTable 8‑1 . Connecti on Specifi cation Cla ss and Cre dentials
1462	VPID is th e connecti on specifi cation exp ected to b e used in most produ ction scen arios. Wha tever end- user authe ntication mechanism is used by a Healthe Vet-VistA applicatio n, the app lication s hould be a ble to obt ain the VP ID for a g iven end-u ser as an output fro m the auth entication process. When the e nd-user is authentic ated, the J2EE appli cation can use the V PID as a w ay to iden tify the e nd-user to any VistA M systems , when exe cuting RPC s on such systems on behalf of the end-u ser. Kerne l patch XU 8.0309 i s required to suppor t the VPID connectio n specific ation on M -VistA sys tems.
1463	DUZ (with DuzConnect ionSpec) i s the prim ary re-aut henticatio n mechanis m until th e VPID inf rastructur e is fully rolled ou t. At that point Duz Connection Spec will be depreca ted, and V pidConnect ionSpec wi ll be the primary me chanism. I n both cas es (DUZ an d VPID), i t is expec ted that t he login w ill have b een perfor med alread y through a VHA-appr oved authe ntication mechanism, and that authentica tion mecha nism will make the D UZ or VPID available for use b y the appl ication.
1464	The Applic ation Prox y connecti on specifi cation is expected t o be used in either of the fol lowing spe cial situa tions:
1465	The J2EE e nd-user do es not hav e a user a ccount on the M syst em on whic h an RPC i s to be ex ecuted
1466	It is not appropriat e for the RPC to exe cute under the ident ity of a p articular end-user.
1467	RPC Securi ty (B-Type Option)
1468	All RPCs, whether ac cessed in J2SE clien t/server o r J2EE mod e, are sec ured with an RPC con text (a "B "-type opt ion). Any end-user f or whom an RPC is ex ecuted mus t have the "B"-type option in their menu tree asso ciated wit h the RPC. Otherwise an except ion is thr own.
1469	For more i nformation on RPC se curity, se e Getting Started wi th the BDK , Chapter 3 (Extract ): RPC Ove rview, whi ch is bund led in the /doc fold er of the VistALink distributi on, as the file xwb1 _1p13dg-rp c_extract. pdf.
1470	Creating C onnector P roxy Users for J2EE Systems
1471	To allow V istALink a ccess to y our M syst em from a specific J 2EE system (applicat ion server ), a Kerne l "connect or proxy" account mu st be used , as follo ws:
1472	The M syst em manager creates a connector proxy acc ount for a given J2E E system.
1473	The M syst em manager provides the access and verif y code of the connec tor proxy user to th e J2EE sys tem manage r.
1474	The J2EE s ystem mana ger config ures a con nection po ol to conn ect to the particula r M system , using th e access/v erify code credentia ls of the connector proxy user provided by the M s ystem mana ger.
1475	Security C aution
1476	By setting up connec tor proxy users, you are grant ing access on your M server to execute a wide vari ety of RPC s on your system. Th erefore yo u need to do the fol lowing:
1477	Create con nection pr oxy users only for J 2EE system s needing access to your M sys tem.
1478	Give the a ccess/veri fy codes o f the conn ection pro xy users t o approved server ad ministrato rs only.
1479	Create a d ifferent c onnection proxy user (with dif ferent acc ess/verify code cred entials) f or each J2 EE cluster (or data center) th at will be connectin g to your M system.
1480	Make sure not to dis seminate t he access/ verify cod e for a co nnector pr oxy user o utside of secure com munication channels. Creating t he "Connec tor Proxy User"
1481	To create a connecto r proxy us er:
1482	You must h old the Ke rnel XUMGR key.
1483	Add a new connector proxy user by using the Founda tions menu on your M system an d choosing the Enter /Edit Conn ector Prox y User opt ion.
1484	The accoun t requires no additi onal infor mation fro m what is prompted f or by the option.
1485	Leave the connector proxy user 's Primary Menu empt y.
1486	Securely c ommunicate the acces s code and verify co de for the connector proxy use r to the J 2EE system manager s etting up access fro m J2EE to your syste m. Also co mmunicate the IP and port of y our VistAL ink listen er.
1487	Do not ent er divisio ns for a c onnector p roxy user
1488	Do not ent er a prima ry menu
1489	Do not als o use the connector proxy user as a test "end-user "
1490	Utilize th e user onl y as a con nector pro xy userAdd itional Se curity Iss ues (J2SE Mode)
1491	The follow ing issues pertain o nly to Vis tALink's c lient/serv er (J2SE) mode, wher e a Java c lient conn ects direc tly to an M system.
1492	Authentica tion in Cl ient/Serve r Mode
1493	In client/ server (J2 SE) mode, VistALink authentica tion, like that of t he RPC Bro ker, is a wrapper ar ound the K ernel logi n on your M system. It obeys t he same au thenticati on rules a s other Ke rnel login s on your system, an d uses Ker nel code t o obtain a "yes/no" authentica tion decis ion for ea ch login a ttempt.
1494	As with th e RPC Brok er, author ization to execute R PCs is req uired, bas ed on the "B"-type K ernel opti on/context mechanism .
1495	CCOW-Based Single Si gn-on
1496	VistALink' s client/s erver mode supports single sig n-on to M systems ba sed on use r context, as implem ented by t he Office of Informa tion’s Sin gle Sign-O n/User Con text (SSO/ UC) projec t.
1497	NOTE: On V MS-based s ystems, CC OW-based s ingle sign on is dep endent on the GETPEE R^%ZOSV ca ll to retu rn the cli ent IP add ress. The GETPEER^%Z OSV call i s in turn dependent on the DCL COM file used to la unch the V istALink l istener. T his file m ust set up logical s ymbols use d by GETPE ER^%ZOSV.K ernel Auto Sign-on
1498	VistALink' s client/s erver (J2S E) support s an older single si gn-on syst em, Kernel Auto-Sign on. In ad dition to the existi ng require ments for Kernel aut o sign-on, VistALink has the f ollowing r estriction s:
1499	The Broker client ag ent must a lready be running on the works tation.
1500	RPC Broker , Telnet, or VistALi nk can all be the fi rst active connectio n.
1501	NOTE: On V MS-based s ystems, Ke rnel auto sign-on fo r VistALin k is depen dent on th e GETPEER^ %ZOSV call to return the clien t IP addre ss. The GE TPEER^%ZOS V call is in turn de pendent on the DCL C OM file us ed to laun ch the Vis tALink lis tener. Thi s file mus t set up l ogical sym bols used by GETPEER ^%ZOSV.Sen sitivity o f VistALin k-Logged D ata
1502	In client/ server (J2 SE) mode, VistALink uses the l og4J loggi ng utility to write informatio n to a con figurable log. The i nformation written b y VistALin k loggers should not be applic ation-sens itive data , and shou ld not pos e a securi ty issue, even if th e end-user turns on logging to its most detailed l evel.
1503	Troublesh ooting Vis tALink 1.6
1504	Overview
1505	In general , to troub leshoot mo st VistALi nk-related problems, you shoul d check th e followin g location s to gathe r helpful troublesho oting info rmation:
1506	VistALink Administra tion Conso le – revie w the stat us and hea lth indica tors/failu re counts for the co nnector in question, on the se rver in qu estion.
1507	VistALink Administra tion Conso le – can y ou access the detail page for the connec tor, which makes a l ive query over the c onnector t o the M sy stem? Is t he query s uccessful? If not, w hat error message is displayed ?
1508	Review the WebLogic server-spe cific log file and c onsole out put file f or the ser ver on whi ch the err or occurre d:
1509
1510	<DOMAIN_HO ME>/server s/<SERVER_ NAME>/logs /<SERVER_N AME>.log
1511	<DOMAIN_HO ME>/server s/<SERVER_ NAME>/logs /<SERVER_N AME>.out
1512	Review the log4j fil e logs con figured fo r VistALin k's loggin g, for the server on which the error occ urred.
1513	Review the M-side er ror trap(s ) for the M system(s ) involved (D ^XTER)
1514	Symptoms a nd Possibl e Solution s
1515	The table below show s symptoms and possi ble causes and solut ions for V istALink r esource ad apter prob lems. It i s not an e xhaustive list but c ontains so me of the more commo n error co nditions y ou may enc ounter.
1516	Connection Attempt t o Bad List ener Addre ss/Port
1517	Symptom: D uring WebL ogic Serve r startup, an error like the f ollowing p rints out on the com mand conso le and in the WebLog ic Server log:
1518	####<Jul 1 9, 2004 2: 59:08 PM P DT> <Warni ng> <Conne ctor> <tes tserver> < myserver> <main> <<W LS Kernel> > <> <BEA- 190032> << VistaLink Adapter_vl j_testconn ector > Re sourceAllo cationExce ption of g ov.va.med. vistalink. adapter.cc i.VistaLin kResourceE xception: Can not cr eate Vista SocketConn ection;
1519
1520	Root cause exception :
1521
1522	gov.va.med .net.Vista SocketExce ption: Can not creat e TCP/IP s ocket.;
1523
1524	Root cause exception :
1525
1526	java.net.C onnectExce ption: Con nection re fused: con nect on cr eateManage dConnectio n.>
1527	####<Jul 1 9, 2004 2: 59:08 PM P DT> <Warni ng> <Conne ctor> <tes tserver> < myserver> <main> <<W LS Kernel> > <> <BEA- 190024> << VistaLink Adapter_vl j_testconn ector > Er ror making initial c onnections for pool. Reason: g ov.va.med. net.VistaS ocketExcep tion: Can not create TCP/IP so cket.;
1528
1529	Root cause exception :
1530
1531	java.net.C onnectExce ption: Con nection re fused: con nect>
1532	Diagnoses and Soluti ons: The c onnector m odule's IP and port may be con figured to connect t o a non-ex istent lis tener.
1533	Connection Attempt t o RPC Brok er Listene r
1534	Symptom: D uring WebL ogic serve r start up , an error like the following prints out on the co mmand cons ole and in the WebLo gic server log:
1535	####<Jul 1 9, 2004 2: 53:46 PM P DT> <Warni ng> <Conne ctor> <tes tserver> < myserver> <main> <<W LS Kernel> > <> <BEA- 190032> << VistaLink Adapter_vl j_testconn ector > Re sourceAllo cationExce ption of g ov.va.med. vistalink. adapter.cc i.VistaLin kResourceE xception: Foundation sException in execut eInitSocke tInteracti on.;
1536
1537	Root cause exception :
1538
1539	gov.va.med .foundatio ns.utiliti es.Foundat ionsExcept ion: Error executing the inter action;
1540
1541	Root cause exception :
1542
1543	gov.va.med .vistalink .adapter.s pi.VistaLi nkSocketCl osedExcept ion: This connection cannot be retried b ecause con struction has failed ;
1544
1545	Root cause exception :
1546
1547	gov.va.med .net.Vista SocketExce ption: Err or occurre d reading from socke t. ;
1548
1549	Root cause exception :
1550
1551	gov.va.med .net.Vista SocketExce ption: End of stream encounter ed unexpec tedly. on createMana gedConnect ion.>
1552	Diagnoses and Soluti ons: The c onnector m odule's IP and port may be con figured to connect t o an RPC B roker list ener rathe r than to a VistALin k listener .
1553	Invalid Co nnector Pr oxy Creden tials
1554	Symptom: D uring WebL ogic serve r start up , an error like the following prints out on the co mmand cons ole and in the WebLo gic server log:
1555	####<Jul 1 9, 2004 3: 08:34 PM P DT> <Warni ng> <Conne ctor> <tes tserver> < myserver> <main> <<W LS Kernel> > <> <BEA- 190032>
1556	<< VistaLi nkAdapter_ vlj_testco nnector > ResourceAl locationEx ception of gov.va.me d.vistalin k.adapter. cci.VistaL inkResourc eException : Could no t perform logon[]Not a valid A CCESS CODE /VERIFY CO DE pair. o n createMa nagedConne ction.>
1557	####<Jul 1 9, 2004 3: 08:34 PM P DT> <Warni ng> <Conne ctor> <tes tserver> < myserver> <main> <<W LS Kernel> > <> <BEA- 190024> << VistaLink Adapter_vl j_testconn ector > Er ror making initial c onnections for pool. Reason: g ov.va.med. vistalink. adapter.cc i.VistaLin kResourceE xception: Could not perform lo gon[]Not a valid ACC ESS CODE/V ERIFY CODE pair.>
1558	Diagnoses and Soluti ons: The a ccess and verify cod e specifie d for the connector are not va lid connec tor proxy signon cre dentials o n the dest ination M system.
1559	Connector Proxy Expi red Verify Code
1560	Symptom: D uring WebL ogic Serve r startup, errors li ke the fol lowing pri nt out in the comman d console and the We bLogic Ser ver log.
1561	####<Jul 1 9, 2004 3: 13:56 PM P DT> <Warni ng> <Conne ctor> <tes tserver> < myserver> <main> <<W LS Kernel> > <> <BEA- 190032> << VistaLink Adapter_vl j_testconn ector > Re sourceAllo cationExce ption of g ov.va.med. vistalink. adapter.cc i.VistaLin kResourceE xception: Need new V erify Code : true Nee d to selec t Division s: false o n createMa nagedConne ction.>
1562	####<Jul 1 9, 2004 3: 13:57 PM P DT> <Warni ng> <Conne ctor> <tes tserver> < myserver> <main> <<W LS Kernel> > <> <BEA- 190024> << VistaLink Adapter_vl j_testconn ector > Er ror making initial c onnections for pool. Reason: g ov.va.med. vistalink. adapter.cc i.VistaLin kResourceE xception: Need new V erify Code : true Nee d to selec t Division s: false>
1563	Diagnoses and Soluti ons: The v erify code specified for the c onnector h as expired . Try sett ing VERIFY CODE neve r expires? to "Yes" for the co nnector pr oxy user. If this do esn’t clea r up the p roblem you may need to change the verify code of t he connect or proxy u ser and no tify all c onnecting systems to update th eir connec tor config urations w ith the ne w verify c ode.
1564	Note: All Connector Proxy user s created using the Enter/Edit Connector Proxy Use r option ( on the Fou ndations m enu) shoul d have VER IFY CODE n ever expir es? automa tically se t to true.
1565	Sporadic S ocket Time outs
1566	Symptom: A pplication requests occasional ly fail, a nd a Vista SocketTime OutExcepti on is foun d in the l og4j logs coincident with requ est failur es. For ex ample:
1567	60871641 2 008-03-11 15:07:37,5 20 [[ACTIV E] Execute Thread: '1 ' for queu e: 'weblog ic.kernel. Default (s elf-tuning )'] DEBUG gov.va.med .vistalink .adapter.s pi.VistaLi nkManagedC onnection: executeInt eraction:1 103 - gov. va.med.vis talink.ada pter.spi.V istaLinkMa nagedConne ction[]10. 6.15.10[]8 016[]1[]J2 EE[fdi]1[m di]5 M $JO B=24008
1568	So cket timeo ut has occ urred
1569	go v.va.med.n et.VistaSo cketTimeOu tException : Socket T imeout occ ured. Time out settin g was: '15 000 ms'. ;
1570	Ro ot cause e xception:
1571	ja va.net.Soc ketTimeout Exception: Read time d out
1572	java.net.S ocketTimeo utExceptio n: Read ti med out
1573	at java.net. SocketInpu tStream.so cketRead0( Native Met hod)
1574	at java.net. SocketInpu tStream.re ad(SocketI nputStream .java:129)
1575	at sun.nio.c s.StreamDe coder$Char setSD.read Bytes(Stre amDecoder. java:411)
1576	at sun.nio.c s.StreamDe coder$Char setSD.impl Read(Strea mDecoder.j ava:453)
1577	at sun.nio.c s.StreamDe coder.read (StreamDec oder.java: 183)
1578	at java.io.I nputStream Reader.rea d(InputStr eamReader. java:167)
1579	at java.io.B ufferedRea der.fill(B ufferedRea der.java:1 36)
1580	at java.io.B ufferedRea der.read1( BufferedRe ader.java: 187)
1581	at java.io.B ufferedRea der.read(B ufferedRea der.java:2 61)
1582	at java.io.R eader.read (Reader.ja va:122)
1583	at gov.va.me d.net.Sock etManager. receiveDat a(SocketMa nager.java :160)
1584	(e tc.)
1585	Diagnoses and Soluti ons: Reque sts from t he J2EE si de are occ asionally timing out at the so cket level . Response time may occasional ly take lo nger than the config ured conne ction time out due to load on t he target M system, network lo ad, etc., particular ly at the times of d ay with th e heaviest system lo ads.
1586	The partia l log4j ex ception ou tput above contains clues (the IP and po rt of the M system b eing conne cted to, a nd the tim eout setti ng in use at the tim e of the s ocket time out). If y ou are see ing socket timeout e xceptions for a part icular con nector, yo u may want to consid er raising the defau lt timeout in the Vi staLink co nnector co nfiguratio n file for the adapt er in ques tion.
1587	Connection Pool Capa city Excee ded
1588	Symptom: A pplication s log the following error when trying to retrieve a connecti on from th e connecto r module:
1589	javax.reso urce.spi.A pplication ServerInte rnalExcept ion: Unabl e to get a connectio n for Vist aLinkAdapt er_vlj_tes tconnector connectio n pool: we blogic.com mon.resour cepool.Res ourceLimit Exception: No resour ces curren tly availa ble in poo l VistaLin kAdapter_v lj_testcon nector to allocate t o applicat ions, plea se increas e the size of the po ol and ret ry
1590	Diagnoses and Soluti ons: There are no co nnections left in th e pool to access. Ch eck the si ze of the pool; you may need t o increase it.
1591	To monitor how many requests a re being r ejected, c heck the W ebLogic co nsole in t he connect or module in questio n. Look un der the Mo nitoring t ab at the Connection s Rejected Total Cou nt column.
1592	Also, chec k the conn ection mod ule for le aked conne ctions: We bLogic con sole, reso urce adapt er module, Monitorin g tab, Num ber Detect ed Leaks c olumn. If the applic ation code does not close a co nnection, it can be leaked. Cl osing conn ections sh ould usual ly be done in the "f inally" po rtion of a try/catch /finally b lock.
1593	ClassCastE xception
1594	Symptom: j ava.lang.C lassCastEx ception th rown to an applicati on. When a n applicat ion (such as the Vis tALink sam ple web ap plication) tries to retrieve t he VistALi nk connect ion factor y from JND I, and cas ts it to V istaLinkCo nnectionFa ctory, a j ava.lang.C lassCastEx ception is thrown. A line of c ode like t he followi ng trigger s the Clas sCastExcep tion:
1595	ic = new I nitialCont ext();
1596	VistaLinkC onnectionF actory cf = (VistaLi nkConnecti onFactory)
1597	ic.look up("myConn ectorJndiN ame);
1598	Diagnoses and Soluti ons: Usual ly this ex ception me ans that V istALink i s not prop erly confi gured on t he J2EE se rver. In p articular, its libra ries are n ot present on a clas sloader hi gher than that of th e calling applicatio n. To get VistALink’ s librarie s on a hig her classl oader, the two recom mended app roaches ar e:
1599	Production Systems: Install th e VistALin k librarie s as J2EE shared lib raries.
1600	Non-produc tion syste ms: VistAL ink suppor ting libra ries shoul d be inclu ded in the exploded RAR, where they will be automa tically lo aded onto a high-lev el classlo ader by We bLogic.
1601	Check you are using the approp riate meth od for you r producti on or non- production server, a nd that th e necessar y supporti ng librari es are dep loyed (as J2EE share d librarie s for prod uction sys tems, or w ithin the RAR for de velopment systems):
1602	vljConnect or-1.6.0.x xx.jar
1603	vljFoundat ionsLib-1. 6.0.xxx.ja r
1604	log4j-1.2. xx.jar
1605	If you are still hav ing diffic ulty, try turning on the follo wing debug settings (WebLogic administra tion conso le, Server -> Debug tab) and t hen examin ing the se rver log o utput when the next ClassCastE xception i s encounte red:
1606	default.Cl assFinder
1607	weblogic.c lassloader
1608	weblogic.c lassloader .Classload er
1609	weblogic.c lassloader .verbose
1610	weblogic.c lassloader .verbose.C lassLoader Verbose
1611	Configurat ion File C onfusion
1612	Symptom: T he setting s actually being use d for depl oyed adapt ers (e.g., ip, and/o r port, an d/or JNDI name, etc. ) don’t co rrespond t o the sett ings in my VistALink configura tion file. Also, whe n I make c hanges in the settin gs in the configurat ion file, and redepl oy my adap ters, the settings a ctually us ed for the adapters don’t chan ge.
1613	Diagnoses and Soluti ons: Check your clas spath to s ee if more than one directory is include d. If so, check to s ee if the file gov.v a.med.vist alink.conn ectorConfi g.xml is p resent in multiple d irectories on your c lasspath. If so, Vis tALink may be readin g settings from the first Vist ALink conf iguration file that it finds o n the clas spath. In this case, remove al l files of this name from dire ctories on your serv er classpa th, except for the o ne that sh ould be th e valid co nfiguratio n file. Ma ke sure th e director y containi ng the val id VistALi nk configu ration fil e is on yo ur server classpath. Redeploy your conne ctors; the correct s ettings sh ould now b e read in for each a dapter.
1614	Reauthenti cation (En d-User Ide ntificatio n) Failure
1615	Symptom: A pplication s log the following error when trying to execute a n RPC.
1616	Exception: gov.va.med .vistalink .security. m.Security DuzDetermi nationFaul tException : Fault Co de: 'Serve r'; Fault String: 'I nternal Ap plication Error'; Fa ult Actor: 'XOBV TES T PING'; C ode: '1823 01'; Type: 'XOBV TES T PING'; M essage: 'N o valid DU Z found. [ Security T ype: DUZ] [DUZ Value : '1170755 55']' at g ov.va.med. vistalink. rpc.RpcRes ponseFacto ry.handleS pecificFau lt(RpcResp onseFactor y.java:261 ) at … [de leted for brevity]
1617	Diagnoses and Soluti ons: DUZ, the end-us er credent ial used f or re-auth entication , is not v alid on th e system b eing conne cted to.
1618	Note: The reported f ailure cou ld also be “no valid VPID foun d”, or “no valid App lication P roxy user found”, de pending on the type of reauthe ntication used to id entify the end-user.
1619	Division M ismatch
1620	Symptom: A pplication s log the following error when trying to execute a n RPC:
1621	Exception: gov.va.med .vistalink .security. m.Security DivisionDe terminatio nFaultExce ption: Fau lt Code: ' Server'; F ault Strin g: 'Intern al Applica tion Error '; Fault A ctor: 'XOB V TEST PIN G'; Code: '182302'; Type: 'XOB V TEST PIN G'; Messag e: 'Divisi on mismatc h during u ser reauth entication for secur ity type [ DUZ]. DUZ: [11707], Passed Div ision: [51 0] …… [del eted for b revity]
1622	Diagnoses and Soluti ons: The d ivision pa ssed in th e end-user credentia l for re-a uthenticat ion is not valid for the given user. See the secti ons of thi s guide J2 EE Re-Auth entication Mechanism s for End Users and Institutio n Mapping.
1623	Failure to Authorize RPC (B-Ty pe Option)
1624	Symptom: A pplication s log the following error when trying to execute a n RPC:
1625	Exception: gov.va.med .vistalink .rpc.NoRpc ContextFau ltExceptio n: Fault C ode: 'Serv er'; Fault String: ' Internal A pplication Error'; F ault Actor : 'XOBV TE ST PING'; Code: '182 006'; Type : 'XOBV TE ST PING'; Message: ' User TESTE R,JOE does not have access to option XOB V VISTALIN K TESTER' at gov.va. med.vistal ink.rpc.Rp cResponseF actory.han dleSpecifi cFault(Rpc ResponseFa ctory.java :253) at … [excerpt]
1626	Diagnoses and Soluti ons: The e nd-user la cks the "B "-type opt ion necess ary to exe cute the R PC in ques tion. See the VistAL ink Develo per’s Guid e for info rmation on writing R PCs.
1627	M-Side Err or Returne d to J2EE
1628	Symptom: A pplication s log the following error when trying to execute a n RPC:
1629	Exception occurred e xecuting X OBV TEST P ING
1630	Exception: gov.va.med .vistalink .adapter.r ecord.Vist aLinkFault Exception: Fault Cod e: 'Server '; Fault S tring: 'Sy stem Error '; Fault A ctor: ''; Code: '181 001'; Type : 'system' ; Message: 'A system error occ urred in M : CALL+1^M YRPC' at g ov.va.med. vistalink. adapter.re cord.Vista LinkRespon seFactoryI mpl.handle Fault(Vist aLinkRespo nseFactory Impl.java: 309) at … [excerpt]
1631	Diagnoses and Soluti ons: An M error occu rred, most likely in the RPC b eing execu ted. Check the M err or log.
1632	Abrupt Dis connects ( M-Side Err ors)
1633	Symptom: < READ> or < ENDOFFILE> errors lo gged by th e M listen er.
1634	Diagnoses and Soluti ons: On Ca ché system s, <READ> errors typ ically mea n an abrup t disconne ct between the WebLo gic server and VistA Link. For example, t his could occur if t he machine that the WebLogic s erver was running on was shut down witho ut perform ing a grac eful shutd own of the WebLogic server fir st.
1635	<ENDOFFILE > errors m ay mean th at the Cac hé server was shut d own withou t shutting down the WebLogic s erver firs t (as ofte n might be the case with enter prise-wide connectio ns).
1636	J2SE Conne ction Atte mpt to 1.0 Listener
1637	Symptom: T he followi ng error m essage occ urs when a ttempting to run the VistALink Swing Sam ple App
1638	Could not create con nection;
1639	Root cause exception :
1640	Gov.va.med .vistalink .adapter.c ci.VistaLi nkResource Exception: Roundation sException executeln itSocket…
1641	Root cause exception :
1642	Gov.va.med .exception .Foundatio nsExceptio n: The res ponse vers ion [1.0] is incompa tible with this vers ion...
1643	Diagnoses and Soluti ons: The J 2SE or J2E E client i s attempti ng to conn ect to a V istALink/M server th at is stil l running a VistALin k 1.0 list ener. Upgr ade to the current V istALink 1 .6 KIDS bu ild.
1644	Analyzing VistALink Errors in the M Erro r Trap
1645	If you loo k through the M erro r trap, yo u may see errors wit h no "subj ect" line.
1646	Such error s may have been logg ed by Vist ALink to n ote a faul t conditio n detected by the li stener. Un fortunatel y, at the present, t here is no easy way to add a n on-M fault to the er ror log an d still ha ve the sub ject show.
1647	XOBSTR Var iable
1648	If you see an error log entry without a subject, e nter XOBST R at the " Which symb ol? >" pro mpt. If th e log entr y is VistA Link-relat ed, that v ariable wi ll be defi ned in the error tra p, and its value sho uld be an error mess age descri bing the f ault condi tion encou ntered.
1649	Example:
1650	4) 13:08: 13 VISTAL INK,ROU 5 53187626 BG875
1651	…
1652	Which symb ol? > XOBS TR
1653	XOBSTR=Pri mary stati on '& apos; of t he request does not match the primary st ation &apo s;11000&ap os; of the M/Kernel system.
1654	Figure 9‑1 . M Error Trap
1655	XWBTIP Var iable
1656	When exami ning a Vis tALink-rel ated error trap, the XWBTIP va riable may be useful in that i t contains the IP ad dress of t he request ing site, as determi ned by the operating system:
1657	1) 22:23: 15 VL-HEA D,ROU 2 5537 \|TCP \|8016
1658	Which symb ol? > XWBT IP
1659	XWBTIP=10. 6.21.65
1660	This varia ble may be useful in particula r, when tr ying to de termine wh ether a pa rticular c lient syst em that is logging a large num ber of err ors in the error tra p, and if so, how to contact t he manager s of that system to correct th e conditio n.
1661	XOBLASTR V ariable (M Request T imestamp)
1662	There is a new varia ble that d evelopers and sites can use fo r debuggin g:
1663	XOBLASTR T imestamp o f last tim e any requ est was ma de on conn ection
1664	Developers and site administra tors can u se this va riable via JOBEXAM o r the Cach e console to watch activity a nd determi ne "dead" connection s.
1665	Analyzing VistALink Java Excep tions
1666	For inform ation abou t VistALin k Java exc eptions fo und in log file outp ut, look u p the exce ption clas s names in the VistA Link Javad oc.
1667	Section 50 8 Complian ce: Differ entiate Fo cus on Cha nge Verify Code Chec k Box
1668	Due to a k nown defec t in Java Swing (htt p://bugs.s un.com/bug database/v iew_bug.do ?bug_id=49 85801), an d as defin ed by Sect ion 508 co mpliance, it might b e difficul t for end- users to d istinguish when focu s occurs o n the Chan ge Verify Code check box in th e login di alog windo w when usi ng the Win dows “Look and Feel” High Cont rast Black color sch eme.
1669	Appendix A : Listener Managemen t for Cach e/NT Syst ems
1670	For Cache /NT system s, listene r processe s are conf igured, st arted, and stopped e ntirely wi thin the M environme nt. The Fo undations Management menu [XOB U SITE SET UP MENU] i s located under the Operations Managemen t menu [XU SITEMGR] a nd provide s several ListMan ac tions to d o these op erations. An example is shown in the fig ure below.
1671	In Windows , unlike V MS-based s ystems, th e VistALin k listener runs as a n M proces s. An appl ication is provided to configu re, start, and stop the listen er in M-ba sed VistA.
1672
1673	Figure A‑1 . Foundati ons Manage r Interfac e (Cache΄ Systems)
1674	Creating/E diting Lis tener Conf igurations
1675	To create or edit li stener con figuration entries, you should use the " Manage Con figuration s" action. The Manag e Configur ations act ion first prompts yo u to selec t a config uration en try. Then, within th e entry, y ou can con figure one or more l isteners, as shown i n the foll owing exam ple:
1676	Select Vis tALink LIS TENER CONF IGURATION NAME: DEFA ULT
1677	NAME: DEF AULT// <En ter>
1678	Select PO RT: 8000// <Enter>
1679	PORT: 800 0// <Enter >
1680	STARTUP: YES// <Ent er>
1681	Figure A‑2 . Create o r edit lis tener conf iguration entries
1682	The table below defi nes the si te paramet er fields for a give n listener entry:
1683	FieldMeani ngNameThis field con tains the name of th e default VistALink configurat ion used w ith the as sociated B OX-VOLUME PAIR speci fied in th e FOUNDATI ONS SITE P ARAMETERS file (#18. 01).PortTh e port the listener will liste n on.Start upIf the l istener sh ould be st arted when this conf iguration is started , set this field to YES. Other wise, set to NO. (If you want to keep th e port in the config uration bu t temporar ily do not want to s tart a lis tener, you would set this fiel d to NO.)T able A‑1. Listener C onfigurati on Entries Descripti on Table
1684	Starting A ll Configu red Listen ers
1685	All listen ers config ured in th e Foundati ons Site P arameters file for a utomatic s tartup, ca n be start ed with th e Start Bo x action. This actio n will sta rt all lis teners for the confi guration a ssigned to the curre nt BOX-VOL UME pair.
1686	For more i nformation on config uring list eners for automatic startup, s ee the sec tion of th is chapter titled "C reating/Ed iting List ener Confi gurations. "
1687	Starting a Single Un configured Listener
1688	To start a listener, use the S tart Liste ner (SL) a ction on t he Foundat ions Manag er interfa ce and ent er the des ired port. The actio n will fir st check i f a listen er is alre ady listen ing on the port and inform you if it is. No damage to the sy stem will occur if a listener is already listening on the po rt.
1689	Stopping a Configure d or Uncon figured Li stener
1690	To stop ne w connecti ons:
1691	Use the St op Listene r (STP) ac tion and s elect the desired li stener.
1692	This actio n may take up to 60 seconds to actually stop the l istener. T his preven ts new con nections f rom being establishe d to the M system. I t does not , however, terminate existing connection s.
1693	To termina te all con nections a nd prevent new ones:
1694	Use the St op Listene r (STP) ac tion and s elect the desired li stener. Th is action may take u p to 60 se conds to a ctually st op the lis tener.
1695	If you hav e access t o the J2EE system (o r can cont act the sy stem manag er), STOP the associ ated VistA Link conne ctor. This shuts dow n the conn ection poo l on the J 2EE side a nd stops i t from req uesting ne w M connec tions.
1696	You should shut down the Liste ner on the M system as well, t o block an y new conn ection req uests that may come from other clients.
1697	NOTE: If t he J2EE co nnector ha s not been stopped, it will co ntinue to try to est ablish con nections t o the M sy stem (whic h is why i t is bette r to STOP the connec tor on the J2EE side ).Manually terminate any remai ning XOBVS KT jobs ru nning on t he M syste m. This mi ght includ e client/s erver conn ections or J2EE conn ectors tha t you were unable to stop.
1698	Scheduling Listener Startup at System St artup
1699	The XOBV L ISTENER ST ARTUP opti on can be tasked to automatica lly start all requir ed listene r processe s upon Tas kMan start -up. This option sta rts all Vi stALink li stener con figuration operation s at one t ime for th e BOX-VOLU ME pair. T his type o f start-up would be required a fter reboo ting the s ystem or r estarting the config uration. A fter VistA Link insta llation on a Cache΄ system, th is option should alr eady be sc heduled to run at st artup.
1700	To automat ically sta rt the lis teners(s) when TaskM an is rest arted, ent er the XOB V LISTENER STARTUP o ption in t he OPTION SCHEDULING file (#19 .2). Sched ule this o ption with SPECIAL Q UEUING set to "Start up."
1701	You can sc hedule the required options by making en tries to t he TaskMan Schedule/ Unschedule Options, as shown i n the figu re below.
1702	Select Sys tems Manag er Menu Op tion: TASK MAN Manage ment
1703	Select Tas kman Manag ement Opti on: SCHedu le/Unsched ule Option s
1704	Select OPT ION to sch edule or r eschedule: XOBV LIST ENER START UP <Enter> Start Vi stALink Li stener Con figuration
1705	. ..OK? Yes/ / <Enter> (Yes)
1706	Edit O ption Sche dule
1707	Option Name: X OBV LISTEN ER STARTUP
1708	Menu T ext: St art VistAL ink Listen er Configu TASK ID:
1709	__________ __________ __________ __________ __________ __________ __________ _________
1710	QUEUED T O RUN AT W HAT TIME:
1711	DEVICE FOR QUEUED JO B OUTPUT:
1712	QUEUED TO RUN ON VO LUME SET:
1713	RESC HEDULING F REQUENCY:
1714	TASK PA RAMETERS:
1715	SPECIAL QUEUEING: STARTUP
1716	__________ __________ __________ __________ __________ __________ __________ _________
1717	Figure A‑3 . Automati cally Star ting Liste ner(s) on TaskMan Re start
1718	Appendix B : Listener Managemen t for DSM/ VMS System s
1719	DSM/VMS sy stems shou ld run Vis tALink as a TCP/IP s ervice, co mmonly kno wn as TCP/ IP Service for OpenV MS (previo usly known as UCX). The TCP/IP Service p ermits mul tiple TCP/ IP clients to connec t and run as concurr ent proces ses, up to the limit s establis hed by the system. T CP/IP list ens on a p articular port and l aunches a specified VistALink handler pr ocess for each clien t connecti on. Config uring, sta rting, and stopping listeners is managed entirely through th e VMS TCP/ IP Service .
1720
1721	DSM/VMS si te systems are in th e process of convert ing to Cac he΄/VMS sy stems. As such, the instructio ns below w ere writte n for the VistALink 1.0 releas e (Novembe r 21, 2003 ) and have not been modified f or the con version.
1722	Setting Up an OpenVM S User Acc ount
1723	The easies t way to c onfigure a n OpenVMS account to be a Vist ALink hand ler is to copy most of the par ameters fr om VA Mail Man TCP ac count. To do this:
1724	Determine an unused User Ident ification Code (UIC) , typicall y in the s ame group as other D SM for Ope nVMS accou nts.
1725	Using the OpenVMS Au thorize ut ility, cop y the XMIN ET account to a new VLINK acco unt with t he unused UIC. You m ust have S YSPRV to d o this.
1726	Make sure that the a ccount set tings for the new VL INK accoun t are the same as in the follo wing examp le. If the y are diff erent, mak e sure tha t the impa ct of the different settings i s acceptab le for you r system. In particu lar, make sure that the DisCtl Y, Restric ted, and C aptive fla gs are set for secur ity reason s.
1727	Setting Up a Home Di rectory fo r the Vist ALink Hand ler Accoun t
1728	You need t o create a home dire ctory for the VistAL ink handle r account. This dire ctory will house the DCL comma nd procedu re that is executed whenever a client co nnects, as well as l og files. Make sure that the o wner of th e director y is the V LINK accou nt.
1729	For exampl e, to crea te a home directory named [VLI NK] with o wnership o f VLINK, e nter:
1730	$ CREATE/D IR [VLINK] /OWNER=VLI NK
1731	Creating a DCL Login Command P rocedure f or the Vis tALink Han dler
1732	To create a DCL logi n procedur e for the VistALink Handler:
1733	Use the ho me directo ry for the handler a ccount.
1734	Make sure the comman d procedur e file is owned by t he VistALi nk handler account.
1735	Adjust the DSM comma nd line (e nvironment , UCI, and volume se t) for you r system.
1736	If access control is enabled, ensure tha t the VLIN K account has access to this U CI, volume set, and routine. ( See "Acces s Control List (ACL) Issues", later in t his chapte r).
1737	It is poss ible to ru n differen t TCP/IP S ervice lis tener proc esses on m ultiple no des.
1738	Sample DCL Login Com mand Proce dure
1739	In the sam ple proced ure below, ‘environ, ’ ‘uci,’ a nd ‘vol’ a re site-sp ecific.
1740	$!VLINK.CO M - for in coming con nect reque sts
1741	$!-------- ---------- ---------- ---------- ---------- ---------- ---
1742	$set noon !Do n't stop
1743	$ set nove rify !c hange as n eeded
1744	$! set ver ify !c hange as n eeded
1745	$! WAIT 00 :00:00
1746	$ purge/ke ep=10 sys$ login:VLIN K*.log !Pu rge log fi les only
1747	$! set pro c/priv=(sh are) !May not be re quired for MBX devic e
1748	$ x=f$trn lnm("sys$n et") ! This is ou r MBX devi ce
1749	$
1750	$ write sy s$output " Opening "+ x !This ca n be viewe d in the l og file
1751	$! Check s tatus of t he BG devi ce before going to D SM
1752	$ cnt=0
1753	$ CHECK:
1754	$ stat=f$g etdvi("''x '","STS")
1755	$ if cnt . eq. 10
1756	$ then
1757	$ write sy s$output " Could not open "+ x
1758	$ goto EXI T
1759	$ else
1760	$ if stat .ne. 16
1761	$ th en
1762	$ cn t = cnt + 1
1763	$ wr ite sys$ou tput "''cn t'> ''x' n ot ready!"
1764	$ wa it 00:00:0 1 !Wait on e second t o assure c onnection
1765	$ go to CHECK
1766	$ el se
1767	$ SE T NOVERIFY
1768	$!-------- ---------- ---------- ---------- ---------- ---------- -----
1769	$ ds m/env=DSMM ANAG /uci= VAH /vol= ROU UCX^XO BVTCP
1770	$!-------- ---------- ---------- ---------- ---------- ---------- -----
1771	$ en dif
1772	$ endif
1773	$ EXIT:
1774	$ logout/F ULL
1775	Figure B‑1 . Sample D CL Login C ommand Pro cedure
1776	Setting Up and Enabl ing the TC P/IP Servi ce
1777	Once you c reate the VistALink handler, c reate the TCP/IP Ser vice to li sten for c onnections and launc h the Vist ALink hand ler. You n eed to cho ose:
1778	The OpenVM S node to run the li stener on.
1779	Choose the node that you want to run the resulting M jobs on to proces s incoming VistALink messages. This is a lso the no de whose I P address will be ad vertised t o other sy stems as t he locatio n of your VistALink listener.
1780	The port i t should l isten on.
1781	The user a ccount and command f ile name t o invoke w hen a conn ection is received.
1782	The steps to set up a TCP/IP S ervice for VistALink are:
1783	Determine the port
1784	Set up the "VLINK" T CP/IP Serv ice
1785	Enable and save the "VLINK" TC P/IP Servi ce
1786	Prior to s etting up TCP/IP in production , you can set up a " test" TCP/ IP Service that logs into an M test acco unt. The t est TCP/IP Service c an use the same Open VMS accoun t and dire ctory as t he product ion TCP/IP Service. Just creat e a differ ent DCL co mmand file using the UCI and v olume set of the tes t account.
1787	Obtaining an Availab le Listene r Port (fo r Alpha/VM S systems only)
1788	Port selec tions conf lict only if another process i s using th e same por t on the s ame system . To list the ports currently in use on OpenVMS sy stems, use the DCL c ommand:
1789	$ TCPIP S HOW DEVICE _SOCKET
1790
1791	Port Remote
1792	Device_soc ket Type Local Remote Se rvice Host
1793	bg3 STREAM 8001 0 Vi stALink 0.0.0 .0
1794	bg23 STREAM 9700 0 Z3 ZTEST 0.0.0 .0
1795	bg24 STREAM 9600 0 ZS DPROTO 0.0.0 .0
1796	Figure B‑2 . Obtainin g an avail able liste ner port ( for Alpha/ VMS system s only)
1797	If ‘8000’ appears in the Local Port colu mn, anothe r applicat ion is alr eady using this port number; s o you shou ld choose another po rt.
1798	Creating t he TCP/IP Service
1799	Since the TCP/IP Ser vice is no de specifi c, make su re you are on the sa me node th at you wan t the list ener to ru n on. Foll ow this ex ample to c reate the service:
1800	$TCPIP
1801	TCPIP> SET SERVICE V LINK/USER= VLINK/PROC =VLINK /PO RT=8000-
1802	_TCPIP> /P ROTOCOL=TC P/REJECT=M ESSAGE="Al l channels busy" -
1803	_TCPIP> /L IMIT=50/FI LE=SYS$SYS DEVICE:[VL INK]VLINK. COM
1804	TCPIP> SHO SERVICE V LINK/FULL
1805	Service: V LINK
1806	Sta te: Di sabled
1807	Port: 80 00 Pro tocol: TC P Addres s: 0.0.0. 0
1808	Use r_name: no t defined Proces s: VLINK
1809	Figure B‑3 . Creating the TCP/I P Service
1810	Enabling a nd Saving the Servic e
1811	Because th e TCP/IP s ervice is node speci fic, make sure you a re on the same node that you w ant the li stener to run on. Fo llow this example to enable th e service:
1812	TCPIP> ENA BLE SERVIC E VLINK (en able servi ce immedia tely)
1813	TCPIP> SET CONFIG EN ABLE SERVI CE VLINK (save serv ice for re boot)
1814	TCPIP> SHO SERVICE/F ULL VLINK
1815	Service: V LINK
1816	Sta te: En abled
1817	Port: 80 00 Pro tocol: TC P Addres s: 0.0.0. 0
1818	Inactivity : 5 Use r_name: VL INK Process: VLINK
1819	Limit: 50 Act ive: 0 Peak: 0
1820	File: SYS$SY SDEVICE:[V LINK]VLINK .COM
1821	Flags: Listen
1822	Socket Opt s: Rcheck Scheck
1823	Receive: 0 Sen d: 0
1824	Log Opts: None
1825	File: not de fined
1826	Security
1827	Reject ms g: All ch annels bus y
1828	Accept ho st: 0.0.0. 0
1829	Accept ne tw: 0.0.0. 0
1830	TCPIP> SHO CONFIG EN ABLE SERVI CE
1831	Enable ser vice
1832	FTP, FTP_CLIENT , VLINK, M PI, TELNET , XMINETMM
1833	TCPIP> EXI T
1834	Figure B‑4 . Enabling and savin g the TCP/ IP service
1835	NOTE: To t est the co nnection, refer to t he section of this g uide calle d "Testing the Liste ner."Acces s Control List ACL I ssues
1836	Some sites use DSM's ACL featu re, which controls a ccess expl icitly to each OpenV MS account needing t o enter th at DSM env ironment. If your si te is usin g ACL, you should se t up the V LINK accou nt with PR OGRAMMER a ccess, and then spec ify the Vo lume set a nd UCI nam e that the VLINK use r account has author ization to access. E nsure that the OpenV MS VLINK a ccount all ows only N etwork lon gings, and prohibits Batch, Lo cal, Dialu p and Remo te logins.
1837	The follow ing is an example of setting t his level of access for a VLIN K account:
1838	$ DSM /MAN ^ACL
1839	Environmen t Access U tilities
1840	1. AD D/MODIFY U SER (ADD^ACL )
1841	2. DE LETE USER (DELETE^ ACL)
1842	3. MO DIFY ACTIV E AUTHORIZ ATIONS (^ACLSET )
1843	4. PR INT AUTHOR IZED USERS (PRINT^A CL)
1844	Select Opt ion > 1 A DD/MODIFY USER
1845	OpenVMS Us er Name: > VLINK
1846	ACCESS MOD E VOL UCI ROUTI NE
1847	---------- - --- --- ----- --
1848	No access rights for this user .
1849	Access Mod e ([M]ANAG ER, [P]ROG RAMMER, or [A]PPLICA TION): > P
1850	Volume set name: > ROU
1851	UCI: > VAH
1852	UCI: > <RET>
1853	Volume set name: > <RET>
1854	Access Mod e ([M]ANAG ER, [P]ROG RAMMER, or [A]PPLICA TION): > <RET>
1855	USER ACCES S MODE VOL UCI ROUTINE
1856	---- ----- ------ --- --- -------
1857	VLINK PROGRAM MER RO U VA H
1858	OK to file ? <Y> <RET>
1859	OpenVMS Us er Name: > <RET>
1860	OK to acti vate chang es now? <Y> <RET >
1861	Creating a ccess auth orization file: SYS $SYSDEVICE :[DSMMGR]D SM$ACCESS. DAT.
1862	Figure B‑5 . Access C ontrol Lis t
1863	Controllin g the Numb er of Log Files
1864	The VLINK TCP/IP Ser vice autom atically c reates log files in the VLINK directory named "VLI NK.LOG;xxx ," where ' xxx' is a file versi on number. This cann ot be prev ented. New versions of this fi le will be created u ntil that file versi on number reaches th e maximum number of 32767. To minimize t he number of log fil es created , you may want to in itially re name this log file t o the high est versio n number w ith the co mmand:
1865	$ RENAM E disk$:[V LINK]VLINK .LOG; disk $:[VLINK]V LINK.LOG;3 2767
1866	Alternativ ely, you c an set a l imit on th e number o f versions of the lo g file tha t can conc urrently e xist in th e VLINK di rectory:
1867	$ SET F ILE /VERSI ON_LIMIT=1 0 disk$:[V LINK]VLINK .LOG;
1868	NOTE: You probably s hould not limit the number of versions o f the log file until you know your VistA Link servi ce is work ing correc tly. Keepi ng the log files can help when diagnosin g problems with the service/ac count.Disa bling New Connection s
1869	To stop in coming con nections, stop the T CP/IP serv ice.
1870	This preve nts new co nnections from being establish ed to the M system. Current co nnections (that have their own connectio n, PID, et c) will re main, but new connec tions cann ot be made until the service i s enabled again.
1871	Terminatin g All Conn ections an d Preventi ng New One s
1872	To stop in coming con nections, stop the T CP/IP serv ice.
1873	If you ha ve access to the J2E E system ( or can con tact the s ystem mana ger), disa ble the as sociated V istALink c onnector. This shuts down the connection pool on t he J2EE si de and sto ps it from requestin g new M co nnections. You shoul d shut dow n the List ener on th e M system as well, to block a ny new con nection re quests tha t may come from othe r clients.
1874	NOTE: If t he J2EE co nnector ha s not been stopped, however, i t will con tinue to t ry to esta blish conn ections to the M sys tem (which is why it is better to STOP t he connect or on the J2EE side) .Manually terminate any remain ing XOBVSK T jobs run ning on th e M system . This mig ht include client/se rver conne ctions, or J2EE conn ectors tha t you were unable to stop.
1875	Glossary
1876	AACFormerl y the Aust in Automat ion Center . Renamed to the Aus tin Inform ation Tech nology Cen ter (AITC) Access Cod eA passwor d used by the Kernel system to identify the user. It is used with the verify cod e. Adapter Another t erm for re source ada pter or co nnector.Ad ministrati on ServerE ach Oracle WebLogic server dom ain must h ave one se rver insta nce that a cts as the administr ation serv er. This s erver is u sed to con figure all other ser ver instan ces in the domain.AI TCAustin I nformation Technolog y CenterAl iasAn alte rnative fi lename. Al pha/VMSAlp ha: Hewlet t Packard computer s ystem
1877	VMS: Virtu al Memory SystemAnon ymous Soft ware Direc tories M directorie s where VH A applicat ion and pa tch zip fi les are pl aced for d istributio n. APIAppl ication Pr ogram Inte rfaceAppli cation Pro xy UserA K ernel user account d esigned fo r use by a n applicat ion rather than an e nd-user.Ap plication ServerSoft ware/hardw are for ha ndling com plex inter actions be tween user s, busines s logic, a nd databas es in tran saction-ba sed, multi -tier appl ications. Applicatio n servers, also know n as app s ervers, pr ovide incr eased avai lability a nd higher performanc e.ASTMAmer ican Socie ty for Tes ting and M aterialsAu thenticati onVerifyin g the iden tity of th e end-user .Authoriza tionGranti ng or deny ing user a ccess or p ermission to perform a functio n.Base Ada pterVersio n 8.1 of W ebLogic in troduced a "link-ref " mechanis m enabling the resou rces of a single "ba se" adapte r to be sh ared by on e or more "linked" a dapters. T he base ad apter is a standalon e adapter that is co mpletely s et up. Its resources (classes, jars, etc .) can be linked to and reused by other resource a dapters (l inked adap ters). The deployer only needs to modify a subset of the lin ked adapte rs’ deploy ment descr iptor sett ings. Note : This mec hanism is no longer supported in WebLogi c 9 and la ter for J2 CA 1.5 ada pters (e.g ., VistALi nk 1.6).BE A WebLogic BEA WebLog ic is a J2 EE Platfor m applicat ion server . Oracle h as acquire d BEA Syst ems, Inc. From here forward it will be r eferred to as Oracle .CachéCach é is an M environmen t, a produ ct of Inte rSystems C orp.Cache/ VMSCache: InterSyste ms Caché o bject data base that runs SQL
1878	VMS: Virtu al Memory SystemCCIC ommon Clie nt Interfa ceCCOWA st andard def ining the use of a t echnique c alled "con text manag ement," pr oviding th e clinicia n with a u nified vie w on infor mation hel d in separ ate and di sparate he althcare a pplication s that ref er to the same patie nt, encoun ter or use r. Classpa thThe path searched by the JVM for class definitio ns. The cl ass path m ay be set by a comma nd-line ar gument to the JVM or via an en vironment variable.C lientCan r efer to bo th the cli ent workst ation and the client portion o f the prog ram runnin g on the w orkstation . Connecti on Factory A J2CA cla ss for cre ating conn ections on request. Connection PoolA cac hed store of connect ion object s that can be availa ble on dem and and re used, incr easing per formance a nd scalabi lity. Vist ALink uses connectio n pooling when runni ng on a J2 EE server. Connector A system- level driv er that in tegrates J 2EE applic ation serv ers with E nterprise Informatio n Systems (EIS). Vis tALink is a J2EE con nector mod ule design ed to conn ect to Jav a applicat ions with VistA/M sy stems. The term is u sed interc hangeably with conne ctor modul e, adapter , adapter module, an d resource adapter.C onnector P roxy UserF or securit y purposes , each ins tance of a J2EE conn ector must be grante d access t o the M se rver it co nnects to. This is d one via a Kernel use r account set up on the M syst em. This p rovides in itial auth entication for the a pp server and establ ishes a tr usted conn ection. Th e M system manager m ust set up the conne ctor user account an d communic ate the ac cess code, verify co de and lis tener IP a ddress and port to t he J2EE sy stem manag er. COTSCo mmercial, Off-The-Sh elfCSVComm a-Separate d Values f ormat DBF Database f ile format underlyin g many dat abase appl ications ( originally dBase)DCL Digital Co mmand Lang uage. An i nteractive command a nd scripti ng languag e for VMS. DivisionVH A sites ar e also cal led instit utions. Ea ch institu tion has a station n umber asso ciated wit h it. Occa sionally a single in stitution is made up of multip le sites, known as d ivisions. To make a connection , VistALin k needs a station nu mber from the end-us er’s New P erson entr y in the K ERNEL SYST EM PARAMET ERS file ( #8989.3). It looks f irst for a division station nu mber and i f it can’t find one, uses the station nu mber assoc iated with default i nstitution . DSMDigit al Standar d MUMPS. A n M enviro nment, a p roduct of InterSyste ms Corp. D UZA local variable h olding a n umber that identifie s the sign ed-on user . The numb er is the Internal E ntry Numbe r (IEN) of the user’ s record i n the NEW PERSON fil e (file #2 00)EAR fil eEnterpris e archive file. An e nterprise applicatio n archive file that contains a J2EE appl ication. E ISEnterpri se Informa tion Syste mEPHIElect ronic Prot ected Heal th Informa tionFatKAA TFat-Clien t (i.e. Ri ch client) Kernel Au thenticati on and Aut horization FDAFileMan Data Arra yFile #18S YSTEM file #18 was t he precurs or to the KERNEL SYS TEM PARAME TERS file (#8989.3), and is no w obsolete . It uses the same n umber spac e that is now assign ed to Vist ALink. The refore, Fi le #18 mus t be delet ed before VistALink can be ins talled. Gl obalA mult i-dimensio nal data s torage str ucture -- the mechan ism for p ersistent data stora ge in a MU MPS databa se.Healthe Vet-VistAT he VHA is converting its MUMPS -based Vis tA healthc are system to a new J2EE-based platform and applic ation suit e. The new system is known as HealtheVet -VistA.HIP AAHealth I nsurance P ortability and Accou ntability ActIDEInte grated dev elopment e nvironment . A suite of softwar e tools to support w riting sof tware. Ins titutionVH A sites ar e also cal led instit utions. Ea ch institu tion has a station n umber asso ciated wit h it. Occa sionally a single in stitution is made up of multip le sites, known as d ivisions. To make a connection , VistALin k needs a station nu mber from the end-us er’s New P erson entr y in the K ERNEL SYST EM PARAMET ERS file ( #8989.3). It looks f irst for a division station nu mber and i f it can’t find one, uses the station nu mber assoc iated with default i nstitution . Institut ion Mappin gThe VistA Link 1.6 r elease inc ludes a sm all utilit y that adm inistrator s can use to associa te station numbers w ith JNDI n ames, and which allo ws runtime code to r etrieve th e a VistAL ink connec tion facto ry based o n station number.ISO Informatio n Security OfficerJ2 CAJ2EE Con nector Arc hitecture 1.6J2CAJ2E E Connecto r Architec ture. J2CA is a fram ework for integratin g J2EE-com pliant app lication s ervers wit h Enterpri se Informa tion Syste ms, such a s the VHA’ s VistA/M systems. I t is the f ramework f or J2EE co nnector mo dules that plug into J2EE appl ication se rvers, suc h as the V istALink a dapter.J2E EThe Java 2 Platform , Enterpri se Edition (J2EE) is an enviro nment for developing and deplo ying enter prise appl ications. The J2EE p latform co nsists of a set of s ervices, A PIs, and p rotocols t hat provid e the func tionality for develo ping multi -tiered, W eb-based a pplication s. A J2EE Connector Architectu re specifi cation for building adapters t o connect J2EE syste ms to non- J2EE enter prise info rmation sy stems.J2EE Java 2 Ent erprise Ed ition. A s tandard su ite of tec hnologies for develo ping distr ibuted, mu lti-tier, enterprise applicati ons.J2SEJa va 2 Stand ard Editio n. Sun Mic rosystem’s programmi ng platfor m based on the Java programmin g language . It is th e blueprin t for buil ding Java applicatio ns, and in cludes the Java Deve lopment Ki t (JDK) an d Java Run time Envir onment (JR E).JAASJav a Authenti cation and Authoriza tion Servi ce. JAAS i s a plugga ble Java f ramework f or user au thenticati on and aut horization , enabling services to authent icate and enforce ac cess contr ols upon u sers. JAR fileJava archive fi le. It is a file for mat based on the ZIP file form at, used t o aggregat e many fil es into on e. Java Li braryA lib rary of Ja va classes usually d istributed in JAR fo rmat.Javad ocJavadoc is a tool for genera ting API d ocumentati on in HTML format fr om doc com ments in s ource code . Document ation prod uced with this tool is typical ly called Javadoc.JB ossJBoss i s a free s oftware / open sourc e Java EE- based appl ication se rver.JCA C CIJ2EE Con nector Arc hitecture Common Cli ent Interf aceJDKJava Developme nt Kit. A set of pro gramming t ools for d eveloping Java appli cations.JM XJava Mana gement eXt ensions. A java spec ification for buildi ng managea bility int o java app lications, including J2EE-base d ones.JND IJava Nami ng and Dir ectory Int erface. A protocol t o a set of APIs for multiple n aming and directory services.J REThe Java Runtime E nvironment consists of the Jav a virtual machine, t he Java pl atform cor e classes, and suppo rting file s. JRE is bundled wi th the JDK but also available packaged s eparately. JSPJava Se rver Pages . A langua ge for bui lding web interfaces for inter acting wit h web appl ications. JVMJava Vi rtual Mach ine. The J VM interpr ets compil ed Java bi nary code (byte code ) for spec ific compu ter hardwa re.KAAJEEK ernel Auth entication and Autho rization f or Java 2 Enterprise EditionKe rnelKernel functions as an int ermediary between th e host M o perating s ystem and VistA M ap plications . It consi sts of a s tandard us er and pro gram inter face and a set of ut ilities fo r performi ng basic V A computer system ta sks, e.g., Menu Mana ger, Task Manager, D evice Hand ler, and s ecurity.KI DSKernel I nstallatio n and Dist ribution S ystem. The VistA/M m odule for exporting new VistA software p ackages.LD APAcronym for Lightw eight Dire ctory Acce ss Protoco l. LDAP is an open p rotocol th at permits applicati ons runnin g on vario us platfor ms to acce ss informa tion from directorie s hosted b y any type of server . Linked AdapterVer sion 8.1 o f WebLogic introduce d a "link- ref" mecha nism enabl ing the re sources of a single "base" ada pter to be shared by one or mo re "linked " adapters . The base adapter i s a standa lone adapt er that is completel y set up. Its resour ces (class es, jars, etc.) can be linked to and reu sed by oth er resourc e adapters (linked a dapters). The deploy er only ne eds to mod ify a subs et of link ed adapter s’ deploym ent descri ptor setti ngs. Note: This mech anism is n o longer s upported i n WebLogic 9 and lat er for J2C A 1.5 adap ters (e.g. , VistALin k 1.6).Lin uxAn open- source ope rating sys tem that r uns on var ious types of hardwa re platfor ms. Health eVet-VistA servers u se both Li nux and Wi ndows oper ating syst ems. Liste nerA socke t routine that runs continuous ly at a sp ecified po rt to fiel d incoming requests. It sends requests t o a front controller for proce ssing. The controlle r returns its respon se to the client thr ough the s ame port. The listen er creates a separat e thread f or each re quest, so it can acc ept and fo rward requ ests from multiple c lients con currently. log4J Util ityAn open -source lo gging pack age distri buted unde r the Apac he Softwar e license. Reviewing log files produced at runtime can be he lpful in d ebugging a nd trouble shooting. loggerIn l og4j, a lo gger is a named entr y in a hie rarchy of loggers. T he names i n the hier archy typi cally foll ow Java pa ckage nami ng convent ions. Appl ication co de can sel ect a part icular log ger by nam e to write output to , and admi nistrators can confi gure where a particu lar named logger’s o utput is s ent.M (MUM PS)Massach usetts Gen eral Hospi tal Utilit y Multi-pr ogramming System, ab breviated M. M is a high-level procedura l programm ing comput er languag e, especia lly helpfu l for mani pulating t extual dat a.Managed ServerA se rver insta nce in a O racle WebL ogic domai n that is not an adm inistratio n server, i.e., not used to co nfigure al l other se rver insta nces in th e domain.M BeansIn th e Java pro gramming l anguage, a n MBean (m anaged bea n) is a Ja va object that repre sents a ma nageable r esource, s uch as an applicatio n, a servi ce, a comp onent, or a device. MBeans mus t be concr ete Java c lasses.Mes sagingA fr amework fo r one appl ication to asynchron ously deli ver data t o another applicatio n, typical ly using a queuing m echanism.M ultipleA V A FileMan data type that allow s more tha n one valu e for a si ngle entry . Namespac e A unique 2-4 chara cter prefi x for each VistA pac kage. The DBA assign s this cha racter str ing for de velopers t o use in n aming a pa ckage’s ro utines, op tions, and other ele ments. The namespace includes a number s pace, a pr e-defined range of n umbers tha t package files must stay with in. New Pe rson FileT he New Per son file c ontains in formation for all va lid users on an M sy stem. NIST National I nstitute f or Standar ds and Tec hnologyOIO ffice of I nformation Oracle Web LogicOracl e WebLogic is a J2EE Platform applicatio n server. Oracle has acquired BEA System s, Inc.OSO perating S ystemPatch An update to a VistA software package th at contain s an enhan cement or bug fix. P atches can include c ode update s, documen tation upd ates, and informatio n updates. Patches a re applied to the pr ograms on M systems by IRM ser vices.PHIP rotected H ealth Info rmationra. xml ra.xml is the st andard J2E E deployme nt descrip tor for J2 CA connect ors. It de scribes co nnector-re lated attr ibutes and its deplo yment prop erties usi ng a stand ard DTD (D ocument Ty pe Definit ion) from Sun. Re-au thenticati onWhen usi ng a J2CA connector, the proce ss of swit ching the security c ontext of the connec tor from t he origina l applicat ion connec tor "user" to the ac tual end-u ser. This is done by the calli ng applica tion suppl ying a pro per set of user cred entials.Re source Ada pterJ2EE r esource ad apter modu les are sy stem-level drivers t hat integr ate J2EE a pplication servers w ith Enterp rise Infor mation Sys tems (EIS) . This ter m is used interchang eably with resource adapter an d connecto r.RMRequir ements Man agementRou tineA prog ram or seq uence of c omputer in structions that may have some general or frequent use. M rou tines are groups of program li nes that a re saved, loaded, an d called a s a single unit with a specifi c name.RPC Remote Pro cedure Cal l. A defin ed call to M code th at runs on an M serv er. A clie nt applica tion, thro ugh the RP C Broker, can make a call to t he M serve r and exec ute an RPC on the M server. Th rough this mechanism a client applicatio n can send data to a n M server , execute code on an M server, or retrie ve data fr om an M se rverRPC Br okerThe RP C Broker i s a client /server sy stem withi n VistA. I t establis hes a comm on and con sistent fr amework fo r client-s erver appl ications t o communic ate and ex change dat a with Vis tA/M serve rs.RPC Sec urityAll R PCs are se cured with an RPC co ntext (a " B"-type op tion). An end-user e xecuting a n RPC must have the "B"-type o ption asso ciated wit h the RPC in the use r’s menu t ree. Other wise an ex ception is thrown. S ADSoftware Architect ure Docume ntSE&ISoft ware Engin eering & I ntegration ServletA J ava progra m that res ides on a server and executes requests f rom client web pages . SocketAn operating system ob ject that connects a pplication requests to network protocols . SPIJ2CA service pr ovider int erface Se rvice-Leve l Contract SRSSoftwar e Requirem ents Speci ficationSS H
1879	Secure She ll or SSH is a netwo rk protoco l that all ows data t o be excha nged using a secure channel be tween two networked devices. U sed primar ily on Lin ux and Uni x based sy stems to a ccess shel l accounts , SSH was designed a s a replac ement for Telnet and other ins ecure remo te shells, which sen d informat ion, notab ly passwor ds, in pla intext, le aving them open for intercepti on. The en cryption u sed by SSH provides confidenti ality and integrity of data ov er an inse cure netwo rk, such a s the Inte rnet.TCP/I PTransmiss ion Contro l Protocol (TCP) and the Inter net Protoc ol (IP)Ter mDefinitio nTXTText f ile format UMLUnifie d Modeling Language is a stand ardized sp ecificatio n language for objec t modeling .VADepartm ent of Vet erans Affa irsVACOVet erans Affa irs Centra l OfficeVe rify CodeA password used in ta ndem with the access code to p rovide sec ure user a ccess. The Kernel’s Sign-on/Se curity sys tem uses t he verify code to va lidate the user's id entity.Vis tAVeterans Health In formation Systems an d Technolo gy Archite cture. The VHA’s por tfolio of M-based ap plication software u sed by all VA medica l centers and associ ated facil ities.Vist ALink Libr ariesClass es written specifica lly for Vi stALink.VL VistaLink is a runti me and dev elopment t ool provid ing connec tion and d ata conver sion betwe en Java an d M applic ations in client-ser ver and n- tier archi tectures, to which t his docume nt describ es the arc hitecture and design . VMSVirtu al Memory System. An operating system, o riginally designed b y DEC (now owned by Hewlett-Pa ckard), th at operate s on the V AX and Alp ha archite ctures. VP IDVA Perso n Identifi er. A new enterprise -level ide ntifier un iquely ide ntifying V A ‘persons ’ across t he entire VA domain. WAR fileWe b archive file. Cont ains the c lass files for servl ets and JS Ps.WebLogi c ServerA J2EE appli cation ser ver manufa ctured by Oracle Web Logic Syst ems. WebSp hereWebSph ere Applic ation Serv er (WAS) i s and IBM applicatio n server.X LSMicrosof t Office X L workshee t and work book file formatXMLE xtensible Markup Lan guageXmlBe ansXMLBean s is a Jav a-to-XML b inding fra mework whi ch is part of the Ap ache Softw are Founda tion XML p roject.XOB Namespace The VistAL ink namesp ace. All V istALink p rograms an d their el ements beg in with th e characte rs "XOB."R EF: For a comprehens ive list o f commonly used infr astructure - and secu rity-relat ed terms a nd definit ions, plea se visit t he Securit y and Othe r Common S ervices Gl ossary Web page at t he followi ng Web add ressXE "Gl ossary:ISS Home Page Web Addre ss, Glossa ry"
1880
1881	XE "ISS:Gl ossary:Hom e Page Web Address, Glossary"
1882
1883	XE "Web Pa ges:ISS:Gl ossary Hom e Page Web Address, Glossary"
1884
1885	XE "Home P ages:ISS:G lossary Ho me Page We b Address, Glossary"
1886
1887	XE "URLs:I SS:Glossar y Home Pag e Web Addr ess, Gloss ary":
1888	http:// URL /iss/gloss ary.asp
1889	For a comp rehensive list of ac ronyms, pl ease visit the Secur ity and Ot her Common Services Acronyms W eb site at the follo wing Web a ddressXE " Acronyms ( ISS):Home Page Web A ddress, Gl ossary"
1890
1891	XE "ISS:Ac ronyms:Hom e Page Web Address, Glossary"
1892
1893	XE "Web Pa ges:ISS:Ac ronyms Hom e Page Web Address, Glossary"
1894
1895	XE "Home P ages:ISS:A cronyms Ho me Page We b Address, Glossary"
1896
1897	XE "URLs:I SS:Acronym s Home Pag e Web Addr ess, Gloss ary":
1898	http://v URL /iss/acron yms/index. aspVistALi nk J2M acc ess via link .



1899
		1900	VistALink J2M access via tab.
1901
1902
1903	� http://e n.wikipedi a.org/wiki /Secure_Sh ell
1904
1905	_128203843 9.psd