Implement Company Template¶
The IFS Cloud release delivers pre-defined system templates, associated with the Create Company concept, containing basic data that after installation can be used when creating a new company. The templates enables an easy and quick way of creating a company and associated basic data, thus reducing the time to get started with company related functionality.
The supported and currently installed system templates can always be found using command View Reserved System Template Ids... in the Company Templates page.
The Create Company concept functionality can be summarized as follows,
- During installation each component that supports the concept has to register itself in Enterprise component.
- Each component owns its own basic data as well as associated translations. The basic data part of this information is kept in specific company template files whereas the associated translations are kept in the ordinary component TRS file. The company template files are executed during the installation and create system templates consisting of information related to one or more components. The installed information is kept in the template storage in Enterprise component.
- A new company can be created from an existing company or from a company template.
- Install the company templates files (and translation files) depending on deployment model (Cloud or Remote) used.
- A user defined company template can be created from any existing company.
- Any company template (as well as associated translations) can be exported to file.
Note: Even if template translations can be exported from Create Company specific pages, these files should not be stored in the version handling system for a component.
-
Company template files can be merged to one single file.
-
New data can be added to an existing company by using the Update Company functionality.
The basic principle is to use the power of the application to define a company with suitable setup of basic data and then create a template from this company. The created template can be used for the following purposes,
- As a source for creation of new companies.
- If exported, the company template can be defined in new component releases to support specific market or customer needs. The exported files can also be sent by e.g. e-mail to a subsidiary where they can be imported and used as source for creation of new companies.
In order to utilize the functionality in the concept it is important to perform the implementation correctly.
Use this document as implementation guidelines for the Create Company concept.
Contents¶
- General Component Instructions
- Compatibility Aspects
- Handling Posting Control
- Handling the Registration File
- Adding a Logical Unit to the Create Company concept
- Currency and User Related Data
- Creating Template File(s)
- Creating template file(s) from a valid template
- Specific Implementation Instructions
- Adding new Payment Type Codes
- How to handle specific implementation
- Special Considerations
General Component Instructions¶
This sections covers general instructions for an IFS Cloud component that supports the Create Company concept.
Compatibility Aspects¶
The following is important with respect to Company Template validity,
- During upgrade from an earlier version to the latest release of IFS Cloud, all existing templates in the database will be marked as non-valid if component versions in the template does not match the currently installed component versions. The reason is that template components data might not be compatible with the business logic of the installed component versions.
- If a template is marked as non-valid it cannot be used as source for a new company. The following can be done to handle this case:
- Delete all non-valid company templates that definitely should not be used anymore.
-
For all other non-valid templates the following can be done to make the templates valid again:
- Find the template in the Company Templates page.
- Mark the template and use the command Mark as Valid Template.
- The action will set all component versions in the template to the actual version of the components in the installation. The template will also be marked as valid.
Note: The data in the templates might still not be compatible with the business logic of the installed component versions - Create a new company to test if the template is correct or not. - Correct all errors in the template and continue creating new companies until there are no more errors. Now the template is valid and consistent. - All temporary companies created during the test phase can be removed by using the command Remove Company in the Companies page.
Handling Posting Control¶
In order to handle Posting Control in a component it is required to create the following new Logical Units,
- One for Posting Control named according to <Component>PostingCtrl, e.g. InvoicPostingControl
- One for Posting Control Detail named according to <Component>PostingCtrlDetail, e.g. InvoicPostingCtrlDetail
- One for Posting Control Detail Specification named according to <Component>PostingCtrlDetSpec, e.g. InvoicPostingCtrlDetSpec
- One for Posting Control Combination Details named according to <Component>PostingCtrlCombDet, e.g. InvoicPostingCtrlCombDet
- One for Posting Control Combination Detail Specification named according to <Component>PostingCtrlCDetSpec, e.g. InvoicPostingCtrlCDetSpec
Note: The mentioned Logical Units are necessary if the component handles financial transactions and uses posting control definitions in Accounting Rules to create the transactions.
After having defined the new Logical Units some files representing these Logical Units have to be added to the source code of the component. The only thing that has to be done to make things work is to perform the following in the template files below:
- Rename the files so that they correspond to current module.
- Edit the files and make sure that the module is correctly defined. Do not forget to clean the design history.
- Do not forget to add those new Logical Units as utilities to the component/module model overview diagram.
The template files are:
File Name | Comment |
---|---|
InvoicPostingCtrl.utility | Template model file for a posting ctrl master LU. Module=INVOIC in this case. |
InvoicPostingCtrl.plsql | Template for all business logic PL/SQL code implementation for a posting ctrl master LU. Module=INVOIC in this case. |
InvoicPostingCtrlDetail.utility | Template model file for a posting ctrl detail LU. Module=INVOIC in this case. |
InvoicPostingCtrlDetail.plsql | Template for all business logic PL/SQL code implementation for a posting ctrl detail LU. Module=INVOIC in this case. |
InvoicPostingCtrlDetSpec.utility | Template model file for a posting ctrl detail specification LU. Module=INVOIC in this case. |
InvoicPostingCtrlDetSpec.plsql | Template for all business logic PL/SQL code implementation for a posting ctrl detail specification LU. Module=INVOIC in this case. |
InvoicPostingCtrlCombDet.utility | Template model file for a posting ctrl combination detail LU. Module=INVOIC in this case. |
InvoicPostingCtrlCombDet.plsql | Template for all business logic PL/SQL code implementation for a posting ctrl combination detail LU. Module=INVOIC in this case. |
InvoicPostingCtrlCDetSpec.utility | Template model file for a posting ctrl combination detail specification LU. Module=INVOIC in this case. |
InvoicPostingCtrlCDetSpec.plsql | Template for all business logic PL/SQL code implementation for a posting ctrl combination detail specification LU. Module=INVOIC in this case. |
Note: that it must be checked if a new release of IFS Cloud contains a new version of the template files. If so the existing files in each component must be replaced by the new template versions.
Handling Footer¶
In order to handle Footer in a component it is required to create the following new Logical Units,
- One for Footer Connection named according to <Component>FooterConnection, e.g. InvoicFooterConnection
- One for Footer Field named according to <Component>FooterField, e.g. InvoicFooterField
After having defined the new Logical Units some files representing these Logical Units have to be added to the source code of the component. The only thing that has to be done to make things work is to perform the following in the template files below:
- Rename the files so that they correspond to current module.
- Edit the files and make sure that the module is correctly defined. Do not forget to clean the design history.
- Do not forget to add those new Logical Units as utilities to the component/module model overview diagram.
The template files are:
File Name | Comment |
---|---|
InvoicFooterConnection.utility | Template model file for a footer connection master LU. Module=INVOIC in this case. |
InvoicFooterConnection.plsql | Template for all business logic PL/SQL code implementation for a footer connection master LU. Module=INVOIC in this case. |
InvoicFooterField.utility | Template model file for a footer field master LU. Module=INVOIC in this case. |
InvoicFooterField.plsql | Template for all business logic PL/SQL code implementation for a footer field master LU. Module=INVOIC in this case. |
Note: that it must be checked if a new release of IFS Cloud contains a new version of the template files. If so the existing files in each component must be replaced by the new template versions.
Handling the Registration File¶
A registration file must be included in all components supporting the new Create Company concept. It is named according to CreateCompanyReg<Component>.ins. The purpose with the file is to register information regarding the component in Enterprise.
The file consists of the following parts:
-
Registration of the component: example1.ins
-
Registration of the component details, i.e. supported Logical Units: example2.ins
- Registration of tables in the component from which data should be deleted if the component supports Remove Company: example3.ins
- Registration of remove company details if existing: example3.ins
- Registration of Client Mapping links (used in runtime to redesign the Company Template Detail page) for Company Template columns: example4.ins
Some of the interfaces defined by the file EnterpCompConnectV170.plsql are described here: example5.ins
Two component registration file example are provided:
- Component Enterp: CreateCompanyRegENTERP.ins
- Component Invoice: CreateCompanyRegINVOIC.ins
Adding a Logical Unit to the Create Company concept¶
Start with setting the codegenproperties DbImplementation to "make-company" in the entity file.
For each attribute that is a part of the create company concept the property CompanyCopyColumnName should be set. This property sets the name of the make-company database table column. Columns are named Cx, Nx or Dx, where x is a number. E.g. C15, N2, D6.
Following methods are automatically generated when "make-company" property is set:
Import___
- The
Import___
method is used when creating a new company from a template. - The
Import___
method should read the template data and call a validation method before inserting the data to the table.
- The
Import_Assign___
- Assigns attribute values for data import.
- If the Logical Unit is using a date attribute as <ValidFrom>that defines a starting from date, then:
- If the attribute is not part of the primary key, then set the <ValidFrom> = <CompanyValidFromDate>, e.g.
...
newrec_.valid_from := crecomp_rec_.valid_from;
...
This is done by overriding theImport_Assign___
method. See example6.plsql - Else the normal case is to get the date from the template.
For both cases it might be necessary to consider special logic.
- If the attribute is not part of the primary key, then set the <ValidFrom> = <CompanyValidFromDate>, e.g.
Copy___
- The
Copy___
method is used when creating a new company from an existing company. - Validations are necessary even if the data in the source company most likely is consistent
- The
Copy_Assign___
- Assigns attribute values for data copy.
- If the Logical Unit is using a date attribute as <ValidFrom>that defines a starting from date, then:
- If the attribute is not part of the primary key, then set the <ValidFrom> = <CompanyValidFromDate>, e.g.
...
newrec_.valid_from := crecomp_rec_.valid_from;
...
This is done by overriding theCopy_Assign___
method. See example6.plsql - Else the normal case is to get the date from the template.
For both cases it might be necessary to consider special logic.
- If the attribute is not part of the primary key, then set the <ValidFrom> = <CompanyValidFromDate>, e.g.
Export___
- The
Export___
method is used when a template is created from a company. - The table is used to fetch the appropriate information from the Logical Unit and then the public interface
Enterp_Comp_Connect_V170_API.Tem_Insert_Detail_Data
is used to define the template data.
- The
Export_Assign___
- Assigns attribute values for data export.
Exist_Any___
- Checks if given company already has data.
Check_If_Do_Create_Company___
- Checks if given company should be created of not.
Create_Company_Reg__
- Creates a registration entity into the company copy framework.
Create_Client_Mapping__
- Creates a client mapping entity into the company copy framework.
Make_Company
- This public method is called when creating a new company.
- It is also called for updating a Difference Template when the Logical Unit has a date as a part of the key. When updating a difference template with the recalculated date then the procedure is called with
make_company_='MODIFY_KEY_DATE'.
To facilitate this the Make_Company method needs to be overridden. See example6.plsql
Currency and User Related Data¶
In the current version of Create Company, data in Logical Units Currency Type and Currency Rate are never supplied via templates or companies. The default data will instead be taken from the tables Currency_Rate_Def_Tab and Currency_Type_Def_Tab.
User Related Data, i.e. data containing user identities, will be handled according to the following:
- During internal import, i.e. when a company is created from a template or a company, then User Related Data is defined exactly as in the source template or company.
-
During internal export, i.e. when a template is created from a company then it is possible to choose if User Related Data should be taken from:
- The source company
- A specific company template.
It is recommended to use a template as source for User Related Data and the default template will also be suggested as the source.
Note: When a new template file is created through the Export Company Template it is not very likely that user identities and user identity related data should be a part of the file, since these identities are specific for the current installation. For that reason it is recommended that another template should be used as source for creation of user identity related data when creating a user defined template from a company.
So if a new Logical Unit handles User Related Data, i.e. the Logical Unit has a reference to user or user_group, then this case must be handled in a slightly different way than for other Logical Units. The client attribute string that is sent to the Export___
method will contain an attribute that defines the source for the user data and this attribute must be considered.
One example is Logical Unit UserGroupFinance in Accounting Rules. The default user related data for the Logical Unit is stored in a template. The data in the template for the specific Logical Unit is used if the user so requests else the data in the source company is used. For implementation guidelines please look in the file UserGroupFinance.plsql in Accounting Rules. See section How to handle special implementation for different implementation guidelines for LU's with special implementations.
Creating Template File(s)¶
In order to create a template file the following cases must be considered first:
- Have we added new Logical Units that have never been available in the IFS Cloud version?
- Is it required to create a new template file in a new version of a component that support the Create Company concept?
The first case is typical when developing new basic data Logical Units in a new component version. There is no old basic data available that can be used to fill the template with data for the Logical Unit. The following can be performed in this case:
- Perform the necessary programming for each Logical Unit to be able to support the Create Company functionality.
- Perform an upgrade of the component or install new api/apy files and execute registration file manually.
- Create a company from the old version of the template (does not contain any data in the new Logical Units).
- Use the application to add the necessary basic data for the new Logical Units in the created company.
- Create a template from the company.
- Check the template data via the template forms. Add/modify data if needed.
- Create a new company from the template to make sure that this works without errors. Test the company.
- If not ok, modify, create and test again.
- If everything is ok then perform the following: Creating template file(s) from a valid template
In the second case the existing Logical Units are the same in the new component versions. However we may want to modify the contents in some of these Logical Units. The following can be performed in this case:
- Create a company from the old version of the template.
- Use the application to add or modify basic data for Logical Units to be modified in the created company.
- Create a template from the company.
- Check the template data via the template forms. Add/modify data if needed.
- Create a new company from the template to make sure that this works without errors. Test the company.
- If not Ok, modify, create and test again.
- If everything is Ok then perform the following: Creating template file(s) from a valid template
Creating template file(s) from a valid template¶
- Rename template if needed from e.g. a temporary name to the final name.
- Use the Export Company Template to export the template.
- Choose if one file per component or one single file should be created and start the export. If the purpose is to create template files for a new component release then one template file per component should be created.
- Define the template files in the version handling system for each component if necessary.
Specific Implementation Instructions¶
This sections covers specific implementation instructions like e.g. adding new data in Payment and how to handle special implementations.
Adding new Payment Type Codes¶
If a new Payment Type has to be added to component Payment then the following can serve as a guideline:
-
Modify LU PaymentTypeCode
This is an enumeration LU. The new type must be added to the list of types. -
Make sure that the source code takes care of the new type.
-
Update system templates, e.g. template STD, by defining data for Logical Unit PaymentType.
Specify a Payment Series ID for each Payment Type Code. -
If it is required to associate the type code to a new Series Id then do not forget to add the new Series Id in Logical Unit PaymentSeries.
-
Note: Upgrade scripts should NOT handle definition of Series Id or the link between Payment Type Code and Series Id. After an upgrade data, the necessary data can be added via the Update Company functionality.
How to handle special implementation¶
If special implementation is needed for the LU there are several ways to handle this:
- Override, if possible, the create company method/s in the plsql file: InvoiceAuthorizer.plsql
- Use property DbImplementation "make-company-abstract": PaymentTermDisc.entity
- Overtake the create company method in the plsql file, this should only be used if one method result in an overtake
- If several create company methods result in overtakes then:
- use the property DbImplementation "make-company-abstract" or
- keep the LU outside the new create company concept by adding a notation in the entity. The notation that should be added in the entity is "This LU supports create company but needs manual implementation": UserFinance.entity
Following methods are automatically generated when "make-company-abstract" property is set:
Make_Company
Create_Client_Mapping__
Create_Company_Reg__
Check_If_Do_Create_Company___
Exist_Any___
Following methods are automatically generated, but empty and code needs to be manually written:
Import___
Copy___
Export___
Special Considerations¶
The current Create Company concept solves a lot of problems related to basic data setup for companies. The following considerations/limitations are worth mentioning:
- By default all code part related Logical Units are inactive. This means that values for e.g. Logical Unit "CodeB" (code part B) are not stored in a delivered template, are not handled during export of template and not copied when a company is created from another company. This may lead to errors when posting control data is handled if the posting control refers to code part values that are not available. It is possible to activate these Logical Units but it must be done with care since it is not at all sure that code part values can be "copied" from one company to another, e.g. if a code part represents objects in the Fixed Asset Accounting module.
If a code part is activated then it will still not be possible to import data for the code part from the template to a company or to export data for the code part from a company to a template, if the code part in the company is associated with a code part function.
- Translations of descriptions are supported and can thus be defined in any language. Note however that a Company Template may contain identities that must be modified with respect to language to fit the country or region that the template is supposed to support