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 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 duplicated in the GovStack Confluence or GitBook since it is pertinent only to a specific compliant DPG, not the overall specfication.
(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: 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?
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>}
  }
  
  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.
(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.
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).
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.
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.
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:
  PubSub subsystem
  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 (https://github.com/nortal/GovStack-IM-BB-SandBox-Deployment) 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: Usage of X-Road

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
  PubSub subsystem
  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
PubSub subsystem
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.