Introduction

...

to basic card definition

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.

codetitle

Expand

language xml

title	Basic card definition

Basic XML definition of a card

collapse

Code Block

language	truexml

<?xml version="1.0"?>
<card>
	<applications>
	</applications>
	<fields>
	</fields>
	<preview/>
</card>

Code Block

language

xml

title

Non managed mode, XML example

collapsecode

Code Block

language	truexml

<?xml version="1.0"?>
<card name="Employee Card">
	<applications>
		<front name="Employee Layout">WBusGwIAvwI...IAAQA=</front>
		<magstripe name="Door Controller">UEsA...ADgAA=</magstripe>
	</applications>
	<fields>
		<text name="Field01" text="Name"></text>
		<text name="Field02" text="First Name"></text>
		<text name="Field21" text="Card Number"></text>
		<text name="Field22" text="Card Version"></text>
		<photo name="Field01"></photo>
		<signature name="Field01"></signature>
	</fields>
	<preview front_data="" back_data=""
			max_width="400" max_height="400"
			format="png"/>
</card>

language

xml

title

Managed mode, XML example

collapse

Code Block

language	truexml

<?xml version="1.0"?>
<card name="Employee Card" managed_mode="true">
	<applications>
		<front/>
		<magstripe/>
	</applications>
	<fields>
		<text name="Field01" text="Name"></text>
		<text name="Field02" text="First Name"></text>
		<text name="Field21" text="Card Number"></text>
		<text name="Field22" text="Card Version"></text>
		<photo name="Field01"></photo>
		<signature name="Field01"></signature>
	</fields>
	<preview front_data="" back_data=""
			max_width="400" max_height="400"
			format="png"/>
</card>

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

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.

-

card/applications/‹application›

‹application› {front,back,magstripe,chip,mifare,
legic,hitag,proxif,uhf}^1,2

An application of the card.

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.

¹mifare also includes ICODE encoding descriptions.
²hitag 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.

Note

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.

Expand

title	Request and Response overview

Request and Response overview

Request (REST)

Code Block

title

language	xml		Request (REST)

POST http://localhost:54880/CardDesigner

Request (SOAP)

code

Code Block

title

language	xml		Request (SOAP)

soap operation CardDesigner

Request Data

Code Block

title

language	xml		Request Data

<?xml version="1.0"?>
<cards language="EN"/>

Response Data on success

Code Block

title

language	xml		Response Data on success

<?xml version="1.0"?>
<status_response>
	<result_id>0</result_id>
	<result_text>Success</result_text>
</status_response>

Response Data on error or cancel, see Introduction to API.

Request and Response in detail

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
[in], Required. Root element for the `CardDesigner` request to start it in Managed mode.	`language`	[in] Language of the user interface. See also Introduction to API.

Expand

title

Retrieve cards

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.

Expand

title	Request and Response overview

Request and Response overview

Request (REST)

Code Block

language	xml
title	Request (REST)

POST http://localhost:54880/Cards

Request (SOAP)

Code Block

language	xml
title	Request (SOAP)

soap operation Cards

Request Data

Code Block

language	xml	title	Request Data

None. Therefore, note to use HTTP GET and not POST when using REST!

Response Data on success

Code Block

language	xml
title	Response Data on success

<?xml version="1.0"?>
<cards>
	<card name="Employee" default="true">
		<applications>
			<front name="Employee Layout" />
			<mifare name="Mifare Canteen Payment" />
			<magstripe name="Magstripe Door Controller" />
		</applications>
	</card>
	<card name="Guest">
		<applications>
			<front name="Guest Layout" />
		</applications>
	</card>
</cards>

Response Data on error or cancel, see Introduction to API.

Request and Response in detail

An element/attribute is optional unless mentioned otherwise.

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.

-

Expand

title

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.

Expand

title	Request and Response overview

Request and Response overview

Request (REST)

Code Block

language	xml

...

POST http://localhost:54880/Fields

Request (SOAP)

Code Block

language	xml

...

soap operation Fields

Request Data

Code Block

language	xml

...

<?xml version="1.0"?>
	<fields language="EN">
</fields>

Response Data on success

Code Block

language	xml

...

<?xml version="1.0"?>
<fields language="EN">
	<text name="Field01" text="Last Name" />
	<text name="Field02" text="First Name" />
	<text name="Field03" text="Department" />
	<text name="Field04" text="Company" />
	<text name="Field05" text="Telephone" />
	<text name="Field06" text="Fax" />
	<text name="Field07" text="Email" />
	<text name="Field21" text="Card No" />
	<text name="Field22" text="Version" />
	<text name="Field23" text="Personnel No" />
	<photo />
	<signature />
	<fingerprint />
</fields>

Response Data on error or cancel, see Introduction to API.

Request and Response in detail

An element/attribute is optional unless mentioned otherwise.

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.
`encoding/fields/photo` `encoding/fields/signature` `encoding/fields/fingerprint` [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

Code Block

language	xml

...

#dbfields,D,GB,F
Field01,Name,Last Name,Nom
Field02,Vorname,First Name,Prénom
Field03,Abteilung,Department,Département
Field04,Firma,Company,Entreprise
Field05,Telefon,Telephone,Téléphone
Field06,Fax,Fax,Fax
Field07,E-Mail,Email,Email
Field21,Ausweisnummer,Card No,No de carte
Field22,Ausweisversion,Version,Version
Field23,Personalnummer,Personnel No,No Personnel

The first line describes the structure of the field definition¹. 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.

¹dbfields.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

...

.

Expand

title	Request and Response overview

Request and Response overview

Request (REST)

Code Block

language	xml

...

POST http://localhost:54880/CardComposer

Request (SOAP)

Code Block

language	xml

...

soap operation CardComposer

Request Data

Code Block

language	xml

...

<?xml version="1.0"?>
<card language="EN">
	<applications>
	</applications>
	<fields>
		<text name="Field01" text="Name"></text>
		<text name="Field02" text="First Name"></text>
		<text name="Field21" text="Card Number"></text>
		<text name="Field22" text="Card Version"></text>
		<photo name="Field01" text="Photo"></photo>
		<signature name="Field01" text="Signature"></signature>
	</fields>
	<preview front_data="" back_data=""
		max_width="400" max_height="400" format="png"/>
</card>

Response Data on success

Code Block

language	xml

...

<?xml version="1.0"?>
<card language="EN" name="Employee Card">
	<applications>
		<front name="EmployeeLayout">WBusGwIAAACv...GwIIAAQA=</front>
		<magstripe name="Door Controller">UEsDBBQAAA...DgAA=</magstripe>
	</applications>
	<fields>
		<text name="Field02" text="First Name"></text>
		<text name="Field21" text="Card Number"></text>
		<text name="Field22" text="Card Version"></text>
		<photo name="Field01" text="Photo"></photo>
		<signature name="Field01" text="Signature"></signature>
	</fields>
	<preview front_data="WBusGwI...AAA8=" back_data="WBusAc...DAWu="
			max_width="400" max_height="400" format="png"/>
</card>

Response Data on error or cancel, see Introduction to API.

Request and Response in detail

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.

Expand

title	Request and Response overview

Request and Response overview

Request (REST)

Code Block

language	xml	title	Request (REST)

POST http://localhost:54880/CardDesigner

Request (SOAP)

Code Block

language	xml	title	Request (SOAP)

soap operation CardDesigner

Request Data

Code Block

Request Data

language	xml	title		xml

<?xml version="1.0"?>
<layout language="EN">
	<preview max_width="500" max_height="500"
		format="png"></preview>
	<name></name>
	<data></data>
	<fields>
		<text name="Field01" text="Name"/>
		<text name="Field02" text="First Name"/>
		<text name="Field04" text="Company"/>
		<text name="Field21" text="Card Number"/>
		<text name="Field22" text="Card Version"/>
		<text name="Field23" text="Personal Number"/>
		<photo name="Field01" text="Photo"/>
		<signature name="Field01" text="Signature"/>
	</fields>
</layout>

Response Data on success

Code Block

title

language	xml		Response Data on success

<?xml version="1.0"?>
<layout language="EN">
	<preview max_width="500" max_height="500"
		format="png">iVBORw0KGgoA...TkSuQmCC</preview>
	<name>Employee Front</name>
	<data>WBusGwIAAA...BAOULBAAAAAAA</data>
	<fields>
		<text name="Field01" text="Name" used="true" />
		<text name="Field02" text="First Name" used="true" />
		<text name="Field04" text="Company" />
		<text name="Field21" text="Card Number" used="true" />
		<text name="Field22" text="Card Version" />
		<text name="Field23" text="Personal Number" />
		<photo name="Field01" text="Photo" />
		<signature name="Field01" text="Signature" />
	</fields>
</layout>

Response Data on error or cancel, see Introduction to API.

Request and Response in detail

An element/attribute is optional unless mentioned otherwise.

Element	Attribute	Description
`layout` [in], Required. Root element for the layout definition.	`language`	[in] Language of the user interface. See also Introduction to API.
`layout/preview` [in] Preview element which requests and returns a layout preview. The value returns the BASE64 encoded image data. Note that the returned image shows a card in Design Mode. That means that layout image objects are represented by their corresponding symbolic representation, text fields by their placeholder representation (for example, `<Field21>`).	`max_width` `max_height`	[in] Values describing the maximum size of the returned card preview image. The aspect ratio of the card is always kept. In other words: The returned image is scaled so that it fits into a rectangle defined by these values. The values unit is pixel.
	`format`	[in] The format of the returned card image. Allowed values are png, jpg, bmp, tif or jp2. 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.
`layout/name` [in,out] The name of the layout. To be used as a descriptive text.	`-`	-
`layout/data` [in,out], Required. The layout data, BASE64 encoded. You may provide an empty element to start with a new layout or already existing layout data to edit the layout.	-	-
`layout/fields` [in] Required. `fields` contains all fields used for dynamic values in the layout. This field list is basically 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 let it be printed at a location on the card.	-	-
`layout/fields/‹fieldtype›` `‹fieldtype› {text,photo,signature,fingerprint}` [in] 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	[in], Required. The logical name of the field. You may choose any name for a field. Every field type (like text and photo) has its own field list. Note, that field names from different field types may be identically. For example, the text field "Field01" is different from the photo field "Field01".
	`text`	[in] The textual name of a field which appears in a user interface when selecting a field. When no text attribute is provided, the value of the name attribute is used in the user interface. However, a field in a layout will always store the logical field name.
	`used`	[out] Value `true` in the response indicates that the field is used in the layout.

Expand

title

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.

Expand

title	Request and Response overview

Request and Response overview

Request (REST)

Code Block

title

language	xml		Request (REST)

POST http://localhost:54880/EncodingConfigurator

Request (SOAP)

Code Block

title

language	xml		Request (SOAP)

soap operation EncodingConfigurator

Request Data

Code Block

language	xml	title	Request Data

<?xml version="1.0"?>
<encoding language="EN">
	<name></name>
	<data type="magstripe"></data>
	<fields>
		<text name="Field01" text="Name"/>
		<text name="Field02" text="First Name"/>
		<text name="Field04" text="Company"/>
		<text name="Field21" text="Card Number"/>
		<text name="Field22" text="Card Version"/>
		<text name="Field23" text="Personal Number"/>
	</fields>
</encoding>

Response Data on success

Code Block

language	xml	title	Response Data on success

<?xml version="1.0"?>
<encoding language="EN">
	<name>Magstripe Track1+2+3 Standard ISO 7811 HiCo</name>
	<data type="magstripe">WBusGwIAAA...BAOULBAAAAAAA</data>
	<fields>
		<text name="Field01" text="Name" used="true" />
		<text name="Field02" text="First Name" used="true" />
		<text name="Field04" text="Company" />
		<text name="Field21" text="Card Number" used="true" />
		<text name="Field22" text="Card Version" />
		<text name="Field23" text="Personal Number" />
	</fields>
</encoding>

Response Data on error or cancel, see Introduction to API.

Request and Response in detail

An element/attribute is optional unless mentioned otherwise.

Element	Attribute	Description
`encoding` [in], Required. Root element for the encoding description.	`language`	[in] Language of the user interface. See also Introduction to API.
`encoding/name` [in,out], Required. The name of the encoding description. To be used as descriptive text. The value is generated from the file name of the initial selection when starting without encoding description.	-	-
`encoding/data` [in,out] Required. The encoding description, BASE64 encoded. You may provide an empty element to start with selecting a new encoding description or an already existing encoding description to edit it.	`type`	[in,out] The type of the requested encoding to be selected and configured. Supported values are `magstripe, chip, mifare, legic, hitag, proxif, uhf`.^1,2 You may also provide no attribute or an empty value when selecting a new encoding description. In this case, the first dialog of the wizard allows to select the encoding type by the user. The selected value is returned in the XML of the response. ¹`mifare` also includes ICODE encoding descriptions. ²`hitag` also includes EM4102 encoding descriptions.
`encoding/fields` [in], Text field (currently only textual fields are supported). It may be mapped to an encoding field. You may provide other field types as well (for example, to create a field list in the same way as used with all other requests) but those are currently ignored.	name	[in], Required. The logical name of the field.
	`text`	[in] The textual name of a field which appears in a user interface when selecting a field. When no text attribute is provided, the value of the name attribute is used in the user interface. However, a linked field in an encoding description will always store the logical field name.
	`used`	[out] Value true in the response indicates that the field is used in the encoding description.

Expand

title

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 back¹. 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.

¹The 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.

...

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.

Page Comparison

Versions Compared

Old Version 8

New Version Current

Key

Introduction

to basic card definition

Basic XML definition of a card

Non managed mode, XML example

Managed mode, XML example

Requests in detail

Define cards in Managed mode

Manage cards

Request and Response overview

Request (REST)

Request (SOAP)

Request Data

Response Data on success

Request and Response in detail

Retrieve cards

Request and Response overview

Request (REST)

Request (SOAP)

Request Data

Response Data on success

Request and Response in detail

Retrieve fields

Request and Response overview

Request (REST)

Request (SOAP)

Request Data

Response Data on success

Request and Response in detail

Database Field list file dbfields.txt

Example

Define cards in Non managed mode

Define a card

Request and Response overview

Request (REST)

Request (SOAP)

Request Data

Response Data on success

Request and Response in detail

Design a layout

Request and Response overview

Request (REST)

Request (SOAP)

Request Data

Response Data on success

Request and Response in detail

Configure an encoding

Request and Response overview

Request (REST)

Request (SOAP)

Request Data

Response Data on success

Request and Response in detail

Use CardDesigner/EncodingConfigurator vs. CardComposer

Advantages of CardComposer

Advantages of CardDesigner/EncodingConfigurator

Encoding descriptions

Encoding rules

Customized provisioning and templates

Tools