EMA Write PMS API Implementation Guide - Enrichments
1.0.0 - ci-build

EMA Write PMS API Implementation Guide - Enrichments - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Examples

Example API Requests

The following diagrams show the steps necessary to retrieve a product Bundle, make changes, and then update it.

GET [base]/MedicinalProductDefinition/[pmsId]/$everything (Get Bundle)

The following diagram shows an example product Bundle being read. The product version is 16 and the initial package size is 10. The version number is significant when it comes to updating, and the package size is what this scenario will be editing.

Get Bundle

POST [base]/MedicinalProductDefinition/$merge

In this example, the user attempts to change the package size of the same product to 20.

$merge

POST [base]/MedicinalProductDefinition/$merge - Response

In this example, the response to the $merge request has been asynchronous (HTTP 202 – Accepted), and a 3rd request (Content-Location URL) will have to be executed to fetch the result.

It could have been synchronous (HTTP 200 – OK). In those cases, the returning bundle (after the change) can be immediately found in the response body. It is not necessary to execute the extra request presented in the next section.

$merge Response

GET [location header URL] (Async)

A request to the async url returned by the previous request. The package size was correctly changed to 20 and the product version was incremented to 17.

Get async $merge

Examples - A more complex use-case: Create/Delete Manufacturers

Resource Diagram

The previously API request examples show how to change a node (package size) of an existing domain resource (PackagedProductDefinition).

The Write API allows using the same API Requests for something more complex: adding or deleting entire (inter-referencing) domain resources.

One realistic use-case for this would be the creation or deletion of a Manufacturing Operation.

This API represents a Manufacturing Operation using the ActivityDefinition resource for the operation itself, and a RegulatedAuthorization to say that it is officially approved.

To Add a manufacturer, one has to:

  • Add an ActivityDefinition
  • Add a manufacturing RegulatedAuthorization, which points at the ActivityDefinition
  • Add a MedicinalProductDefinition.operation node, which also points at the ActivityDefinition

Consequently, to remove a manufacturer, one has to:

  • Remove the ActivityDefinition
  • Remove the manufacturing RegulatedAuthorization
  • Remove the MedicinalProductDefinition.operation node

These Resource/Nodes are marked in red below:

Create/Delete Manufacturers

Inter-Resource referencing

When a new resource is created, PMS assigns it a PMS ID.

Because new resources don't yet have this ID, when it is necessary to add two new resources at the same time, which reference each other, a special technique must be used. This will make sure that the FHIR server establishes the association between them, even though the IDs are not yet assigned.

To do this, it is necessary to add to each new resource a Bundle.entry.fullurl node, to act as a temporary id, like this:

  • <fullUrl value="urn:uuid:a57ef872-40cf-4bc8-a486-211ba46f367f" />

This can be any valid uuid, but each fullUrl must be unique within the Bundle.

(In this example the resource is an ActivityDefinition)

Then, on the resource that references this new resource (whether the referencing resource is new or old), add a reference to the new one, using the same uuid:

  • <reference value="urn:uuid:a57ef872-40cf-4bc8-a486-211ba46f367f" />

(In this example the resource referencing the new resource is a Manufacturing RegulatedAuthorization).

This will create the necessary link between the new ActivityDefinition and the new Manufacturing RegulatedAuthorization.

If, instead, the resource already existed, to reference it from a new resource, one would use:

  • <reference value="ActivityDefinition/123456" />

(where 123456 would be the PMS ID)