pear on-boarding guide

PEAR On-Boarding Guide

Business Solutions Center of Excellence


Version 1.12

OA/OIT


Revision HistoryDate Version Description Author

06/13/2007 1.0 Initial Creation. Deloitte

09/07/2007 1.1 Removed Administration content. Rae-Ann Ginter

09/19/2007 1.2 Removed visibility information. Updated Reporting section.

Rae-Ann Ginter

10/25/2007 1.3 Updated Project Manager, CoE information. Included information regarding Asset Views and examples of group and project structures.

Rae-Ann Ginter

11/1/2007 1.4 Minor editorial changes. Julie Lobur

11/1/2007 1.5 Update table of contents. Rae-Ann Ginter

11/9/2007 1.6 Updated the Figure 3 diagram. Link was not working. Updated PEAR roles diagram to include Project User. Updated report definitions. Updated Contact Information to include remedy.

Rae-Ann Ginter

11/20/2007 1.7 Updated the name of the visibility classifier to “Certification Level”. Diagrams and text need to reflect this change. Included new functionality documentation regarding CoE asset deletion approvals for deletion of assets with “Agency” Certification Level.

Rae-Ann Ginter

12/5/2007 1.8 Updated Page 8 para 2 & 4. Updated Page 13 removing the requirement of a request slip with group/project diagram.

Rae-Ann Ginter

12/6/2007 1.9 Asset deletion diagram Figure 5 and description page 12.

Rae-Ann Ginter

4/11/2008 1.10 Asset Owner governance updated and new consumer role added. Updated sections 2, 2.1, 2.2.1, 4.1.1, 4.2.

Rae-Ann Ginter

4/30/2008 1.11 Added Figure and Table captions. Created links to document properties. Numerous editorial changes.

Joe King

OA/OIT


5/22/2008 1.12 Removed Note from section 2.2. Adjusted paragraph 3 & 7 under figure 2. Adjusted paragraph 1 under figure 4. Adjusted paragraph 1 under figure 5.

Rae-Ann Ginter

OA/OIT


Table of Contents

1. Introduction 4

2. PEAR Roles 5

2.1 Agency Level PEAR Roles 5

2.2 Enterprise Level PEAR Roles 6

3. PEAR Organizational Structure 7

4. Default PEAR Processes 10

4.1 Asset Submission 10

4.2 Asset Acquisition 14

4.3 Asset Deletion 12

5. Agency On-Boarding 16

5.1 Define Base Organizational Structure 16

5.2 User Creation 16

6. Contact Information 16

OA/OIT



1. Introduction

1.1 Purpose

This document is intended to guide Commonwealth of Pennsylvania (“Commonwealth”) agency technical personnel through the process of establishing organizational processes and procedures in the initial use of the Pennsylvania Enterprise Asset Repository (PEAR). We will hereafter refer to this process as agency on-boarding. Agency on-boarding includes defining user roles, understanding the PEAR organizational hierarchy and governance, and then effectively assigning roles and organizing the agency’s user groups and projects within PEAR.

1.2 Scope

This document applies to all Commonwealth agencies desiring to use PEAR.

1.3 Overview

PEAR was designed to make software assets readily available to software developers and policy makers. This document first defines PEAR roles and processes. Then, after describing how agencies set up an organizational structure within PEAR, the document explains how to configure roles and processes to make assets available to the appropriate users.

2. PEAR Roles

PEAR users are formally assigned to roles, which confer authority to perform specific processes. A single user may be assigned multiple roles in different groups or projects. A PEAR group comprises a number of PEAR users–normally within a single agency. A PEAR project comprises PEAR users assigned to a specific project that may involve several agencies. This section defines PEAR roles so that agencies can effectively assign them.

Inheritance is an important feature of PEAR roles. An agency can configure its PEAR hierarchy into various levels of authority (see Appendix A and Figure 2). A role grants authority not only at the user’s assigned organizational level, but also, by inheritance, for each group and project below that level in the organizational hierarchy. The exceptions are Project Managers, whose roles encompass only projects.

OA/OIT


Table 1 ties user roles to the processes with which each role may be involved. For a given process, a user’s participation is required (yellow icon), optional (red icon), or unnecessary (no icon), depending on the user’s role. Click the table’s hyperlinks for detailed descriptions of the processes; here are brief definitions:

Submission. Adding an asset to the PEAR repository.

Acquisition. Downloading a PEAR asset from the repository for use within a project.

Deletion. Permanently eliminating a PEAR asset from the repository.

Role

Agency Level Roles Enterprise Level Roles

Pro

cess

Consumer ACE Asset

Owner

Project

Manager

CoE Enterprise

Architect

Repository

Administrator

Publisher

Submission

Acquisition

Deletion

Table 1. Roles and Processes

Required

Optional

Note: Users accessing PEAR from outside the formal on-boarding process have no roles assigned to them, and thus can view only Enterprise-level assets.

2.1 Agency Level PEAR Roles

Project User. Project User is not listed in Table 1 because the role does not pertain to any single process. A Project User may, however, collaborate on a project.

Consumer. The Consumer role functions at the project level. A Consumer can search for assets and acquire them, but cannot contribute assets or approve them. Consumers are assigned to projects so they can collaborate with project members and acquire assets on behalf of a project (see Figure 5).

OA/OIT


Asset Capture Engineer (ACE). An ACE can contribute (submit) assets on behalf of his or her group or project. For example, an ACE for the BSCoE group can submit assets on BSCoE group’s behalf. Similarly, an ACE for a project in the library can submit assets on that project’s behalf. A user can be an ACE for several projects or groups at the same time.

The ACE role is inherited by child groups from parent groups (inheritance of roles is explained in Section 3). During the asset creation process, the ACE designates the group that will own a submitted asset; thereafter, the asset can be edited only by ACEs of the owning group.

Note: ACEs can submit assets on behalf of peer-level groups and projects and they can reassign asset ownership among peer-level groups and projects. We advise against these practices, because an ACE who submits an asset on behalf of a peer-level group or project will not be able to edit that asset.

Asset Owner. If an ACE submits an asset with the Asset Owner Approval Required classifier set to “True,” then any user request to acquire that asset is forwarded to, and must be approved by, the Asset Owner. An Asset Owner can approve or reject acquisition requests for any asset that belongs to a project or group for which he or she is an Asset Owner. For example, an Asset Owner at the BSCoE group level can approve asset acquisition requests for any asset owned by the BSCoE group.

Like the ACE role, the Asset Owner role is inherited by child groups from parent groups. A group-level Asset Owner has the Asset Owner role for any groups or projects that are children of that level, and will receive acquisition requests for assets from all of those levels.

Project Manager. A Project Manager (PM) is responsible for assigning and managing PEAR roles. A PM can add any user to a project if the user already has a PEAR account; however, such actions may compromise the agency’s user roles document (see Appendix B) and are not recommended. Project Managers must inform the PEAR administrator ([email protected]) of all role changes.

Depending on a project’s configuration, a Project Manager may be required to approve asset acquisition requests before they are forwarded to the Asset Owner.

Center of Excellence (CoE). The CoE is the first-level approval authority for assets submitted to the PEAR library. If an asset’s Certification Level classifier is set to "Agency," CoE approval is the only step in the approval process. The CoE’s approval adds the asset to the PEAR library; disapproval rejects the asset and ends the process. If an asset’s Certification Level classifier is set to "Enterprise," both the CoE and the Enterprise-level approving authorities must approve the asset.

Like other PEAR roles, the CoE role is inherited from parent groups by child groups. A group-level CoE has by default the CoE role for any groups or projects that are children of that level, and will be notified of submission requests for subordinate-level assets.

A CoE can also approve or reject asset deletion requests for assets with an “Agency” Certification Level.

OA/OIT

mailto:[email protected]


Note: the PEAR CoE role is not the same as the Local Center of Excellence (LCoE), a liaison between BSCoE and the LCoE’s agency.

2.2 Enterprise Level PEAR Roles

Enterprise Architect. For assets submitted to the PEAR library with the Certification Level classifier set to "Enterprise," the asset must first be approved by the CoE. Upon approval by the CoE, the asset goes to the Enterprise Architect, who initiates an approval process culminating in Enterprise Architecture Standards Committee (EASC) and BSCoE Asset Review Team (BART) review and approval (see Appendix C). Upon approval, the Enterprise Architect adds the asset to the library; disapproval ends the process.

Repository Administrator. The Repository Administrator (RA) is the approval authority for deletion of assets that have a Certification Level of “Enterprise.”

The RA role is inherited by child groups from parent groups. A group level RA has the RA role for all groups or projects that are children of that level, and will be notified of deletion requests for assets at and below the RA’s assigned level.

Publisher. Publisher is a very important role that should be assigned with great care. A group’s Publisher can allow users to edit the published information for assets owned by that group. For a given asset, publishers can 1) change the owning group, 2) change the cross-charge amount, 3) decide whether to notify the Asset Owner during asset acquisition, and 4) decide whether to require Asset Owner authorization for acquisition requests. Publishers can add contacts to an asset and declare whether an asset’s artifacts are public or private. (In most cases, Publishers will only become involved with public or private artifact, cross charge, and Asset Owner notification determinations.)

2.2.1 Reports

Users accessing PEAR through uncontrolled access, that is, users not formally on-boarded, have their reporting group set to Enterprise by default. Thus, they cannot access PEAR reports.

Formally on-boarded users, on the other hand, can access PEAR’s SQL Server reports. An on-boarded user can generate reports based either on Enterprise data or on subsets of data associated with the user’s reporting group and its subgroups.

Here are the reports that on-boarded users can access:

Asset Metrics Lists all acquisitions of and subscriptions to a particular asset. Acquisition Information specifies the asset’s associated project and its project manager. Subscription Information lists all users that have subscribed to the asset.

Governance Monitoring

Lists completed and active approval requests (submission, acquisition, and deletion) that have been submitted over a specified time period.

OA/OIT


Group Metrics

Lists all owned and acquired assets for a specified group, project, or Enterprise. Acquisition Information lists an asset’s name and type, and the agency from whom it was acquired.

Repository Savings

Lists the total Return On Investment (ROI) and time savings estimate for each asset that has been acquired at least once during a specified time period. It can also provide a total ROI and time savings estimate for the entire Enterprise for that same time period.

Search Analysis

Specifies the parameters for all unsuccessful searches across the Enterprise over a specified time period.

Stale Assets Lists assets that have not been acquired by any group, project, or Enterprise over a specified time period.

Success Metrics

Measures the following success criteria: number of assets contributed, number of projects reusing assets, and ratio of successful searches across a group, project, or Enterprise over a specified time period.

User Assignments

Lists all registered users and their roles for a group, project, or Enterprise.

What's Hot Lists assets that have the most registered acquisitions across a group, project, or Enterprise over a specified time period.

What’s New Lists new assets that have been published across a group, project, or Enterprise over a specified time period.

3. PEAR Organizational Structure

PEAR’s “single library” approach means that its organizational configuration defines what a user can and cannot do. In the single library structure, each agency represents an organizational group that contains varying numbers of groups and projects (see Appendix A). (Note the difference between the terms: groups are subsets of the organizational group.) Every organizational group is in turn a child of the PEAR Enterprise group.

An agency can configure its organizational group however it chooses, remaining unaffected by any other agency’s configuration. The only relationship between agencies is that they all belong to the Enterprise group (Figure 1) and that they are all part of the same content library:

OA/OIT


Figure 1. PEAR Enterprise Structure

Figure 2 depicts how an agency might structure itself within its organizational group. “Rounded” rectangles represent projects. Standard rectangles represent groups or agencies:

Figure 2. Organizational Group Example

In Figure 2, the entire flowchart comprises an organizational group–normally, an entire agency such as the Department of Public Welfare (DPW). Within an

OA/OIT


organizational group, individual groups are created to organize asset ownership, and projects are created to organize asset consumption–both are important for metric definition and the governance process.

The rectangle labeled “Agency A” in Figure 2 represents the highest level of an agency–DPW in our example–logically. Because of PEAR’s inheritance property, a user assigned a role in Agency A will have that role for all subordinate levels; that is, for the entire organizational group.

An agency can classify assets as Agency Only assets; these assets can be accessed only by users assigned to that agency.

Within a group or project, an agency can assign users to any of the roles defined in Section 2, the only requirement being that each project must have a Project Manager.

The following examples, based on Figure 2, demonstrate how a user’s role and organizational level affect what the user can do:

A user can have roles in more than one group or project. For example, consider an ACE for Projects R and T. When that ACE creates an asset, he or she can contribute it on behalf of either Project R or Project T.

A user with the ACE role for Group Z submits an asset on behalf of Project R. CoEs assigned to Group Z, Group W, and Agency A are notified that an asset awaits their approval; any of them can approve the asset.

A user in Project R requests to acquire an asset that was created in Project T. Depending on how the project is configured (see Section 4.2), the request may require Project Manager approval. If Project Manager approval is not required, Asset Owners for Project T, Group X, or Agency A can approve the request.

While not all-encompassing, the above examples represent the most common transactions.

OA/OIT


4. Default PEAR Processes

This section describes the three default PEAR processes: Asset Submission, Asset Acquisition, and Asset Deletion.

4.1 Asset Submission

In PEAR, Asset Submission means more than just offering an asset for inclusion in the repository; except for Asset Deletion, any change to an existing asset must undergo the formal Asset Submission process. For example, to retire an asset you follow the submission process (Figure 3), not the deletion process (Figure 6). Any change to an asset’s life-cycle status is considered an asset edit, and therefore must undergo the submission process before the change can be published.

Only ACEs can submit assets on behalf of a group or project. Upon submission, internal governance occurs: PEAR initiates a one- or two-step approval process depending on the asset’s Certification Level classifier. If an ACE assigns an asset a Certification Level of Agency, the agency CoE must approve it. If an ACE assigns the asset a Certification Level of Enterprise, both the CoE and the Enterprise-level approval authorities must approve it.

4.1.1 Asset Views

Upon approval, an asset enters the appropriate Publish Template (Figure 4)–a set of formal instructions that determines where in the library the asset gets published, and therefore who can access it. The asset’s owning group dictates where the asset gets published–whether within the agency or across the Enterprise.

Publish Templates work in concert with Asset Views to restrict access to assets. By default, assets are published across the Enterprise. Therefore, BSCoE recommends that each agency create at least one Agency Only group (naming it, for example, “[agency name]_Only”) when first configuring its PEAR organizational structure. If the agency determines that an asset should not be shared across the Enterprise, it can assign it to an Agency Only group which directs it to the Agency publish template and then to the Agency Only asset view.

PEAR views are managed at the Enterprise level. The Enterprise asset view is associated with the Enterprise group. Unlike assets with an Agency Only asset view, assets with an Enterprise asset view are accessible across the Enterprise despite their association with a particular agency. Since each agency is a child of the Enterprise Group, a user can access the asset either through the Enterprise asset view or the user’s Agency asset view.

Note: agencies can configure PEAR to publish assets to particular views by default.

OA/OIT


Figure 3. Asset Submission Process

OA/OIT


Figure 4. "Publish" Templates

The organizational level at which the CoE and Enterprise Architect roles are assigned affects how an agency approves assets. The CoE role can be assigned at any level in an agency’s hierarchy; however, if an agency wants to centralize its approval authority, it should assign the CoE role at the highest agency level. Because of the inheritance property of roles, that CoE can then approve or reject any agency asset. If an agency wants to decentralize approval authority, it can assign the CoE role at the group or project level. Finally, an agency can configure itself as a combination of centralized and decentralized authority if this approach best meets its needs. (See Section 3 for organizational structure details.)

While the CoE role can function at any level, the Enterprise Architect role is assigned only at the Enterprise Group level. The Enterprise Architect does not receive assets with the Certification Level classifier set to agency since those assets are “contained” within an agency.

Assets with the Certification Level classifier set to Enterprise must be approved at agency CoE level before reaching the Enterprise Architect level. The Enterprise Architect then submits the asset for review by the Enterprise Architecture Standards Committee (EASC) and by the BSCoE Asset Review Team (BART) (see Appendix C).

OA/OIT


Note: An asset’s Certification Level classifier does not determine where the asset is published; by default, all assets are published to the Enterprise. To publish an asset only to your agency, you need to define an Agency Only group and create the asset there. (See Section 4.1)

4.2 Asset Acquisition

The asset acquisition governance depends on both the project configuration and the asset’s classifier settings. Only users with the “Consumer” role for a project may acquire assets for that project.

Figure 5. Asset Acquisition Process

OA/OIT


Only projects should acquire assets. An asset acquired for a project is available to all individuals attached to that project. Projects can be configured to require project manager approval for acquisition requests. If approval is required, the project manager must approve the request before it is sent to the appropriate Asset Owner.

Note: If you belong to several projects, you may acquire an asset for “Project A” and later decide to incorporate it into “Project B.” If you do, please formally acquire the asset for Project B also, so that PEAR can properly calculate the asset’s reuse value.

4.3 Asset Deletion

Assets can be permanently deleted from the PEAR repository. The deletion process is standard throughout the PEAR repository and is depicted here:

Figure 6. Asset Deletion Process

When an asset is submitted for deletion, the request is sent to the enterprise group repository administrator or the CoE of the owning group, depending on the whether the asset’s certification level is Enterprise or agency. If the request is approved, the asset is removed from the library; if rejected, the asset remains there.

OA/OIT


5. The Agency On-Boarding Process

5.1 Define Base Organizational Structure

First, each agency must determine how it wants its groups and projects configured within its organizational group. The hierarchy can be modified at any time, but initially the agency must establish at least one group and one project.

Each agency must submit an organizational diagram similar to Figure 2. This diagram forms the basis for any future modifications; all changes must be documented in this “master” diagram, whose template can be found at Appendix A. Each agency must submit this diagram to the PEAR Administrator ([email protected]), who will store it on BSCoE’s collaboration site.

5.2 Evaluate Default Processes

When an agency comes on board, they have the option of using PEAR’s default processes or creating their own customized processes. (The process most likely to be customized is the asset submission process.)

5.3 Define User Roles

The agency must identify which users will represent it in PEAR. Next, the agency must identify each role that each user is to play and in what organizational groups or projects they are to be assigned those roles. The agency then completes and submits a single User Roles Request Document to the PEAR administrator ([email protected]); all changes must be documented in this “master” document, whose template is at Appendix B. The PEAR Administrator stores the document on BSCoE’s collaboration site.

6. Contact InformationEach agency should define a point of contact (POC) for PEAR issues. The POC can communicate with the PEAR administrator via the OA PEAR resource account ([email protected]) or by submitting a remedy ticket to OA-Services & Solutions, OA-BSCoE, PEAR-Tool.

OA/OIT







Appendix A – The Organizational Group

OA/OIT


OA/OIT


Appendix B – User Roles Request Document

Group: _________________________________ Submitted By: ______(name & date)___________________________

OA/OIT

Users Roles

CWOPA User

Name

First Name Last Name Group/Project ACE Asset

Own

er

CoE Consu

mer

Proje

ct

Mgr

Project

User

Reporti

ng

Group

Example:

jdoe Jane Doe BSCoE X X X Yes


Appendix C – The Enterprise-Level Asset Approval Process

OA/OIT

pear on-boarding guide

Technology

pear roles pear users

pear asset

pear project

pear repository

pear group

pear hierarchy

pear roles5

number of pear