Implement Company Template

The IFS Applications 9 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 RMB View Reserved System Template Ids... in the Company Templates window.

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.
• Company templates files (and translation files) can be imported.
• 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 as well as imported from Create Company specific windows, 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 Applications 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 Applications, 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 window.
• Mark the template and select the RMB 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 RMB Remove Company in the Overview Companies window.

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:

Also note that it must be checked if a new release of IFS Applications 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:

Also note that it must be checked if a new release of IFS Applications 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 window) 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:

1. Component Enterp: CreateCompanyRegENTERP.ins
2. 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.
• 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 the Import_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.

• 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
• 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 the Copy_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.

• 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.
• 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 to File Assistant 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 core or localized versions?
• 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 File Assistant 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