|home||specifications||WIJIS URIs||gateway||CDCL||GJXDM example||warrants/po exchange||wijis articles||developer's checklist|
So let's say, and why not, that you are a geek technical resource. Let's further say that you work for an agency or for a consortium of agencies that is getting ready to participate in sharing its back-end records via the WIJIS Gateway; in other words, you are an Operator acting on behalf of a prospective Submitter.
And your first, reasonable question is, "Where in the world do I start?"
The answer is, "Right here."
This is a set of technical tasks that every Operator must perform in order to be ready to interact with the WIJIS Gateway on behalf of a data Submitter. It's presented as a simple checklist format, with hyperlinks to embedded content and to helpful external descriptions and definitions.
This is almost a standalone HTML page. It depends on availability of the desired XSLT referenced in the processing instruction, unless you wish to use a different XSLT. All external links are absolute, not relative. You can copy the source of this to any file, and use it locally as desired.
WIJIS provides two completely separate Service environments for the Gateway: Staging and Production.
This is primarily a Business operation, but it will require considerable technical involvement. You need to know about it.
Briefly, Data Certification is a process in which a prospective Submitter creates a representative sample of its data, uploads it to a non-Production instance of the Gateway, and conducts checks on a statistically significant sampling of the uploaded data, verifying that it is present and complete and that it is consistent with the data in the back-end Record Management System from which it was extracted. This verifies correct operation of the original data extraction process, and it tests for any non-obvious errors in the upload.
Data certification is described in more detail at WIJIS's Geeklog site.
HTTPS service calls are made directly to the servers maintained by WIJIS.
WIJIS currently provides the following services:
This is a simple, essentially dataless service intended to exercise the connections, frameworks, and basic messaging capabilities of your invocation of WIJIS services. When you are developing or troubleshooting anything other than data operations, use this service. You'll be glad you did.
These are the Pointer Services, as described in detail below in "Pointer Services (You are the Service Consumer.)".
For your client development and testing purposes, the
HelloWijis service will be
hosted on ports:
17080(HTTP in the clear),
17444(HTTPS with X.509 client certificate authentication).
The three Pointer Services will be hosted only
You will need to acquire and install a machine-specific X.509 certificate (see below)
in order to invoke any WIJIS Gateway Service hosted on port
17444. Each operator
is limited to a maximum of three development/testing certificates.
Certificates acquired for development/testing workstations are inadequate for invoking production instances of Gateway services. You must request and install a production certificate in order to access these service endpoints.
To confirm you have network connectivity to all these ports, you can
telnet command. You will specify both a host and a port to connect
telnet wijisgwtest.wisconsin.gov 17080
telnet wijisgwtest.wisconsin.gov 17443
telnet wijisgwtest.wisconsin.gov 17444
telnet wijis.wisconsin.gov 17444
Connected to wijisgwtest.wisconsin.gov.
Escape character is '^]'.
The endpoint data are supplied in the WSDLs. The WSDL are published at the following locations for the Staging server:
The WSDL are located at the following locations for the Production server:
Please note that the 'Hello Wijis' service is not available on the production platform.
If you elect to use web services for invoking Gateway services (such as Pointer Upload), then you will need a certificate for your machine that hosts your Gateway interface in order to identify itself to the Gateway system.
Most operators run both the Pointer Services clients and the hosted Record Retrieval Service on the same machine and, therefore, need only one certificate for that production machine. Some operators, though, prefer to run the clients on a different production machine from that used for the hosted service. Such an operator would then need two certificates: one for each production machine.
WIJIS provides step by step instructions for acquiring and installing X509 client certificates.
If you plan to use DOT NET, click here
If you plan to use Python, click here
If you plan to use Java, click here
Here is a General overview of the steps necessary to acquire and install the machine certificate. The specific step by step instructions are in the links above.
The implementation of the WIJIS service clients is up to each submitter. The Gateway has successfully been accessed by operators using .NET, Java, and Python to implement their service clients. Other platforms also have Web Service capabilities, and if you are adventurous, you can roll your own.
If you are using .NET as your web service client, click here for example code and instructions.
If you are using Python as your web service client, click here for example code and instructions.
If you are using Java as your web service client, click here for example code and instructions.
If you are unable to implement an HTTP Web Services client, all WIJIS services are fully
functional using FTP. Bear in mind that it doesn't work the other way around, though: FTP is
required for the
The authoritative definition of a WIJIS Service is in a very simple WSDL file. That file will reference the WIJIS Message Schema, and the Service Definition Schema for the Service under consideration.
However, the XML Schemas have been optimized for reuse, with highly structured orderly datatype definitions and element declarations. This has been really nice in a lot of ways, but it has turned out to be a hard challenge for a lot of the code-generation frameworks
In the Web Services world, a lot of effort has been put into automating the creation of Object-Oriented code from the WSDL or XML-Schema files that define a Web service. In general, the automation framework creates "stubs": classes whose interfaces match the Web Service interface definitions. With that part done, developers can fill in a much-reduced amount of implementation code that accomplishes whatever work is desired for the Service implementation.
Autogeneration of code is utilized both various frameworks including .NET. It is also used by the Java project AXIS and XFIRE.
WIJIS Messages comply with the
published by the W3C's XML Protocol Working Group.
Every SOAP Message consists of an
which contains a
Header element (which encloses handling, routing,
transmission, and tracking information) and a
(which contains the Message's actual data content, often referred to as "payload").
WIJIS Messages contain a single item in the
Header, and a single item
This Message structure is established in the WSDLs, but here's the synopsis:
WIJIS has developed a fairly rich and complex message tracking artifact
called the Message Tracking Info. It's the only thing that goes into
Every Service is formally defined by a Service Definition XML Schema. This schema, for each Service, specifies a single payload root element. It can be a Request, Response, or Error element. But it is a single element, that will never have any sibling.
The Pointer Services are provided by the WIJIS Gateway. They permit you to upload Pointers
A Pointer is a reference to a record that the Submitter acknowledges
having on its back-end system(s). It includes a unique
recordURI, which serves two purposes:
Every Pointer also includes a limited set of summary data that characterize the back-end record. This allows a Gateway User to decide whether the record is of interest in the first place.
Pointer format is controlled by the
WijisPointer schema, which
can be found by going to
and following the link to the current version/release.
You will need to create client mechanisms to invoke the services. These can use FTP, or they can use HTTPS, as described in the respective list items above. The Pointer Services, as stated, are provided by WIJIS, and your client mechanism acts as the Service Consumer.
The Pointer Count Service is like this:
Why you care: because when managing a collection of data items, getting a count is a very basic kind of sanity check.
Why you care, Part 2: because the
Service is a small, fast, inexpensive service call that involves
small amounts of wire traffic, you can use it to exercise
Service Definition details available at http://wijiscommons.org/specs/#pointer_count.
The Pointer Download Service is like this:
Bodyand instead are always provided by the Gateway over FTP as a Data File. The Response Message will point to the location of this Data File.
Why you care: because when managing a collection of data items, getting a complete copy of the collection is the basis for just about any kind of sanity check you might want to perform.
Service Definition details available at http://wijiscommons.org/specs/#pointer_download.
The Pointer Upload Service is like this:
recordURI, and either:
recordURIshould be deleted, and not replaced.
deleteAllPrevious, which means that all of the Submitter's Pointers in the Gateway Pointer Precache should be deleted before uploading the contained Pointers. (And if there are no contained Pointers, it serves as a means of ensuring that the Submitter (that's you, yo) has no remaining Pointers in the Precache at all.)
transactional, which means that all of the Pointer Upload operations (including
deleteAllPreviousif present) must succeed, or else the entire Pointer Upload Service Request has no effect.
Why you care: This is the only way your Pointers can be provided to the Gateway. In the fullness of time, WIJIS expects to provide a real-time delegated search capability, which would mean that you would provide no Pointers to the cache and instead provide Pointers in response to a specific Search Request immediately at the time the request is made. This is a feature that the Gateway itself won't support for a while, and it is a feature that will likely strain the infrastructure of some operators should any elect to do it.
Service Definition details available at http://wijiscommons.org/specs/#pointer_upload.
The Find Pointers By Record Key Data Service is like this:
Why you care: This is a way to query the gateway to find out what records are in the gateway without doing an entire pointer download. Some submitters provide a case number of other specific business data as part of the record key data. This service allows them to retrieve pointers that are relate to each other.
Service Definition details available at http://www.wijiscommons.org/specs/#find_pointers_by_record_key_data.
This one is different. Instead of being a Service that the WIJIS Gateway provides and you consume, this is a Service that you must provide. The Gateway is the consumer, which invokes your service instance.
Fortunately, this is a pretty simple Service. It goes like this:
recordURIidentifying the record we want to see more about. Example from wijiscommons
noRecorddeclaration, stating that the Record is unavailable/withheld/nonexistent Example from wijiscommons ; or
The record itself can be formatted as a standard IEPD, or as an N-DEx report.
In order to reduce the operational burden on Submitters who are auto-generating code from the Service Definitions, we have made the decision to remove the IEPD specification(s) from the Record Retrieval Service Definition. That Service Definition controls wire-level message formatting, which is reasonably separable from this particular kind of heavyweight payload specification.
Instead, we will be enforcing the content format in the business logic in our consumer code behind the wire interface. The exact IEPD formats permitted for the Record Representation will be annotated in the Service specification, but will not be incorporated in such a way as to be dragged into the code-generation process.
Service Definition details available at http://wijiscommons.org/specs/#record_retrieval.
The Record Retrieval service implementation is a three step process that involves exposing your service over http, https, and https w/client certificates. To begin, you will first expose a simple 'helloRms' service that is similiar to 'helloWijis' which will simply echo whatever string is passed to it. Once this service is implemented, it will be tested over all 3 transports listed above. This will allow WIJIS and the submitter to establish connectivity prior to passing live data over the wire.
To assist in this process, WIJIS currently provides example implementations using DOT NET and Java. There are 2 parts to each example implementation: server configuration and web services code. First choose your platform and then proceed to the relevant server configuration. Please note that these configurations are examples and might have to be modified for your specific environment and security infrastructure.
Agencies should first implement a Record Retrieval service which returns the following 3 responses: error, no record and contact info. Once this has been established, agencies can work with WIJIS staff to map data elements in their rms to an IEPD.
If you are using .NET for Record Retrieval, click here for example code, server configuration and instructions.
If you are using Java for Record Retrieval, click here for example code, server configuration and instructions.
To test the record retrieval service, WIJIS will test connectivity, service responses and security. During the initial testing phase, WIJIS will test your service from a standalone python script. This script could also be of benefit to you when you are doing your own testing. This script allows you to test your service over http, https and https with client certs.
Here is a link to the python script. Here is an example record retrieval invocation file
that you can use (note that you will have to customize to match your submitter). To invoke this service do this:
python rrServiceTester.py xmlExamples/recordRetrievalInvocation.xml
The script above takes a single command line argument which is the record retrieval invocation. You will also need to edit the script and enter the hostname, port number and URL of your service. You will also need to point to your private key and certificate file.