This article describes the card's XML representation. All requests use this definition (or elements of it) in its basic form. Depending on the request, the definition slightly varies. Furthermore, the XML representation is an excellent approach to understand the parts of the card and how they fit together.
These are the differences between the definition in Non managed mode and Managed mode:
In Non managed mode, all layout and all encoding data is directly contained in the definition.
In Managed mode, all layout and all encoding data is referenced by the name of the card that is defined by the CardDesigner in its card table. Therefore, there is no value for an application's element. The mode itself is defined by the attribute managed_mode="true".
The definition represents a card type. Enriched with field values it represents a person's card to be produced. It is then sent (with further minor extensions) to the corresponding web service request to create a card job or to create a card preview.
In other articles is described how to refine this basic definition especially with focus on the requests for:
Defining a single card in Non managed mode using the CardDesigner/EncodingConfigurator or CardComposer request
Defining all cards in Managed mode using the CardDesigner request
Creating a card preview using the CardPreview request
Creating a card job using the CardJob request
Requests in detail
Element
Attribute
Description
Element
Attribute
Description
card
Root element for the card definition.
name
Name of the card.
In Non managed mode, input and output value from the CardComposer request. It is intended to be used as a descriptive text and reference when storing the definition in your database (for example, "Employee Card", "Guest Card", ...)
In Managed mode, required input value for the CardPreview and CardJob requests. It references the card in the CardDesigner's card type table.
card/applications
Element containing all applications which describe the card. Applications are the card's front and back and chip encodings.
In Non managed mode, this element is input for and output from the CardComposer.
The element is always required input for the CardPreview and CardJob requests.
front and back are the card's visual descriptions defined as layouts. All other values are encodings, described by encoding descriptions.
magstripe is a magnetic stripe encoding, chip stands for a contact chip encoding, all other encodings are proximity encodings.
In Non managed mode, optional input and returned output from the CardComposer request. It is required input for the CardPreview and CardJob requests.
In Managed mode, only the element itself is required and input for the CardPreview and CardJob request. The actual value is defined by the corresponding card in the CardDesigner's card table.
For production, a corresponding device must be configured by the Configuration Manager. For the card's front and back a card printer, for an encoding (magstripe, chip, mifare, legic, hitag, proxif, uhf) a corresponding encoding device.
1mifare also includes ICODE encoding descriptions. 2hitag also includes EM4102 encoding descriptions.
name
The name of an application.
In Non managed mode, it is the name of a layout or encoding description, generated and used by the CardComposer. It is only descriptive but it may be very practical, as it describes an encoding with a name like "Magstripe Door Controller".
In Managed mode, there is no real application for this attribute and is therefore without meaning. However, there is only one exception using the Cards request: This request returns all defined cards and their applications as defined by the CardDesigner. And these applications application elements do return a name. It describes the application for information purposes. See heading "Retrieve cards" for details.
card/fields
fields contains all fields which are used as dynamic values in layouts and encoding descriptions.
In Non managed mode, the list is completely free to be defined by you. Do not change (reduce) the list after using it with CardComposer, CardDesigner or EncodingConfigurator. The reason is that the fields may have be referenced and stored within layouts and encoding descriptions.
In Managed mode, the list is predefined. It is used and managed by the CardDesigner. You may retrieve it by the Fields request. See heading "Retrieve fields".
Fields is always a required element for a CardComposer, CardDesigner, EncodingConfigurator, CardPreview and CardJob requests.
The field list is intended to correspond to the list of relevant fields of your table or view in your database: Designing a layout, the user has an immediate perception to select one of "his" fields to print it on the card. Using encoding descriptions, the user makes a link of "his" field to an encoding field on the chip.
For this reason, the fields are named as Database Fields when shown in any SDK's user interface.
-
-
card/fields/‹fieldtype›
‹fieldtype› {text,photo,signature,fingerprint}
Field element of one of the four available types. text is a textual field and contains an UTF8 encoded string. All other types transport BASE64 encoded binary (image) data.
name
The logical name of the field which has to be unique for each field type. However, field names from different field types may overlap. For example, it may exist a text field "Field01" but alsoa photo field "Field01".
text
The textual name of a field. Used in Non managed mode for the CardDesigner, EncodingConfigurator and CardComposer requests. Textual values are used when a field is displayed in any user interface.
This allows the use of translated field names. For example, "Card Number" in English and "Ausweisnummer" in German, but always addressing the same logical field. When no text attribute is provided, the interface uses the value of the name attribute. However, a field reference in a layout or in an encoding description will always store the logical field name.
card/preview
Preview element which holds a card's front and back preview.
It is an optional input value used for the CardComposer, CardJob and CardPreview requests to control card preview generation. The detailed behavior is controlled by its attributes.
front_data
Using the CardComposer, CardJob and CardPreview requests, an existing empty data attribute (front_data=””) instructs the component to return the card preview image BASE64 encoded. In this case, the returned XML contains the BASE64 encoded image data as the attribute's value.
back_data
Same as front_data but for card back.
front_image
If this attribute is provided, it instructs the SDK to create a card preview image on the web service, retrievable via an HTTP GET request. In the request, you may either provide an empty value (image=””) or a name of the image object (for example, image=”front.png”). In the response and if an empty value was provided, the attribute's value does contain a generated unique name (for example, image=”front15.png”). Or, if a value was provided, the same value is returned. In both cases, the preview image is available using a URL like http://localhost:54880/front15.png to retrieve the image. The typical case of application is to provide a preview image within an HTML page via an HTML img tag.
The image is retrievable as long as the service is running or an HTTP DELETE request for this image is done (always use the complete URL likehttp://localhost:54880/front15.png with GET or DELETE). The web service's list is also limited to 100 images. If more images are requested, the ones created first are deleted (realizing a FIFO principle).
back_image
Same as front_image but for card back.
max_width max_height
Values describing the maximal size of the returned card preview images. The aspect ratio of the card is always kept. In other words: The returned image is scaled that it fits into a rectangle defined by these values. The values unit is pixel.
format
Describes the format of the returned card image. Possible values are png, jpg, bmp, tif or jp2. The recommended format is png. The reason is that returned card images contain rounded corners and the area between card corners and image boundary is returned transparent. This is only supported by png. If other formats are used the area is filled with white color.
Define cards in Managed mode
Manage cards
In Managed mode, the CardDesigner is responsible for designing card layouts but also for managing card types. It can be called like any Windows application by starting CardDesigner.exe. It handles all data by itself. Compared to the usage of the CardDesigner in Non managed mode, there is no need to pass parameters and there are no values returned. You can start it directly using the desktop link or using the Windows start menu. Furthermore, there is the possibility to start it by a web service request. As the request starts a user interface, it may only be called from localhost.
As the CardDesigner edits its own managed card types including the layouts, it uses an empty cards element in the request but always returns the standard status response.
Element
Attribute
Description
Element
Attribute
Description
[in], Required. Root element for the CardDesigner request to start it in Managed mode.
In Managed mode, all card types are defined by the CardDesigner. The Cards request allows you to retrieve the list of defined cards. To start a Card Job, you have to reference one of these cards in the card job. As the request does not use a user interface, the web service may be located on localhost or on a separate machine. But consider that the returned card list is the one that was configured on the system where the web service is running.
An element/attribute is optional unless mentioned otherwise.
Element
Attribute
Description
Element
Attribute
Description
cards
Root element of the Cards request answer.
-
-
cards/card
The card element that describes the content of one defined card. It corresponds to the card element described under heading "Introduction to basic card definition".
The only differences are:
The card element may be contained multiple times - for each card type definition defined in the CardDesigner's card table
Each card element will only contain the applications element.
-
-
Retrieve fields
In Managed mode, the SDK uses a predefined field list. The Fields request allows to retrieve this list. As the request does not use a user interface, the web service may be located on localhost or on a separate machine. But consider that the returned field list is the one that was configured on the system where the web service is running.
An element/attribute is optional unless mentioned otherwise.
Element
Attribute
Description
Element
Attribute
Description
fields
[in,out] Required root element of the Field request. The element is empty in the request. The response contains all existing fields. It is basically identical to the fields element of the basic card definition in Introduction to basic card definition.
language
[in] Language for the returned textual field names. For details see Introduction to API.
encoding/fields/text
[out] Text field. Currently only textual fields are supported in Managed mode.
name
[out] The logical name of the field.
text
[out] The textual name of a field. The returned value depends on the language which was specified in the language attribute. If no language attribute is provided, the language configured in the Configuration Manager controls the returned value.
[out] Image fields. In Managed mode, fields for image objects have no name. This is a speciality for these field types in this mode. Only one photo, one signature and one fingerprint is supported. Therefore the image fields do not need to have a name in Managed mode.
-
-
Database Field list file dbfields.txt
For the predefined list of text fields, a data dictionary file (dbfields.txt) is used. It is located in the SDK's data directory (see Initial setup of Configuration Manager for more information). The file is a simple Unicode text file that you can edit with any text editor.
Example
The first line describes the structure of the field definition1. It must not be changed or deleted. Each of the following lines defines a variable field, starting with the logical field name followed by its translations. You can always change or extend the field list, customizing it to your individual requirements. But be careful not to delete those fields you have already used in a layout or in an encoding description. Using the Fields request, you will always get the current list as defined in dbfields.txt.
1dbfields.txt uses language identifiers basically corresponding to the XML language identifier due to ISO 639-1 in its first line. However, they differ for DE, FR, EN, ZH. Instead, D, F, GB, CH are used at this point.
Define cards in Non managed mode
Define a card
The CardComposer is the tool to define a card. It uses the CardDesigner to design layouts and the EncodingConfigurator to configure encodings. As the request opens a user interface, it may only be called from localhost. See also heading "Use CardDesigner/EncodingConfigurator vs. CardComposer" in this article.
The CardComposer request works on the complete card definition as described under heading "Introduction to basic card definition" and constructs the card's applications element by adding, removing and editing front and back layouts and encoding descriptions.
Note following two features:
The preview element, requested and returned by the CardComposer, is returned in a Design Mode: Image objects are visualized by their symbolic representation, text fields by their logical field name representation.
If a card side was requested but has not been defined previously, a corresponding symbolic picture is returned. It is just a diagonal cross to visualize that the corresponding card side is not defined. When requesting the image in png format, its background is transparent. If requesting the image in other formats, its background is white.
Design a layout
The CardDesigner is the tool to create and edit a layout. The request's result are layout data and layout name. As the request opens a user interface, it may only be called from localhost. See also heading "Use CardDesigner/EncodingConfigurator vs. CardComposer" in this article.
Configure an encoding
The EncodingConfigurator is the tool that selects and edits an encoding description. Starting the request with no encoding description runs a wizard style configuration dialog. The dialog lists available encoding descriptions from the SDK's data directory and allows the mapping of encoding fields to the fields of your provided field list. Starting the request with an existing encoding description, the appearing dialog allows to modify the field links. The return of the request is the BASE64 encoded description file which also contains the field links. As the request opens an user interface, it may only be called from localhost. See also heading "Use CardDesigner/EncodingConfigurator vs. CardComposer" in this article.
Use CardDesigner/EncodingConfigurator vs. CardComposer
There are two ways to create the card type definition (layouts and encoding descriptions):
Using the CardDesigner along with the EncodingConfigurator.
Using the CardComposer which itself uses the CardDesigner and the EncodingConfigurator.
This article gives some recommendation and is a guideline when to use CardDesigner/EncodingConfigurator and when to use CardComposer.
Advantages of CardComposer
Using the CardComposer is straight forward: You get the complete card definition, consisting of all layouts and all encodings. You can immediately use the the returned definition enriched with the person's text and image values for a print job.
Advantages of CardDesigner/EncodingConfigurator
In applications, which require a more sophisticated integration and intend to use many card types, it may be advisable to manage layouts and cards separately.
For instance: A company environment typically uses a large number of card types. All of these card types use different fronts but always the same back1. In such a constellation it may be better to maintain layouts and encoding descriptions separately by CardDesigner/EncodingConfigurator and to set up an own card type management that references these layouts and encoding descriptions. Only at the moment when the card job is created, the card definition is assembled from the data references (layouts, encoding descriptions and fields). This card management may slightly increase your efforts but leads to a more sophisticated solution.
However, CardComposer can be used at the beginning of a development process to create card definitions quickly. In a later stage of development you can switch over using the CardDesigner together with EncodingConfigurator directly. But nevertheless, it may be appropriate to only use the CardComposer when the number of card types is low.
1The CardDesigner allows to create layouts with dynamically varied or hidden layout objects (so called variants and conditions). The variation and visibility is controlled by the content of specified fields. This is very useful if you need multiple layouts which have a basic common appearance. It allows to specify one layout instead of many similar ones. We recommend to use this feature whenever possible. It is actually and usually the card's back that is used by multiple card definitions. Front sides are typically either completely different and therefore not shared or implemented by one base card layout that varies using variants and conditions.
Encoding descriptions
There are two important definitions which describe the personalization of the card: The layout for the visible and the encoding description for the machine readable part of the medium.
The layouts are created by the CardDesigner. In most cases, this is done either from scratch or guided and inspired by provided samples, as it may be dictated by your corporate identity.
Creating the encoding descriptions is a more complex topic. Building a layout may be an intuitive matter just like using image drawing software. But creating a definition for encoding rules usually requires profound knowledge of chip encoding technologies.
Encoding rules
SDK offers a wide set of encoding rules for typical and known requirements. After installation, the SDK already offers a collection of encoding descriptions for basic encodings: all magnetic stripe variants and some RFID samples reading the chip UID.
On request, Nexus can provide further encoding descriptions from an existing pool that covers a wide range of requirements.
Customized provisioning and templates
According to your requirements, encoding descriptions are created and customized on request. In many of these cases, templates can be provided. Such templates are prepared for specific purposes, but allowing adaption when bringing them into service.
A typical example:
Very often, access control terminals for time and attendance frequently use RFID chips, carrying the same basic encoding information, only varying in different keys and/or system codes. For such cases, it is possible to provide templates, suitable for all of these access control terminals. In the field, customer specific information is eventually used to complete the encoding description.
Tools
In case of frequent need for new or changing encoding descriptions (for example, for Service Providers) tools are provided. This DescriptionBuilder application may be provided on request for selected partners. Supported by a user interface, it allows encoding description design for several chip technologies like Mifare. Using such a tool requires profound knowledge of the according chip technology.
