Services


This point explains the general and utility services that are used by the whole system.

Infrastructure Services

These services give support to the following features:

Public point

Public Point is a service that displays records and data-sets in read-only mode. Only information allowed for publication by the current legislation is displayed (i.e. it does not show bids of the bidders until the opening session (disclosure) of the bids.

   Quick test and definitions of endpoints with Swagger

AccessPoint

https://sandbox.public.mtender.gov.md

Retrieving data

To retrieve a list of data or individual entity data-set use GET-request parameterized with one or more options sent to corresponding end-point.

Getting list of all data

Sorting

By default all data returned from public point are sorted by modification time (from oldest to newest).

Limiting number of Tenders returned

You can control the number of data entries in the entity feed (batch size) with limit parameter. If not specified, data is being returned in batches of 100 elements.

GET /get/tenders?offset=...&limit=20&order=asc&mode=history

Example of Response

{
 "data": [
   {
     "ocid":
"",
     "date":
""
   }
 ],
 "offset":
""
}

Batching

The response contains ‘offset’ element. This is the parameter that needs to be added to the original request made to get the next page. If the next page request returns no data (i.e. empty array) then there is no purpose in fetching for further pages.

Synchronizing

It is often necessary to be able to synchronize changes of Central Unit with the local database. The default sorting “by modification date” together with Batching mechanism allows one to implement synchronization effectively. The synchronization process can go page by page until there is no new data returned. Then the synchronizer has to pause for a while to let Central Unit register some changes and attempt fetching subsequent page.

   The safe frequency of synchronization requests is once per 5 minutes

Getting individual entity information

To get an individual entity data set (as Record Package) provide your GET-request with unique ID of specific entity as depicted below:

GET /tenders/ocds-000-00001?offset=...

Getting details of stage (part) of individual entity information

To get a detailed information about a stage of individual entity data set (as Release Package) provide your GET-request with unique ID of particular entity and unique ID of particular stage of the particular stage as depicted below:

GET /tenders/ocds-000-00001/ocds-000-00001-PIN?offset=...

Getting list of documents

The document can be retrieved by requesting the URL returned in structures from document list request in data[*].url. It is safe to provide the download URL to end user for download.Functionality

Retrieving budgets. EIs, FSs: lists and items

POST /budgets

Retrieving tenders. PNs, PINs, CNs, ACs, CIs: lists and items

POST /tenders

Figure 8. Process Sequence Diagram

Flow Description

File to be registered

DS performs following actions:

  1. The file size is checked - if the value is exceeded, the process is thrown
  2. The file format is checked for a valid format
  3. In case of a valid format, the file is saved:
  1. description is stored in the database according to the model
  2. Returns file descriptions to the client according to the attribute composition

Feed point

MTender use an Apache Kafka® platform to organize real-time communication between parties (including Platforms) for transferring a personalized data as a closed feed. Apache Kafka® is a distributed open-source stream processing platform developed by the Apache Software Foundation. The project aims to provide a unified, high-throughput, low-latency platform for handling real-time data feeds.

   Learn more about Apache Kafka 

Handles Clients

Starting with the 0.8 release Apache Foundation maintaining all but the jvm client external to the main code base.

C/C++

Python

Go (AKA golang)

Erlang

.NET

Clojure

Ruby

Node.js

Proxy (HTTP REST, etc)

Perl

stdin/stdout

PHP

Rust

Alternative Java

Storm

Scala DSL

Clojure

Swift

   See previously supported Client Libraries

AccessPoint

https://sandbox.feed.mtender.gov.md

Respond Service

After processing BPE always provides response, reporting either success or failure and available details. In all cases, the BPE will return an HTTP Status Code that indicates the nature of the failure (see below), with a response body in JSON format containing additional information.

General responses
2xx Success

This class of status codes indicates the action requested by the client was received, understood, accepted, and processed successfully

Code

Description

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used.

201 Created

The request has been fulfilled, resulting in the creation of a new resource.

202 Accepted

The request has been accepted for processing, but the processing has not been completed.

4xx Client Error

This class of status code is intended for situations in which the error seems to have been caused by the client. Except when responding to a HEAD request, the server should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents should display any included entity to the user

Code

Description

401 Unauthorized

A valid API key was not provided with the request, so the API could not associate a user with the request.

403 Forbidden

The API key and request syntax was valid but the server is refusing to complete the request. This can happen if you are trying to read or write to objects or properties that you do not have access to.

404 Not found

Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.

409 Document conflict

The request could not be completed due to a conflict with the current state of the target resource. Please repeat your request.

410 Archived

The resource requested is not and will not be available.

412 Precondition failed

See Authentification.

422 Unprocessable Entity

This status code means the server understands the content type of the request entity. For example, this error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions.

429 Rate Limit Enforced

Rate Limit Enforced. See Performance Recommendations.

500 Server Error

The server failed to fulfill a request. Response status codes beginning with the digit "5" indicate cases in which the server is aware that it has encountered an error or is otherwise incapable of performing the request.

MConnect

MTender uses a software daemon to retrieve needed data, available according to systems’ permissions in the Interoperability Governmental Platform MConnect which facilitates the exchange of data between the authorities to increase the efficiency and quality of delivery of public services. Through the interoperability platform, the public authorities exchange data in real time without requesting it from citizens and the business environment in the form of certificates, reports, etc.

   Learn more about M-Connect

AccessPoint

https://sandbox.mconnect.mtender.gov.md

Functionality
IBANs

Request parameters

idno

The IDNO if the Contracting Authority (whos budget will be spend under this tender)

cpv

Classification of the subject of procurement according to CPV (3rd digit)

year

The budget year of this contracting process

Example

GET /budget/iban?idno=...&cpv=...&year=... HTTP/1.1
Host: sandbox.mconnect.mtender.gov.md

200 OK
Content-Type
: application/json; charset=UTF-8

{
 "getIbanList_response": {
   "iban": [
   
   ]
 }
}
 

Amounts

Request parameters

iban

IBAN code number according to Treasurys’ classification

year

The budget year of this contracting process

Example

GET /budget/get?iban=...&year=... HTTP/1.1
Host: sandbox.mconnect.mtender.gov.md

200 OK
Content-Type
: application/json; charset=UTF-8

{

  "sum":"90000.00"

}

Validity of amounts

Request parameters

iban

IBAN code number according to Treasurys’ classification

year

The budget year of this contracting process

sum

Amount of funds to be checked

Example

GET /budget/check?iban=...&year=...&sum=... HTTP/1.1
Host: sandbox.mconnect.mtender.gov.md

200 OK
Content-Type
: application/json; charset=UTF-8

{

  "result":"1"

}

Contracting Authority Profile

Request parameters

idno

The IDNO if the Contracting Authority

Example

GET /organization/public?idno=... HTTP/1.1
Host: sandbox.mconnect.mtender.gov.md

200 OK
Content-Type
: application/json; charset=UTF-8

{
 "IDNO":
"",
 "FiscalCode":
"",
 "Name":
"",
 "ShortName":
"",
 "LegalFormCode":
"2" ,
 "PropertyFormCode":
"2",
 "RegistrationDate":
"",
 "VATCode":
"",
 "BudgetDebt":
"",
 "Address": {
   "Country":
"",
   "Region":
"",
   "Locality":
"",
   "LocalityCode":
"",
   "Street":
"",
   "House":
"44",
   "Block":
"",
   "Flat":
""
 },
 "Conductors": {
   "Conductor": {
     "PersonalData": {
       "IDNP":
"",
       "LastName":
"",
       "FirstName":
""
     },
     "RoleCode":
"18"
   }
 },
 "ChefAccount": {
   "PersonalData": {
     "IDNP":
"",
     "LastName":
"",
     "FirstName":
""
   }
 }
}

Economic Operator Profile

Request parameters

idno

The IDNO if the Economic Operator

Example

GET /organization/private?idno=... HTTP/1.1
Host: sandbox.mconnect.mtender.gov.md

200 OK
Content-Type
: application/json; charset=UTF-8

{
 "IDNO":
"",
 "FiscalCode":
"",
 "Name":
"",
 "ShortName":
"",
 "LegalFormCode":
"",
 "PropertyFormCode":
"",
 "RegistrationDate":
"",
 "VATCode":
"",
 "BudgetDebt":
"",
 "Address": {
   "Country":
"",
   "Region":
"",
   "Locality":
"",
   "LocalityCode":
"",
   "Street":
"",
   "StreetCode":
"",
   "House":
"",
   "Block":
"",
   "Flat":
""
 },
 "Activities": {
   "Activity": [
     {
       "ActivityCode":
"",
       "ActivityType":
"",
       "OrderNumber":
""
     }
   ]
 },
 "Founders": {
   "Founder": {
     "PersonType":
"",
     "PersonShortData": {
       "IDNP":
"",
       "LastName":
"",
       "FirstName":
""
     }
   }
 },
 "Conductors": {
   "Conductor": {
     "PersonalData": {
       "IDNP":
"",
       "LastName":
"",
       "FirstName":
""
     },
     "RoleCode":
""
   }
 },
 "ChefAccount": {
   "PersonalData": {
     "IDNP":
"",
     "LastName":
"",
     "FirstName":
""
   }
 }
}

Responsible Person Profile

Request parameters

idnp

The personal code of the individual

Example

GET /citizen/get?idnp=... HTTP/1.1
Host: sandbox.mconnect.mtender.gov.md

200 OK
Content-Type
: application/json; charset=UTF-8

{
 "IDNP":
"",
 "FirstName":
"",
 "LastName":
"",
 "SecondName":
"",
 "BirthDate":
"",
 "BirthDateStatus":
""
}

Business Services

These services give support to the following features:

Auth Service

MTender use a ‘JSON Web Token’ (JWT) open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA.

   Learn more about JWT

AccessPoint

https://sandbox.auth.mtender.gov.md

auth.eprocurement.systems

Functionality
ID Token

The ID token is a JWT that contains user profile information (like the user's name, email, and so forth), represented in the form of requests. These requests are statements about the user, which can be trusted if the consumer of the token (Auth Service) can verify its signature.

How to get an ID Token

Only authorized applications (Platforms) can obtain an ID Token from an Administrator of the MTender

Access Token

The Access Token is a credential that can be used by a application to access BPE. Its purpose is to inform the API that the bearer of this token has been authorized to access and perform specific actions (as specified by the scope that has been granted).

The Access Token should be used as a Bearer credential and transmitted in an HTTP Authorization header to the BPE

Refresh Token

A Refresh Token is a special kind of token that obtains a renewed Access Token — that allows to access a protected resource. You can request new Access Tokens until the Refresh Token is blacklisted. Refresh Tokens must be stored securely by an application because they essentially allow a user to remain authenticated forever. A Refresh Token is issued from the Auth Service endpoints along with the Access Token. When the Access Token expires, the Refresh Token can be used to obtain a fresh Access Token with the same permissions, without further involvement from a user.

   Learn more in Auth Service api-guide

Documents Service

Document Service is a System Environment Component responsible for registering, uploading, archiving, organising and controlling the access to all documents (files), enabling long-term preservation of them in a digital format and ensuring that they can be easily retrieved without conversions. The service also provides basic document management functionalities for reception, dispatch, storage and retrieval of documents.  

 

Requirements
Supported Document Formats (Media Types)

According to the Media Types Data standard, the following formats are supported by the Document Service:

Size restrictions

The common limit for file size is 52428800 bytes (50Mb)

Components

The Document Service consists of several components:

File Repository Management System - Document Service Gateway

Gateway managing the access to the file repository: controls access and reads the files from the repository.

File Repository - Storage

Storage of the files attached to the tender notices, offers, and complaints.

AccessPoint

All of the document uploading API endpoints follow the same set of rules and uses single access point.

https://sandbox.storage.mtender.gov.md

storage.eprocurement.systems

Functionality
Registration of Document

Registers a document that will be nested in an information entity and a backup location for uploading the document file to the file repository. To register any document hash of such, the document should be sent to the DS. The result of a document registration is its permanent link (URL) in the file repository, which will be returned within the respond of DS as part of a successful data-package. This link can be associated to other entities after a successful registration. Furthermore, a registered document with an identical hash must be uploaded.

End-Point

POST /registration

Flow Description

When a document is received to be registered, the DS performs the following actions:

  1. The file size is checked - if the value is exceeded, the process is thrown.
  2. The file format is checked for validity.
  1. In case of a valid format, the file is saved:
  1. A description of the document is stored in the database according to the model.
  2. The system returns the file description to the client according to the attribute composition.

Example

POST /registration HTTP/1.1
Authorization:
Content-Length: 58
Content-Type: application/json
Host: sandbox.storage.mtender.gov.md

{
 "data": {
   "hash":
"9a0364b9e99bb480dd25e1f0284c8555",
   "weight":
"1024",
   "fileName":
"file.txt"
 }
}

201 Created
Content-Type
: application/json; charset=UTF-8

{
 "data": {
   "id":
"9a0364b9e99bb480dd25e1f0284c8555",
   "url":
"https://sandbox.storage.mtender.gov.md/get/389684cc28c242b79c97c56be5142e25",
   "dateModified":
"2017-12-25T17:05:56.044677"
 }
}

Upload of Registered Document

A previously registered Document could be uploaded into the File Repository (Storage).  

End-Point

POST /upload

Flow description

When document is received to be uploaded DS performs following actions:

  1. The owner is checked for compliance with the one to whom the document registration URL was issued
  2. The hash is calculated using the checksum algorithm.
  3. The checksum of the received file is compared with the file stored in the reserve by reference. In case of mismatch, an exception is returned and the process is terminated.
  4. The file format is checked for validity.
  5. In case of a valid format, the file is saved.

Example

POST /upload/389684cc28c242b79c97c56be5142e25 HTTP/1.0
Authorization:
Content-Length: 58
Content-Type: multipart/form-data; boundary=----------a_BoUnDaRy572732436472$
Host: sandbox.storage.mtender.gov.md

------------a_BoUnDaRy572732436472$
content
------------a_BoUnDaRy572732436472$--

201 Created
Content-Type: application/json; charset=UTF-8

{
 "data": {
   "url":
"https://sandbox.storage.mtender.gov.md/get/389684cc28c242b79c97c56be5142e25"
 }
}

Get Uploaded Document

If a document is registered and stored in the Document Service, it can be retrieved by any user after the publication date of the document is reached (the document is public and the relevant link is published via Public Point). To retrieve the file, a GET-request should be sent to the Document Service.

End-Point

GET /get/

Example

GET /get/389684cc28c242b79c97c56be5142e25 HTTP/1.0
Host: sandbox.storage.mtender.gov.md

200 OK
Content-Disposition: attachment;
filename=file.txt
Content-Type: text/plain;
charset=UTF-8

Enterprise Services

These services give support to the following features:

Operation Service

BPE should always know what client is going to do before this action. Accordingly 'X-OPERATION-ID' is required when the POST-request is sent. 'X-OPERATION-ID' can be got via GET-request.

AccessPoint

https://sandbox.operations.mtender.gov.md

operation.eprocurement.systems

Functionality
X-OPERATION-ID

BPE should always know what client is going to do before this action. Accordingly 'X-OPERATION-ID' is required when the POST-request is sent. 'X-OPERATION-ID' can be got via GET-request..

Get X-OPERATION-ID

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF
-8
Content-Length:
99

{
 "data" : {
   "operationId" :
"3a0a5d62-e460-4dc5-9b3e-ae06226c58b4"
 }
}

Receive X-OPERATION-ID

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF
-8
Content-Length:
99

{
 "data" : {
   "operationId" :
"3a0a5d62-e460-4dc5-9b3e-ae06226c58b4"
 }
}

Also ‘X-OPERATION-ID’ provides a request identification. Therefore, the ‘X-OPERATION-ID’ should be used  to identify and analyse the data received from the Feed-Point.


Form Service

The Form Service is an additional service that allows Platforms to get actual needed field-set together with existing related information and reference data within one single request to build UI-Form for producing specific type of data-entity by end-user on its side. Accordingly, the platform may not store on its side such information, and receive it in real-time when needed. The Form Service uses ‘Alpaca Forms’ as a UI-Processor for interpretation of Json-Schema of different models as online UI-forms. ‘Alpaca’ provides the easiest way to generate interactive forms for web and mobile applications.

   Learn more about Alpaca Forms

Overview

To get needed information, relevant request should be sent to the Operation Service. The rules are below. In the case of successful requests, the service will provide a json-scheme of field-set, all available data taken from a public point, reference data for pre-defined fields and list of human-readable values of coded fields and data (such as list of available currencies, units of measure, etc) in a requested lang.

   Service is used together with ‘X-OPERATION-ID’ functionality within single request

Request

All requests for Form Service are done through a POST-method (same as for parent Operation Service)

POST ?mainParams[...]&specificParams[...]
Authorization
: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Content-Length: 4359
Content-Type: application/json
Host: sandbox.operations.mtender.gov.md

Main Params

form

Identifier of needed form (e.g. ‘EI’) according to ‘forms’ codelist

lang

Identifier of needed localization (e.g. ‘EN’) according to ‘langs’ codelist

Specific Params

Set of specific parameters required in a particular case. Described below.

Response

For all valid queries, the response will have a common structure:

201 OK
Content-Type: application/json; charset=UTF
-8

{
 "data": {
   "operationId":
"",
   "form": {
     "schema":{},
     "data":{}
   }
 }
}

   Objects "schema" and "data" will be present even if they are empty

For all invalid queries, the response will have a common structure:

4XX
Content-Type: application/json; charset=UTF
-8
{
 "errors":[
  {
    "code":
"",
    "description":
""
  }
 ]
}

Playground

Choose a JSON Form example below and check the generated form. Refer to this documentation for details and directions to extend the form.

   Try it at eProcurement.Forms playground

Functionality

All data-sets for each needed form are available in the Form-service and could be retrieved by Platforms:

Next Steps


How to get

All data-sets for each needed form are available in Form-service and could be retrieved by Platforms:

Expenditure Item Scheme

To get needed scheme for preparation of EI:

Create-form request params

Title

Value

Description

form

EI

Identifier of needed form according to ‘form’ codelist

country

MD

Identifier of country of jurisdiction according to ‘country’ codelist

identifierSchema

MD-IDNO

Identifier according to Organizations Identifier Schema

lang

RO

Identifier of needed localization according to ‘langs’ codelist

Update-form request params

To update existing EI different parameters should be set to indicate what exactly EI should be updated:

Title

Value

Description

form

UPDATE-EI

Identifier of needed form according to ‘form’ codelist

ocid

OCID-...

OCID of EI to be updated

lang

RO

Identifier of needed localization according to ‘langs’ codelist

Funding Source Scheme

To get the needed scheme for the preparation of FS:

Create-form Request Params

Title

Value

Description

form

FS

Identifier of needed form according to ‘form’ codelist

lang

RO

Identifier of needed localization according to ‘langs’ codelist

ocid

OCID-...

OCID of parent EI

funder

Identifier of role according to ‘funder’ codelist

payer

Identifier of role according ‘payer’ codelist

isEuropeanUnionFunded

TRUE | FALSE value

Update-form request params

To update FS different parameters should be set to indicate which specific FS should be updated:

Title

Value

Description

form

UPDATE-FS

Identifier of needed form

ocid

OCID-...

OCID of FS to be updated

lang

RO

Identifier of needed localization according to ‘langs’ codelist

Planning Notice Scheme

To get the needed scheme for the preparation of PN:

Create-form request params

Title

Value

Description

form

PN

Identifier of needed form according to ‘form’ codelist

pmd

OT

Identifier procurementMethodDetails according to ‘pmd’ codelist

lang

RO

Identifier of needed localization according to ‘langs’ codelist

ocid

OCID-...

OCID of parent EI

procuringEntity

Identifier of role according to ‘procuringEntity’ codelist

responsibleContactPerson

Identifier of role according to ‘responsibleContactPersone’ codelist

Update-form request params

To update PN different parameters should be set to indicate which specific PN should be updated:

Title

Value

Description

form

UPDATE-PN

Identifier of needed form according to ‘form’ codelist

ocid

OCID-...

OCID of PN to be updated

lang

RO

Identifier of needed localization according to ‘langs’ codelist

Contract Notice Scheme

Create-form “from scratch” - request params

To get the needed scheme for preparation of CN “from scratch” relevant request should be send to OS.

Title

Value

Description

form

CN

Identifier of needed form according to ‘form’ codelist

pmd

OT

Identifier procurementMethodDetails according to ‘pmd’ codelist

lang

RO

Identifier of needed localization according to ‘langs’ codelist

ocid

OCID-...

OCID of parent EI

procuringEntity

Identifier of role according to ‘procuringEntity’ codelist

responsibleContactPerson

Identifier of role according to ‘responsibleContactPersone’ codelist

Create-form “CNonPN”(“CNonPIN”) - request params

To get needed scheme for preparation of CN based on PN/PIN  relevant request should be send to OS.

Title

Value

Description

form

UPDATE-CN

Identifier of needed form according to ‘form’ codelist

ocid

OCID-...

OCID of used PN/PIN to be used as a base for future CN

lang

RO

Identifier of needed localization according to ‘langs’ codelist

Update-form request params

To update CN different parameters should be set to indicate which specific CN should be updated

Title

Value

Description

form

UPDATE-CN

Identifier of needed form according to ‘form’ codelist

ocid

OCID-...

OCID of CN to be updated

lang

RO

Identifier of needed localization according to ‘langs’ codelist

Tender Cancellation Scheme

To get the needed scheme for preparation of the tender cancellation amendment:

Request params

Title

Value

Description

form

CANCELLATION-TENDER

Identifier of needed form according to ‘form’ codelist

lang

Identifier of needed localization according to ‘langs’ codelist

ocid

OCID-...

Lot Cancellation Scheme

To get needed scheme for the preparation of the specific lot cancellation amendment:

Request params

Title

Value

Description

form

CANCELLATION-LOT

Identifier of needed form according to ‘form’ codelist

lang

Identifier of needed localization according to ‘langs’ codelist

ocid

OCID-...

lot-id

Enquiry Scheme

To get the needed scheme for the preparation of ENQUIRY:

Request params

Title

Value

Description

form

ENQUIRY

Identifier of needed form according to ‘form’ codelist

lang

Identifier of needed localization according to ‘langs’ codelist

lot-id

identifier of lot if this enquiry relates to a specific lot

Answer Scheme

To get the needed scheme for the preparation of ANSWER on ENQUIRY:

Request params

Title

Value

Description

form

ANSWER

Identifier of needed form according to ‘form’ codelist

lang

Identifier of needed localization according to ‘langs’ codelist

Bid Scheme

To get the needed scheme for the preparation of BID:

Create-form Request params

Title

Value

Description

form

BID

Identifier of needed form according to ‘form’ codelist

lang

Identifier of needed localization according to ‘langs’ codelist

ocid

lot-id

Update-form request params

To update BID, the same parameters should be set

Title

Value

Description

form

BID

Identifier of needed form according to ‘form’ codelist

lang

Identifier of needed localization according to ‘langs’ codelist

ocid

lot-id

Award Scheme

To get the needed scheme for the preparation of update of an auto-generated AWARD:

Request params

Title

Value

Description

form

AWARD

Identifier of needed form according to ‘form’ codelist

lang

Identifier of needed localization according to ‘langs’ codelist

lot-id

identifier of lot

Contract Preparation Scheme

To get needed scheme for preparation of update of auto-generated CONTRACT:

Request params

Title

Value

Description

form

CONTRACT

Identifier of needed form according to ‘form’ codelist

lang

Identifier of needed localization according to ‘langs’ codelist


Form Service Parameters

‘lang’ codes

EN

English

RU

Russian

RO

Romanian

‘country’ codes

MD

Republic of Moldova

‘form’ codes

EI

Expenditure Item

UPDATE-EI

Update of existing EI

FS

Funding Source

UPDATE-FS

Update of existing FS

PN

Planning Notice

UPDATE-PN

Update of existing PN

CN

Contract Notice

UPDATE-CN

Update of existing CN

BID

Bid

UPDATE-BID

Update of existing bid

ENQUIRY

Enquiry

ANSWER

Answer for specific enquiry

AWARD

Award

UPDATE-AC

Update of automatically prepared draft of future contract

CANCELLATION-TENDER

Cancellation of contracting process

CANCELLATION-LOT

Cancellation of specific lot of contracting process

‘funder’ codelist

BUYER

STATE

DONOR

‘payer’ codelist

BUYER

THIRDPARTY

FUNDER

‘procuringEntity’ codelist

BUYER

THIRDPARTY

‘responsibleContactPerson’ codelist

BUYER

THIRDPARTY

‘pmd’ codelist

MV

Micro Value Procedure

SV

Small Value Procedure

OT

Open Tender Procedure

How to Convert to OCDS-ready payload

Receiving a form is just a first step in the preparation of the data-set (payload) to be processed by CDU. Then the form is completed by user, collected data should be transformed into command-model, described for each type of data-entity separately (see description in 'Data-models' section). To do that ocds-hints can be used. Such hints provided by form-service within json-schema for each form-row. Each hint contains a path (attribute 'ocds'). Collected data should be placed in prepared dataset according to this path for build a expected command model.

For this purposes next JavaScript scenario could be used:

function convertJSONtoOCDS(data, schema) {
 
const isObject = value => value && typeof value === "object" && value.constructor === Object;
 
const isArray = value => Array.isArray(value);
 
const path = [];
 
const paths = [];
 
let docIndex = 0;
 
let itemIndex = 0;
 
const OCDSJSON = {};
 
function getOneOfIndex(schema, arr) {
   
const testField = Object.keys(schema)[0];
   
for (let [testIndex, variant] of schema[testField]["oneOf"].entries()) {
     
if (variant["properties"].hasOwnProperty(arr[0])) {
       
return [testField, testIndex];
     }
   }
 }
 
function getPaths(data) {
   
for (let key in data) {
     
if (isObject(data[key])) {
       path.push(key);
       getPaths(data[key]);
     }
else if (isArray(data[key]) && isObject(data[key][0])) {
       path.push(key);
       
for (let [index,] of data[key].entries()) {
         
if (key === "documents") {
           path.push(docIndex);
           ++docIndex;
         }
else if (key === "items") {
           path.push(itemIndex);
           ++itemIndex;
         }
else {
           path.push(index);
         }
         getPaths(data[key][index]);
         path.pop();
       }
     }
else if (!isObject(data[key])) {
       path.push(key);
       paths.push({
         path: path.slice(),
         value: data[key]
       });
     }
     
if (path.length > 0) {
       path.pop();
     }
   }
 }
 
function getOCDS(schema, arr) {
   
for (let item of arr) {
     
if (schema["properties"][item].hasOwnProperty("ocds") ||  

         (schema["properties"][item].hasOwnProperty("items") &&    

          schema["properties"][item]["items"].hasOwnProperty("ocds"))) {

       
if (schema["properties"][item].hasOwnProperty("ocds")) {
         
return schema["properties"][item]["ocds"];
       }
else {
         
return schema["properties"][item]["items"]["ocds"];
       }
     }
     
if (schema["properties"][item].hasOwnProperty("items") && !schema["properties"][item].hasOwnProperty("ocds")) {
       
const firstEl = arr[0];
       arr.shift();
       arr.shift();
       
return getOCDS(schema["properties"][firstEl]["items"], arr);
     }
else if (schema["properties"][item].hasOwnProperty("dependencies")) {
       
const firstEl = arr[0];
       arr.shift();
       
const [testField, testIndex] = getOneOfIndex(schema["properties"][firstEl]["dependencies"], arr);
       
return getOCDS(schema["properties"][firstEl]["dependencies"][testField]["oneOf"][testIndex], arr);
     }
else if (isObject(schema["properties"][item])) {
       
const firstEl = arr[0];
       arr.shift();
       
return getOCDS(schema["properties"][firstEl], arr);
     }
   }
 }
 
function getOCDSPath(schema, path) {
   
for (let item of path) {
     item[
"ocds"] = getOCDS(schema, item["path"].slice());
   }
 }
 
function getItemIndex(arr, key) {
   
for (let [index, item] of arr.entries()) {
     
if (item === key) {
       
return arr[index + 1];
     }
   }
 }
 
function fillOCDS(formPath, pathsArr, value, obj) {
   
const [nodeName, type] = pathsArr[0].split("::");
   
if (type === "object") {
     
if (!obj.hasOwnProperty(nodeName)) {
       obj[nodeName] = {};
     }
     pathsArr.shift();
     fillOCDS(formPath, pathsArr, value, obj[nodeName]);
   }
else if (type === "array[object]") {
     
if (!obj.hasOwnProperty(nodeName)) {
       obj[nodeName] = [];
     }
     
let i = getItemIndex(formPath, nodeName);
     
if (obj[nodeName].length < i + 1) {
       obj[nodeName][i] = {};
     }
     pathsArr.shift();
     fillOCDS(formPath, pathsArr, value, obj[nodeName][i]);
   }
else if (type !== "object" && type !== "array[object]") {
     obj[nodeName] = value;
   }
 }
 getPaths(data);
 getOCDSPath(schema, paths);
 
for (let item of paths) {
   
if (item.ocds) {
     
const ocdsPathArr = item.ocds.split("/");
     fillOCDS(item.path, ocdsPathArr, item.value, OCDSJSON);
   }
 }
 
return OCDSJSON;
}

BPE

A Business Process Engine (BPE) is a software framework that enables the execution and maintenance of process workflows. It provides business process interaction and communication between different data/process. The framework used to link and manage all MTender processes is Cassandra. You can read more about this in the section 4. Business Process Engine of the _ARCHITECTURE OF THE OCDS OPEN SOURCE CENTRAL UNIT OF THE ELECTRONIC PUBLIC PROCUREMENT SYSTEM - v3.0 document.

MTender uses ‘Camunda’ as the main business process engine (BPE). ‘Camunda’ is an open-source flexible framework for workflow and process automation with a native BPMN 2.0. in its core that enables the execution and maintenance of process workflows. It provides business process interaction and communication between different data/process sources spread across one or more IT applications and services.

   Learn more about Camunda BPE

Overview
AccessPoint
p class="c5">https://sandbox.bpe.mtender.gov.md

Request

All requests for Form Service are use POST-method (same as for parent Operation Service)

POST endPoint?specificParams[...] HTTP/1.1
Authorization: Bearer ...
X-OPERATION-ID: ...
Content-Type: application/json
Host: sandbox.bpe.mtender.gov.md

Specific Params

Set of specific parameters required in particular case. Described below.

Response

For all valid queries, the response will have a common structure:

202 Accepted
Content-Type
: application/json; charset=UTF-8

   Objects "schema" and "data" will be present even if they are empty

For all invalid queries, the response will have a common structure:

4XX
Content-Type: application/json; charset=UTF
-8
{
 "errors":[
  {
    "code":
"",
    "description":
""
  }
 ]
}

Functionality
How to work with
Expenditure Item (EI)

Create ei

To create new entity of EI standard POST data model should be used for preparation of POST-request for BPE. Such POST-request must be based on EI data-model and includes only required and optional data-fields.

POST /do/ei?country=...

Request parameters

country

Identifier of country of jurisdiction according to ‘country’ codelist

Update ei

To update existing entity of EI existing rules for update of EI must be considered for preparation of request.

POST /do/ei/ocid

Request parameters

ocid

OCID of EI to be updated

Funding Source (FS)

Create fs

To create new entity of FS standard POST data model should be used for preparation of POST-request for BPE. Such POST-request must be based on FS data-model and includes only required and optional data-fields.

POST /do/fs/ocid

Request parameters

ocid

OCID of parent EI

Update fs

To update existing entity of FS existing rules for update of FS must be considered for preparation of request.

POST /do/fs/ocid/fs-ocid

Request parameters

ocid

OCID of parent EI

fs-ocid

OCID of FS to be updated

Planning Notice (PN)

Create pn

To create new entity of PN standard POST data model should be used for preparation of POST-request

POST /do/pn?country=...&pmd=...

Request parameters

country

Identifier of country of jurisdiction according to ‘country’ codelist

pmd

Identifier procurementMethodDetails according to ‘pmd’ codelist

Update pn

To update an existing entity of PN standard Command Model should be used.

POST /do/pn/ocid/pn-ocid

Request parameters

ocid

OCID of parent Contracting Process

pn-ocid

OCID of PN to be updated

Contract Notice (CN)

Create cn

To create new entity of CN standard Command Model should be used.

POST /do/cn?country=...&pmd=...

Request parameters

country

Identifier of country of jurisdiction according to ‘country’ codelist

pmd

Identifier procurementMethodDetails according to ‘pmd’ codelist

Create cn based on pn

POST /do/pn/ocid/pn-ocid

Request parameters

ocid

OCID of parent Contracting Process

pn-ocid

OCID of PN to be updated

Update cn

POST /do/cn/ocid/cn-ocid

Request parameters

ocid

OCID of parent Contracting Process

cn-ocid

OCID of CN to be updated

Clarification

Create enquiry

POST /do/enquiry

Request parameters

cpid

OCID of parent Contracting Process

ocid

OCID of CN

Create answer

POST /do/enquiry

Request parameters

cpid

OCID of parent Contracting Process

ocid

OCID of CN

answer-id

Identifier of enquiry

Submission

Create bid

POST /do/bid

Request parameters

cpid

OCID of parent Contracting Process

ocid

OCID of CN

Update bid

POST /do/bid

Request parameters

cpid

OCID of parent Contracting Process

ocid

OCID of CN

bidid

Identifier of bid

Update winning bid

POST /do/bidDocs

Request parameters

cpid

OCID of parent Contracting Process

ocid

OCID of CN

bidid

Identifier of bid

Withdraw bid

POST /cancel/bid

Request parameters

cpid

OCID of parent Contracting Process

ocid

OCID of CN

bidid

Identifier of bid

Awarding

The award section is used to announce any awards issued for this tender. Releases can contain all, or a subset, of these awards. A related award block is required alongside every contract block, as the award contains information on the suppliers.

Update award

To update created ‘award’ standard data-model should be used for preparation of POST-request for BPE.

POST /do/award/

Request parameters

cpid

OCID of parent Contracting Process

ocid

OCID of CN

awardid

Identifier of award

Submit awarding protocol

Once winner is selected for each lot, CA submits the protocol which, in its turn, indicates the end of awarding process. To submit ‘protocol’ to particular stage CA should send related POST-request for BPE

POST /do/protocol

Request parameters

cpid

OCID of parent Contracting Process

ocid

OCID of CN

lotid

Identifier of lot


Contracting

Update awarded contract

POST /do/contract/ocid/ac-ocid

Request parameters

ocid

OCID of parent Contracting Process

ac-ocid

OCID of the contract to be updated

Issue contract to be approved

POST /issue/contract/ocid/ac-ocid

Request parameters

ocid

OCID of parent Contracting Process

ac-ocid

OCID of the contract to be issued

Approve contract

POST /do/confirmation/ocid/ac-ocid/request-id

Request parameters

ocid

OCID of parent Contracting Process

ac-ocid

OCID of the contract to be approved

request-id

Activate approved contract

POST /activate/contract/ocid/ac-ocid

Request parameters

ocid

OCID of parent Contracting Process

ac-ocid

OCID of the contract to be activated

Cancel awarded contract

POST /cancel/contract/ocid/ac-ocid

Request parameters

ocid

OCID of parent Contracting Process

ac-ocid

OCID of the contract to be cancelled

Master data service

AccessPoint

https://sandbox.public.mtender.gov.md

Functionality
Common Procurement Vocabulary

Common codes

GET /mdm/cpv?lang=...&code=09000000-3 HTTP/1.1
Host: sandbox.public.mtender.gov.md

Supplementary codes

GET /mdm/cpvs?lang=en HTTP/1.1
Host: sandbox.public.mtender.gov.md

Units of Measure

Class

GET /mdm/units-class?lang=... HTTP/1.1
Host: sandbox.public.mtender.gov.md

Units in class

GET /mdm/unit?lang=...&unitClass=... HTTP/1.1
Host: sandbox.public.mtender.gov.md

Organizations Identifier Schema

GET /mdm/registration-scheme?country=...&lang=... HTTP/1.1
Host: sandbox.public.mtender.gov.md

Geography

Countries

GET /mdm/country?lang=... HTTP/1.1
Host: sandbox.public.mtender.gov.md

Regions

GET /mdm/region?lang=...?country=... HTTP/1.1
Host: sandbox.public.mtender.gov.md

Locality

GET /mdm/locality?lang=...?country=...&region=... HTTP/1.1
Host: sandbox.public.mtender.gov.md

Languages

GET /mdm/languages?lang=en HTTP/1.1
Host: sandbox.public.mtender.gov.md

Currency

GET /mdm/currency?lang=...&country=... HTTP/1.1
Host: sandbox.public.mtender.gov.md

Procurement Method Details

GET /mdm/pmd?lang=...&country=... HTTP/1.1
Host: sandbox.public.mtender.gov.md