Preparing custom templates for migration

If your organization uses custom templates (knowledge sources) in BMC Helix ITSM: Knowledge Management, you must prepare equivalent templates in BMC Helix Innovation Suite Knowledge Management (ISKM) before migrating articles. Template preparation includes reviewing auto-generated field mappings, adding missing mappings, and creating the corresponding ISKM custom template.

If you use only out-of-the-box templates, you do not need to prepare or migrate custom templates.

Before you begin

Before you prepare a custom template migration, make sure that the following prerequisites are met:

You have administrator permissions and reviewed key considerations.
Custom knowledge sources of type AR Form and lifecycle enabled are registered in BMC Helix ITSM: Knowledge Management. Registration is required for ISKM to retrieve template metadata and generate initial field mappings. For more information, see Registering-and-modifying-knowledge-sources.
The prerequisites required for enabling ISKM are completed. For more information, see Configuring BMC Helix Innovation Suite Knowledge Management as a knowledge provider for BMC Helix ITSM.

To prepare a custom template for migration

The process includes the following tasks:

Task 1: To access the Field Mappings page

As an administrator, log in to BMC Helix ITSM.
Click Settings.
Expand Helix IS Knowledge Management and click Enabling IS Knowledge Management.
On the Enabling Helix Innovation Suite Knowledge Management (ISKM) page, verify that you have completed the prerequisites.
In Steps to enable ISKM, click Prepare Custom Template Migration.
The Prepare custom template migration option is available only when at least one custom knowledge source is available in BMC Helix ITSM: Knowledge Management.
On Custom Template List, review the list of templates.
Only registered custom templates are displayed. For each custom template, you need to validate and complete the field mapping before creating the ISKM template.
Select the custom template that you want to prepare and click Validate Field Mapping.
The Field Mappings panel is displayed.

Task 2: To validate the field mappings

The Field Mappings panel displays the auto‑generated mappings between the selected BMC Helix ITSM: Knowledge Management custom template and the ISKM custom template. Each row in the mapping list represents a field mapping and displays the following columns:

Column	Description
Field ID	Unique identifier of the source field. Clicking this value opens the mapping for review or editing.
Field name	Name of the field in the source template. For example, Resolution, Request ID, and Short Description.
Type	Indicates the field type: RTF (content field) Attachment (article attachment or inline image)
Sequence	Order in which this field will be displayed in the ISKM template.
Mapping	Corresponding field that will be created or mapped in ISKM.
Reference	(Applicable to the Attachment field type) Unique identifier of the selected reference field where the attachment is available.

Important

ISKM uses registration metadata to create the initial mappings. Auto-generated mappings might be incomplete. Review all mappings before proceeding.

Review the existing mapping and edit it if required.
1. On the Field Mappings panel, click a Field ID to view mapping details.
2. On the Edit Field Mapping panel, verify the mapped ISKM field, sequence, and reference values.
  Dimmed fields are system‑defined and cannot be edited.
3. Update editable values as needed.
4. Click Save.
(Optional) Add a new mapping.
1. On the Field Mappings panel, click + New.
  The Create Field Mapping panel is displayed.
2. On the Create Field Mapping panel, select the required values for the following fields:
  - Knowledge Source Name: Automatically populated. It indicates the Source Name that you specified while registering the custom knowledge source.
  - Knowledge Source Form Name: Automatically populated. It indicates the Form Name you selected while registering the custom knowledge source.
    
    Click here to view the example custom knowledge source registration form in BMC Helix ITSM: Knowledge Management
  - Type: Select one of the following:
    - RTF: For rich‑text content fields
    - ATTACHMENT: For attachment fields
  - Source Field Name: Select the source field from the list.
  - Source Field ID: Enter or verify the field ID.
  - Mapping ISKM Field Name: Select the corresponding field that will be created or mapped in ISKM.
  - Mapping ISKM Field ID: Automatically populated after Mapping ISKM Field Name is selected.
  - Sequence: Specify the display order.
  - When ATTACHMENT is selected, the following additional fields are displayed:
    - Reference Field Name: Select the reference field where the attachment is available.
    - Reference Field ID: Automatically populated after Reference Field Name is selected.
3. Click Save to add the mapping.
Repeat the validation and mapping steps until all required fields for the selected template are mapped.

Task 3: To create the corresponding ISKM custom template

ISKM uses the validated field mappings to create a new custom template aligned with the source structure.

On the Field Mappings panel, click Create ISKM Template.
The corresponding ISKM template is generated, including the validated field mappings as sections according to the field sequence.
On the Edit Article Template panel, review the auto-generated template and modify it as required.
The sections are displayed in the sequence as defined in the field mappings. You can reorder sections by using drag-and-drop. You can add or remove sections, set the template as global or disable it, and define localization values.
Click Save.
A link to the ISKM template appears on the custom templates list page.

The ISKM custom template is registered and ready for use in data migration. After registration, the Migrate Custom Articles step is added to the migration steps table as displayed in the following screenshot. You can then initiate the migration. For details, see Performing the migration.

migrate custom template

After migration, the templates are available in the ISKM templates list and can be used to create new ISKM articles.

Troubleshooting

Issue	Cause	Resolution
Prepare Custom Template Migration option is not visible in ISKM	No registered custom knowledge sources are detected in BMC Helix ITSM: Knowledge Management	In BMC Helix ITSM: Knowledge Management, make sure that registered knowledge sources meet the following requirements: Knowledge source is of type AR form Life cycle Management is enabled Registered source is in the Ready state
RTF field mappings are not created automatically in ISKM	No content fields are detected for the knowledge source in BMC Helix ITSM: Knowledge Management	When registering the knowledge source in BMC Helix ITSM: Knowledge Management, make sure the relevant fields are entered on the Content Fields page. If not, enter field mappings manually in ISKM.
Fields or attachments are missing	Required RTF or attachment fields were not mapped during template preparation Auto‑generated mappings were not reviewed and corrected A field or attachment exceeded the supported limits The field is non‑editable and cannot be adjusted to match the source template	Review and complete all required field mappings before creating the template.