Hendon Publishing - Article Archive Details
Techniques to ensure a LEXS-compliant IEPD
Written by Aaron Gorrell
Note that this article is technical in nature and the reader should have an understanding of the NIEM and IEPD development techniques. But first, a quick technical overview describing the structure of a LEXS-based schema.
The LEXS Structure
A LEXS message is organized hierarchically into a number of different components.
• Data Item Package: The data item package represents a unit of information and is typically analogous to a report such as an incident report. It is contained within a message and may occur any number of times—meaning that a single message is capable of containing multiple reports. The data item package is further broken down into the digest and payload.
• Digest: The digest is static across all LEXS-based IEPDs. It is organized into 15 different entities such as EntityPerson, Entity-Organization, EntityVehicle and EntityLocation. These entities provide a mechanism to group related base objects.
• Base Object: Base objects represent real-world objects and roles such as a person, witness, organization, and location.
• Payload: The payload is similar to an extension schema as it contains those elements not available in the digest. Based on business requirements, entities may contain properties that need to be split between the digest and the payload. In a LEXS message, these split entities can later be reconstructed through the use of a LEXS element called the SameAsDigestReference.
The Top Ten
1. The most reliable way to assure a LEXS-compliant IEPD is to reuse one that already exists. For law enforcement, a number of LEXS-based IEPDs already exist, such as those developed for the Suspicious Activity Report (SAR) and the N-DEx programs. If the work you are doing involves a law enforcement incident or field interview report, you should start by reviewing these existing IEPDs. They can be extended by changing the Community URI element within the payload (similar to the target namespace) and then by mapping data requirements to either the digest or payload. If the project requirements are so unique that reusing an existing IEPD is not practical, it is recommended that you at least carefully study the way that they have been assembled.
2. The LEXS IEPD development process does not differ from the NIEM development process. The first step is to gather exchange requirements. Once these requirements have been fully defined, the developer should attempt to map as many to elements within the digest as possible. The interoperability potential of a LEXS-based schema is directly proportional to the number of requirements mapped to the digest. A typical law enforcement document could have 70% to 80% of its requirements fulfilled by elements in the digest.
3. Data requirements left over will need to be mapped to elements in the payload. These elements may be from NIEM or created with a local extension. When developing your payload schema, it is easiest to view the payload and digest as two separate and distinct IEPDs. As such, the payload will, at a minimum, contain its own document schema and NIEM schema subset. This loosely coupled relationship means that changes to the digest will never impact the payload and vice-versa.
4. Digest elements should not be duplicated in the payload. An example that we will use throughout this article is PersonName. In LEXS 3.1, PersonGivenName is included as a property of PersonName within the digest. On the other hand, PersonName-SuffixText (e.g. Jr. III) is not in the digest definition of PersonName. As such, it will need to be included as a property of ext:PersonName in the payload. When creating the NIEM schema subset for the payload, the developer should take care to only include PersonName-SuffixText. The other PersonName properties should not be included since they already exist in the digest. Note that the extensive use of inheritance by NIEM may result in inadvertent but unavoidable duplication of some elements.
5. An element that will represent the document root should be created in the payload. All report properties will “hang” off of this element either directly or through the SameAsDigestReference. In N-DEx 2.0, this element is IncidentReport, and in SAR 1.1 it is represented by the SuspiciousActivityReport element.
6. Developers should take care in how they develop the payload to ensure that they do so in a way that facilitates entity reassembly. Fundamentally, this means that the payload should be developed in a NIEM conformant way by extending the appropriate NIEM base class and using an augmentation as the container for any non-NIEM properties.
a. For entities that are split between the payload and digest, be sure to extend the same base type as the related digest object. For example, with a split PersonName, our ext:PersonType will extend nc:PersonType. As discussed in #4, as the properties of nc:PersonType are selected during the sub-setting process, be sure to only include those properties that are not already in the digest.
b. Group all non-NIEM elements into an augmentation container. A good practice is to create ext:AugmentationType, which is inherited from s:Augmenta-tionType. Include lexslib:SameAs-DigestReference as a property of ext:AugmentationType. Then, create an object specific augmentation type with a base of ext:Augmenta-tionType (e.g. ext:PersonAug-mentationType) and include any extended properties. Be sure to add ext:PersonAugmentation as a property of ext:PersonType. This approach ensures the inclusion of the all-important SameAs-DigestReference while encapsulating the extended elements. Note that in some situations, SameAsDigestReference may be the only element in the augmentation. Be sure to follow the NIEM conformance guidelines when creating a new element to ensure that the objective of having a LEXS and NIEM conformant IEPD is accomplished.
7. Associations may link objects in the payload or objects in the digest. An association cannot link a payload object to a digest object—this can only be accomplished with the SameAsDigestReference.
8. Just like in NIEM, most elements in the digest are optional and may occur any number of times. This can create a number of issues when using table generation tools such as those often incorporated in Extraction, Transformation and Load (ETL) tools. As such, it is recommended that developers include a constraint schema for the payload. The digest includes a constraint schema that can be further constrained to reflect business requirements. Just remember that the interoperability capabilities offered by LEXS means that only the Department of Justice should add or remove elements from the constraint schema.
9. The LEXS Metadata object is automatically included as a property in all digest entities. This container offers a number of very useful properties including Source ID and Logical ID. Source ID is especially useful when developing a repository system where records from multiple agencies are collected into a central data warehouse. The property allows an exchange to identify the record ID of the source agency for future reference, record updates, etc. The Logical ID property allows the user to indicate that two or more objects may be logically the same. For example, if an agency Master Name Index has multiple entries indicated as possible aliases for a given person, this field may be used to associate these aliases to the primary person in the repository.
10. Because of its complexity, comprehensive examples are key to successfully implementing a LEXS-based exchange. Several complete sample instances should be developed using documents with real data. The concept of splitting the properties of an entity is typically foreign to most developers, and a comprehensive examples will help them understand how to construct the message and how to reassemble the pieces. Note that the SameAsDigestReference element should only associate an object in the payload with an entity in the digest—it should not reference any of the digest base objects.
To validate a message during development, it is necessary to separate the sample instance into two separate .xml files. This special treatment is necessary because the payload is attached to the LEXS message through the use of an xsd:any structure. When a schema validation tool such as XML Spy is used, it will not validate anything contained under the xsd:any structure. To split the message, create a copy of the complete XML message and rename the copy by adding “_payload” to the file name. Edit this file by stripping out all digest elements and add any required namespace declarations.
Part 3 of this article will go into the technical details of implementing LEXS in a production environment.
Aaron Gorrell is president and CEO of Waterhole Software, a firm that specializes in the development of robust system architectures and specifications for justice organizations. He can be contacted at email@example.com.
Published in Public Safety IT, Jul/Aug 2008
Rating : Not Yet Rated
Related CompaniesWaterhole Software
Related ProductsLEXS Compliance
Click to enlarge images.