Protecode tools consist of the Protecode Global IP Server (GIPS^TM), which is the continuously updated global repository of software IP attributes, and the Protecode Client, which includes the Protecode Tracker^TM, the Protecode Reporter^TM and the Enterprise Adopter^TM. The Protecode Admin^TM – a web-based administration module - enables definition, capture and assignment of IP compliance policies to project teams. This is like setting an approved vendor list – determining what software content is acceptable for use in a specific project.

The Protecode Tracker is the core of the client product. It detects and logs software content – external or proprietary - as it is introduced in the course of development and automatically generates records called pedigree files. These pedigree files (*.wd files) are normally hidden and automatically stay with their subject files as the latter are checked in/out or moved within the development environment. Through interaction with the GIPS, Protecode identifies the origin, license and other information about the content or initiates the capture of such information within the development process, thus enabling creation of a comprehensive software pedigree report.

The Protecode Reporter creates the software Bill of Materials (BOM) and issues appropriate software IP policy compliance reports to the developers, the product and development managers, and to other concerned organizations (legal, finance, etc.) in the company.

The Protecode Enterprise Adopter analyzes existing legacy code base (for example files in a library prior to Protecode adoption) to identify external content and create appropriate pedigree reports.

Please support us by giving us feedback our email is support@protecode.com. We appreciate your effort to help us and we will try get back to you within a business day.

2. Quick Install

This is for first time users of Protecode.

1. Install the Protecode client via the normal Eclipse Plug-in installation process. Section ‎3 has details of how to install a plug-in if you have never done this before. Protecode Update Site is at http://update.protecode.com. You need the following components:

a. com.protecode.client and

b. com.protecode.enterprise.cvsadopter , or

com.protecode.enterprise.svnadopter, or

com.protecode.subclipse , depending on the repository you use.

2. Restart Eclipse. Protecode plug-in will try to determine if you are a valid user. It will ask you to log into Protecode.

At this stage you do not have a user ID and password yet. Click on “Need a user ID?”. You will be presented with a temporary user ID and password dialog. Enter your ID (a valid email address) and choose a password (8 chars minimum, must contain both letters and numbers). Click on Login button.

A browser window will open with the latest copy of the readme.txt file. On the Eclipse window, you will be presented with a warning window “No Policy File Found”. Ignore this for now and press OK to clear it.

That’s it. For a quick experience of Protecode software detection and identification, you may skip to section 4 Using Protecode. Later, you will have to come back to the Protecode Administration website http://admin.protecode.com and register yourself as an administrator, set up organizational or project policies, and assign other developers to your project.

Note: Protecode server will automatically send you an email to verify the email address you provided. You must complete this verification in order to be authenticated next time you start Eclipse.

3. Protecode Client Installation

Protecode client is a standard Eclipse plug-in that can be installed in one of two ways.

3.1. Common Eclipse plug-in installation

Developers install the Protecode plug-in through the standard Eclipse update manager process. From the Eclipse window go Help -> Software Updates and then select “Available Software” tab. Select the appropriate Protecode version and the press “Install”

If the Protecode update site is not present, then click on Add Site … and add a new remote site with the following site name and update site address:

Site Name: Protecode Update Site

Update site: http://update.protecode.com

Accept the license text when requested.

You need the following components:

a) com.protecode.client and

b) com.protecode.enterprise.cvsadopter , or com.protecode.enterprise.svnadopter, or com.protecode.subclipse , depending on the repository you use.

Note: For the usage of the Protecode Enterprise Adopter feature please refer to the relevant section below.

3.2. Installing Protecode Client manually

To install the Protecode Client 1.0.x.x from a stand-alone zip file:

a) Download the appropriate Protecode Client 1.0.x.x zip file from the Eclipse project web site at http://update.protecode.com/downloads/.

b) Extract the contents of the zip file to a new empty directory on your local disk.

c) Open the main update manager by clicking Help > Software Updates > Find and Install. This opens the Install Wizard.

d) Select Search for new features and click Next.

e) Select Protecode Update Site. If it is not there, add an update site by clicking New Local Site. Browse to the location of the extracted the file from step 2.

f) Rename the location if you like and click OK.

g) Select the location created in step 6.

h) Select the Protecode Client 1.x.x.x feature and click Next.

i) Accept the license and click Next.

j) Select the directory into which the feature is to be installed and click Next.

k) Click Finish to allow the installing to proceed.

l) Click Yes when asked to exit and restart the workbench for the changes to take effect. The examples are now installed in the workbench.

The following files will be created in your Eclipse directory after installation:

- features/com.protecode.client_1.0.x.x/

- features/com.protecode.enterprise.cvsadopter_1.0.x.x/

- features/com.protecode.enterprise.svnadopter_1.0.x.x/

- features/com.protecode.subclipse_1.0.x.x/

- plugins/com.protecode.core_1.0.x.x.jar

- plugins/com.protecode.reporter_1.0.x.x.jar

- plugins/com.protecode.tracker_1.0.x.x.jar

- plugins/com.protecode.subclipse_1.0.x.x.jar (optional)

- plugins/com.protecode.cvsadopter_1.0.x.x.jar (optional)

- plugins/com.protecode.svnadopter_1.0.x.x.jar (optional)

4. Protecode Administration

A Protecode administrator, generally a project manager, R&D manager, Project lead, R&D lead, Operations lead, does the following steps:

Register as an administrator using the Protecode Administration website (http://admin.protecode.com). Registration is confirmed by standard email verification process and completed by standard profile update. Note: If you have already registered, use your ID and password to enter the admin area.

m) Define a new policy for each project and save it. Click on Policies button on the left of the page.

o Click on New policy

o Policy Name: Give the policy a name in order to identify it later. There could be multiple policies for multiple projects in an organization and naming the policy facilitates the management. However, please note that the exported policy always has the same name “policy.ppe” (more on exporting later).

o License Name/Version/URL and Copyright Owner: Optionally, some information or attributes may be entered about the code that is created in your organization. This information will be stored against the “pedigree” of the files that you create on your system. This information could include what copyright or license the project is shipped under. The administrator may enter the name of the license, a link to the text of the license and the identity of the organization that holds the copyright such as the organization that the administrator works for or for a contractor the organization that has commissioned the work.

o Specify what action to take if this policy is violated.

Annotation Action on Violations/Unknowns: Setting annotation pop-ups (for when code license is unidentified or in violation of a policy) to be mandatory (user must fill in some values for external content), Optional (the popup must always appear, but user can cancel) or voluntary. If the policy is set to voluntary, the user can turn off the pop-ups by going to Windows > Preferences > Protecode and uncheck Display annotation popup in real time.
Minimum code size to report on: The policy can set how many lines of code and/or how many characters of code (e.g. for binaries) are deemed to be relevant from an IP perspective. Files or snippets that are larger than the defined settings will be tracked normally. Smaller snippets will be ignored.

o Accepted Licenses: click on this link to select which open source licenses are acceptable for the project.

o When you are done, save the policy you just created by clicking on save button on top of page. Your policy is now listed on My Policies page.

Export the policy: The policy you defined is captured in a file named “policy.ppe”. When you export a policy, you receive the policy.ppe file from Protecode server. Click on Export button.

In the new page, click on Export policy.ppe button to start receiving the policy.ppe file. As administrator, you put a copy of this file in the root of the project in the version control system. This way the policy file is accessible to all developers working on that project. Alternatively, the policy.ppe file could be sent to Protecode users to add to any project they wish to use Protecode under that policy e.g. a brand new project. This also allows having different policies for different projects within a single workspace.

Notes on policies:

a) If there is no policy file in place all projects in your workspace will be protecoded with the default policy (default is to accept all licenses).

b) To allow sandbox projects to go on without pedigree tracking you can create a file named "ignore.ppe" on their root.

c) New policies can be exported any time later and will dictate compliance going forward and what is reported.

The next step is specifying which developers are working on the project. Select Assign Protecoders from the menu on the left of the Administration page. The administrator must provide valid email addresses for all the developers that are working on the projects to be protecoded so they can register with Protecode and can use the system.

Developers who have been assigned as protecoders by the administrator will receive an email to complete registration and authorization. During this step they also complete their profile information. The profile information is used for reporting of the content that they introduce into their protecoded projects.

5. Using Protecode

After installation of the Protecode Client, normally accompanied by an Eclipse restart, developers can start using Protecode by simply logging in at the eclipse Protecode login prompt. Check Auto Login box if you are the only user of the machine and don’t want to explicitly log in every time.

Once logged in, any project in the Eclipse workspace will be automatically protecoded (pedigree information for files in that project will be created).

- Default policy settings are to accept all licenses, and ignore (do not try to identify, or report on) files or snippets less than 4 lines of code and 100 characters. Comments are NOT considered part of code.

Projects with a policy file policy.ppe at their root are treated under that specific policy. It is important to note that pedigree files will be generated with or without the presence of a policy file. In lieu of a policy.ppe file, the default policy will be applied and it’s perfectly fine to start without a policy.

If a policy file is added later, then all subsequent reports will use the new policy to check compliance. For new projects developers can easily add the policy.ppe file to the root right after creation. For projects imported or checked out of the repository the policy file may already be included by the administrator in the root of that repository or project area.

- Importing content (files, snippets etc.) to a protecoded project results in this new content being logged as external content and the client will try to identify the ownership of the content. If this content has already been protecoded, then the pedigree information will be carried forward to the current project.

- If a code snippet or file either violates a policy or is unidentified, the developer will optionally see a pop up window to ask for comments or annotation respectively. Annotations will be used to identify the same file again if applicable. This is also an opportunity to manually add the URL where the file was found for example.

See the Tips & Tricks in section 9 on how to disable/enable violation or unidentified-content pop-ups.

- Once you generate a report, you have a chance to select one or more External Content Records (ECRs) in a report, and manually accept, comment or annotate them (e.g. accept violations, or comment against violations, or identify unrecognized items).

Quick Test: set up a temporary project on your workspace. Bring a bunch of files into this project and then create a Protecode report by right clicking on the project and selecting Protecode -> Report (see section 6). Try modifying one of the files (cut & paste some lines from outside) and regenerate a report.

6. Creating and using a Protecode report

A Protecode report will show information such as software licenses of identified content and compliance to the corresponding policy. A Protecode report can be generated at any time over a protecoded project, its folders or individual files by:

a) select the project, file(s) or folder to be reported on

b) Right click and select Protecode >Summary Report or Protecode >Detailed Report

Comments can be added to any file(s) or folder by simply selecting Protecode > Add Comments from the corresponding context menu of the objects. These comments will be shown in subsequent reports. Comments added to a folder will be applied to all individual files under that folder.

If very many files are to be reported on, this can take some time and the report can be optionally generated in the background with progress indicated on the bottom right of the screen.

Note: A Protecode report can be generated for files that have no pedigree files associated (i.e. they were created before Protecode use). The process will attempt to identify the files. See also Enterprise Adopter described in Section 7.

The Summary report has a header and a summary table that presents the pedigree information in an easily reviewed one line per file format. The Detailed report includes the Summary report contents and an additional detailed section that presents all the external content associated with each file.

6.1. Header

The header displays the name of the user who generated the report, the time the report was generated, a legend on how to interpret the report, and vital statistics on the files being reported on.

6.2. Summary

The Summary section has the following columns associated with a file:

- status (compliance with policy, annotated by user)

- Path

- Name

- created and modified dates

- last developer that modified it

- license (none if file is less than the minimum size, or unidentified)

- type

-
Number of ECRs that are not unidentified, violating or complying with a policy.

Notes

a) The Summary Report has a list of all the files covered by the report.

b) Within the summary section, each column can be sorted by clicking on the column heading at the top.

c) By clicking the individual file name in the summary report you will be brought to the corresponding detailed record for that file in the Detailed Report.

6.3. Details

The Detailed Report section provides more information on each file, including details of each external content detected, corresponding licensing information and how the licensing was identified.

Each record in the Detailed Report section has a checkbox. You can select one or more records, and click on the Annotate button at the beginning of the Details Section to provide pedigree information about the external content, to add comments, or to override the compliance status (i.e. manually accept a violating record).

· The Detailed Report first lists the file name and path for each file

· For each file, a record of each external content is described

· By hovering over the text in the Source field, the source location of the file or content will be displayed at status bar the bottom of the screen

· Clicking on the text in the Source field will open that location in a browser, enabling you to directly view or navigate to the file that is the source of the external content

· By hovering over the text in the License field, the corresponding location of the license text associated with the external content will be displayed at the bottom of the screen

· Clicking on the text in the License field will open the license text in a browser

· The details field contains and comments or annotation information provided by the user