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 add the Metric/Measure of Success or Milestones fields? 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.

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. One of those features is whether the goal is set as private (only the user can see the goal) or public (users with the appropriate permissions can see the goal). The visibility of goals is controlled by the new-obj-share-status-public and use-text-for-privacy attributes.

• Private Access and Share Action Permissions will also impact whether the Visibility field can be edited or is read-only.

The figure illustrates the view for both the XML and the Create Development Goal screen after defaulting a goal to Private and enabling the Visibility field.

Text Replacement allows you to replace standard text for the "Instructions" attribute with custom text within the XML (note that the "I" at the beginning of the attribute is capitalized). If the instructions are not showing, choose the "Introduction" text on the Development Goal Plan Screen to toggle the text on and off.

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. You can search the DTD for the term "Text-Replacements" and you will find the list of options.

The figure below illustrates the XML code and the Development Plan view showing examples of XML-based text replacement.

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. After creating new categories you can delete the <default-category> element to control the order.
• 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>

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.

   The <field-definition> element is used to define each development goal field. You must define all fields that are to be used in the plan.

   All development goal plan templates come pre-populated with several configured development goal fields.

   You can make additions, remove, or edit these fields according to customer requirements. There are many fields that you can add to the development goal plan.

2. Permission the field.

   The <field-permission> section determines who can read (view) and write (edit) specific fields.

   For individual employee roles, fields can be hidden altogether with the none (no access) permission type.

3. Add the field to the Layout.

   The <plan-layout> section no longer determines the layout of the development goal plan screen, but it’s still necessary to add fields 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>

Fields in the goal plan are controlled by <field-definition> elements in XML. Each field has its own unique field definition and this, in turn, may have the following sub-elements and attributes.

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

Select the buttons to learn 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.

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 want the field to be a required field, change the required code. Required fields are indicated with an asterisk (*).

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

For clarity, avoid using DTD defined attributes like "type" or "id" as the literal values inside quotation marks. Doing so could cause confusion among developers and administrators.

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

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 (only custom fields need this attribute. All standard fields are reportable by default).

The figure below shows adding the custom field done (% complete).

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 creating goals or viewing private goals.

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.

The <field-permission> element defines who sees and edits fields in the goal plan. Permissions are based on the relationship between the employees in the organization. Field permissions can only be configured in the XML template, not in Manage Templates.

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 <field-permission> element consists of the following tags:

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 read or edit "metric" field because there is no permission for the "metric" field. The after example shows three permission blocks (highlighted in yellow). In this example: everyone can read the "metric" field, the roles E and EM can edit "metric", and the roles EM+ and EH can edit "comments".

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

With Latest Development Goal Plans, the plan layout does not actually impact the Development Plan screen. But at this time you need to have a plan layout in the XML file for it to validate and to upload the file in Provisioning. And the Plan Layout will be in any templates that you upgrade to LGM. The actual layout of the Latest Development Goal Plan screen cannot be changed.

As mentioned above, even though you can’t change the layout of the Latest Development Goal screen, at this time the Plan Layout XML needs to be in the template in order to validate the XML file. To edit the plan layout you would export the Development Plan XML to an XML editor, make any necessary changes, and upload the template to the instance.

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.

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 in the Development Goal Plan Template XML. The comments can be added, edited, or deleted after the goal has been added using the Goal Details screen.

The "competencies" field type links development goals to one or more competencies or attributes 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>Attributes</field-label>
    <field-description>Competencies</field-description>
    <field-format>use-competencies</field-format>

You can only have one "competencies" field per development plan, but you can have multiple skills or competencies added to a goal using that single field. And that "competencies" field can have a label of "Attributes" because both competencies and skills can be added to a goal.

To use behaviors in the Competencies 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.

Only the competencies that have behaviors are shown, and skills are no longer shown. You can select behaviors under the parent competency when creating a development goal. The competencies field then lists the selected behaviors.

If you had competencies and skills in a goal and you change the XML to use behaviors, all previous skills and competencies will be removed from the Competencies/Attributes field.

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