HAPI FAQ – Working Documents API Overview and Key Information

HAPI FAQ – Working Documents API

Where is the Working Documents API documented?

XSD: https://bitbucket.org/sdo-hapi/data-models/src/master/schema/xsd/documents/harmonized-documents.xsd
OpenAPI: IEC API Portal – https://api-portal.iec.ch/ (developer account required)

Which legacy feeds does it replace?

IEC Data Feeds – Working Documents (XML): https://www.iec.ch/iecdatafeeds
DOCSEND CSV feeder (pacxxxx.txt), e.g. https://assets.iec.ch/public/feeder/pac0109.txt

Why are Working Document IDs different from the legacy feeds?

The legacy feeds grouped all files of a document in one entry. HAPI has one entry per file, so each file has its own URN (e.g. iec:doc:343967). A translation table between former and new IDs is available on request.

How do legacy fields map to HAPI?

Legacy XML tag / CSV field	HAPI element
`ID`	`urn`
`PROJECTS` / Project reference	`references/projects/project` (`urn`, `targetType`, `displayName`) → Projects API
`COMMITTEES` / Doc Committee	`originator` (`urn`, `targetType`, `displayName`) → Identity Management API
`NO` / Doc Number	`NNumber`
`TYPE` / Doc Type	`subType` (e.g. CDV)
`REFERENCE`	`reference` (e.g. `86B/4344/CDV`)
Doc Class	No longer used – part of `reference`
Doc Supplement (A, B, C…)	No longer used – part of `reference` (e.g. `86B/4344A/RVN`)
`TITLES` / Title EN, Title FR	`title xml:lang="en"`, `title xml:lang="fr"` (FR only if it exists)
`CIRCULATIONDATE`	`lifecycle/circulation/date`
`CLOSINGDATE`	`lifecycle/action/dueDate`
`FILES/FILEURL`	`releaseItems/releaseItem/contentRef`
Number of pages	No longer used
Previous Doc (committee, number, type)	Via the project's stages (see below)
Interested TC/SC	Committee codes of the TC/SCs interested in the project
– (new)	`lastChangeTimestamp`

What is in the `lifecycle` block?

Element	Content
`status`	Document status, e.g. `CIRCULATED`
`version`	Document version
`creation`	Creation date + actor (person URN, name)
`lastModification`	Last modification date + actor
`circulation/date`	Circulation date
`action`	Expected action, e.g. `actionType` = `VOTE`, with `dueDate` (closing date)

HTML

<lifecycle>
  <status>CIRCULATED</status>
  <version>1</version>
  <creation><date>2020-02-07T08:55:22</date><actor>…</actor></creation>
  <lastModification><date>2020-04-04T01:05:09</date><actor>…</actor></lastModification>
  <circulation><date>2020-02-07T00:00:00</date></circulation>
  <action><actionType>VOTE</actionType><dueDate>2020-04-03T00:00:00</dueDate></action>
</lifecycle>

How do I download the document file?

Each file is a releaseItem with type = DOCUMENT. Use contentRef/url:

HTML

<releaseItem>
  <type>DOCUMENT</type>
  <format>PDF</format>
  <contentLanguage>en</contentLanguage>
  <multilingual>false</multilingual>
  <contentRef>
    <id>980241</id>
    <url>https://api.iec.ch/harmonized/documents/download/980241</url>
    <contentLength>596999</contentLength>
    <mimeType>application/pdf</mimeType>
    <fileExtension>pdf</fileExtension>
  </contentRef>
</releaseItem>

contentLength gives the file size and mimeType/fileExtension give the format. There is one release item per language/file.

How do I find the previous document of a working document?

Take the project URN from references/projects/project/urn.
Call the Projects API for that project.
Read the documents attached to each stage.

Example: the previous document of a CDV is on the ACDV (30.99) stage → iec:doc:345137, type DECISION, subtype RR, name 57/2327/RR.

What do the URNs in a working document point to?

references/projects/project/urn → Projects API
originator/urn → Identity Management API (committee)
lifecycle/.../actor/urn → Identity Management API (person)

How are working documents linked to other APIs?

Projects API: each stage lists its documents (URN, type, subtype, name).
Ballots API: the Compilation of Comments (CC) download requires the FULLDOC permission in the Working Documents API.
Meetings API: official working documents linked to a meeting carry their Working Documents URN. Other meeting documents have a direct download URL only.