Configuring the Career Worksheet XML

After completing this lesson, you will be able to:

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

















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 analysis graph)
  • 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> <field-description></field-description> </field-definition> Expand

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.

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.

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.

With Development Plans the plan layout arranges the fields in the order they should be viewable on the Development Plan screen. 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 (thermometer) 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 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

The example from the previous section is as follows:

  • The target role requires six competencies, all with an expected rating of 3 (50%).

  • The user was rated a 5 (out of 5) on two out of the six competencies. Competencies that have not been rated do not satisfy the readiness requirement.

  • Based upon the readiness value calculation, the user is 2/6, or 33%, ready for the target role.

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

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.

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.

Configure Career Worksheet Features

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

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
  • Search for New Roles and display Suggested Roles


  1. Using an XML editor, open the latest version of your Career Worksheet template. It should be THR95 Career Worksheet [Your Name] v01.xml that you created in an earlier exercise.

    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

    The Career Worksheet XML can be validated with the same DTD file used to validate the development plan: objective-template_4_0.dtd.
  2. Configure the Last Rating field and the Readiness Meter field. In the Career Worksheet find the XML element <rating-scale-id> inside the last_rating field definition. Remove any alpha-numeric values and replace with the following value: THR95 1-5 Rating Scale. 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-label>Last Rating</field-label> <field-format>#.#</field-format> <rating-scale rate-on-form-option ="false"> <rating-scale-id>THR95 1-5 Rating Scale</rating-scale-id> </rating-scale> </field-definition> Expand
  3. Find the field definition code for development_goals and after that field definition, add a new line, and then enter the following code into the new line:

    Code snippet
    <field-definition id="readiness_meter" type="percent" required="true" detail="true" viewdefault="on" showlabel="false"><field-label>Readiness Meter</field-label></field-definition> Expand
  4. 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> <role-name><![CDATA[*]]></role-name> <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"/> </field-permission> Expand
  5. 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 and copy that code:

      Code snippet
      <column weight="0.0"> <field refid="development_goals"/></ column> Expand

      Paste the code and replace development goalswith readiness meter:

      Code snippet
      <column weight="0.0"> <field refid="readiness_meter"/> </column> Expand
  6. 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
      <switches> <switch for="new-role-readiness-calculation" value="on" /> </switches> Expand
      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 your form. 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 search for the following code:

      Code snippet
      <'--==========================================================--> <!-- Categories <NO Categories needed for Career Worksheet -­ ><!--=========================================================-->Expand

      After that code enter the following code:

      Code snippet
      <self-assessment> <each-assessment>123</each-assessment> <each-assessment lang="en US">l23</each-assessment> </self-assessment> Expand

      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.

  7. Validate your file and save it as a new version: THR95 Career Worksheet v02.xml.

  8. Import this file into Provisioning.

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

    2. Click 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. Click Save Changes.

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

    1. Open your 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 add the Marketing Manager role.

    2. Click the Evaluate Your Readiness link to launch a Role Readiness form for yourself. Rate yourself for 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 your Career Worksheet.

    3. Now that the form has been completed, observe the new readiness rating for the role you selected earlier. 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.

    4. Once you are finished testing forms, use Action Search to navigate to Delete Form. Select the radio button for Advanced Search and in the field for Form Template click the link for Select. Select the checkbox for THR95 Future Role Readiness Form Template and click Done to close that window. Then click the Search button and select and delete any forms that appear.

    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.

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 Admin CenterCompany SettingsManage Job Roles.

  2. Access the desired Family and Role.

  3. Click the link under the Expected Rating % column for the desired competency.

  4. Enter the Expected Rating percent.

    The system will compute the proper Expected Rating % (yellow highlight in the figure, Expected Ratings). Use the calculator to enter Lowest, Highest, and Expected Score).

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

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

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. Click the "+" icon.

  2. Click the Role Title for details.

Configure Suggested Roles

To learn how to configure Suggested Roles, watch this video:


  1. Navigate to Development and Career Worksheets page. Select Suggested Roles and observe the two roles that appear: Executive and Manager.

  2. Using Action Search navigate to Manage Suggested Roles.

  3. Observe the criteria for making role suggestions.

  4. Confirm that Common Job Family is selected and that it is 20% of the total score.

  5. Using Action Search navigate to Manage Job Roles and notice there are two Job Families: Extended job profiles and SuccessFactors.

  6. Open the SuccessFactors Family and notice two of the roles listed match what was seen on the Suggested Roles page (Executive and Manager).

  7. Click on the All Families link in the click path at the top of the page to return to the list of families.

  8. Open the Extended Job Profiles Family and search for the Administrator role. Open that role and take note of the Job Code: Administrator. In this particular case the role name and job code match.

  9. Navigate to Manage Users, select your user and in the Job Code field change it from IC (Individual Contributor) to Administrator (Administrator). You can type in the first few letters in the field to get suggestions and then you must click on the selection you want to make it turn yellow. Click on Save to save your changes.

  10. Navigate to Development and Career Worksheets page. Select Suggested Roles and note the list of roles is different and substantially longer. The change of Job Code for your user changed its mapping to the role of Administrator, which is in the SuccessFactors family. And since that family only has 2 roles and your user is in the Manager role now, you only see one suggested role.

  11. Navigate to Manage Users, select your user and in the Job Code field change it from Administrator (Administrator) back to IC (Individual Contributor). You can type in the first few letters in the field to get suggestions and then you must click on the selection you want to make it turn yellow. Click on Save to save your changes.

  12. Navigate to Development and Career Worksheets page. Select Suggested Roles and note the list of roles is back to what is was before (Executive and Manager).

  13. In a future exercise, you will create a career path and that can be used to alter the Suggested Roles results as well.

Log in to track your progress & complete quizzes