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 allow 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"

Note

Be sure to leave the obj-plan-id as is. If this is changed, an entirely new Development Plan will be uploaded. Development plan IDs are in the following range: 2000-2999.

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.

Note

Private goals can only be viewed by the roles permissioned to see private goals. When using proxy, you will not see another user's private goals. Privacy is controlled by XML permissions and can be set to allow any permissioned role to see private goals.

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.

Note

The instructions, as seen previously, can be edited via the Admin Center, but they can also be changed in XML. Instructions are the only text replacement option that can be completed through Admin Center.

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.

Note

Do not set the category ID to a number. Numbers are not intuitive when the customer is running reports. The category ID is case and space sensitive; using spaces is not recommended.

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:

<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.

Note

The reportable attribute must be included for reportability on several reports, including Ad hoc reports.

Note

Remember, adding custom fields can be completed in Admin Center, but reportability is an XML-only attribute. The above could be an example of first adding in Admin Center and then including the reportable attribute in XML.

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:

<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. For example, 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 click 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.

Note

Private access is an important and sometimes misunderstood concept. Privacy can mean different things to different people based on business context. So it is important to point out that private access can be granted to any role including the everyone (*) role. Typical configurations include access only to the employee (E) or access to the employee and employee's manager (EM). Private access configuration should be clearly communicated with employees to avoid any issues.

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.

Note

None is the default permission (users have no permissions until Read or Write are assigned), so normally a None permission would not be necessary.

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:

<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.

 < 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.

<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:

<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. Clicking on 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:

<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 drop-down 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.

Note

Search the objective-template DTD and the CDP Configuration Guide for more details on the <field-format> tag.

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:

Forms and Roles: No configuration

Forms

Note

There are some cases when custom competencies will not immediately appear as options to be selected using a competency browser. See the following KBA for more details: https://launchpad.support.sap.com/#/notes/2259810

Also see Wiki article: https://wiki.scn.sap.com/wiki/display/SAPSF/Development+Plan+-+Competency+Filters

Code snippet

Copy code

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

Expand

Roles

Code snippet

Copy code

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

Expand

Note

Hidden competencies are those competencies that have their status set to Hidden. This is set in each competency definition.

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

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

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

...
</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 ...

...
</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 ...