Write guidance for common operations #54
Comments
|
I think the common operations for eForms and Standard forms should be a differente documents (= different URL). We'll need to think of how we publish eForms next to the standard forms:
I think the first option works well. Any opinion on this @jpmckinney? |
|
I prefer the first option as well. |
|
Related to #77, we must update the part about referencing a previous publication to cover the case where the referenced publication is a release or procedure that lead to a direct award (current procedure). |
|
Copying draft from a file that had been committed to this repo (ultimately it must be committed to https://github.com/open-contracting-extensions/european-union instead): # Common operations
To avoid repetition in the guidance, we refer and link to the following common operations.
## Create a release
1. Set [`id`](https://standard.open-contracting.org/latest/en/schema/identifiers/#release-id) to the notice number (`/*/cbc:ID`).
1. Set `initiationType` to 'tender'.
1. Set `ocid` as described below.
The notice's `ocid` will either be a new `ocid`, or the same `ocid` as the previous publication concerning this procedure. The notice's `ocid` will be a new `ocid` if one of the following is true:
* The notice is the first publication concerning the procedure.
* The previous publication is a prior information notice or a periodic indicative notice (PIN) that has multiple `/*/cac:ProcurementProjectLot` elements, it potentially lead to the launch of several procedures, each with its own `ocid`.
* The notice is a contract award notice (CAN) for an award within a framework agreement or dynamic purchasing system.
If none is true, then set the notice's `ocid` to be the same as the previous publication's `ocid`. Otherwise, set the notice's [`ocid`](https://standard.open-contracting.org/latest/en/schema/identifiers/#contracting-process-identifier-ocid) by prepending your [OCID prefix](https://standard.open-contracting.org/latest/en/guidance/build/#register-an-ocid-prefix) to a unique identifier of your choice (e.g. a [version 4 UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) or a suitable system-internal identifier).
If the notice is a contract award notice for an award within a framework agreement or dynamic purchasing system, you must also add a `RelatedProcess` object to the `relatedProcesses` array, set its `.id` to '1', add 'framework' to its `.relationship` array, set its `.scheme` to 'ocid', and set its `.identifier` to the `ocid` of the procedure that set up the framework agreement or dynamic purchasing system.
## Reference a previous publication
If the *Previous publication concerning this procedure* is neither a prior information notice nor a periodic indicative notice (PIN), or if the PIN has a single `/*/cac:ProcurementProjectLot` (*Object*) element, then discard `/*/cbc:ID`. In this case, the *previous publication concerning this procedure* is the OCDS release with the same `ocid` as this release and with the nearest earlier `date` to this release.
Otherwise, if the *Previous publication concerning this procedure* is a prior information notice or periodic indicative notice that has multiple `/*/cac:ProcurementProjectLot` (*Object*) elements, add a `RelatedProcess` object to the `relatedProcesses` array, set its `.id` to '1', add 'planning' to its `.relationship` array, set its `.scheme` to 'eu-oj' (or to a scheme of your choice if outside the EU), and map `/*/cbc:ID` to `.identifier`.
## Add a party
Add an `Organization` object to the `parties` array, and set its `.id` (string). **A party's `.id` needs to be consistent across all notices.** It is recommended to implement a register of organization identifiers to assign consistent identifiers. For more information, [see the OCDS documentation](https://standard.open-contracting.org/latest/en/schema/identifiers/#organization-ids).
## Add a bids statistic
Add a `BidsStatistic` object to the `bids.statistics` array, and set its `.id` (string) sequentially across all notices for this procedure. For example, if a first F03 notice for a given procedure has nine bids statistics, it uses `id`'s '1' through '9'. A second F03 notice for the same procedure then uses `id`'s '10' and up, etc.
## Convert a date to ISO format
[OCDS dates](https://standard.open-contracting.org/latest/en/schema/reference/#date) must be formatted according to ISO 8601 and include a time component.
If a time component is missing from a date, use 'T23:59:59Z' for end dates and 'T00:00:00Z' for other dates.
If a timezone component is present in the date (e.g. '+02:00'), preserve it. Otherwise, use the UTC timezone indicate 'Z'.
The final value would be '2020-10-21T23:59:59Z' or '2020-10-21T00:00:00Z'.
## Lot identifiers
eForms relies in the structure of the XML document to imply the related lot. For a given XML element, retrieving the corresponding lot identifier (if any) can done with the following Xpath:
```text
ancestor::cac:ProcurementProjectLot/cac:ID
```
## Groups of lots
## Procedure type
The possible values for BT-105 Procedure type ([official code list](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://publications.europa.eu/resource/authority/procurement-procedure-type#)) and the corresponding guidance in OCDS:
| Procedure type code | OCDS guidance `|
|---------------|-------------------|
| Competitive dialog (`comp-dial`) | Set `tender.procurementMethod` to 'selective', and set `tender.procurementMethodDetails` to 'Competitive dialogue' |
| Competitive tendering (`comp-tend`) | |
| Innovation partnership (`innovation`) | Set `tender.procurementMethod` to 'selective', and set `tender.procurementMethodDetails` to 'Innovation partnership' |
| Negotiated with prior publication of a call for competition / competitive with negotiation (`neg-w-call`) | Set `tender.procurementMethod` to 'selective', and set `tender.procurementMethodDetails` to 'Negotiated with prior publication of a call for competition / competitive with negotiation' |
| Negotiated without prior call for competition (`neg-wo-call`) | |
| Open (`open`) | Set `tender.procurementMethod` to 'open', and set `tender.procurementMethodDetails` to 'Open procedure' |
| Other multiple stage procedure (`oth-mult`) | |
| Other single stage procedure (`oth-single`) | |
| Restricted (`restricted`) | Set `tender.procurementMethod` to 'selective', and set `tender.procurementMethodDetails` to 'Restricted procedure' |
## Get a translation
No guidance yet. |
|
Noting that parts of PINs are separate OCIDs, like in the old forms. See also open-contracting-extensions/european-union#94 about how bundled award notices might yield multiple OCIDs. |
|
The guidance on referencing a previous publication is referenced from the following business terms in
|
|
I think the guidance for fields ending in |
|
Sounds good. There's a suggestion in #71 (comment) to add similar guidance for groups of lots. |
|
From @jpmckinney via Slack:
|
✔️The following business terms all refer to identifiers so will also need covered by the common guidance:
|
|
We'll also need guidance on setting award and contract identifiers and linking awards and contracts. eForms and OCDS have different approaches: in eForms, a There might also be issues with clashing identifiers since the eForms SDK states that both regular identifiers (e.g. BT-150-Contract) and 'technical' identifiers (e.g. OPT-316) should, rather than must, be unique (see Identifiers). This is relevant to BT-150-Contract and likely to some of the other business terms that appear as part of SettledContract. |
|
Just noting here (as I don't know where else to make a note of it) that SDK 1.0.0 now has a machine-readable file for all 40 notice types, in case we ever need it: https://github.com/OP-TED/eForms-SDK/blob/1.0.0/notice-types/notice-types.json |
✔️BT-5011 references the common operations guidance for adding a party. For now, I've left the link as |
✔️In eForms, data on beneficial owners is not nested within the organization they relate to so, similar to the guidance for linking awards and contracts, we'll need guidance on identifying which organization in the parties array to add beneficial ownership information to. This is relevant to the following BTs:
Proposed guidance
|
✔️Edit: I realised that ordering is important for the BTs listed below so I instead repeated the following guidance for each BT:
|
✔️Several BTs map to properties of organizations so we'll need guidance on how to identify the correct organization in OCDS. The guidance for touchpoints includes setting Proposed guidance
|
|
Looks good! Maybe style as a numbered list after "If none exists yet:", as the paragraph contains a lot of long XML, which makes it a bit harder to scan. |
I've updated the proposed guidance. |
✔️The draft guidance for BT-10-Procedure-Buyer, BT-11-Procedure-Buyer, BT-610-Procedure-Buyer and BT-740-Procedure-Buyer begins with:
However, how to actually do that isn't explained, nor is what to do if the Organization object doesn't exist yet. In keeping with the proposed guidance in #54 (comment), I think that this sentence should link to the following common operations guidance:
Does that sound good? |
✔️
For terms in BG-137: Procedure Lot Result (
Edit: For BT-142-LotResult at least, we also need the following:
|
✔️
This guidance should also include setting The guidance is referenced in:
Edit: Proposed guidance
|
|
I've added myself to the assignees for this issue to work on adding the content to @odscjen are you done with the task mentioned in #54 (comment)? |
|
I've added the content from this issue and the related issues to I removed some sections from the original draft in #54 (comment):
Since the page is not intended to be read from start to finish, I decided not to group the common operations under any sub-headings, but I did try and order the operations logically: generally applicable first, then organization related, then by stage of the contracting process. To do:
|
Still working slowly through it! |
|
After seeing how it renders, I've added some subheadings, just to make the menu easier to scan. |
|
Re. The guidance is:
And
The guidance in the current TED based OCDS EU profile for Get a translation is:
Which still mostly works for eForms (although it's not strictly speaking a label we're asking the user to translate, just a sentence we've given them) but as it's only applicable for these 2 terms and these 2 sentences is it worth having in common guidance or should we just add a summarized version of the above to guidance.yaml for BT-160 and BT-162, or just change the line that references get-a-translation to:
|
|
✔️ Do we need common guidance for "Get the item for the ProcurementProjectLot (schemeName='Part') or ProcurementProject"? In going through checking that "Get the item for the ProcurementProjectLot" was correctly referenced I realised there's quite a few pieces of guidance that go something like:
Where the associated mapping guidance for BT-263-Part reads very similarly. So both refer to "the item" without ever stating how the item should be created in the first place and where to find it. Related there are pieces of guidance like:
Where this is the sole piece of guidance and so there is nothing that could tell a user how to set the item's It looks like BT-26(a), BT-262 and BT-263 are the only terms that would need this as they're the only ones with an item specified at the EDIT:
So rather than common guidance we could just change BT-26(a)-Part to:
With similar changes to BT-263, |
I've now gone through all of the guidance and I think all the common references are being correctly referred to (with the exception of my most recent comments on translation and |
eForms has The translation is in a key like
and 162:
Since the steps might be a bit long, I guess it's worth having common guidance, even if only used twice. |
|
Good catch on BT-26(a), BT-262 and BT-263 - seems fine to take the same approach as BT-723, etc. (unless you think it's better or less repetitive to change both sets of mappings to refer to new common operations). |
|
Just checking - do you mean only the -Procedure forms of those BT-26xxx? |
the -Procedure and the -Part forms of those BT's |
|
✔️
sounds good. Looking at that page it looks as though they're now providing translations for more than just labels. So theoretically the guidance for "Get a translation" could be used in many more places, e.g. anywhere that the guidance says to map a code to a field. But I'm assuming we don't want to go down that route? In which case how does the following sound?
|
|
✔️
I think the same approach as BT-723 is the best way to go. Because -Part and -Procedure have different XPATH absolute head terms there would need to be two new common guidance pieces which wouldn't actually cut down that much on the repetition. And now I'm noticing that the 3 pieces of common guidance that reference "... for a ProcurementProjectLot" should probably be changed to "...for a ProcurementProjectLot[cbc:ID/@schemeName='Lot']" as otherwise it could also be read as applying to -Part terms which we decided to treat the same as -Procurement and not map to |
The linked comment is:
#77 has since been resolved and, if I understood correctly, referencing the previous publication is covered by the mapping of BT-1252 so there's no need to update the common operations guidance. |
|
regarding #54 (comment)
common operations for referencing documents has been created and is referenced in those 3 BTs but there's no common guidance for participation fees and each of the 3 referenced BT's just have some repetition in their guidance. Are we happy to leave them like that or should we pull out the common guidance and put it into operations? |
|
I think it would be good to author a common operation: Get the participation fee for a document. The guidance will need to address both the |
|
@jpmckinney have you had a chance to look at #54 (comment) and the proposed "Get a translation" in the common guidance? |
|
@duncandewhurst how does this sound:
|
Correct - we only want to get translations where absolutely necessary. In the old forms, we translated only four strings, in cases where we needed a prefix to Guidance looks fine - I think they key doesn't have any spaces, though. |
|
✔️
Looks good, but the XPath syntax isn't quite right, the paths are missing the
|
|
I think there are no outstanding things to be dealt with in this issue now so I'm closing it, reopen if necessary |
Throughout this issue, comments for which the relevant updates to
guidance.yamlare done are marked with a ✔️The same way we did for standard forms, in order to avoid repetitions, we need to document the guidance that applies to any eForms document.
The text was updated successfully, but these errors were encountered: