Frequently Asked Questions

Disclaimer: Don’t assume the attempted answers as correct as we are exploring on connecting all the dots.

Questions Reordered by Priority

Top Priority from Integration Perspective

Should PubSub APIs be used for async API communication between Building Blocks? Ex: Registration BB consuming Pay BB Batch transfer API to disburse benefits to a list of beneficiaries.

Allan’s answer: As far as I understand the GovStack core principles all communication between BB's should use Information Mediator. So from that perspective the answer is yes.
(15) Do you think that any of the documentation in Confluence and Gitbook and Github points to BB integration scenarios? Context: All flow/UML diagrams have missing actors for applications (sub-systems or the underlying service producing the REST API)
1. Attempted Answer: Addressing remarks diagram shows an arrow between Information System A and a system for mapping protocol headers with the arrow labelled as Headers to be transformed. Can this be elabored?
  
  Allan’s answer: please DO NOT take information out of context and PLEASE do read documents fully to understand them. This specific example was given to illustrate the difficulties that WOULD arise IF this solution would have been implemented - it never was! THIS DOES NOT DOCUMENT THE SYSTEM AS-IS!
  
  IM-BB SandBox sample implementation uses X-Road as a (compliant) base technology. To understand how to integrate with it, understanding of x-road is needed. First and foremost, please read through (and I mean READ and THROUGH, not just skim for information) this: https://docs.x-road.global/
  The mechanisms of connecting sub-systems to x-road are documented in the Security Server user guide: https://docs.x-road.global/Manuals/ug-ss_x-road_6_security_server_user_guide.html#version-history
  
  This information IS NOT and will not be duplicated in the GovStack Confluence or GitBook since it is pertinent only to a specific compliant DPG, not the overall specification. Technologies other than X-Road may be proposed as candidate solutions in the future and those technologies would in turn have their own documentation as well.
  
  On the topic of X-Road:
  X-Road is an open source DPG which has an excellent community so if you are a technician installing/integrating with the sandbox implementation IM-BB, I highly recommend to engage with the community chat there. You most likely will get x-road related questions answered there much much faster than here:
(16) If X-Callback-URL in Pay-BB API is not being passed by the Room (receiving the publish API call) to the underlying REST API, then how do we map the callback to the pushURL specified in the event type subscription call to SS04(Pay-BB)? There are no references to implementer documentation in the demo or in the documentation. The question is elaborated through the below diagram :-
1. Attempted Answer: diagram shows an arrow between Information System A and a system for mapping protocol headers with the arrow labelled as Headers to be transformed. Can this be elabored?
2. Alternative attempted answer: Consume Get subscribtion API(IM BB API) for event type batch transfer from bulk processor or IMBB transformer service. Get the registered push URL and set it as a batch transfer callback URL config through a new API so that batch transaction x-callback-url header can be made non mandatory.
  
  Allan commenting on the attempted answer: Please read documentation in full and do not take information out of context! The diagram linked is a hypothetical scenario that was never implemented and will never be implemented. It serves to illustrate the complexity of changing the X-Road protocol headers to IM-BB protocol headers for a sample implementation in SandBox.
  
  Allan commenting on the alternative attempted answer: This would not work since x-callback-url can not be called from inside IM-BB network. ALL communication between subsystems has to go through a security server, which acts as both ingress and egress proxy to the IM-BB network. Any external urls CAN NOT! be called using IM-BB.
  It is a SECURE network and protocol, not an API gateway or average COTS reverse-proxy. Nothing other than a security server can talk to another security server in the network and they use their own protocol headers which (for the sake of current discussion) a subsystem CAN NOT affect in any way shape or form.
  
  Allan’s answer: X-CALLBACK-URL and other not protocol specific headers will not be passed on by IM-BB protocol. Please bear in mind that a subsystem can not directly communicate with another subsystem, that would violate the four-corner data exchange model among other things.
  A subsystem (A) will use a security server to contact another security server which in turn will contact the other subsystem (B) (four-corner data exchange model). The message coming from subsystem A will be encrypted and signed by it's security server, the message headers that the message will have will be IM-BB specific (in sample implementation X-Road specific) the other security server will receive the message, verify the signature and origin and if everything checks out decrypt it and pass it on to subsystem (B).
  X-CALLBACK-URL will not make ANY sense here since a callback would have to transverse the same route! You CAN NOT "call-into" an IM-BB network from outside sources (i.e. without using a security server), you CAN NOT "call-out" from an IM-BB network to outside sources (i.e. to any other URI than a registered security server).
  Your callback would have to be in a IM-BB compliant protocol form, meaning the member and subsystem to be contacted. Which also means you would have to specifically handle it anyway on the receiving end.
  Any information that a service would like to transmit to another service would have to be specified in the request content. It can be wrapped, for example:
  
  "content": {
  "customHeaders": {<any header information you'd like to attach>},
  "payload": {<actual message payload>}
  }
  
  (Both field/object names are completely arbitrary here and there can be more wrapped inside the “content” object - which is not arbitrary and the only part actually required by the PubSub system.)
  
  The receiving Security Server would the pass that on the relevant subsystem which in turn must be capable of reading (and understanding) both the “customHeaders” and “payload” object.
  
  In essence, you would need to pass the call-back location as part of the message and the receiver should have the logic to extract that (also see X-Road documentation on obtaining the memberID of the Security Server that sent the message and accessing your own Security Server), compile the return to a IM-BB protocol compliant request submitted through its Security Server.
(17)a) Is Sandbox team maintaining the Playground environment?
b) What is the impact of playground environments being migrated?
c) Can the team maintaining the Playground environment (having IMBB installed & configured as per the demo video) share the Postman environment file for IMBB or a list of URLs & the list of secrets for accessing UI, creating rooms, creating event types, etc?
(1) Please confirm that the Owners in the diagram are ministries / registering institutions. Ex:- Registration BB publishing and PayBB subscribing. In the case of callback responses, isn't PayBB publishing and Registration BB subscribing. For this communication, is it fair to assume that both Registration BB and Pay BB has to create separate rooms?
1. Definitive answer is outstanding.
2. Attempted answer:
  Event Type creation with Message schema is part of Room creation and not part of subsystem creation. Rooms are linked to Subsystems through Managers. If BatchTransfer API is in a sub-system of Pay-BB member, the Manager for G2P-Pay Room links the room to the sub-system. Event Type Batch Transfer API is then inside the G2P-Pay room.
  
  Allan commenting on the attempted answer: Yes an event type is specific to a room and an event type can not exist without a room to be tied to. However rooms can have multiple event types or exist without an event type entirely. So while some clarification is needed, overall the assumption is correct.
  
  However the idea that Rooms are linked to Subsystem through managers is completely wrong. IM-BB has members, members have security servers and subsystems provide the services (in the form of OpenAPI definitions) inside IM-BB. Those services are registered in their respective Security Server and collected and published (in the service discovery) by the Central Server.
  
  PubSub component itself is also a sybsystem, providing two services Messaging API and Management API, which can be interacted with by any other service WITHIN the IM-BB network. For this the Security Server exposing PubSub has to allow the connection (familiarize yourself how service authorization is handled in X-Road documentation). For the push notifications to work the other side’s Security Server also has to enable incoming communication from the PubSub.
  
  Manager can be local (interacts with room using UI deployed in the same system as the Security Server and PubSub component) or remote (interacts with room using calls to the Management API, over X-Road).
  
  So first and foremost you’ll have to make sure that the systems can communicate by enabling that in eachothers security server. For PubSub side (where the room resides) you’ll have to enable incoming connections from each other Security Server, this has nothing to do with rooms (yet) you are enabling the systems behind the other security server to interact with the PubSub system. Then you’ll have to assign the (much more nuanced) access rights in the Management UI by specifying who (from those who can access the PubSub component on the infrastructure/X-Road level) can interact with which room and concerning which event types.
  
  In your example (without having an in-depth knowledge how MIFOS works - sorry) the RegistrationBB as a central component would be set up behind an instance of IM-BB, able to access both the Management and Messaging part of IM-BB. It would register both Management and Messaging as services in their Security Server.
  
  It would then use Management UI to create the room(s) and Event Types (with message schemas) it would need to enable its functionality. It can be the same room with two types of events specified (requests from different PayBB’s and responses, in case of callback, from RegistrationBB) or it can be two separate rooms for different messages.
  
  In any case RegistrationBB would then subscribe to the room (they can interact with their IM-BB ManagementAPI locally and also access the messages using the MessagingAPI locally) where he intends to listen to the messages from PayBB’s and would add itself as a publisher to the room it would want to publish the answers (can be the same room, you can be both a subscriber and a publisher at the same time, even for the same event type - but in this example it would be different event types).
  
  Now if PayBB’s (and there may be multiple) want to connect to that. First they would have to deploy their own SecurityServer part of IM-BB, deploying or configuring the PubSub is not necessary for them since the room’s are created on RegistrationBB side. They can install the component but it’ll do nothing.
  
  Second they would have to register their service (using their OpenAPI declaration) in their IM-BB’s SecurityServer, that is x-road specific, ManagementAPI is not involved. A service does not have to provide any endpoints or features, it can be there to just publish messages to some other room or subscribe using PULL only. But it can, if it wants to receive push messages or provide other features inside IM-BB network.
  
  -- now we have a basic setup. There are two security servers, one running the PubSub components the other some custom service (even if it doesn’t provide any endpoints). The central server’s service discovery should show at least 3 services, Management API, Messaging API, PayBB’s service.
  
  Now accesses need to be handled on the X-Road level. RegistrationBB’s Security Server must be configured to allow access from PayBB’s SecurityServer to it’s PubSub services (management and messaging) and if callbacks are to be handled also communication towards PayBB’s published service (now for messaging only because management does not communicate out).
  
  PayBB’s security server should be configured the same way. Allowing outgoing information towards RegistrationBB’s Management and Messaging API services and in case of PUSH is needed also incoming traffic from Messaging API.
  
  -- now the X-Road part of the system should be fully functional. Now (using the PubSub Management UI) the PayBB (using it’s SecurityServers member code, selected from dropdown) can be added as a publisher to the room they’d have to publish their requests to, with the event type(s) they are able to generate. For subscriptions PayBB would then have to use the ManagementAPI (over X-Road since they are behind different Security Servers) to subscribe to the room they would be listening for responses from RegistrationBB, in case callback functionality is needed (correlation ID’s can be added to the payload - but NOT the headers, custom header’s will not be submitted by IM-BB protocol as discussed earlier in this document).
  
  PayBB’s can now publish to the room(s) on RegistraionBB side over x-road, RegistrationBB will be polling (or receiving push notifications) from the MessagingAPI which is local to their environment and respond in kind - which then PayBB would be polling (or receiving push notifications) over X-Road.
  
  All transactions between Security Servers are encrypted and so can transverse the public internet. Detailed information and logs are generated and kept at each Security Server location and general logs and metrics collected by the Central Server using the X-Road Metrics component.
3. Based on assumptions made from watching the video and reading documentation, SS2(REG-BB) is subscribing to BatchTransfer eventType with pushUrl specified. When SS2(REG-BB) request/event publishes to SS4/PAY-BB, then callback goes to that pushURL and a second room creation is not required. So both publishing messages and subscription to the BatchTransfer event type can be done by SS2(REG-BB).
  
  Allan’s answer: That would be correct.
4. 1a: How would a different SS (ex: RegistrationBB, SS2) publish an event to Pay-BB/SS4? OR
  Is Sub-System(Service) Access shown in first video giving indirect access for one SS to publish events to a room of another SS?
  1. Attempted Answer: Yes, service access has less to do with rooms and more to do with sub-system with REST API access. Perhaps around 17:16 in the first video or not clearly shown in the video.
    
    Allan’s answer: I have explained the mechanism in detail in a previous answer however yes, any system behind any Security Server can be given access to publish to a room in another location’s Security Server. There are two access layers to consider. Allowing one subsystem behind one SS to access another subsystem behind another SS, that is done using X-Road and then there’s managing the PubSub part that is done using Management API and/or Management UI.
    
    One system (with its own SS) can publish events into a room another systems (with a separate SS) message room and it can even be a manager of the room (i.e. CRUD event types, publishers, subscriptions for that room) using Management API of that PubSub instance over x-road.
5. 1b: How is PatientPortal Room (linked with a Manager from SS4 subsystem) being used in SS2
  1. Attempted Answer: Based on the assumptions from previous answer, these are done through sub-system(service) access which is indirectly linked to Rooms through Managers.
    
    Allan’s answer: If the PatientPortal room is created on the SS2 side and managerial access to that is delegated to SS4 then on the SS2 side it does not necessarily have to be used in any way.
    
    But it can be used - on SS2 the Management API can be used directly (without going through x-road) to subscribe to rooms and messages. If the manager on the SS4 adds the system on SS2 side as a publisher for an event type then on the SS2 the Messaging API could be used for publishing messages to that room (also without “calling out” over x-road).
    
    The idea here is that it may be necessary for a central authority to host the actual PubSub instance - or a ministry office wants to keep their data on-prem for compliance reasons. In that case they can set up rooms in their system that someone else (over x-road) is actually managing using the Management API. Those managers can not create or delete rooms but within that space they have the autonomy over dataflow, while the data itself and logs are kept on the central side.
    
    A more common usecase however is that the manager of the room is also (within) the system that sets up the PubSub - and using Management UI for that, with roles and users defined in Keycloak. Everyone else can either publish or subscribe. That would be the most common usecase.
6. 1c: Will Schema validation one day provide aggregated errors related to mandatory fields, field data type failures, field length validations?
  
  Allan’s answer: If the question is regarding whether the PubSub component will eventually return a message containing detailed validation errors for creating an event based on event type (i.e. if the event created does not conform to event type schema defined) then I'd say "anything is possible" and the PubSub component code is open source, so anyone can either fork it or propose changes, it would not be overly complex to achieve for a Java developer. However currently no further updates for the PubSub component are planned and no resources allocated, so the specific answer to any feature requests is - no.
7. 1d: Would subscribing with pushURL get them the response from PayBB to RegBB?
  Attempted Answer: I don't think a separate room is required on RegBB for async callbacks from PayBB to RegBB.
  
  Allan’s answer: The attempted answer is correct. If the pushURL is (correctly) specified as a subsystem behind another Security Server and that Security server has been configured to allow messages from the Security Server where PayBB resides - the messages will go through without the need to even have a PubSub component on the RegBB side, let alone creating a room for that.
8. 1e (Promoted to top level question number 16): Refer Q16.
Why specify REST API name once in Subsystem and do a similar step during EventType registration
1. Attempted Answer: Event Type Schema is the request body schema where REST API defined in SubSystem is not related to message schema validation. If you publish a message that doesn't match with the schema, event is rejected.
  
  Allan’s answer: I do not fully understand what is meant by "REST API name" here. Attempted answer is correct in assuming that the event type schema is the request body for an event to be published and that the service ("REST API") defined as a SubSystem within the security server is not directly related to it.
(4) Which API or configuration to use to subscribe to event type? We can't find these in published Service APIs.
1. Answer: We have found the API in the demo.
2. Follow up question 4b: Where can we find the IM-BB Postman Collection? There are several disconnects between shared Open API specifications and Postman collection and we would prefer to use the Postman collections in the demo video.
  
  Allan’s answer: There are no disconnects between the Postman collection shown during the demo and Open API declarations specified for the sample implementation:
  
  Since it is a actual implementation and thus more specific (having more details) than the overall IM-BB specification then yes the Open API specifications given in the GovStack IM-BB specification will not have all necessary functions and should not be used to generate collections. However the specific Open API declaration I just linked absolutely do have all the details.
  The Postman collection seen in demo is not available since it was created for the demo only, including demo and environment specific information (including access keys).

Tier 2 priority Questions

(14) Where is the default helm chart which sets up all the components with sensible defaults for the GovStack usecase without a lot of steps embedded in CI?
1. Attempted Answer: No such Helm chart exists at the moment.
  This repo ( consists of X-Road chart, X-Road SS chart and multiple charts for each separate PubSub components and couldn't find a parent chart combining all of these charts and configuring them with post-install K8s jobs.
  
  Allan’s answer: Since a production-grade, cloud-native deployment of a core infrastructure component like IM-BB was deemed too costly and impractical for the SandBox purpose, there is no such deployment and it is unlikely that one will be created. Since for the current sample implementation of IM-BB that would necessitate a large-scale rewrite of X-Road DPG.
(3) If we agree on the exact room names and event type names with registration BB, then is there a need to do the optional discovery steps (list members, list rooms, list event types)? Or is the recommended way to find the room name and event type is by hitting the APIs instead of talking with other Building Blocks and waiting for their response?
1. Outstanding. Reduced priority of the question to Tier 2.
  
  Allan’s answer: If the exact configurations are known the communication can be enabled without any discovery. However the second part sounds like you are thinking of linking Building Blocks directly - that MUST NOT be done since it would not be a secure and governable communication and would go against the core principles of IM-BB.
  If you do know the rooms and event types beforehand you can set up your systems to communicate with those without the discovery, however they should still communicate using IM-BB

Tier 3 priority ------

Rooms UI cannot be accessed from CS UI and can be only accessed from Management UI. Is Management UI from CS or SS or both?

Allan’s answer: There are three distinct UI's not connected to eachother. The fact that they look visually similar does not change that. X-Road DPG as an underlying technology uses two types of UI's. The Central Server has its own UI and each Security Server has its own UI.
The Management UI for the PubSub system is separate from both - however since PubSub is always deployed together with a Security Server they share users and acces roles - both use the KeyCloak that is packaged together with them.
Anything related to managing the PubSub component can not be accessed from UI's of the underlying X-Road DPG, from x-road's (and it's UI's) perspective anything related to PubSub is just a subsystem. PubSub has it's own management UI.
30:23 Which servers produces the Subscriber Mock pushURL API registered in subscriptions API?

Allan’s answer: it is an EXTREMELY simple application (few lines of code that just creates 1 endpoint logging the message to console) that has been registered as a subsystem on the "subscriber" end. This was created solely for the demo purpose and was running as a separate container/instance within the subscriber network (i.e. behind subscriber’s Security Server and registered in that server as a service). Substitute that with any system (register it as a subsystem/service in it's security server) and endpoint you'd like to receive messages on.
(12) How do we link an event type with an OpenAPI API which is part of a larger OpenAPI file?
Outstanding
Why create a fork of X-Road?

Allan’s answer: please see the documentation (including documentation for/of the changes) here:

Questions solved by the Demo :-

(2) a)Where can we find Room creation API / config steps?
1. Attempted answer 2a: Based on the demo videos, major configurations are UI driven (or config driven) and there is NO plan to provide Room Creation APIs or Event Type / Message schema registration APIs. This essentially means we cannot write end to end integration tests and have to rely on already pre-configured continuously (throughout the year) accessible environments to make integration tests pass.
From the perspective of X-Road both Management API and Messaging API will need to be registered as a subsystem and their API definition provided.
1. So registration of Management and Messaging API was both from post-deployment configuration perspective and to provide a demo for implementer perspective.
(5) Add subscription API looks like a room subscription API. Where is the event type ID? Is srcOperationId or dstOperationId the event type?
1. Postman API shown in the demo solves this problem but we can't find the Postman collection.
  
  Allan’s answer: The API's are documented here
  
  Postman collections where specific to the demo and are not available.
(6) Which API to use for publishing events?
A: Postman API shown in the demo solves this problem but we can't find the Postman collection. 34:10

Allan’s answer: The API's are documented here

Postman collections where specific to the demo and are not available.
(8) Shouldn't OCSP be setup and configured only by Sandbox team? If yes, how are things moving on this front?
A: See demo video 11:58. If Sandbox moving to new Sandbox creates some sort of outage and we need to install IMBB stack in our cluster, all related questions will reopen.
(9) Responder Cert - Shouldn't sandbox team create a certificate (by setting up CA, configuring OCSP) for Payment BB instead of us doing self signed certificate?
A: See demo video 11:58 onwards.
Previously Answered:
(7) Check access rights - How to configure PayBB security server with the access rights for certain events? Assuming that this is not a responsibility of Central Server based on the diagram.
Aleksander Response: Security Server has UI for assigning rights to services. You as Payment BB declare what applications can reach you. If you want to reach application X, then admin for X must allow this access.
(10) OCSP Check requestor cert - Are there any steps or configurations that PayBB Security Server needs to do?
Aleksander response: Not sure but I think that no.
Allan's response: Aleksander is correct, if the OCSP is working and Security Servers where provided the correct anchors from the Central Server, it should just work.
(11) Check document signature - Are there any steps or configurations that PayBB security server needs to do?Defining event type
Aleksander Response: No

Q&A captured from the Demo Video

Is TSA part of Central Server?
1. TSA is part of Central Server Image.
Are SubSystems services?
1. Yes.
What's a Member from GovStack perspective?
1. Each BB is a Member.
What's an anchor?
1. Anchor is a secret for service accessibility.
A room has multiple APIs so it can be considered as a set of APIs serving one use case.
1. Example attempt :- G2P Batch Transfer Room can have batch transfer and channel transfer APIs.
Is "Sandbox/org/client/test" the room name or test is the room name?
Not sure. "Sandbox/org/client/test" is the room name. Patient Portal is a demo pre-existing room.