Creating a distribution project

The figure below describes the general structure of a distribution project.

general structure for a distribution project

Note

A distribution project can contain one or more distributions, and each one can be from a different type (payslips, bonus letter, etc).

A project is defined by general settings, common to all the distributions it contains, such as:

  • The title of the project (visible on Document Manager)

  • The paper configuration, selected from a list (pre-defined during the implementation phase). See Paper configuration for more details.

  • The notification delay to notify employees who have active e-vaults that a new document is available

  • Options like “Distribution group” to restrict access to the project, etc.

For each new project these parameters must be set. The parameters can be set manually, but if the creation is automatic then these parameters are either set via an XML configuration file included in a ZIP file, or set by UKG teams and retrieved based on the distribution file name.

To benefit from the greatest autonomy, UKG customers are advised to use the ZIP format, via a project ZIP file, containing:

  • An XML file (project.xml) to describe the project

  • An XML file to describe one or several distributions

Two examples of project ZIP files are available in the present documentation.

Content of project.xml

This file contains the project parameters:

  • title mandatory: Title of the project, displayed in the interface and used to identify the project. For example, “Payslip distribution January 2021”. Maximum length: 50 characters.

  • paper_conf_id mandatory: Identifier for the paper configuration. During the implementation phase, a certain number of transmission settings are provided. These settings can be used to adjust the quality of the paper used or even the postage method. The attribute type is used to specify the type of identifier used:

    • id: Identifier as stored in the database (default)

    • code: Free identifier used during the settings phase. Format: alphanumeric lower case characters with “-” and “_”). The code option allows you to keep the same code for staging and production environments.

Note

Paper configuration is mandatory, even when UKG does not handle printing.

  • regroup_paper: Parameter used to group paper shipments. When sending multiple documents, one of the spools must be labeled as the main spool, the corresponding documents will then appear first in their respective packages.

  • notification_delay mandatory: The period, in number of days after project confirmation, before the notifications are sent by e-mail for the employees with active evaults. If set to “0”, the e-mails are sent directly after the project is processed.

  • sender_technical_id: Technical identifier of the creator of this project (as it would be displayed if a user had created the project from the web interface).

  • group_code: Distribution group identifier. When set, the project is available to all managers in this distribution group.

  • use_paper_conf_contact: Only available for parcel delivery sent to employee organization address. Sets the contact as defined in the paper configuration.

  • sending_address: Package delivery address. If this parameter is set and if the documents are sent in packages (based on the paper configuration used…), then the packages are sent to this address. Otherwise, the packages are addressed to the employee organizations.

    • country: Two-letter country code

    • contact: e-mail or phone number (international format). Used when the parcel cannot be delivered.

Note

Technical codes/ids, such as “paper configuration id”, are defined by UKG and the customer during the implementation phase.

Example of a distribution project directly sent to employees

In this example, as the paper configuration is set to “emp-letter”, the documents are sent directly to the employees.

<?xml version='1.0' encoding='UTF-8'?>
<project version='1.0' xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <title>Distribution Payslips January 2021</title>
  <paper_conf_id type='code'>emp-letter</paper_conf_id>
  <regroup_paper>true</regroup_paper>
  <notification_delay>2</notification_delay>

  <!-- (optionals) -->
  <sender_technical_id></sender_technical_id>
  <group_code>hr-group-67</group_code>
  <!-- (optionals) -->
</project>

Example of a distribution project sent as a parcel to the organizations of the employees

In this example, as the paper configuration is set to “parcel” but no sending_address is defined, the documents are sent to the organizations of the employees.

  • As use_paper_conf_contact is set to true, the contact field (email or phone number used when the parcel cannot be delivered) is set as defined in the paper configuration.

<?xml version='1.0' encoding='UTF-8'?>
<project version='1.0' xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <title>Distribution payslips January 2021</title>
  <paper_conf_id type='code'>parcel</paper_conf_id>
  <regroup_paper>true</regroup_paper>
  <notification_delay>2</notification_delay>

  <!-- (optionals) -->
  <sender_technical_id></sender_technical_id>
  <group_code>hr-group-67</group_code>
  <use_paper_conf_contact>true</use_paper_conf_contact>
  <!-- (optionals) -->
</project>

Example of a distribution project sent as a parcel to an address set in the XML

In this example, as the paper configuration is set to “parcel” and a sending_address is defined, the documents are sent to this sending_address.

  • If contact is left empty, it is set as defined in the paper configuration.

<?xml version='1.0' encoding='UTF-8'?>
<project version='1.0' xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <title>Distribution payslips January 2021</title>
  <paper_conf_id type='code'>parcel</paper_conf_id>
  <regroup_paper>true</regroup_paper>
  <notification_delay>0</notification_delay>

  <!-- (optionals) -->
  <sender_technical_id></sender_technical_id>
  <group_code>hr-group-67</group_code>
  <!-- (optionals) -->

  <sending_address>
    <recipient_firstname>Jean</recipient_firstname>
    <recipient_lastname>Dupond</recipient_lastname>
    <address1>12 rue Jean Jaurès</address1>
    <address2></address2>
    <address3></address3>
    <zip_code>75001</zip_code>
    <city>Paris</city>
    <country>FR</country>
    <contact>[email protected]</contact>
  </sending_address>
</project>

Distribution

A distribution is defined by:

  • A title, visible on Document Manager for the HR Users

  • A distribution type (pre-defined during the implementation phase), such as payslips or bonus letters

  • The documents to be distributed

A distribution can be created/added manually or be defined in an XML file in a project ZIP file.

Format of XML descriptor file for a distribution

Note

This file must be present and comply with the following format whatever the type of batch.

This file contains the parameters of a distribution:

  • title mandatory: Title of the distribution, displayed in the interface and used to identify the batch within a distribution project. For example, “payslips” / “Timecards”. Maximum length: 50 characters

  • distribution_type_id mandatory: Identifier of the distribution type. During the implementation phase, a certain number of distribution types are provided. The attribute type is used to specify the type of identifier used:

    • id: Identifier as stored in the database (default)

    • code: Free identifier used during the settings phase. Format: alphanumeric lower case characters with “-” and “_”). The code option allows you to keep the same code for staging and production environments.

Note

This code/id is shared by UKG during the implementation phase.

<?xml version='1.0' encoding='UTF-8'?>
<distribution version='1.0' xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<title>Bulletins de Paie</title>
<distribution_type_id type='code'>bulsal-employee-only</distribution_type_id>
</distribution>

To complete the project ZIP structure you must add the file to distribute: there are 3 ways to do that.

Project ZIP structure

The batch may exist in many forms, the standard formats accepted by UKG are the following:

  • “ZIP meta”: n PDF files accompanied by n XML metadata files in a ZIP file (default)

  • “ZIP pilot”: 1 unique PDF file (= 1 PDF spool), containing all documents to be distributed, accompanied by 1 unique XML descriptor file, in a ZIP file

  • “PDF spool”: 1 single PDF file containing all documents to be distributed.

The figure below shows the 3 solutions to define a project ZIP file, for 1 distribution.

Note

ZIP pilot and ZIP meta solutions allow you to be autonomous on the parameters sent to UKG, and change the document format without impact. ZIP meta is the standard solution recommended by UKG.

On the other hand, PDF spools with extraction maps must be avoided whenever possible, especially when the extraction maps do not contain identification bars: any change to the document format might break the PDF spool configuration.

three ways to define a distribution project

Description and naming

Each project ZIP file must be sent via SFTP, and must contain:

  • A project descriptor file project.xml

  • A ZIP file (“meta” or “pilot”) or a PDF spool per distribution batch, accompanied by a descriptive XML file per distribution batch. The ZIP/PDF and XML files from the same batch must have the same name (except for their extension).

Note

A best practice is to use the technical ID or registration number + organization code as part of the file naming to avoid any issues with homonyms.

The project ZIP file has to be:

  • Uploaded on the in/pro repository of the SFTP server

  • Named according to the format described in File naming conventions

All file names must only contain alphanumeric characters (a, b, c…z, 0…9) with the _ character allowed as a separator.

Note

SFTP server address as well as directory name for the upload are given during the configuration phase. For more information, see: Exchange protocol via SFTP file transfer.

Example of a project containing 2 distribution batches:

ndmat_partenairex_clientx_pro_456789067546.zip
-- project.xml
-- ndmat_macrosoft_macrosoft_dis_bulsal_hra_v7_2345678906767.zip
-- ndmat_macrosoft_macrosoft_dis_bulsal_hra_v7_2345678906767.xml
-- ndmat_macrosoft_macrosoft_dis_annexe_hra_v7_456T654578978.zip
-- ndmat_macrosoft_macrosoft_dis_annexe_hra_v7_456T654578978.xml

To see how to build a “zip meta” file (default format) or a “zip pilot” file, and to find downloadable examples: