Configuring the Career Worksheet XML


After completing this lesson, you will be able to:

  • Configure fields in the Career Worksheet XML
  • Set up field permissions and the plan layout in a Career Worksheet template
  • Utilize the Readiness Meter
  • Calculate options for Career Role Readiness
  • Attach Role Readiness forms to the Career Worksheet for future roles
  • Configure the Career Worksheet Gap Graph
  • Display Development Goals in the Career Worksheet
  • Manage Suggested Roles

Configuration of Fields in the Career Worksheet XML

There are seven available standard fields to include in the Career Worksheet, listed in the table below. All field configurations are done through Provisioning in XML, giving you full configuration control. Career Worksheet template configuration is not available in Admin Center.

V12 Features - Overview

Number on Screen
























Custom fields cannot be used and are not available in the Career Worksheet V12.

All fields will have a label, a field ID, and a field type. Labels can be localized to any language you have enabled in the system. Configurable items for the standard fields are as follows:

  • Field Label Modifications.
  • Inclusion or Exclusion of Fields (For example, you can remove the gap_graph field if you don't want to include the gap graph analysis).
  • Rating-scale-id in the last_rating field definition (This is the normalized scale used for displaying rating comparisons).
  • Permissions for functions and fields.
  • Maximum number of roles that a user can add, with the max-per-category attribute (recommended max: 20).
  • Instructions for top of page, with the text-replacement tag.

The Career Worksheet template has the same Attributes and Elements as the Development Plan template because they share the same objective-template_4_0.dtd file. Therefore, element and attribute configuration are syntactically the same. Details such as field IDs can be different.

Adding new fields through Provisioning using XML follows a three-step process:

  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 competency_name field that we can break down to see the various attributes.

Code snippet

<field-definition id="competency_name" type="text" 
required="true" detail="false" viewdefault="on" showlabel="false" 
field-show-coaching-advisor="false" cascade-update="push-down">
    <field-label>Required Competencies</field-label>

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.

Field Permissions and Plan Layout Setup

Set up Action and Field Permissions

In addition to configuring fields on the Career Worksheet, the customer needs to decide which business roles can work with the worksheet. Career Worksheet permissions are different than Role-Based Permissions, but both are used to grant access to users.

Role-Based Permissions allow access to the Career Worksheet. Once users have access to the worksheet, all other permissions are governed by the XML plan permissions.

Action Permissions

Action permissions define the roles that have the ability to perform specific actions on a career worksheet, such as adding or viewing roles.

The only Access permissions available for Career Worksheets are Private access, Create, and Delete.

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.

Field Permissions

In order for fields to be visible or editable, Field permissions must be put in place.

The Field permissions available for Career Worksheets are as follows:

  • Read - the user with Read permission can see, but not edit the field.
  • None - the user cannot see (or edit) the field at all.
None is the default permission (users have no permissions until Read or Write are assigned), so normally a None permission would not be necessary.

Additional information about Action and Field permissions are available in the Development Goal Plan Unit.

Edit the Plan Layout

After you have configured and permissioned fields, the next step is to decide which fields should be placed on the plan layout.

For Career Worksheets, the plan layout does not actually impact the Career Worksheet screen, but you must have a plan layout in the XML file for it to validate and to upload the file in Provisioning. The layout of the Career Worksheet screen cannot be changed.

Readiness Meter Utilization

Utilizing the Readiness Meter

The Career Worksheet V12 includes a Readiness Meter for future roles (Job Roles I'm Considering).

The Readiness Meter is optional. To include it, make sure this field is defined in your template and referenced in the field-permissions and plan-layout.

A role within Job Roles I’m Considering is also commonly referred to as a Future Role or Target Role.

The Role Readiness score is calculated as a percentage based on the number of competencies met for a future role against the total number of competencies/attributes required for that role. A competency that is met is worth a full point and each competency not met is worth zero.

The readiness value is calculated as A/B where this criterion is used as shown in the table Readiness Criteria.

Readiness Criteria



Number of competencies I have been rated on and where my rating meets or exceeds the expected rating for the target role


Number of competencies required for the target role

If you have Job Profile Builder enabled, you can access the full Role Details directly from the Readiness Meter of the Career Worksheet. Just hover over the "i" in the header of the role, and the details will open. The role details can be printed, but not edited, from the Career Worksheet.

Calculation options for Career Role Readiness

Customers can choose a proportional calculation in which each competency rating is weighted as a percentage of the expected rating. A role readiness score calculated proportionally could more accurately show how close a user is to full readiness for a role.

A switch has to be included in the Career Worksheet XML template configuration for the proportional calculation. Switches are used to enable or disable features in a Career Worksheet template and would be placed after the <obj-plan-due> in the XML (code placement does matter). The switch shown in the screen below can be used to enable the new role readiness calculation.

Depending on whether the new calculation option is used or not, the role readiness result can be very different.


Expected Rating

Employee Rating

Old Score

New Score

Competency 1





Competency 2





Competency 3





Competency 4





Competency 5





Competency 6








Role Readiness Form Attached to the Career Worksheet

To attach a Role Readiness form to the Career Worksheet, the following XML element needs to be added to your Career Worksheet template: <self-assessment>. It gets placed after the text-replacement section and before the first <field­-definition>.

The screen above shows two samples of the code. The code in red has not had the form IDs entered yet, but it shows where in the XML the code would be placed. The second code sample shows that form ID 22 will be launched for US users and form ID 23 will be launched for French Canadian users, demonstrating that you can launch different Role Readiness forms for different locales.

To locate the form template ID, go to Form Template Administration within Provisioning. Once you find your Role Readiness form listed in the Template Name list, the form ID is in the Type ID column.

To learn more about the Role Readiness Form ID, watch this video:

The form must be permissioned for the employee to create and self-assess. When properly coded and permissioned, the user will see a link to the form for Job Roles I'm Considering.

Role Readiness Evaluate Your Readiness

The form will be created, and the user will be taken directly to the form, bypassing the usual form creation steps. When the form launched for a particular role is in progress, the system will tell the user, as shown in the figure.

Once the form is complete, the updated ratings will be used on the Career Worksheet, and the display will once again allow a role readiness form to be launched. Users can launch Role Readiness forms again for the same role, as many times as they want.

  • It is critical that customers have a complete understanding of how the Career Worksheet and other parts of the system handle competency ratings of record before implementing this feature.
  • The latest rating of record from any form is the one used on the Career Worksheet (assuming assessment filters are not included - new ratings eclipse old ones).
  • Competency ratings are not differentiated by role (that is, a rating of 5 on Communications will apply to both my current role and a future role, if they share that competency).
  • Some functions can differentiate ratings by form, such as Dashboards, List Views, the Employee Scorecard, and Live Profile.
  • Other functions, however, cannot differentiate by form. These include the Career Worksheet, Talent Search, and Side-by-Side Comparison.

Recommended Configuration

Therefore, even though the system will allow a variety of form configurations, the following configuration is strongly recommended:

  • Do not calculate an overall performance rating with this form.
  • Route the form to a manager for a final manual rating (do not rely on the employee to enter a rating of record). The route map should be EEMComplete.
  • Exclude this form from Dashboard processes used for current performance reporting.
  • Make sure succession planners understand that this form could provide competency ratings that override the last performance review.

Alternate configurations may not be supported and should be deployed with extreme care.

Form Title With Or Without the Role Name

There are two different ways to have form names displayed. One option supports translations, and one does not. The option that does not include translations does allow the future role name to be included.

These settings are controlled in Company System and Logo Settings and impact all Performance Management forms including Role Readiness forms. For this reason, Performance Management consultants and CDP consultants will need to coordinate their form settings.

Configure the Role Readiness Link for the Current Role

Users can also launch Role Assessment forms for their current roles directly in the Career Worksheet. In order to create this link to the current role, you will need to place the following switch code into the XML of the Career Worksheet. Sample code is below:

After adding the switch code, add the following <current-self-assessment> code after the closing tag of the <self­-assessment> code as seen below:

Be sure to replace the number in the code (i.e. 764) with the desired form template ID. To locate the form template ID, follow the same procedure you used for the future role readiness assessment. Once you’ve entered the code and uploaded your template, you should be able to see the additional link in the current role.

Competency Rating Source

The default behavior is for the rating on the Career Worksheet to come from the last-rated and last-completed form (Role Readiness form, Performance Review form, whichever form was last completed).

It is possible to identify a specific form or a number of forms as the only source of existing ratings. For example, customers might not want performance reviews to be considered for ratings on the Career Worksheet. That form ID would NOT be included in the code below.

Data Source Filter

The above figure shows an example of the code to add in red (placed right before the first field-definition). This code is specifying exactly which forms to be used, by Form ID, for competency ratings on the Career Worksheet.

If you need to delete the completed Role Readiness forms and start over, use Action Search to navigate to Delete Form. Select the radio button for Advanced Search and in the field for Form Template choose the link for Select. Select the checkbox for THR95 Future Role Readiness Form Template and choose Done to close that window. Then choose Search and select and delete any forms that appear.

Configure Career Worksheet Features

To learn how to complete this exercise, watch this video:

Practice configuring Career Worksheet Features:

Business Example

As a consultant, you are asked to configure Career Worksheet features.

Upon completion of this exercise, you will be able to configure Career Worksheet features:

  • Export and check the Career Worksheet XML
  • Set up Expected Ratings for the Gap Graph
  • Configure the Readiness Meter


  1. Export the latest version of the Career Worksheet XML template from Provisioning.

    1. Navigate to Provisioning and select your Company ID. Navigate to Managing Plan Template and select Import/Update/Export Career Worksheet Templates.

    2. Export the latest version of the THR95 Career Worksheet template using the red arrow on the right side of the screen.

    3. Open the template in your preferred XML Editor and save the file to a new name and version. You should put the file in the same location as the Development Plan templates, which has the DTD file.

  2. Verify that the file has the following six field definitions in the Field Definitions section of the file:

    • competency_name

    • last_rated_form

    • last_rated_date

    • last_rating

    • gap_graph

    • development_goals

  3. Configure the Last Rating field. In the Career Worksheet find the XML element <rating-scale-id> inside the last_rating field definition. Enter the following value: THR95 1-5 Rating Scale in place of "Add rating scale reference here." Be sure to match case, spelling, and spacing for the name of the rating scale. The completed code will look like this:

    Code snippet
      <field-definition id="last_rating" type="number" required="true" detail="true" viewdefault="on" showlabel="false" field-show-coaching-advisor="false" cascade-update="push-down">
        <field-label>Last Rating</field-label>
        <rating-scale rate-on-form-option="false" default="true">
         <rating-scale-id>THR95 1-5 Rating Scale</rating-scale-id>
  4. Find the field definition code for development_goals and after that field definition, add a new line to have enough space to enter the following Readiness Meter field definition code (you may need to remove some carriage returns to validate the file):

    Code snippet
      <field-definition id="readiness_meter" type="percent" required="true" detail="true" viewdefault="on" showlabel="false" field-show-coaching-advisor="false" cascade-update="push-down">
        <field-label>Readiness Meter</field-label>
  5. Find the code for field permissions that are set to type read: <field-permission type="read">. Inside that field add a reference to the new readiness_meter field: <field refid="readiness_meter"/>. The completed field permission section should give read access to everyone for all seven fields and it should look like this:

    Code snippet
    <field-permission type="read">
    <description><![CDATA[The following roles may read the following fields.]]></description>
    <field refid="competency_name"/>
    <field refid="last_rated_form"/>
    <field refid="last_rated_date"/>
    <field refid="last_rating"/>
    <field refid="gap_graph"/>
    <field refid="development_goals"/>
    <field refid="readiness_meter"/>
  6. Add the new readiness_meter field to the plan layout. 

    1. Find the <plan-layout> section of the file and verify that there are six field references with the format <field refid="example_field">. Each field refid element is contained within a column element. Find the last column element that contains the reference to development_goals. Copy the code below, and paste it after the column info for development_goals.

      Code snippet
      <column weight="0.0"> <field refid="readiness_meter"/> 
  7. Configure the calculation option for role readiness and add a reference to the Role Readiness form. 

    1. In your Career Worksheet find the code for <obj-plan-due>12/31/2030</obj­ plan-due> and right after that, add the switch to allow a role readiness calculation that gives partial readiness credit for competencies that are below the expected rating for that role:

      Code snippet
      <obj-plan-due>12/31/2030</obj- plan-due>
      <switches> <switch for="new-role-readiness-calculation" value="on" /> </switches>
      <text-replacement for="Instructions">
      The alternative approach is to only give credit if a user has met the expected rating for a particular competency (all or nothing approach).
    2. Add the code to reference the Role Readiness form. To do this, you must find the ID of your THR95 Role Readiness Evaluation form template. This ID is not contained in the XML of the form template. You must navigate to Provisioning and under your Company, search for Form Template Administration. Inside Form Template Administration look for the THR95 Future Role Readiness Form Template. It should have the highest ID number in the list since it was the most recently created form. Copy the form ID. Return to your Career Worksheet and add the following code before the <field-definition> section:

      Code snippet
      <each-assessment lang="en_US">l23</each-assessment>
      <field-definition id="competency_name" type="text" required="true" detail="false" viewdefault="on" showlabel="false">

      Replace 123 with the form ID you copied earlier on both lines where 123 appears. Depending on the number of languages you are using, you may have to enter the ID several times on successive lines.

  8. Validate your file and save it as a new version.

  9. Import this file into Provisioning.

    1. In Provisioning navigate to your Company Instance and then to Import/Update/Export Career Worksheet Templates. 

    2. Choose Choose File, select your Career Worksheet, and under description of changes enter a meaningful description such as Added readiness meter and role readiness form.

    3. Choose Upload.

  10. Log into the instance to test the changes made.

    1. Navigate to Development using the Main Menu, open the Career Worksheet, and make sure you have a role added under Job Roles I’m Considering. If no roles have been selected yet, go to Browse Roles and select a role.

    2. Select the Evaluate Your Readiness link to launch a Role Readiness form. Rate each competency using between 3 and 5 stars. Finalize the form and send it to the next step which will complete the form. Close the form window and return to the Career Worksheet.

    3. Now that the form has been completed, observe the new readiness rating for the role you selected earlier  (you may need to refresh your browser for the ratings to show). You can launch another form and repeat this process as often as necessary. You can also modify the route map and include a manager in the rating process which is a leading practice.

    Whenever you rate a user against a new role, the competencies from that role and their ratings are stored for that user. Those competency ratings can impact which other future roles may be suggested to that user if those same competencies are mapped to other roles.
    Saving and uploading version 2 will allow you to easily revert if needed in the future, since the system will retain those versions. You can also view the audit history which is much more useful if you set meaningful descriptions each time you upload a new version.
  11. Delete extra Role Readiness Forms if you’ve run the evaluation multiple times.

    1. Using Action Search, navigate to Delete Form.

    2. Choose Select…next to the Form Template field.

    3. Find the name of the Form Template you’ve been using (THR95 Future Role Readiness Form Template) and select it.

    4. Choose Done. You’ll return to the Search screen.

    5. Choose Search.

    6. A list of forms matching the criteria that was entered will appear. Select the forms you wish to delete and choose Delete.

    7. Choose Yes to confirm you wish to delete the form(s).

Career Worksheet Gap Graph Configuration

The Career Worksheet has the ability to populate the Gap Graph. This is a graph depicting the gap between a competency rating and the expected rating. In the figure, the rating exceeds the expectation, so the competency has been "met."

To make sure that the gap graph shows on the Career Worksheet, it is important that the last_rating field in the XML points to an existing rating scale in Admin Center. In the XML, the syntax MUST be exactly the same as the name of the rating scale in Admin Center. This reference to a valid rating scale is also a condition for the Readiness Meter.

Ratings come from completed Performance Management (PM) forms, 360 forms, or a modified PM form called the Role Readiness form. The last rating will be used in the Career Worksheet; no averaging is supported at this time.

Gaps are calculated using the Expected Rating set up in Admin CenterCompany SettingsFamilies & Roles and the last rating from the form mentioned in the figure.

To configure Expected Ratings, complete the following steps:

  1. Navigate to Manage Job Profile Content (with JPB) or Manage Job Roles (with JDM).

  2. Access the desired Family and Role.

  3. Edit the Expected Rating.

    1. With JPB, select the Mapped Competencies tab, then choose the calculator next to the rating.
    2. With JDM, choose the Expected Rating % number for the desired competency.
  4. Enter the Expected Rating percent.

    Enter the Lowest, Highest, and Expected scores to have the system compute the proper Expected Rating %.

  5. Choose Save Edits.

  1. Expected Ratings can also be imported through Admin CenterCompany SettingsImport Job Roles. You can first export your roles from the Manage Job Roles page to get the correct file format.

  2. Since expected ratings can vary by role, the same competency might show different gap values for different roles. For example, an employee might have a positive competency gap for the current role, but when evaluating a role with higher expectations, the same competency might show a negative gap.

Development Goals in the Career Worksheet

Displaying Development Goals

Development goal information can be included within the Career Worksheet to help users work toward their future roles. The development goals are populated and linked to a competency on the development goal plan.

To add the ability to link development goals to the Career Worksheet, you’ll need to add a line of XML code after the text replacement section:

<behaviors hide="true" hide-ratings="true" use-in-readiness="false"/>

Once the code has been added to the XML, based on the competencies for the role, you’ll see if any development goals have been added for those competencies. The plus sign (+) gives you the ability to add new development goals linked to that competency.

Other configurations must be made as follows:

  • The Read and Write permissions for the user are derived from the Development Plan template configuration.

  • The link to add development goals always adds goals to the default development plan.

  • The development plan must include a Competencies field, which links development goals to specific competencies. Since a goal can be linked to more than one competency, the same goal may be counted more than once in the Career Worksheet. The same goal can also be represented in more than one job role.

Suggested Roles Management

Role Search in Suggested Roles

Users can add roles to their Career Worksheet using a Role search in addition to browsing the Family and Role library.

All users will have access to the Role search in the search bar. Simply start typing the Role name and the autocomplete search will suggest appropriate matches.

Choose the role name to add it to your worksheet.

Manage Suggested Roles

Customers also have an option to enable a Suggested Roles tab. This tab proactively suggests roles to the user.

Manage Suggested Roles

The Suggested Roles are based on a formula that combines the following attributes selected in Admin CenterDevelopmentManage Suggested Roles:

  • Competency Association

  • Common Job Family

  • Open Positions

  • Proximity of role in career path

  • Peer popularity

  • Filters

Utilizing Suggested Roles

When utilizing the Suggested Roles tab as an end user, competencies are weighed the most. Thereby roles with significant competency matches will most likely surface to the top of the list.

To add roles from the Suggested Roles tab to the Career Worksheet V12, complete the following steps:

  1. Choose the "+" icon.

  2. Select the Role Title for details.

Log in to track your progress & complete quizzes