DELMIA Apriso 2019 Technical Guide
® 2 0 1 8 D a ssa u lt S yst è m e s. A p ri so , 3 D E X P E R IE N C E , th e C o m p a ss lo g o a n d th e 3 D S lo g o , C A T IA , S O L ID W O R K S , E N O V IA , D E L M IA , S IM U L IA , G E O V IA , E X A L E A D , 3 D V IA , B IO V IA , N E T V IB E S , a n d 3 D X C IT E a re co m m e rci a l tr a d e m a rks o r re g ist e re d tr a d e m a rks o f D a ssa u lt S yst è m e s o r it s su b si d ia ri e s in th e U .S . a n d /o r o th e r co u n tr ie s. A ll o th e r tr a d e m a rks a re o w n e d b y th e ir re sp e ct ive o w n e rs. U se o f a n y D a ssa u lt S yst è m e s o r it s su b si d ia ri e s tr a d e m a rks is su b je ct to th e ir e xp re ss w ri tt e n a p p ro va l.Contents
1 Introduction
3
1.1 Objective 3 1.2 Scope 3 1.3 Definitions, Acronyms, and Abbreviations 32 Framework Overview
4
2.1 Motivation 4 2.2 Requirements 4 2.3 Implementation 4 2.3.1 Triggering Label Printing 4 2.3.2 Label Printing Process Overview 4 2.3.3 Label Data Retrieval 5 2.3.4 Different Types of Mapping 5 2.3.5 Spooling Types 83 Usage
10
3.1 Installing Required Tools 10 3.2 Performing Main Tasks 10 3.2.1 Designing Label Layout 10 3.2.2 Preparing Label Definition File 11 3.2.3 Developing Label Data Providers 13 3.2.4 Preparing XSLT Mapping or Format File 13 3.2.5 Registering Labels 15 3.2.6 Invoking Label Printing 15 3.3 Code Templates 16 3.4 Compilation Issues 164 Best Practices
17
4.1 Developing Reusable Label Data Providers 17 4.2 Parameters Naming 175 Sample Project Description
18
5.1 Project Availability 18 5.2 Project Overview 186 Appendix A: Checklist
19
7 References
20
Figures
Figure 1 Preparing the label definition file in Microsoft InfoPath 13 Figure 2 Registering a label in Report Administrator 151 Introduction
This document presents the information required to use the DELMIA Apriso Label Printing Framework.1.1 Objective
The objective of this document is to gather all the information required by the programmer to use the Label Printing Framework and to understand the concept of label configuration for DELMIA Apriso. The knowledge included in this document should allow the programmer to use the Label Printing Framework without major prior knowledge of the subject.1.2 Scope
The scope of this document explains the fundamentals of the Label Printing Framework. The document describes the tasks that must be performed by the Label Developer to enable its printing in DELMIA Apriso.1.3 Definitions, Acronyms, and Abbreviations
LPF – DELMIA Apriso Label Printing Framework, which is a set of classes that enable the
2 Framework Overview
2.1 Motivation
Most business scenarios require labels to be printed as part of the business process. DELMIA Apriso should offer a flexible framework for printing labels. Label printing can be invoked from inside processes or from other codes.2.2 Requirements
Support for: Simple label printing without coding Different types of formats Flexible label data retrieval Different types of printers Triggering printing from various places Synchronous and asynchronous printing2.3 Implementation
The LPF is implemented as a set of classes, interfaces, and engines designed to meet the above requirements with a high level of flexibility. The following sections describe in detail the important implementation details.2.3.1 Triggering Label Printing
Label printing is invoked by specifying all the required attributes (such as LabelID and PrinterID) as well as the values of all the Input parameters in the LabelPrintRequest class. The class can be passed directly for processing or can be queued in Workflow Manager for asynchronous processing. During asynchronous processing, the LabelPrintRequest class is deserialized in the Workflow Manager plugin process and the actual processing is invoked by the Workflow Manager plugin.
2.3.2 Label Printing Process Overview
When the LPF receives a request to print a label, the following steps are executed: 1. A label definition file is retrieved from the disk and deserialized to obtain all the details related to the label. 2. All the configured label data providers are invoked to fill the PropertyBag with the fields required for the label. 3. The configured label mapping engine is invoked to map the values stored in the
PropertyBag into the output file.
4. The label output file is a spooled printer using the spooler type required by the printer.
2.3.3 Label Data Retrieval
Label data retrieval is a two-part process. The first round of parameters values is delivered in the LabelPrintRequest class as Input values by the Process that invoked printing. The second round of parameters is obtained from the label data provider during the label processing. Each data provider implements the ILabelDataProvider interface, which is the communication protocol between the data providers and the framework. The framework dynamically loads all the data providers configured for the label and the call methods of the above interface. The label data providers can deliver additional parameters into the PropertyBag based on the existing parameters. Calling the data providers is optional. Labels can exist that do not require custom providers, as they can take all the required fields as Input parameters.
2.3.4 Different Types of Mapping
The LPFsupports several types of mapping in order to support different types of label printing scenarios. A mapping type can be configured for each label. The section below lists the possible options.
“None” Mapping
“None” mapping is designed especially for debugging purposes. This mapping engine produces an XML-serialized PropertyBag with all the value parameters as output. The output of this mapping is very useful for testing the logic of data providers. The output of the mapping is also the primary sample data for authoring the XSLT mapping. For this mapping type, no mapping file is required.XSLT Mapping
The XSLT mapping engine executes the XSLT script stored in a mapping file against an XML-serialized PropertyBag containing the values of all the parameters. An XSLT script can map, loop, or transform the values of parameters into any format required by the printer or a third-party printing software. The source of the transformation is always XML with the values of the label parameters. The output is determined by the printer or third-party printing software. The LPF does not perform any additional processing on the output file, so the XSLT script must deliver the exact output file that will be spooled directly. For this mapping type, the mapping file contains the XSLT script. This is a sample XSLT script:<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xsl:template match="/"> <html>
<head /> <body>
<h1>List of employees in Department: <xsl:for-each select="LabelData"> <xsl:for-each select="Department.Name"> <xsl:apply-templates /> </xsl:for-each> </xsl:for-each> </h1> <br /> <xsl:for-each select="LabelData"> <xsl:for-each select="EmployeeList"> <table border="1"> <thead> <tr> <td>Name</td> <td>Position</td> <td>Salary</td> </tr> </thead> <tbody> <xsl:for-each select="Employee"> <tr> <td> <xsl:for-each select="Employee.Name"> <xsl:apply-templates /> </xsl:for-each> </td> <td> <xsl:for-each select="Employee.Position"> <xsl:apply-templates /> </xsl:for-each> </td> <td> <xsl:for-each select="Employee.Salary"> <xsl:apply-templates /> </xsl:for-each> </td> </tr> </xsl:for-each> </tbody> </table> </xsl:for-each> </xsl:for-each> </body> </html> </xsl:template> </xsl:stylesheet>
Replacement Mapping
The replacement mapping engine takes the content of the mapping file, looks for all the macros (that are placeholders for the actual values), and replaces the found macros with the values of corresponding parameters. This engine allows for the embedding of actual data into label format files or any other type of file. The mapping author's responsibility is to provide a label format that matches the printer or third-party printing software requirements with the embedded macros. The names of the parameters used in the macros must match the names of the parameters defined for the label and retrieved by the data providers. The parameter names are case sensitive. For this mapping type, the mapping file contains the label format (content) with the embedded macros. This is a sample file with macros:!!! This is a fake label. It may not be printed correctly on actual printer ^XA^MCY^XZ ^XA^LRN^FWN^CFD,24^LH0,0^CI0^PR2^MNY^MTT^MMR^MD0^PON^PMN ^XZ^XA^FO0,1014^GB830,4,4^FS ^FO0,811^GB835,4,4^FS ^FO0,609^GB835,4,4^FS ^FO0,402^GB812,4,4^FS ^FO0,199^GB812,4,4^FS ^BY2^FO46,48^BCN,112,N,N,N^FD>:0720^FS ^A0N,41,42^FO46,162^CI0^FD0720^FS ^A0N,28,36^FO46,648^CI0^FDPONO:^FS ^A0N,28,36^FO46,705^CI0^FDLINE:^FS ^A0N,28,36^FO46,761^CI0^FDDATE:^FS
^A0N,28,36^FO46,23^CI0^FDPO Employee badge label^FS ^BY2^FO46,458^BCN,112,N,N,N^FD>:2620^FS ^A0N,41,42^FO46,572^CI0^FD2620^FS ^A0N,28,36^FO46,434^CI0^FDLOT^FS ^BY2^FO46,865^BCN,112,N,N,N^FD>:1520^FS ^A0N,41,42^FO46,979^CI0^FD1520^FS ^A0N,28,36^FO46,840^CI0^FDSERIAL^FS ^A0N,39,32^FO46,232^CI0^FD1340^FS
Department:--->{Department.Name}<---^FS!!! this line contains replacement macro
---Employee1 Name:--->{Employee.Name[0]}<---^FS!!! this line contains replacement macro Employee1 Position:--->{Employee.Position[0]}<---^FS!!! this line contains replacement macro
Employee1 Salary:--->{Employee.Salary[0]:C}<---^FS!!! this line contains replacement macro Employee2 Name:--->{Employee.Name[1]}<---^FS!!! this line contains replacement macro Employee2 Position:--->{Employee.Position[1]}<---^FS!!! this line contains replacement macro
Employee2 Salary:--->{Employee.Salary[1]:C}<---^FS!!! this line contains replacement macro Employee3 Name:--->{Employee.Name[2]}<---^FS!!! this line contains replacement macro Employee3 Position:--->{Employee.Position[2]}<---^FS!!! this line contains replacement macro
Employee3 Salary:--->{Employee.Salary[2]:C}<---^FS!!! this line contains replacement macro ^A0N,39,32^FO46,271^CI0^FD1440^FS ^A0N,28,36^FO187,648^CI0^FD2420^FS ^PQ$$8620,0,1,Y ^XZ
2.3.5 Spooling Types
The LPF currently supports two ways of spooling labels. The spooling type is configured per printer and is chosen based on the target printer taken from the print request.Printer Spooler
This spooling type sends the label directly to the printer using the Spool Address as a printer address. This spooling type only works for printers that accept text label files. Typical office printers require an Enhanced Metafile (EMF) format that is not supported directly by the LPF and requires third-party printing software. The DELMIA Apriso Print Engine must have access to and the permission of the printer.File Spooler
This spooling type saves the file to disk or a network folder using the Spool Address as the target folder name. The framework creates a file with a unique name in the folder and persists the result of the mapping. This file is usually picked by the third-party printing software and sent to the actual printer.3 Usage
3.1 Installing Required Tools
The following tools are required to effectively use the LPF.
Task Tool Where to Find the Tool
Label layout design Third-party label designing tool Third-party software vendors Preparing label definition files Microsoft InfoPath (recommended), XML editor, or text editor for editing files Microsoft Office Preparing label definition files LabelDefinition.xsd – schema LabelDefinition.xsn – InfoPath form DELMIA Apriso Assemblies folder DELMIA Apriso Guidelines folder Developing label providers Microsoft Visual Studio or .NET SDK or third-party .NET development tool Microsoft or third-party software vendors Preparing XSLT Third-party XSLT, XML editor, or text editor Third-party software vendors Authoring Processes to invoke label printing Process Builder DELMIA Apriso
3.2 Performing Main Tasks
The following section lists the major tasks related to label printing. The tasks can be divided into two major parts: Tasks related to the design and preparation (of labels) These are performed by the Label Designer or Developers Tasks related to invoking printing These are performed by the Process Author or Developers
3.2.1 Designing Label Layout
The LPF is not involved in designing the label layout. The label layout should be created using the third-party tools available on the market that specialize in this area. The third-party tools usually produce a format file that uses the control codes to encode the layout. The label format file also contains the macros that should be replaced with the actual values before printing.
3.2.2 Preparing Label Definition File
A label definition file contains all the information required by the framework to process and print a label. One label definition file should be created per single label during the label design.
A label definition file is a simple XML document that is compliant with the Label Definition schema: LabelDefinition.xsd. The document can be created in any text or XML editor, but the recommended (and easiest) method is to fill out the Label Definition form using the Microsoft InfoPath and the Label Definition template: LabelDefinition.xsn.
Both ReportDefinition.xsn and ReportDefinition.xsd files are available on the DELMIA Apriso server through the DELMIA Apriso Server Configuration page (in Tools and File Packs). This table presents descriptions of the most important parameters: Parameter Description Label ID The unique hierarchical name of the label. It should use the namespace that corresponds to the similar DELMIA Apriso business logic. For example: FlexNet.Production.Label.SimpleProductionLabel. Label Name The user-friendly name of the label. Label Description The user-friendly and author-friendly description for the label. Version Specifies the version of the label. Input Parameters A list of the parameters that must be provided when label printing is triggered. These parameters can be used by the data providers or they can be used by the label format. This list contains only the “external” parameters (the ones that are gathered during the print triggering). Name in Input Parameters Specifies the name of the label's Input parameter. Description in Input Parameters Specifies the description of the label's Input parameter. Type in Input Parameters Defines the type of parameter. The possible choices are: Char, Integer, Decimal, Boolean, DateTime, or Date. Label Fields A list of the parameters that are used by the label mapping or label format. This should contain all the parameters that are used by the label, and they should either be provided by the label data providers or be the same as Input Parameters. This list is validated during the label processing to check that all the parameters have values and that they can also be used by developers of label
data provider components. Name in Label Fields Specifies the name of the label field. Description in Label Fields Specifies the description of the label field. Type in Label Fields Defines the type of the field. Possible choices are: Char, Integer, Decimal, Boolean, DateTime, or Date. Grouping in Label Fields This parameter affects the way the label parameters are persisted to XML before applying the XSLT transformation. Specifying the same grouping for several fields that are arrays will group them together in the XML generated for the XSLT processing. Leaving the grouping blank will create independent lists with single elements. Key Value Number in Label Fields When printing a label from a Function, the parameter values are saved to specific fields of the PRINT_REQUEST_HISTORY table. These fields are named Key1, Key2, Key3, etc. The Key Value Number allows for the assigning of parameters to table fields (e.g., Key1 fields correspond to Key Value Number 1). Data Providers A list of components that are data providers for the label. The components are invoked during label processing and should provide the values of the Label Fields based on the Input Parameters. Each component should be configured using the fully qualified assembly and class name. Class Name in Data Providers Specifies the data provider component's class name. Assembly Name in Data Providers Specifies the data provider component's assembly name. Mapping Type Specifies the mapping type that should be used for this mapping. For a detailed description of the mapping types, see 2.3.4 Different Types of Mapping.
Figure 1 Preparing the label definition file in Microsoft InfoPath
3.2.3 Developing Label Data Providers
Label data providers are simple .NET components (classes) that implement the
ILabelDataProvider interface. The class does not need to inherit from any special class, but it is recommended that it inherits from BaseComponent in order to utilize all the infrastructure (such as logging) offered by the base class.
The ILabelProvider interface has a single method: GetLabelData. Refer to the framework online documentation for a detailed prototype of the method. Inside, the method logic should find the required Input parameters in the PropertyBag that is being passed. Based on these Input parameters, the logic should retrieve additional fields from the database or any other source and insert the retrieved data as new rows in the PropertyBag. Each element of the PropertyBag can be a simple type (int, string, etc.) or an array of simple types (int[], string[], etc.). In this way, the PropertyBag is filled with all the fields that require labeling. Each label data provider is coded to expect specific Input parameters in the PropertyBag and to deliver specific fields as outputs. This information must be documented in the component documentation to allow the label to be designed using the correct names of parameters and fields. From the other side, the label definition file should list all the Input parameters and label fields to allow the developers to program the components that retrieve all the required information.
3.2.4 Preparing XSLT Mapping or Format File
XSLT Replacement For both mapping types, it is recommended to start with the “None” mapping type in order to see what the layout of the serialized PropertyBag is. The serialized PropertyBag contains all the parameters and the values of these parameters. This helps in testing the passing of Input parameters and label data providers. The following sections describe the details related to both types of mapping.
Preparing an XSLT Mapping
To prepare an XSLT mapping label, the Label Designer must use third-party tools (or regular text or an XML editor) to author the XSLT file that converts the serialized PropertyBag into a file that is expected by the printer or third-party printing software. Using “None” mapping is recommended in order to obtain a sample XML with the serialized PropertyBag and to use this as the source document. The XSLT transformation must be compliant with the Microsoft .NET XML engine. The target format is dependent on the printer/third-party software. The Label Designer can consult the third-party documentation for details.Preparing a LabelFormat File for Replacement Mapping
Replacement mapping uses a regular label format file to replace the macros with actual values. The easiest way to prepare such a file is to perform the following steps using the third-party label design tools: 1. Design the label layout used third-party software. 2. Place the macros in places where the runtime values should be populated. 3. Assign the label to the printer type on which the label will be printed. 4. Print the label from the file. Consult the third-party software documentation for details related to the above activities. As a result of the above steps, the third-party software should generate a label format file that contains all the control codes corresponding to the label layout and the macros for the replacement engine. In this case, the format file is the mapping file required for label processing. This file is analyzed and all the macros are replaced with actual values during label processing. Each macro should be in following form:
For arrays: {ParameterName} or {ParameterName[n]}
For formatted arrays: {ParameterName:Format} or {ParameterName[n]:Format}
The ParameterName must match the name of the Input parameter or the label field defined in the label definition file. This is the same name that is used as a key in the label parameters
PropertyBag as processed by the label data providers. The name should follow the naming conventions described in 4.2 Parameters Naming. Note that n is a zero-based index for parameters that are arrays. All the arrays must be accessed using indexers. The optional format specifies the formatting that should be applied to the parameter during replacement. The LPF supports all the standard formatting supported by Microsoft .NET. For more details refer to the Formatting Types or Standard Numeric Format Strings topics in Developer Network Library for details. Here are some sample macros that can be embedded in the label format file:
{Employee.Salary:c}, {Product[5].Name}, {Product:ExpirationDate:d}, and {Quantity}.
3.2.5 Registering Labels
Register your label using Report Administrator, which is available in Apriso Classic Portal under this path: Administration }System Administration }Report Administrator.
Figure 2 Registering a label in Report Administrator
3.2.6 Invoking Label Printing
This task is not performed by the Label Designer. It is performed by a Process Author or a Developer who wants to trigger the printing of a label that has already been designed.
Label printing can be invoked from the Processes executed in the Apriso Classic Portal and designed in Process Builder, or it can be invoked from any code.
Invoking Label Printing from Processes
To invoke printing from Processes, the Process Designer must use the special Function type called Submit Print Request. After adding this Function to the Process, the Process Designer must specify which label should be printed. Process Builder then populates the Input list with the label’s Input parameters. The values of the parameters must be provided in runtime to trigger the label processing and printing. Label printing is always asynchronous in this scenario. Please consult the referenced use cases for additional details.
Invoking Label Printing from code
It is possible to invoke label printing directly from the code. To achieve this, the Developer must populate all the required properties of the LabelPrintRequest class and invoke: PrintManager.ProcessPrintRequest() for synchronous printing PrintManager.QueuePrintRequest() for asynchronous printing For a detail prototype of the methods and structures, refer to the framework online documentation.
3.3 Code Templates
Code templates are embedded in the previous sections.3.4 Compilation Issues
Make sure to create a reference to the FlexNet.BusinessRules.Report.Interfaces library and the FlexNet.BusinessRules.Report namespace before using DELMIA Apriso Label Printing. The FlexNet.BusinessRules.Report.Interfaces assembly uses several other assemblies from the LPF. These assemblies are not references directly, but they are dynamically loaded in runtime. They must be available in runtime for the framework to work correctly.
4 Best Practices
4.1 Developing Reusable Label Data Providers
Label data providers, like any other code component, should be designed and written so that they are reusable. The providers should be atomic, delivering data specific to the business entity. The LPF supports calling several data providers for a label, so each label should be configured to use several data providers versus coding a single, non-reusable, monolithic data provider for each label. The providers should not be designed or tightly coupled with specific labels , in order to eliminate the need to change the code each time a label changes.
4.2 Parameters Naming
The framework assumes that “communication” between a label definition file, Input parameter, data providers, and label fields is organized by the named values stored in the PropertyBag. This requires a solid organization of names in order to eliminate confusion and conflicts. For parameters and fields, using these hierarchical naming patterns is recommended:TableName.ColumnName or EntityName.FieldName. Such conventions should produce sample names such as Employee.Salary and Product.Name.
5 Sample Project Description
Sample labels are installed as part of the standard DELMIA Apriso installation. They are installed into: <drive>\Program Files\Dassault Systemes\DELMIA Apriso 2019\Labels
Definitions\Samples\. A sample solution is prepared together with this document. This solution demonstrates the major elements of label printing, such as sample labels and sample data providers.
5.1 Project Availability
A label printing sample project is available on request. Contact your Dassault Systèmes representative or DELMIA Apriso Support to obtain the project package.5.2 Project Overview
The solution contains three sample labels. Each label demonstrates the following aspects: Label Area Employee badge A simple label with external parameters only. Does not use any custom data providers. Uses replacement mapping based on the Employee badge.fmt format file. The format file demonstrates simple replacement macros. Employee Details A label that demonstrates usage of label data providers. Using the “None” mapping demonstrates the parameter persisting in the XML prepared for XSLT transformations. Employee List A label that demonstrates usage of label data providers. This label uses array parameters that are grouped together to make the XSLT transformation simpler. The label also uses a simple XSLT transformation (Employee List.xslt) to prepare the output file. The label can also use Replacement mapping to demonstrate the macros based on arrays. This solution also contains a project with simple data providers. The sample implementation provides hard-coded data. In a “real world” application, the data should be taken from real sources like a database, but the concept stays the same. The solution also contains a simple screen that allows for the triggering of label processing and printing. It allows for the simple development and testing of labels without the need to have all of DELMIA Apriso installed and configured for printing. The sample application contains hard-coded values for the database primary key (likeREPORT.ID or PRINTER.ID). These values should be modified, or the database should be updated for successful execution of the sample.
6 Appendix A: Checklist
Point to be checked Grade (0-5) The label ID has a hierarchical name. The label name is meaningful. The label description is provided. All the Input parameters are provided with types and descriptions. All the label fields are provided with types and descriptions. All the parameters used are correctly named. The label data providers are reusable. The mapping file is provided.All the internal documents referenced in this section are available from the DELMIA Apriso Start page, which can be accessed on your DELMIA Apriso server (<server name>/apriso/start). The newest versions of all documents are available from3DS Supportat:
http://www.3ds.com/support/documentation/overview/
7 References
External Documentation
Listed below are external resources which can be accessed using the URLs provided. 1. Developer Network Library
https://msdn.microsoft.com/en-us/library/26etazsy.aspx
3DS Support Knowledge Base
If you have any additional questions or doubts not addressed in our documentation, feel free to visit the 3DS Support Knowledge Base at https://www.3ds.com/support/knowledge-base/.
