PaCv2 Reference

This is the reference documentation for the PaCv2 model.

danger

Some values are overridden or set by default for activities that use the Forge-provided CI. If that is the case, there will be a warning on this page.

Key

The code blocks give you information of where different properties can be used.

An initial value of . means "root of the document", while an initial value of * means "anything that contains".

Common properties

`assignmentGroups`

. -> assignmentGroups
. -> assignmentGroups -> (item) -> assignmentGroups    (repeatable)

Defines an assignment group.

If an assignment group a is defined as part of another assignment group b, then a is a child of b.

`assignments`

. -> assignments
. -> assignmentGroups -> (item) -> assignments

Defines a list of assignments.

This can be used from the root to define a "flat" activity, e.g. an activity that is just a list of assignments and does not take advantage of the graph system.

When used from an assignment group, this defines assignments that is part of the group.

`dates`

. -> dates
* -> assignmentGroups -> (item) -> dates
* -> assignments -> (item) -> dates
* -> assignments -> (item) -> submissions -> (item) -> dates

🏞️ Cascading by overriding

This property is cascading. Values defined lower in the hierarchy of your YAML file will override previously defined values.

Defines the dates. Dates are defined at the submission level, but can be defined at higher levels.

The following dates must be defined:

Field name	Description
`closingAt`	Time after which submissions are no longer accepted. Students still have access to the assignment.
`openingAt`	Time after which submissions are accepted and students get access to the assignment.
`publishingAt`	Time after which the results for the submission are published to students.

`descriptionMd`

. -> descriptionMd
* -> assigmnentGroups -> (item) -> descriptionMd
* -> assignments -> (item) -> descriptionMd

A description for the assignment, assignment group or activity, displayed on the intranet. This description can be formatted using CommonMark.

`groups`

. -> groups
* -> subscriptions -> (item) -> groups

🔃 Referencing property

This property is defined at the root and only referenced from other places. Define values at the root, then reference them using the ID/slug.

When specified at the root, this defines a group that can be subscribed to assignments, groups, submissions, etc.

Groups are defined as follows:

groups:
  - { slug: my-group, logins: [abc.def, foo.bar, xavier.loginard] }

Where:

slug is the identifier for the group. This is the identifier you will use to subscribe the group to things.
logins is the list of Forge logins of the members of the group.

See the subscriptions section for more information on how groups can be subscribed.

`managers`, `additionalManagers`

. -> managers
* -> assignmentGroups -> (item) -> additionalManagers
* -> assignments -> (item) -> additionalManagers
* -> submission -> (item) -> additionalManagers

🏞️ Cascading by summing

This property is cascading. Values defined lower in the hierarchy of your YAML file will be added to previously defined values.

The managers for the activity, with additional managers added for the assignment group, assignment or submission.

`maxLearners`

. -> maxLearners
* -> assignmentGroups -> (item) -> maxLearners
* -> assignments -> (item) -> maxLearners

🏞️ Cascading by overriding

This property is cascading. Values defined lower in the hierarchy of your YAML file will override previously defined values.

The maximum number of students that can be contained in a group.

`notions` and `bounties`

. -> notionsq
* -> assignmentGroups -> (item) -> notions
* -> assignments -> (item) -> bounties

🔃 Referencing property

This property is defined at the assignment group or the activity and only referenced from other places. Define values at the assignment group or the activity, then reference them using the ID/slug.

Definition

When used in an assignment group, defines a list of notions, e.g.:

notions:
  - name: My notion
    slug: my-notion
    validationThreshold: 30
  - name: My other notion
    slug: my-other-notion
    validationThreshold: 10

Available properties are:

Field name	Description
`name`	Name of the notion, as it is displayed on the intranet.
`slug`	Slug for the notion, without spaces or slashes, e.g. `my-great-notion`
`validationThreshold`	Amount of points required to validate the notion

Usage

The bounties property is used to let assignments award points to specific notions when validated.

bounties:
  - notionSlug: my-great-notion
    value: 10
  - notionSlug: my-other-notion
    value: 1

Available properties are:

Field name	Description
`slug`	Slug for the notion. This must match a notion's slug from the assignment group's `notions`.
`value`	Amount of points awarded when validating an exercise

`subscriptions`, `exclusiveSubscriptions`

. -> subscriptions
* -> assignmentGroups -> (item) -> subscriptions
* -> assignmentGroups -> (item) -> exclusiveSubscriptions
* -> assignment -> (item) -> subscriptions
* -> assignemnt -> (item) -> exclusiveSubscriptions
* -> assignment -> (item) -> submissions -> (item) -> subscriptions
* -> assignment -> (item) -> submissions -> (item) -> exclusiveSubscriptions

Subscriptions control who has access to (parts of) the activity.

Students are only able to see parts of the activity they are subscribed to, including parents of the parts they are subscribed to.

See the graph documentation for more information on how subscriptions are propagated.

danger

Assignments must have at least one submission to have people subscribed to it. This is because subscriptions cascade all the way to submissions. Whether someone has access to something or not is solely determined on whatever ended up in the submissions.

See this section for more details.

Subscription format

Subscriptions (whether inclusive subscriptions or exclusiveSubscriptions) are lists that have the following format:

subscriptions: # or exclusiveSubscriptions
  logins: [xavier.loginard, john.smith] # subscribing via a login
  criGroups: [ing1-prs] # subscribing via CRI groups
  groups: [group-slug-1, group-slug-2]

By default, logins, criGroups and groups take an empty list if omitted.

Items in groups correspond to the slug of groups defined at the root of the activity (see here)

danger

criGroups field is not yet available but is being considered for an upcoming version.

Inclusive subscriptions

🏞️ Cascading by summing

This property is cascading. Values defined lower in the hierarchy of your YAML file will be added to previously defined values.

When defining subscriptions using subscriptions, subscriptions are added for the specific activity/assignment group/assignment in addition to any defined higher in the hierarchy.

Let's say we have the following setup:

Exclusive subscriptions

🏞️ Cascading by overriding

This property is cascading. Values defined lower in the hierarchy of your YAML file will override previously defined values.

Exclusive subscriptions will completely override subscriptions defined above. qSubscriptions defined above will not apply to the node that has exclusive subscriptions.

Example

Let's say we have the following activity:

With the following subscriptions:

anna.a on Activity A's subscriptions
brandon.b on Assignment B1's subscriptions
charlie.c on Assignemnt group CA's subscriptions
diane.d on Assignment CA2's exclusiveSubscriptions

note

While this example uses individual logins, the logic is the same when using Forge groups or activity groups.
This example only goes as deep as assignemnts, but the reasoning is the same for subscribing students to submissions.

Anna would have access to the following nodes (in green):

That is, she has access to everything in the graph except sections that are use an exclusiveSubscription.

Here is Brandon's graph:

Brandon only has access to B1 (via its subscriptions) and its parents.

Here is Charlie's, who is in the same situation, except that his subscription gives him access to the entire CA assignment group and not just a single assignemnt, except for the parts that use exclusiveSubscriptions:

Finally, here's Diane's situation. She has access only to CA2, via an exclusive subscription. This means that only users explicitly subscribed to CA2 are allowed, and users that would otherwise have implicit access (such as Anna or Charlie) do not get access to the CA2 assignment:

Activity properties

In addition to the fields defined above, activities contain the following properties:

Field name	Description	Required?
`name`	The name of the activity, as displayed on the intranet.	Yes
`newsGroup`	The newsgroup students should use to communicate about the project.	No
`newsTag`	The tag that students should use in news subjects.	No
`slug`	The slug of the activity, without spaces or slashes.	Yes
`tenantSlug`	Slug of the tenant within which your activity will be added.	Yes
`validationMode`	See this page for more information	No
`enableLFS`	Enables Git Large File Storage (LFS) on students repositories for this activity (default: disabled)	No

Assignment group properties

In addition to the properties defined above, assignment groups contain the following properties:

Field name	Description	Required?
`assignmentGroups`	A list of assignment groups that are children of this group. assignment	No
`assignments`	List of the assignments that are children of this group.	No
`name`	The name of the assignment group displayed on the intranet	Yes
`precedence`	A list of slugs that are ancestors of this node. Empty list by default.	No
`required`	Define if the assignment group is required to validate the assignment group it is in*	No
`slug`	Slug of the assignment group, without spaces or slashes, e.g. `my-phenomenal-assignment-group`.	Yes
`validationMode`	See this page for more information	No

* Only valid if this group has a parent and if the parent uses NODES or THRESHOLD_AND_NODES validation.

Example of precedence

Let's say that we want to define 4 assignment groups like so:

We can define precedence like so:

assignmentGroups:
  - slug: group-a
    name: Group A
    # ...

  - slug: group-b
    name: Group B
    precedence: [group-a]
    # ...

  - slug: group-c
    name: Group C
    precedence: [group-a, group-b]
    # ...

  - slug: group-d
    name: Group D
    # ...

Assignment properties

In addition to the fields defined above, assignments contain the following properties:

Field name	Description	Required?
`documents`	See below	No
`name`	Name of the assignment, as displayed on the intarnet	Yes
`required`	Define if the assignment is required to validate the assignment group it is in.*	No
`slug`	The slug for the assignemnt. This is a unique name without spaces or slashes, e.g. `my-assignment`.	Yes
`submissions`	The submissions that are defined for this assignment.	Yes
`tracePercentValidationThreshold`	The minimum percentage that needs to be obtained in traces to validate the assignment. 100 by default (100%).	No

* Only valid for NODES and THRESHOLD_AND_NODES assignment groups.

caution

Assignments need at least one submission. See submissions for details.

Documents

Documents are attached to submissions and serve several purposes.

The following document types exist:

Type	Description
`S3`	A regular document that students will be able to see in the "Documents" section. Default.
`EMBEDDED`	A document that will get embedded onto the page. Displayed on the assignment page.
`EXTERNAL`	A link to an external resource.
`WORKFLOW`	A document that is a JSON file contain a MaaS workflow
`TESTSUITE`	A file (can be a tarball) that contains the testsuite

caution

EMBEDDED documents are displayed on the assignment page using a sandbox. This means that the JavaScript is disabled and that the document is not allowed to access any information on the page. You should refer to the iframe sandbox attribute to learn more about the restrictions.

Documents are defined using the following properties:

Property	Description	Required?
`filename`	Name of the file (without spaces or slashes) that will be used to store the document	Yes
`name`	Name of the document as it will be displayed on the intranet	Yes
`path`	See below	Yes
`publishedAt`	Date after which the document will be available. If null, it will be published as the same time as the assignment	No
`type`	The type of the document. See above for available values.	No
`version`	The current version of the document. This can be a hash of the content of the document.*	Yes*
`visibility`	Visibility of the document. Public by default.	No

* This is generated automatically for tenants using the Forge-provided CI. You do not need to provide one yourself in this case.

The path value must contain:

For S3, EMBEDDED, WORKFLOW or TESTSUITE, the relative path to the document in question within your activity repository.
For EXTERAL, a URL to the external document.

For the visibility field, the following values are available:

PUBLIC: Available for students
PRIVATE: Only available to project managers via Operator

Here's an example of a simple document definition:

documents:
  - filename: subject.pdf
    name: Subject
    type: S3
    path: subjects/subject.pdf # (document path relative to the root of the activity repository)

Submissions

Submissions define opportunities for students to submit their work and are used to compute who has access to what within an activity.

Submissions and subscriptions

Submissions are the element used to determine whether someone has access to a resource or not. They are the element that everything cascades to. Subscriptions are always computed in terms of submissions. In consequence, you will need to have at least one submission in each assignment so that PaCv2 has a place where it can compute the effective subscriptions. In case there is nothing to submit (e.g. because the assignment is just a subject without anything students have to hand in), you will still need a submission with a REGISTRATION_ONLY handoff type.

In addition to the fields described above, submissions contain the following:

Field name	Description	Required?
`autoDispatch`	If true, a job is created automatically when the student submits to this submission.	No (true by default)
`autoPublish`	If true, the students will be able to see their trace result automatically when the jobs associated to this submission are finished.	No (false by default)
`link`	Only applicable if `handoffType` is `LINK_TAB` or `LINK_IFRAME`. The URL where students can submit their work	No
`handoffType`	How subscribed students can submit their work. See below for more information.	No (`REGISTRATION_ONLY` by default)
`incrementalTrace`	Nonfunctional at the moment, contact us if you wish to use this.	No
`limit`	Maximum amount of submissions allowed per `{limitType}`	No (default 1)
`limitType`	The interval of time for `limit`. See below for possible values	No (default `HOUR`)
`maxInFlight`	Maximum number of submissions that can be processed simultaneously. Exceeding this will temporarily block the student's submissions.	No (default 1)
`pick`	Determines what submission is used for grading: either `LAST` for the latest submission or `BEST` for the best one.	No (default `BEST`)
`slug`	The slug (unique name without spaces or slashes) of the submission.	Yes
`tagPrefix`	Only applicable if `handoffType` is `GIT_TAG`. The prefix of the tag. (e.g. `exercises-foo-`)	Yes if using `TAG_TYPE`, No otherwise
`workflow`	The workflow to use for automatically testing the submission. See this section for more details	No

Limits

You can limit the amount of submissions that can be made within a specific amount of time. Specifically, the limit is defined as limit per limitType.

limit can be any strictly positive number.

limitType can be any of the following:

SUBMISSION: only allow a specific amount of submissions for the entirety of the submission.
HOUR, DAY, MINUTE, WEEK: allow a specific amount of submissions per hour, day, minute or week.
- The reset is done at:
  - Second 0 of the next minute for MINUTE
  - Minute 0, second 0 of the next hour for HOUR
  - Midnight (00:00:00 AM UTC) for DAY
  - Mondays, midnight (00:00:00 AM UTC) for WEEK
caution
Reset times are in UTC, not CET/CEST
HOUR_ROLLING, DAY_ROLLING, MINUTE_ROLLING, WEEK_ROLLING: Only allow submissions as long as there are less than limit valid (i.e. running, waiting or finished) submissions in the past type. The checked range is [currentTime - type; currentTime]

Example: simple limit

For example, the following...

limit: 3
limitType: HOUR

... will let students tag three times per hour, resetting the count on every new hour.

Example: rolling limit

Let's say that we have a limit of 3 submissions per rolling hour. A hypothetical student as the following:

The current time is 15:05. The student has already submitted 3 tags in the last hour, meaning that if they try to submit another, the would get rejected:

However, if they wait until 15:16, they will once again be able to push since they will have only 2 valid tags that were pushed between 14:16 and 15:16:

Handoff types

The following handoff types are available:

GIT_TAG: Students submit their work by pushing a tag on the main branch following a tag pattern.
GIT_DEFAULT: Students submit their work by pushing on their default branch (master)
REGISTRATION_ONLY: the submission is only used to provide effective registrations. If students do not need to hand in anything, you must have at least one REGISTRATION_ONLY submission.
LINK_TAB: the submissions is done on another website, using the link provided in the link field.
LINK_IFRAME: creates an <iframe> on the assignment page that points to the URL defined in the link field.

caution

Not all handoff types are fully operational at the moment. Feel free to contact us if you intend to use handoff types other than REGISTRATION_ONLY or GIT_TAG.

Only GIT_TAG and GIT_DEFAULT are able to dispatch a job (and will do so automatically if autoDispatch is set to true).

Useful submission patterns

A common pattern is to have:

One submission for students with a relatively strict submission policy
Another submission for managers with a lax submission policy (via exclusiveSubscriptions for example)

This lets managers test the activity freely while still restricting students.

PaCv2 Reference

Key​

Common properties​

assignmentGroups​

assignments​

dates​

descriptionMd​

groups​

managers, additionalManagers​

maxLearners​

notions and bounties​

Definition​

Usage​

subscriptions, exclusiveSubscriptions​

Subscription format​

Inclusive subscriptions​

Exclusive subscriptions​

Example​

Activity properties​

Assignment group properties​

Example of precedence​

Assignment properties​

Documents​

Submissions​

Submissions and subscriptions​

Limits​

Example: simple limit​

Example: rolling limit​

Handoff types​

Useful submission patterns​

Key

Common properties

`assignmentGroups`

`assignments`

`dates`

`descriptionMd`

`groups`

`managers`, `additionalManagers`

`maxLearners`

`notions` and `bounties`

Definition

Usage

`subscriptions`, `exclusiveSubscriptions`

Subscription format

Inclusive subscriptions

Exclusive subscriptions

Example

Activity properties

Assignment group properties

Example of precedence

Assignment properties

Documents

Submissions

Submissions and subscriptions

Limits

Example: simple limit

Example: rolling limit

Handoff types

Useful submission patterns