# Polarion Integration

## About This Project

P4Polarion is an integration for Perforce with the [Polarion ALM system](https://www.polarion.com)

## Support

This integration is not support by Perforce Support.

## License

Please refer to
[LICENSE](https://swarm.workshop.perforce.com/projects/perforce_software-p4polarion/files/main/LICENSE).

## Notes

Work-In-Progress: to be updated during development...

### Scan Jobs (Polarion CRON)

Scans for 'user' modified Perforce Jobs and updates the Polarion WorkItem.

```
<job name="Perforce Job Scanner" 
     id="jobscanner.job"
     cronExpression="0 0 1 ? * *"
     scope="project:paul">
</job>
```

### Import Jobs (Polarion CRON)

Imports new 'user' added Perforce Jobs (based on ReportedDate) and create new Polarion WorkItems setting the WorkItem Type filed and assigning to a Polarion Project.

```
<job name="Perforce Job Import" 
     id="jobimport.job"
     cronExpression="0 0 1 ? * *"
     scope="project:paul">
     
	<view>PolarionProject=paul</view>
	<type>defect</type>
	<delete>false</delete>
</job>
```

### WorkItem to Job replication

WorkItem (id)     | Replacation             | Job (field)
------------------|:-----------------------:|-------------
`id`              | `CREATE`-->             | `Job`
`project`         | `CREATE`-->             | `PolarionProject`
`description`     | <--`CREATE|UPDATE`-->   | `Description`
`title`           | <--`CREATE|UPDATE`-->   | `PolarionTitle`
`status`          | <--`CREATE|UPDATE`-->   | `PolarionStatus`
`author`          | `CREATE`-->             | `ReportedBy`
`linkedRevisions` | <--`CREATE|UPDATE`-->   | (`p4 fixes`)


### Perforce counters
Stores the last scan in Perforce Server time using Epoch in seconds.

`p4 counter Polarion.Job.Time` (Default start value: 0)

Stores the last import in Perforce Server time using Epoch in seconds.

`p4 counter Polarion.Import.Time` (Default start value: 0)

Polarion Server address used by Swarm to link within a Perforce Job.

`p4 counter Polarion.Server.Url` (Example: http://phooey-win.das.perforce.com)


### Perforce JobSpec Fields

field-name        | data-type     | length    | field-type    | preset
------------------|---------------|-----------|---------------|--------------
`Job`             | word          | 32        | required      | 
`Status`          | select        | 10        | required      |
`Description`     | text          | 0         | required      | `$blank`
`ReportedBy`      | word          | 32        | required      | `$user` 
`ReportedDate`    | date          | 20        | once          | `$now`
`ModifiedBy`      | word          | 20        | always        | `$user`
`ModifiedDate`    | date          | 20        | always        | `$now`
`PolarionTitle`   | text          | 80        | required      | 
`PolarionProject` | word          | 32        | required      | 
`PolarionLink`    | word          | 128       | optional      |
`PolarionStatus`  | word          | 20        | optional      | 'open'


### Example Perforce JobSpec

```
Fields:
        101 Job word 32 required
        102 Status select 10 required
        105 Description text 0 required
        107 ReportedBy word 32 required
        109 ReportedDate date 20 once
        110 ModifiedBy word 20 always
        111 ModifiedDate date 20 always
        112 PolarionTitle text 80 required
        113 PolarionProject word 20 required
		114 PolarionLink text 128 optional
		115 PolarionStatus word 20 required

Presets:
        Status open
		PolarionStatus open
        Description $blank
        ReportedBy $user
        ReportedDate $now
        ModifiedBy $user
        ModifiedDate $now
        PolarionStatus open
```

### Multiple Perforce 'repository' connections

In a situation where more than one Perforce repository is connected to a Polarion Project, the WorkItem 'Linked Revisions' will link a Perforce change and update the corresponding 'fix' record on the server.

![Polarion Mapping](docs/images/mapping.png)