Configuring Development Goal Plan Using XML

The Development Plan XML gives you full configuration control, whereas Manage Templates in Admin Center gives you limited options. For example, do you want to have one competency per development goal, or multiple competencies per development goal? This can only be configured through the XML. All items within Admin Center are also configurable within the XML. For example, the plan Start Date uses the XML element <obj-plan-start>. Some elements are easy to correlate while others can be challenging.

The General Settings elements and attributes are located at the top of the XML.

Many of the General Settings attributes cannot be edited in the Admin Center and must be changed via XML. This section reviews some of those General Settings attributes that must be changed via XML.

To edit the Development Goal Plan template in XML, the template must first be exported from Provisioning. This is done in the Managing Plan Template area, under Import/Update/Export Development Plan Templates. Once the template has been exported, it can be opened in an XML editor to make changes.

To learn how to edit template XML files, watch this video:

General Settings allows you to activate different features within your development plan template:

Example 1: Newly created goals are currently defaulting to "public," but the customer wants them to default to "private." Change the new-obj-share-status-public attribute as follows:

• from: new-obj-share-status-public="true"
• to: new-obj-share-status-public="false"

Example 2: To change the public/private indicator from an icon to text, change the use­-text-for-privacy attribute as follows:

• from: use-text-for-privacy="false"
• to: use-text-for-privacy="true"

The figure illustrates the before view for both the XML view and the Development Plan view of Examples 1 and 2 outlined in the previous section.

The goal privacy indicator is an icon and defaults to a light color that means it is set to public.

Text Replacement allows you to replace standard text with custom text within the XML. Do not confuse this with the Text Replacement tool in Admin Center. All text replacement options can be found in the DTD objective-template_4_0.dtd and are added via the text-replacement element.

The figure below illustrates the before view for both the XML code and the Development Plan view showing examples of XML-based text replacements.

Categories are used to organize development goals, and they are set up using the category element. Within the category element, there must be a category ID and a category name.

The category ID appears in reports and can only be configured in the XML. The category name is what appears in the instance.

It is best practice to have the category ID and category name be as similar as possible. In addition, special characters should not be used in the category IDs. When a category is added from Admin Center, the system assigns an ID with the name "categoryX" where X is a numeric value. This ID should be edited in the XML to match the category name.

The <default-category> has the following considerations: 

• There is only one <default-category> that can be configured as such in the XML template.
• The <default-category> always comes after the last </category> defined in the XML template. This order is enforced by the DTD objective-template_4_0.dtd. 
• The <default-category> is optional and more frequently used in goal plans than development plans. 

Here’s an example of the <default-category> XML:

1234567891011

<category id="Goals">
<category-name>Current Goals</category-name>
</category>
<category id="ArchivedGoals">
<category-name>Archived Goals</category-name>
</category>
<default-category id="Default">
<category-name>Select Current or Archived Goals Category</category-name>
</default-category>

We have already seen that custom fields can be added through Admin Center. They can also be added through XML. For custom fields, the field ID and field type are determined by the customer. It is important to decide if custom fields need to be reportable.

The figure below shows adding the custom field link AFTER the standard purpose field.

As discussed in previous sections, both standard and custom fields are available to be added to a development plan. Although adding fields is generally completed in Admin Center, both standard and custom fields can be added through XML.

Adding new fields through provisioning using XML follows a three-step process, because a couple of the steps that were performed automatically for you in Admin Center now need to be done manually in XML:

1. Define the field.
2. Permission the field.
3. Add the field to the Layout.

The XML for a standard field follows a repeatable pattern. Here’s an example of the name field that we can break down to see the various attributes:

1234
<field-definition id="name" type="textarea" required="true" detail="false" viewdefault="on" showlabel="false" default-calc-type="step" field-show-coaching-advisor="true" cascade-update="push-down">
<field-label>Goal</field-label>
<field-description>Goal</field-description>
</field-definition>

The Development Goal Field configuration interaction provides additional details on each step in adding a new field through XML.

Select the buttons to learn more about Goal Fields configuration.

Select the buttons to learn more about Field Definition elements.

Certain attributes are required for any field definition. For example, the id attribute and the type attribute must be defined or the file will fail to validate against the DTD. Some attributes are not required, such as detail or showlabel.

There is also one required child element: field-label . All other child elements are optional.

Select the buttons to learn more about standard fields.

Additionally, the table Standard Fields lists details about commonly used Development Plan standard fields. These can all be added through Admin Center.

The table Field Types shows a list of available field types. It is important to remember that Standard fields are limited to a predetermined set of field types. Custom fields typically use text, textarea, enum, date, or percent.

While all of these field types are available in XML, not all of them are available when adding fields through Manage Templates in Admin Center.

Similar to Goal Management, other standard fields can be configured on the Development Plan. These are standard fields that cannot be added through Manage Templates in Admin Center. They need to be added through the XML. An example is if the customer wants the user to add milestones to each of their goals. The milestones field is a non-Admin Center standard field.

Here are some other standard fields:

To make changes to attributes not available in Admin Center, locate the desired element, and make the change. For example, if you do not want the field to be automatically turned on in the Display area of the Development Plan, change the viewdefault code.

This change will force the end user to select the checkbox in the Display area of the development plan in order to see it on the plan.

The table describes additional <field-definition> attributes and can be saved for reference.

*These permissions are used in Goal Plans in the Performance and Goal Management module.

The words used for the attributes in the XML cannot be used as the field-definition IDs. Doing so would create issues.

For example, if we configure a custom field with field-definition id="type" type="enum", because the word type is a field attribute, when adding a development goal on the mobile application, this custom field displays as a free text box and not an enum field.

There are additional field options, which can be found in the Career Development Planning Implementation Guide: Goal Plan Template Elements and Attributes

In addition to configuring fields on the development plan, the customer needs to decide which business roles are able to work with the goals and fields. Development Plan permissions are different than Role-Based Permissions, but both are used to grant access to users.

Role-Based Permissions allow access to the Development Goal Plan. Once users have access to the goal plan, all other permissions are governed by the XML plan permissions.

When fields are added in Admin Center, permissions for that field are automatically added to all existing permission blocks. This may not be the desired behavior, so permissions must be further edited via XML.

When fields are deleted from Admin Center, the field and its permissions are removed.

When fields are added through XML, permissions need to be added to all existing permission blocks manually. The same is true when fields are deleted through XML.

The next sections discuss the process of editing two kinds of Development Plan permissions: action permissions and field permissions.

Action permissions define the roles that have the ability to perform specific actions on a goal plan, such as adding or viewing private goals.

Select the buttons to learn more about Action Permission.

The above figure shows an example of the XML before permissions are modified (that is, no HR Rep) and after permissions are modified, that is, the HR Rep is included. In the after example, the HR Rep permission is represented by the EH role that is highlighted in yellow.

The table All Permissions displays a list of possible action permissions.

In order for fields to be visible or editable, field permissions must be put in place. This is an XML-only configuration.

Possible field permissions are as follows:

• Read: The user with Read permission can see, but not edit the field. 
• Write: The user with Write permission can see and edit the field. Write permission implies Read permission, so they do not have to both be set up.
• None: The user cannot see (or edit) the field at all.

Field permissions exist in blocks that are read by the system from top to bottom, so a lower Read permission block could potentially override a higher Write permission block. Best practice is to place Read permissions above Write permissions in the code list.

The above figure shows the before and after XML when a field permission is changed. The before examples shows two permission blocks (highlighted in yellow). In this example, no one can edit "link" because there is no permission for "link". The after example shows three permission blocks (highlighted in yellow). In this example, the roles E and EM can edit "competency" and the role EH can edit "link".

Select the buttons to learn more about the Line of Sight Hierarchy.

Roles for Development Plan XML Permissions are the same as in Goal Management and the non-RBP data model.

For a complete list of roles, see the following KBA: https://launchpad.support.sap.com/#/notes/2087940

By now, you know how to configure fields and how to permission fields. You also know how to add goals to the Development Plan. But where are the goals and the fields? Why are they not visible?

The next piece in working with Development Plan fields is to decide which fields should be placed on the plan layout. The plan layout arranges fields in the order they should be viewable on the Development Plan in the instance.

The first step in editing the plan layout is to export the Development Plan XML to an XML editor and analyze existing behavior.

The following bullets explain what we see in the code in the above figure: 

• Four fields are configured in the layout: "name," "metric," "due," and "state."
• The column weight determines how wide the column is on the layout. The "name" field will be the widest. If columns have a weight of 0, the field only takes up as much space as it requires .
  Note

  Note that columns with a weight of 0 will not show up in the performance form at all.
• Columns will populate left to right in the order defined from top to bottom.
  Note

  You can have more than one field in a column.

When fields are added in Admin Center, they are automatically placed on the plan layout. XML-added fields are not automatically placed in the plan layout like they are in Admin Center.

The figure above shows the before and after XML where a customer has requested the following:

• The "link" field to be located in the first column, under the "name" field
• The "desc" field to be located in the second column, under the "metric" field
• The "state" and "due" fields to be equally weighted

The figure above shows the effect of the XML code change in the instance.

There are advantages and disadvantages to configuring development plans in either Admin Center or using XML. For example, configuring items in Admin Center prevents consultants from making any syntax errors. On the other hand, certain items can only be added using XML. Depending on the items you’re configuring, you’ll want to choose the more appropriate configuration method.

One strategy is to add as much as possible through Admin Center, and then complete the configuration in XML.

The table below lists some examples of advantages and disadvantages of both configuration methods.

The standard comment field is used to store public comments for the goals. This field will always include the author's name and the time stamp when a comment is entered.

It is not possible to add this field in the Development Plan template from Manage Templates. The configuration is done in the XML. The field ID comments is in the plural form, whereas the field type comment is in the singular form:

12345678910
<field-definition id="comments" type="comment" required="false" detail="false" viewdefault="on" showlabel="true" field-show-coaching-advisor="false" cascade-update="push-down">
   <field-label>Comments</field-label>
   <field-label lang="en_US">Comments</field-label>
   <field-label lang="fr_FR">Commentaires</field-label>
   <field-description>Comments</field-description>
   <field-description lang="en_US">Comments</field-description>
   <field-description lang="fr_FR">Commentaires</field-description>
  </field-definition>

Like any other fields, the standard comment field has to be added to the Field permission and to the layout in the Development Goal Plan Template XML. These comments can only be added when creating or editing a goal. Once a comment is created, it is not possible to delete it.

As another option, the comments can be displayed in the plan layout using a switch.

Switches are used to enable or disable features in a Development Goal Plan template. The default value of the switches is off.

As an example, the standard comment field can have its regular view modified by adding the "threaded feedback" switch. This switch allows users to add, edit, or delete their comments without opening the goal. Switches have to be added in the XML file after the <obj-plan-due> date line and before the text replacement section.

12345678
 < obj-plan-start>01/01/2018 </obj-plan-start>
 <obj-plan-due>12/31/2020 </obj-plan-due>
 <switches>
  <switch for="threaded-feedback" value="on"/>
  <switch for="continuouspm-integration" value="off"/>
  <switch for="show-competency-browser" value="on"/>
  </switches>
  <text-replacement for="Instructions">

When the threaded-feedback switch is configured, the comment field is not visible in the goal pop-up window. This is the correct and expected behavior. Users will be able to add, edit, or delete their own comments directly from the plan layout.

There are other switches that can be added for different functions, and we’ll add them as they become necessary.

The "competencies" field type links development goals to one or more competencies that the employee is trying to develop.

1234
<field-definition id="competency" type="competencies" required="false"  detail="false"  viewdefault="on"  showlabel="false" field-show-coaching-advisor="false">
    <field-label>Competencies</field-label>
    <field-description>Competencies</field-description>
    <field-format>use-competencies</field-format>

You can only have one "competencies" field per development plan, but that "competencies" field can be displayed in more than one way. The screenshot above shows a configuration that allows a user to select multiple competencies.

You can enable access to the Competency Browser by adding a switch in the Goal Plan template XML so that the user can add additional competencies to the development goal that are not currently displayed:

123
<switches> 
<switch for="show-competency-browser" value="on" />
</switches>

A Competencies link appears next to the list of available competencies in the Add Development Goal window. Selecting the link displays the Add Competencies window, where competencies are organized into hierarchical lists of categories under tabs for each competency library. Users can select the checkbox next to one or more of these competencies and choose the Select button to add competencies to the development goal.

An Add Competencies link appears next to the list of available competencies when you add or edit a development goal.

To force users to pick a single competency, preventing them from selecting multiple competencies, set the field-format tag (within the field-definition block) to "use­ competencies-single" as follows:

1234
<field-definition id="competency" type="competencies" required="false"  detail="false"  viewdefault="on"  showlabel="false" field-show-coaching-advisor="false">
    <field-label>Competencies</field-label>
    <field-description>Competencies</field-description>
    <field-format>use-competencies-single</field-format> 

The competencies field will then use a dropdown list, instead of a list with checkboxes.

When use-competencies-single is used, the goal screen will change so only one competency can be selected.

The list of competencies that displays can be derived in many ways. See the configuration handbook for more details/information.

To use behaviors in this field instead of competencies, set the field-format tag (within the field-definition block) as follows: <Field-format>use-behaviors</ field-format>.

The competencies field will then list behaviors within their parent competencies. At this time, you cannot use the single-select option for behaviors.

The Development Plan template uses a set of specific competencies by adding filters inside the XML template. To include competencies from any of the following, you can add a <competency-filters> tag that defines the sources of competencies that the Development Plan will use. These are:

• Forms
• Roles
• Categories
• Libraries
• Exclude hidden competencies
• Exclude skills & questions

Below are some examples of the <competency-filters> tag:

123456
...
</default-category>
<competency-filters>
<exclude type="roles"/>
</competency-filters>
<field-definition ...

123456
...
</default-category>
<competency-filters>
<exclude type="forms"/>
</competency-filters>
<field-definition ...

1234567
...
</default-category>
<competency-filters>
<exclude type="forms"/>
<exclude type="hidden"/>
</competency-filters>
<field-definition ...

12345678
...
</default-category>
<competency-filters>
<exclude type="forms"/>
<exclude type="roles"/>
<include type="category" match="category name"/>
</competency-filters>
<field-definition ...

12345678
...
</default-category>
<competency-filters>
<exclude type="forms"/>
<exclude type="roles"/>
<include type="library" match="library name"/>
</competency-filters>
<field-definition ...

123456789
...
</default-category>
<competency-filters>
<exclude type="forms"/>
<exclude type="roles"/>
<include type="category" match="category name A"/>
<include type="category" match="category name B"/>
</competency-filters>
<field-definition ...

123456789
...
</default-category>
<competency-filters>
<exclude type="forms"/>
<exclude type="roles"/>
<exclude type="hidden"/>
<include type="category" match="category name" library="library name"/>
</competency-filters>
<field-definition ...