Produce cards

Create a card preview

The CardPreview request generates a card preview for card front and/or card back. The request does not have an user interface, therefore the web service may be located on localhost or on a separate machine. When working in Managed mode, make sure that the referenced card types are available on the machine on which the service is running.

Request (REST)

POST http://localhost:54880/CardPreview

Request (SOAP)

soap operation CardPreview

Request Data in Non managed mode

<?xml version="1.0"?>
<card>
	<applications>
		<front name="Employee Layout">WBusGwIAAACvGwI...IAAQA=</front>
		<magstripe name="Door Controller">UEsDBBQAA...ADgAA=</magstripe>
	</applications>
	<fields>
		<text name="Field01" text="Name">Doe</text>
		<text name="Field02" text="First Name">Joanne</text>
		<text name="Field21" text="Card Number">10078</text>
		<photo name="Field01">WBusBCe...ABB8=</photo>
	</fields>
	<preview front_data="" back_data=""
			max_width="400" max_height="400" format="png"/>
</card>

Request Data in Managed mode

Response Data on success

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

Creating a card preview is done by calling the CardPreview request, using the basic carddefinition including the person's data. It returns the previews for card front and back. See heading "Introduction to basic card definition" in Define cards for details.

In opposite to all other requests which enrich the XML request definition, the preview request returns the preview element only but nothing else. It is a performance issue: The sent XML may contain large values (images and also layouts in Managed mode) which are necessary for preview generation but unnecessary in the response. This avoids unnecessary network data traffic and delayed request response time.

Create a card job

The CardJob request produces a card. As the request only uses a user interface for information purposes, the web service may be located on localhost or on a separate machine. When working in Managed mode, make sure the referenced card types are available on the machine on which the service is running.

Request (REST)

Request (SOAP)

Request Data in Non managed mode

Request Data in Managed mode

Response Data in Non managed mode on success

Response Data in Managed mode on success

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

Creating a card job is done by calling the CardJob request, using the basic card definition including the person's data. It also returns the previews for the front and back side. The request is synchronous, that means it will return only if the card is completely produced, if an error occurred or if the card job is cancelled by the user.

An element / attribute is optional unless mentioned otherwise.

Element	Attribute	Description

Element	Attribute	Description
`card_job` [in], Required. Root element for the card job.	`language`	[in] Language for the user interface. For details see Introduction to API.
`card_job/card` Card to be produced. The element corresponds basically to the basic card definition, see heading "Introduction to basic card definition" in Define cards ¹ ¹You can actually send the card element without being embedded in the `card_job` element to the `CardJob` request. The card will also be processed. However, we strongly recommend to embed it in the `card_job` element, as future SDK versions may support further card job controlling mechanisms like asynchronous job processing. Such job controlling information will be provided in the `card_job` element. Therefore, using the `card_job` element makes you ready to use such future features.	-	-
`card_job/card/applications` [in], Required. Each application to be produced must be named. See the description of the basic XML definition under heading "Introduction to basic card definition" in Define cards.	`produce`	[in] Value “true” controls production of all contained applications.
`card_job/card/applications/<application>`	`produce`	[in] Value “true” controls production of the single application. This attribute can be used alternatively to attribute `produced` in element `applications` to produce only a subset of applications.
`card_job/card/applications/<application>`	`device`	[in] Optional and reserved for the special use cases when different devices (printers or encoding units) have to be used: For application front and back, the value of a Printer Name from the list of configured printers in the Configuration Manager may be specified. It is one of the Printer Setup dialog's left column: Note: Especially when using this feature in combination with a Client server architecture, it may make sense to change the locally configured printer names, which are originally generated from the Windows' printers, to names like First Printer, Second Printer or Printer with Standard PVC Cards, Printer with Mifare Cards, ... This allows to configure multiple workplaces with different printer models or printers containing different materials, but accessing them using a unique server side generated card job. For all RFID and contact chip encoding applications (chip, legic, mifare, ...) you may specify the name of an encoding device as configured in the Configuration Manager: In a case like this, you have two Legic encoders and you may address either Proximity Encoder Legic Advant (SC-2560 Series) or Proximity Encoder Legic Advant (SC-2560 Series) (2) specifying the corresponding name for the application's device. Note: Using this device attribute as described here should be reserved for use cases when this feature is really required. Consider, it requires an increased effort to administer the systems and a mismatching configuration may cause issues. However, when used though, it adds sophisticated features for complex system configurations.
`card_job/card/fields` [in], Required. Field list, including the persons values as described for the `fields` element of the basic card definition under heading "Introduction to basic card definition" in Define cards.	`read`	[out] Value `true` in the response indicates that a field value was read. A typical use case is to return a chip serial number:

Create one card job for all applications

When creating a card job, you can control if only a single or multiple applications shall be processed (by using the attribute produce). However, there is a strong recommendation when creating a card job:

Always create a card job that produces all applications in one single card job.¹

Example

If a card contains a front layout and a proximity encoding, then create one card job that produces these two applications. Do not first create a card job that processes the card printing in one card job and the card encoding in a second (or the other way round).

Reasons to use this "produce all in one" approach:

The card job processing is actually designed to control all individual production steps. And it behaves differently in different configuration constellations in regard to the use of stand alone or printer integrated encoding devices.
The control of all separate application processing steps is furthermore intended for your convenience. Create one card job only and not multiple ones where your application needs to control their sequence.

This example is a simplified one, describing a card job that contains one encoding and card printing (card front and/or back). This may actually cover a wide range of use cases. However, the complete sequence for card jobs containing any number of applications is described comprehensively and in detail under heading "Card job application processing order" in this article.

Example, continued:

Continuing the example of a card job containing an encoding and a card printing. There can be two device situations:

Using a card printer and a stand alone encoding device.
Using a card printer with a printer integrated encoding device.

When using the "produce all in one card job", the SDK will produce the card in the following two ways for the two devices:

Printer and stand alone encoding device:
1. The card is printed (process step 1) and ejected from the printer.
2. The user will be requested to place the card onto the encoding device.
3. The card is encoded (process step 2).
4. The user will be requested to take the card from the device.
Printer with printer integrated encoding device:
1. The card is fed into the printer to its proximity encoding position and encoded (process step 1).
2. After encoding, the card is moved to printing position, then printed (process step 2) and ejected. No user interaction is required.

Conclusion:

The sequence of processing the applications is different. This is automatically done by the SDK's device configuration. You don't have to care about your device equipment when developing the application.

¹ As discussed in heading "Introduction to basic card definition" in Design cards, a card type definition becomes a card job by adding field values and the produce attribute(s). When we now discuss, to produce all applications, we of course talk about the production of those applications you actually want to produce at this moment and at this system. But not necessarily all those applications which are basically defined as card type applications. However, in some use cases it may make sense indeed to produce only a subset of applications initially and to produce the remaining applications afterwards in the field when issued.

Configure encoding device

This topic describes how to configure an encoding device, guided by the Configuration Manager. The two device situations described in "Create one card job for all applications" are used. In both cases, the printer configuration is the same, only the encoding device configuration is different.

Select the encoding device:
Configure the device by selecting its port:
The configuration is done.

Card job application processing order

As described in "Create one card job for all applications", the SDK's design intends to process all card applications within one card job. However, it may be necessary to control or to know the order of the single production steps. This is especially necessary when a read value shall be used in a succeeding production step. For example, a read chip serial number shall be printed onto the card. This topic is discussed under the heading "Use retrieved values within one card job" in this article as "carry-overs".

This diagram describes the sequence of processing a card job that contains any number of applications:

Use retrieved values within one card job

A carry-over means the usage of a read encoding value to be used in a succeeding production step. A typical situation for this is: when processing a card job consisting of chip encoding and card printing, you want to print the unique chip number (UID) onto the card.

Assume that we use a printer integrated encoding. This is required to process chip encoding before card printing. The actual chip UID provisioning is done by using the field list's feature to work as one data pool when processing the card job's applications:

Starting the card job, the field list is initialized by the card job's field values.
When processing the applications one by one, each application may not only retrieve field values from this list, but it may also update the list by values which arise when an application is processed (for example, typically by chip UIDs). An application processed afterwards may immediately access these values.
Eventually, you get the card job response containing the field values updated by the processing of all applications.

This sequence illustrates the example process of reading and printing a chip UID:

Continuing our example of printing the chip UID, we use an extra field in our field list (see also the discussions regarding the field list usage under heading "Introduction to basic card definition" in Define cards):

When configuring the encoding description with EncodingConfigurator (in Non managed mode) or CardDesigner (in Managed mode), you will map the Encoding Field that returns the chip UID (Mifare Chip UID) field of the field list. The left dialog below shows such an assignment. When editing the layout in the CardDesigner we again select this field. You may use the CardDesigner's field formatting options, to get this field being printed formatted (for example, padded with leading zeros):

In the same way you can use values read from a chip in applications processed afterwards which encode chips. For example, using a read Mifare UID being encoded into a contact chip smartcard on this card. However, you need to note the application's processing order as described under heading "Card job application processing order" in this article.

Define card job modes: read only and move a card within a printer

Two further card job processing modes exist. These modes are controlled by the mode (and eject) attributes of the request's card element. See following XML, describing the basic card job definition but extended with the new attributes:

mode is the important attribute and controls the card job mode. Valid values are write (which is the default value), read and printer_control.

Value	Description

Value	Description
`write`	The default mode and therefore used if no mode attribute is provided. The write (or read) mode controls the behavior of processing the proximity and contact chip applications. Using write means, a chip may be written and/or read. However, writing is the focus of attention.
`read`	Used to read a chip only. Using the read mode, combined with an encoding description which usually writes (and optionally reads) the chip, suppresses writing but only reads and returns encoded data. This mode is intended for special use cases, in which an already encoded card shall be read to retrieve its encoded content.
`printer_control`	Used for a very specialized use case: Using this mode, the card is neither written nor read nor is it printed. It is only used to move the card into, within or out of the printer. This mode is primarily intended for backward compatibility: Former SDK versions offered this feature to encode cards within a printer together with system integrator's own encoding software. It can still be used, but the implementation of an "ice"-component is the recommended way to use the SDK with an integrator's own encoding module.

The printer_control mode is used by sending a stripped-down card job (and there is no relation to any Managed mode or Non managed mode context). It requires a card job request XML that contains just the applications element:

with exactly one application that stands for the position where this encoder type is (or would be) built in;
with no application but the eject attribute to eject the card from the printer.

Use the following XML to move the card to the proximity position (we use mifare here, but you can also use legic or hitag or any other proximity chip application - each proximity chip application stands for the one and only proximity chip position in a printer):

Use this XML to move the card to the contact chip position:

Use the following XML to eject a card from the printer (a kind of "eject application" makes no sense, therefore ejecting is implemented by this attribute):