This phase is about documenting your sources of contracting data, and documenting how that data "maps" to OCDS – that is, identifying which data elements within your data sources match which OCDS fields and codes. The mapping phase is one of the longest and most important steps in the implementation process.
When starting out, consider working in parallel on the map and build phases, because the choices you make at the build stage might affect how you need to map your data. For example, your choice of architecture might determine whether you are able to publish a change history using releases and records.
If your contracting processes are managed on paper, using local spreadsheets or via unstructured electronic documents, and you’re reusing one of the existing tools for collecting OCDS data, then please get in touch with the OCDS Helpdesk for guidance on how to identify which OCDS fields match your local concepts.
Mapping data to OCDS is not always easy. Before writing any software, this phase is an opportunity to:
The documentation you produce can also later be included in your Data User Guide.
As you make progress through this phase, we encourage you to maintain a project plan, in order to help set priorities and ease communication within your team, with your stakeholders, and with the OCDS Helpdesk.
Involve the right people¶
As described in the Field-Level Mapping Template Guidance (introduced below), you will need at least:
A data expert who is familiar with the IT systems that capture and store contracting data and related documents, to identify the data elements within those systems.
A procurement expert who is familiar with procurement legislation and procedures, to identify which data elements match which OCDS fields, at a semantic level.
A technical expert who understands the data structures in OCDS, to help identify which data elements match which OCDS fields, at a technical level.
Identify your data sources¶
To implement OCDS you need to first identify which IT systems capture and store contracting data and related documents. You also need to identify how to connect data held in different systems, to get a complete picture of the contracting process. The Technical Assessment Template guides you through this process.
If your contracting processes are managed on paper, using local spreadsheets or via unstructured electronic documents, you should use the template to identify those data sources, too.
Once complete, you can:
Ask the OCDS Helpdesk to review your Technical Assessment.
Fill in the Systems sheet of your Field-Level Mapping (introduced below).
Localize OCDS to your context¶
Before mapping individual fields and codes, consider whether to first localize OCDS to your context. Localization can be useful when you need to map several different systems, or when multiple organizations will work on implementing OCDS in your country.
Download the mapping templates¶
To make the mapping easier we provide templates to list the data elements within your data sources, and map them to either:
If your contracting data is managed on paper or in unstructured electronic documents, you should use the templates to list the data elements in those data sources and map them to OCDS.
You can contact the OCDS Helpdesk for support and guidance on using the mapping templates.
Complete the mapping¶
You can complete the mapping in parts. For example, you might choose to split your mapping by any of the following:
data source (e-procurement system, contract management system, financial management information system, etc.)
contracting process type (open procedure, selective procedure, concession contract, framework agreement, etc.)
contracting process stage (planning, tender, award, contract, implementation)
public notice (tender notice, award notice, etc.)
The preferred approach is to eventually list all the data elements within your data sources in your Field-Level Mapping, decide whether to publish each, and then map each. The decision to publish a data element is up to you; it isn't necessary to map all your contracting data.
It is also important to focus on the data elements whose disclosure was prioritized by users during the design phase. If you have not determined which data elements are a priority, you ought to do this now, based on your user needs.
Whichever approach you take, it's important that your eventual OCDS publication contain at least as much information as your other public datasets of contracting data; otherwise, users are less likely to use your OCDS publication.
Deal with the hard cases¶
Mapping data to OCDS is not always obvious. Please refer to our how-to guides and worked examples to learn how to map data for specific hard cases:
- Unsuccessful processes
- Framework agreements
- Pre-qualification and pre-selection
- Awards and contracts
- Electronic catalogs
- Updates and amendments
- Buyers and suppliers
- Organization references
- Organization identifiers
- Personal identifiers
- Organizational units
- Organization classifications
- Beneficial ownership information
Consider using extensions¶
Some data elements might not match any field or code in OCDS. To cover such cases, you can add fields and codes to OCDS using extensions.
Before using extensions, double-check whether the data elements can be disclosed using existing fields. For example, to disclose the date by which the buyer or procuring entity will respond to enquiries, you can use the
tender.milestones field, instead of adding a new field.
If you do need to use an extension, consider whether the new fields will affect how users interpret existing fields. If so, you can add information to existing fields, to avoid misinterpretation – in addition to adding the new fields.
For example, you have created an extension to add a new field to indicate whether a contracting process is about the disposal of a state asset (like a vehicle). If the
tender.title field refers only to the vehicle, then users who are unaware of the new field might misinterpret the contracting process as being about its purchase. To avoid misinterpretation, you can add a "Disposal: " prefix to the
Resource OCDS Glossary
Action: Contact the OCDS Helpdesk to get help with mapping data or authoring extensions.
Action: If you are stuck on a particular concept and are concerned about how it is modelled in OCDS, search the issues in our GitHub tracker to see what others in the community are saying about the topic. If you do not see your issue, create a new one!