Help Center

Veonics® Portal Users Manual

Veonics® Portal Elements

The Veonics® Portal is a cloud-based platform used for managing photo identification information, printing, and issuance. This article provides a technical overview of its element structure, flow, and functionality.

The Veonics Portal is entirely built on PHP and uses a MySQL database to manage most of the information, except the photo binaries, which are kept separately and accessed through a “service provider”.

Currently, there are two service providers:

simple file system (images are stored as simple files in a secured folder in the host server)
S3 (images are stored in a secured S3 bucket on AWS).

While the Veonics® Portal operates as a web-based identity management system IDMS, the functionality extends far beyond traditional badging applications.

In the Veonics® Portal, several entities handle the identity data, as the diagram below shows below.

Core elements (in blue) are the primary entities to hold the identity and photo information and define how it will be interpreted.
Support elements (orange) complement the core elements and are used for specific operations. These elements are described in more detail in the following sections.

portal_elements

Core Elements

These elements implement the primary functions of handling information and photo information.

Card Record

The central element for holding identity information is the Card Record object. In Veonics® Portal, Card Records (cards) are always part of a Record Properties, which defines the common properties of these cards, including the fields captured for each card. Cards have a lifecycle defined by a workflow described below. Besides the specific information fields, each card has a globally unique identifier and other system fields used to trace its status in the workflow, the date of creation, and the date of the last change. If the Record Properties in a card are defined to support this function, each Card object will be attached to a Virtual ID (vID), access to which is controlled by a specific policy, as discussed below. Access to a Card Record is restricted to users in organizations with scope over that Record Properties, as discussed below, and even then, individual fields may be protected by additional permissions.

Photo

While photos are logically considered as another field in a Card Record object, they hold a privileged place in the Veonics® Portal and have a lifecycle independent of the cards to which they are linked. In fact, a single photo may be shared by multiple cards, typically in the same Record Properties, but potentially across Record Properties and even organizations. When originally brought into the Veonics® Portal, photos may be linked only to the Record Properties into which they are uploaded and later tied to a specific card. This is typical of the scenario where photos are uploaded in bulk and later matched to cards by using the original filename and checking it against a pattern formed by fields in the card record (for instance, last name, followed by an underscore, followed by the initial of the first name, and the “.JPG” extension). Photos may also be brought into the Veonics® Portal by using a CELLfie™ request, which provides a token-based link that a person can use to upload or capture their photo.

Photos are typically not used “as-is” but rather validated against a specified Standard to ensure they possess the desired quality attributes for an ID. This validation may require certain manipulations (cropping, red-eye reduction, contrast, and other filters) that alter the original image to make it compliant. This establishes a simple workflow, described below. The policy in Veonics® Portal is that the original photo is always kept intact, so every time the image is modified, a new version is saved with a pointer that allows the Veonics Portal to trace the photo’s “pedigree”.

When a photo is brought into a Portal, it gets cryptographically stamped. If the image is exported, it will retain this stamp, which allows a system user to verify its authenticity.

Record Properties

The Record Properties defines several common characteristics of a set of Card Record objects. This includes the Standard used to validate the Photos in the Cards, the linking of the vID Design and policy that controls access to vID’s for Card Records in this group, and the Record Setup that defines the fields available to Cards in the group. It also identifies the organizational scope of the Card Records and provides a placeholder for additional custom fields, which are not handled by the system but are provided as a convenience for the user. Record Properties have a very simple workflow, described below. In addition to this, Record Properties may optionally be assigned to a “Family”. Family members belong to the same organization sub-tree and typically share the same Record Setup. When a card is part of a group that is, in turn, part of a family, it is possible to “move” the card from one Record Properties to another one within the same family.

Record Setup

The Record Setup defines a list of fields available for use in a card record and the policies and characteristics of that field. This enables the Veonics® Portal to have a uniform way of handling records with a different structure. Record Setups have a simple workflow, too, but the activation operation in the design is particularly important since it generates all the scaffolding within the Portal to handle the variable structure that having a design affords.

Note, Record Setups in Veonics® Portal are “flat”: each field is presented in the assigned Record Properties and the data is saved in its own table and can not be shared by other Record Setups assigned to other Record Properties. The can only be moved using the Family feature. Also, Record Properties are recommended to be among multiple Record Properties within the same visibility hierarchy, especially if they have the same requirements and configuration. This makes it easier to fine-tune and effectively share badge template designs.

Field Properties

The following properties define each field in a design:

Field: this is what defines the semantic characteristics of the data being stored in the field. It is selected from a list of predefined fields, containing most common data elements (such as first name, last name, employee number, position, etc.), as well as a number of “generic”, all-purpose fields of specific data types. Not all fields are equal: some, less frequent ones, are implemented in a way that imposes a slight performance penalty, in order to maximize flexibility. These are clearly marked, and it is recommended to limit the use of those only to situations where it is truly necessary. By the same token, though, it is important to choose the field that best fits the ¬meaning of the information being stored. For instance, if storing the title of an employee, it is better to choose the “position” field rather than “generic text 1”.
Caption: this is the label that will be used to identify the field for the user in the Portal. It is otherwise not used by the system, so there is entire freedom in choosing this value according to the user’s preference. For instance, some organizations may have a particular designation for an employee code, such as “Partner Number”, and it is preferable to use what they will be most familiar with.
Alias: this is the name that will be used inside the Portal and associated products to identify this field. There are, therefore, some basic rules for choosing this value, but usually the default will be enough.
Order: this only identifies the relative position on which the field gets displayed among other fields in the card, and is only relevant for display and user convenience: the system does not rely on this property.
Visibility: this is a critical property that defines the rules to grant access to a field. The possible values are:
- Public: any person, whether a user or not, will be able to view this field. In particular, this applies to screens in the Portal that do not require a proper user login, such as CELLfie™, vID viewer and photo verifier. Only non-sensitive information should be marked this way.
- Normal: these fields are available to any user who has scope over this card. It is recommended for most non-sensitive information.
- Management Tier 1 and 2: these fields are available only to users who have been granted a specific permission to view fields with those visibility levels. They are meant for fields that are not considered PII but should also be restricted only to certain individuals. One example of this could be the person’s salary or paygrade.
- Private: these fields have the highest level of sensitivity, typically for full-fledged PII. In order to access these fields, not only do the users need to have a specific permission, but they are not displayed by default: the user must mark the ones they require, and click on a button to retrieve their values, adding a note to justify the need to access them. This access is also logged for audits.
Critical Identifier: this optional property identifies this field as one of up to 10 critical identifiers. These are particularly important when synchronizing external sources, either via VCDB or manual file import. The use of critical identifiers is described in more detail below.
Display on List/Search Enabled: these property determines if there will be a column for this field when looking at a list of cards in the group, and if there will be a specific search box on this field. It is recommended to limit this to those fields that are most commonly used to identify a particular card. Having too many fields will take too much screen real estate, and will also have a performance impact.
Catalog: if this property is selected, when editing a card, the user will be presented with a dropdown of values taken from a Catalog (described below), rather than allowed free entry of the values.
Generation: this option is used for fields whose values are not entered by the user, but rather generated by the system using a specified pattern. There are several configuration options for generation, but they are beyond the scope of this document.

Critical Identifiers

When importing or synchronizing records, if there are critical identifiers defined for a Record Properties design, a new record is created only if none of the existing records’ critical identifiers match the corresponding identifier in the imported record. If a match is found, instead of creating a new record, the matched one will get updated. Up to 10 critical identifiers may be defined, and each of them can consist of one or more fields. For a critical identifier to match, all the values of the fields in the identifier must be equal. A record is considered matched if at least one of the critical identifiers is found to be matched. This design allows a great deal of flexibility, especially when synchronizing data from different systems, which may use different elements for uniquely identifying a record.
Consider the following scenario: the table below lists some fields in a hypothetical Record Setup, marked with the assigned critical identifier they belong to, if any.

critical ID table Assume the following data is already present in the Record Properties.

card setup field list And consider the following data is being imported.

card setup field list import The resulting Record Properties will be as follows.

resulting import

The first import record, John Doe, matched ID 8 on critical identifier 2 (Department=H.R., Dept. Code=8), and Access Badge # was updated to A13456Z.
The second import record, Jane Samplename, matched ID 9 on the critical identifier (EmployeeID=14663). No data was updated since the only field that changed, Department, was blank in the import set.
The third import record, Alex Perez, matches the name of ID 10, but the first and last names are not critical identifiers (it is usually not a good idea to use names as critical identifiers since there is the possibility of homonyms). There is no Employee ID or Access Badge #, and, while in both cases, the Department is “H.R.”, Dept.Code is 9 in the card record and 11 in the import, and a match on both is required to meet critical identifier 2, which is compound, so a new/additional record gets created, ID 19.
The fourth import record, Max LeJeune, also finds no match on any critical identifier, creating a new record, ID 20.

Template Designer

The Template Designer specifies the graphic layout of a virtual ID: which elements are displayed and where, and what their visual properties are. Badge designs are created with the Template Designer and can include advanced features such as conditions on individual fields or a group of fields, elements calculated on a formula based on existing fields, barcodes, QR codes, and support for encoding and/or reading of magnetic stripe, with placeholders for the future addition of support for RFID and chip. When a template design is assigned to a Record Properties, cards in that property automatically acquire the ability to be rendered as Virtual ID's to be displayed on common browsers. One of the most important features of Designer is that designs can be rendered in real-time to reflect changes in the status of the card or of individual data elements. These, in turn, can be used to trigger conditions, such as to make particular conditions visible, for instance, an expired, stolen or inactive card, or, on the other hand, the acquisition of an accreditation to perform CPR by an emergency responder. Also, cards in a group supporting vID’s gain the possibility of being printed using vPQM.

veonics portal template designer Elements

Organization

Organizations are key to separating visibility and sharing elements in the Veonics® Portal. Organizations follow a strictly hierarchical scheme: every organization has a parent, except the system-defined “Root”, and can contain zero, one, or more “child” organizations. An Organization may be assigned quotas on multiple properties and have a default language, plus a set of user-defined custom fields provided for user convenience. Users are assigned to an organization, and this determines which Record Properties are accessible to this user, as discussed below.

User

A user is an account, whether of an individual or a system, that is granted access to the services of the Veonics® Portal. A user should always have an assigned e-mail address which is used for notifications. As mentioned above, a user is assigned to an organization, which determines the user's visibility. A user is also assigned one or more roles and may be granted additional individual permissions, determining the operations the user may perform in Veonics® Portal. The user may be able to control additional options, such as the predetermined length of lists and the language used in the Portal.

Support Elements

These elements are used to support the implementation of the platform operations in conjunction with the core elements.

Standard

A Photo Standard is a collection of rules that a photo is expected to meet to comply with the quality requirements for use in a card of a particular Record Properties. Standards are, like most elements, assigned to an organization, and may be shared up or down the chain. For the most part, standards are defined at the global level, but it is possible to define standards that are only accessible to a particular organization and its descendants, for private, generally stricter, rules. Rules in a standard can fall into two broad categories: system-enforced, or manual. Manual rules are simply text entries that a user, manually validating the photo, must read and visually determine if the photo (or photos) comply with that rule. This is generally used for attributes that cannot be reliably validated in an automated fashion, such as absence of headgear and piercings, uncovered forehead, image crispness, etc. On the other hand, system-enforced attributes contain additional attributes which are used by the Portal to determine if the photo is acceptable. The most critical, and only mandatory, rule is the aspect ratio. Two other optional rules can control the minimum and maximum resolution of the photo. A photo below minimum resolution would typically print too grainy, while a photo with too high resolution takes more storage space and imposes a performance toll on operations that access it. A final rule for coverage uses multiple attributes to generate an overlay that should frame the face in the photo, and is also used to drive the automatic cropping when supported.

Catalog

Catalogs are simply lists of value pairs, one of them serving as a code, and the other as the description, although it is not unusual that both values be identical. When selected for a particular field in the Record Setup, users editing data will be presented with a dropdown to select the value from the list. Catalogs may be created manually, imported from a simple Excel or CSV file, or generated based on the data already in a particular Record Properties. Catalogs are also assigned to an organization and may be shared up and down the chain. At the root level, it is usual to have some common catalogs, such as “Gender” or “State” (in this case, for instance, the typical code would be the 2-letter post office designation, such as “FL”, and the description would be the actual name, “Florida”)

Queue

Queues are used to control printing from the Portal using vPQM. A card that has been approved may be placed in a particular queue, and a vPQM instance connected to that queue will be able to retrieve the card, print it, and mark it as printed. While in a queue, a card may be put on hold, so it remains there but will not be printed until the user decides to, or may be moved to a different queue. This allows for a very flexible mechanism for managing printing. While queue management follows the familiar hierarchical scheme, users allowed to print to a particular queue must be specifically assigned to it. There is a particular variant of queues: proofing queue. When a card is printed from a proofing queue, it does not get marked as printed, but rather is returned to the “approved” status. Also, when printing from a proofing queue, vPQM will not print cards individually, but rather print to a letter-sized page, up to 8 images (with double-sided cards taking two images printing side by side). This allows the printer to create a proofing run in inexpensive paper or, better yet, generate a PDF document to allow the end customer to review how the actual cards will look and make corrections while it is still possible to do so cheaply.

Token

“Token” is a very generic concept and there are several different scenarios under which they are used inside the Veonics platform. In general, they consist of a long chain of pseudo-random numbers and letters, and typically have a defined validity period. Some of the current scenarios for token use include:

CELLfie™ Request: In this case, the cardholder receives an e-mail message with a link that includes the token. By following the link, the Portal can determine which card should the photos (and data) be linked to. The assumption is that the delivery via e-mail to a known address minimizes the risk of the request being used by someone other than the intended individual.
vID Policy: a vID may be protected with a policy that requires a token. In this case, the link to access the vID will include the token. Anyone with the link will have access to the vID, but it falls in the hand of the cardholder to control access to this link. The main protection, in this case, is not so much controlling access to the vID but to prevent an unauthorized party to brute-force gaining access to a vID by simply testing consecutive card ID’s.
User API Token: these tokens are generated, typically with a short validity period, in order to grant access to the Portal services without the need to pass credentials (username and password) on every single call. This is most critically used by the vID Mobile App.

Station

In the Veonics® Portal, a Station is a logical system, typically a computer, authorized to remotely invoke a series of services associated with a recognized application. A Station must have a designated system user, whose account is used to determine the scope of the access and the permissions to execute specific operations.

Import/Export Data Definitions

An Import Data Definition is used as a template to map elements in an import dataset to the fields in Record Properties, Record Setup. Once the definition is initially configured, the user can import information from additional datasets without creating a new mapping, provided that the new datasets follow the same structure as the initial. Currently, import data definitions accessible through the Veonics® Portal support Excel files, delimited or fixed-width column text files, or XML files with a particular two-level structure, while VCDB adds support for imports coming from a database query.

Export Data Definitions operate almost in the same way, but in the reverse, selecting which fields from the records will be exported and what the captions will be for the corresponding columns. Currently, exports generate only CSV or Excel files.

Notification

A particularly powerful feature of the Veonics® Portal is the ability to dispatch notifications to predefined targets when certain events occur within the system. Currently, all notifications are done via e-mail messages, although the framework would allow for the inclusion of alternate delivery mechanisms. The subject and body of the e-mail are controlled by a notification text, depending on the specific event that triggered the notification, and that text can include a substitution of certain fields, which allows for the personalization of those messages. Also, alternate versions of the text for the same event may be assigned to different organizations, allowing text customization to be sent. If a particular organization does not have custom text assigned, the Portal looks for text on the parent organization, and so on, until the top of the hierarchy, with the default message, is reached. E-mail notifications may use most HTML elements, including embedded images, to allow for a richer message.

Element Workflows

Implementing a workflow for key element objects is a very important feature of the Veonics® Portal. A lifecycle comprises multiple statuses and is implemented as a state machine. At each stage, only certain actions are admissible, and some of those actions trigger a change in the status. Element objects may be active or inactive in most cases and alternate between those conditions as needed. Objects are generally not completely deleted, even when no longer useful, because audit traceability would be invalidated otherwise.

Other objects, however, have more complex lifecycles. The most common of those workflows use three states: New, Active, and Inactive.

The “New” state is typically a scratchpad state where the object is still not completely defined and ready for use;
The “Active” state means that the object can be used normally;
The “Inactive” state means that the object should no longer be used but is retained and remains valid for current objects already using it.

“Forward” transitions (from “New” to “Active” to “Inactive”) are considered normal, while “reverse” transitions are considered exceptional and are protected by special permissions because they can have additional implications and side effects.

status_workflow

Card

The Card object has, by far, the most complex workflow of all, as depicted in the diagram Above. The complexity is better understood by breaking down the workflow into parts that apply to certain conditions. The basic flow, when everything goes as usual, is the following:

usual_workflow In this case, a New card is created, and while at this state, users can make any change to the object’s fields. Once all data is correct, the record gets Approved, meaning it is ready for printing. If the card is printed via vPQM, it gets Enqueued (placed in a specific Queue for printing), from which it is marked as Printed once vPQM has produced the physical card. If the record is being printed externally, it should be manually marked as Printed. This would be the normal end of the card’s lifecycle.

Of course, sometimes things may not go as smoothly, reflected in adding certain actions and states, as presented in this augmented workflow version.

status_inactive

In this flow, a New card may be wholly deleted. An Approved card may be reopened to make changes to the data. An Approved, Printed, or Enqueued card may be inactivated if no longer relevant or valid. An Inactive card may be reactivated. A Printed card may need to be reprinted, typically because the printout was somehow faulty. For the most part, these are exceptional transitions, protected as such.

The final pieces of the workflow are put into place to account for what may happen after a card has been Printed. A card may be marked as Shipped: this is a “convenience” status, not interpreted by the system, but potentially relevant to users in a service bureau setting. A card may also be reported as Lost or Stolen, in which case it is no longer valid but is potentially still at large, and a person trying to use it for identification suggests the possibility of fraud. Finally, a card may need to be reissued, usually as a replacement for an expired, lost, or stolen card, in which case the current card gets marked as having been superseded and a new card record is created with the same data, and linked to the original one for traceability.