====== Modules - Business cards [bsc] ======

This module will give you the possibility to create business cards for users in IdM. Business card is some pdf document. Data for this document must be saved in IdM. It doesn't matter where the data are saved. You have the option to create business card from basic identity attribute, EAV, contract attribute, etc.

In default implementation which you get out of box when you enable this module you will be able to generate business card in following design: {{  .:businecc_card_generated_bsc.png?nolink&  }}

===== Admin guide =====

====   ====

==== Generate card from user detail ====

If you want to generate business card for one specific user you can just go to the user detail and there you will find tab "Business card" When you click on this tab you will see form as you can see on the picture below. {{  .:businecc_card_bsc.png?nolink&  }}

You can change the information as you want before you generate business card, but if you want to generate business card again you will need to make these changes again. For this reason, we recommend to change the source from the information are pre filled. Business cards using these attributes:

  * Full name - Joined from first name and last name
  * Titles before name - Titles before
  * Titles after name - Titles after
  * Department - EAV attribute businessCardName on tree node where the user has contract - if you want to edit this you can use button "Edit department for all" which forward you to EAV attributes of this specific tree node you can make the change there save it and then go back and the new value will be available
  * Position - Name of contract
  * Personal number - Personal number
  * Type of business card (optional, see below)

==== Bulk action ====

If you want to create business card for more then one user, you can use standard bulk action which is available in users agenda. {{  .:bulk_bsc.png?nolink&  }}After that you will see modal window where you can select if you want to save business cards automatically to drive. Data which will be used for each user are calculated automatically based on primary contract.

==== Configuration and installation on IdStory appliance ====

Add the module and its dependecies ([[https://github.com/bcvsolutions/czechidm-business-card/blob/develop/Realization/libraries.tar|https://github.com/bcvsolutions/czechidm-business-card/blob/develop/Realization/libraries.tar]]) to /data/volumes/czechidm/modules/

Add frontend sources ([[https://github.com/bcvsolutions/czechidm-business-card/tree/develop/Realization/frontend/czechidm-bsc|https://github.com/bcvsolutions/czechidm-business-card/tree/develop/Realization/frontend/czechidm-bsc]]) to /data/volumes/czechidm/frontend-modules/czechidm-bsc/

Create following structure in the /data/volumes/czechidm/data:
<code>

├── business_cards
│   ├── background
│   │   └── defaulBck.png
│   ├── cards
│   ├── config
│   │   ├── fop-businessCard.xml
│   │   ├── fop.conf
│   │   └── fonts
│   │       ├── OpenSans-Bold.ttf
│   │       └── OpenSans-Regular.ttf
│   └── images
│       └── 54321.png
└── temp

</code>

The folder **images**  can be omitted if we generate cards from profile photos.

The file **defaulBck.png **is the background used for business cards (use this exact name).

Configure following application properties:

<code>
idm.sec.bsc.configuration.bck.path=//opt/czechidm/data/business_cards/background/
idm.sec.bsc.configuration.fop.config.path=//opt/czechidm/data/business_cards/config/fop.conf
idm.sec.bsc.configuration.image.file.extension=png
idm.sec.bsc.configuration.save.path=//opt/czechidm/data/business_cards/cards/
idm.sec.bsc.configuration.template.path=//opt/czechidm/data/business_cards/config/fop-businessCard.xml
idm.sec.bsc.configuration.tmp.path=//tmp/
idm.sec.bsc.configuration.additional.text=Some additional text

</code>

**After that EAV attribute must be created.**  Go into Settings → Form definitions → IdmTreeNode (default) → Form Attributes → Create new one: Code: businessCardName Name: It can be whatever. E.g. Name of organisation on business card Attribute Type: Text Face Type: TextArea Regular Expression: (?>[^\r\n]*(?>\r\n?|\n)){0,3}[^\r\n]*\z Validation message: Text can have maximum of 4 rows.

==== Support for different types of business cards ====

The module may be configured to support multiple types of business cards. This is mostly needed when you need different background for different types of users, or some different text on the card.

In such case, the type of business card is determined by specific EAV (form) attribute **businessCardType**  of identities or contracts.

**Installation**  (example where you want to use different background image and different text):

  * Put all background images to the folder configured in the property ''idm.sec.bsc.configuration.bck.path''
  * Create the code list (Settings → Code lists) with the code **business-card-types. **In this codelist, create EAV (form) attributes for every parameter that you want to make different in your business cards. For example, create the EAV **backgroundImage **and e.g. **additionalText**.
  * Create a code list item for every type of business card you want to create and configure their EAV attributes.
  * Create a new EAV (form) attribute in the main form definition of type IdmIdentity or IdmIdentityContract with the code **businessCardType, **attribute type Code list and select the code list business-card-types

**Usage**:

  * Set the value of EAV businessCardType for identities or their contracts. This value is persisted.
  * When generating a new business card, the value from identity or contract is used as the default. Just before generating the card, you may change it (this works similarly to other attributes in business cards).

Note: The EAV businessCardType** **can be defined for identities or identity contracts. If it is defined and contains values for both types, the EAV on identity is preferred.

===== Developers guide =====

This module is using [[https://xmlgraphics.apache.org/fop/|Apache FOP]] library for generating pdf files. This module needs some files to be able to generate pdf correctly:

  * fop.conf - configuration file for Apache FOP. As far as you just want different template you probably can use the one which is part of this module. For more info about config follow [[https://xmlgraphics.apache.org/fop/0.95/configuration.html|official documentation]]
  * fop-businessCard.xml - This is the template which is used for generating the final pdf. By this template you can define how the pdf will look. You can use [[http://www.java4less.com/fopdesigner/fodesigner.php|FO Designer]] for create or edit template

<note tip>Path to font files (*.ttf) is set in **font-base**  tag in fop.conf </note>

Whole project can be found on our [[https://github.com/bcvsolutions/czechidm-business-card|github]] page. If you need other attributes then the default ones you can fork this repo or just override **DefaultBscBusinessCardService**  and use annotation @Priority(-10) you can use different number just be sure that the priority is higher then the default one (0).

All methods has javadoc so you should be able the get the idea of the purpose of each method. If you want some different attributes you definitely need to override **getFormInstance**  method where you can define which attributes will shown and which values will be pre filled into it.

For rendering attributes we are using EAV. That means that we will render attributes according to FormInstance which is returned by the above mentioned method **getFormInstance**  Only difference between for example identity EAV is that the EAV are not persisted as the FormInstance is build on runtime. The reason for this is, that we don't persist Business card object to database so we can't use the "Form definitions" tabs in IdM setting to specify these attributes. We have only DTO which is used for data transfer between BE and FE.

<note tip>All required libraries are stored in** libraries.tar**  for easy use in appliance.</note>

===== Notes =====

Example properties for older installations for Windows: '' ''

''Folder where is stored background for card - file named "defaulBck.png" If path is on Linux you need to use two forward slashes at the beginning e.g //opt/somepath idm.sec.bsc.configuration.bck.path C:\somepath\background\ Path to Apache FOP config file idm.sec.bsc.configuration.fop.config.path C:\somepath\config\fop.conf Optional - Folder with user images which are used on business cards. File names inside this folder must be as PERSONALNUMBER.png Dont use this property if you want to use profile photos from identities. idm.sec.bsc.configuration.image.path C:\somepath\images\ File type extension of images which are used idm.sec.bsc.configuration.image.file.extension png Folder where the generated business cards will be saved automatically if you check the options to auto save idm.sec.bsc.configuration.save.path C:\somepath\business-cards\ Path to Apache FOP template idm.sec.bsc.configuration.template.path C:\somepath\config\fop-businessCard.xml Folder where IdM will save tmp files for generating If path is on Linux you need to use two forward slashes at the beginning e.g //opt/somepath idm.sec.bsc.configuration.tmp.path C:\somepath\tmp\ ''

''Optional - Additional text for business card idm.sec.bsc.configuration.additional.text This card is created by Idstory ''