Wednesday, September 25, 2024

#1026 - OIC REST API Log file download - How To for OIC3

 

This OIC Gen2 api lets you download -

  • ICS Diagnostic Log
  • ICS flow log
  • Audit Log
The request format is as follows - 

https://oicpm-oicpm-px.integration.ocp.oraclecloud.com/ic/api/integration/v1/monitoring/logs/log


The valid log values are -

  • icsdiagnosticlog
  • icsflowlog
  • icsauditlog

Download the Diagnostic Log

I now download the diagnostic log and see the following, when I unzip it -
Note the structure -



The following files are weblogic specific -

  • access.log
  • oic_server1.log
  • oic_server1.out
  • oic_server1-nodemanager.log

As you can see, this is essentially of little use to an OIC admin.

Now to the ics-flow.log

It does contain OIC relevant data e.g. 


 

ActionID:y0][ActionName:InvoicesToATP][ActionType:Return]: Response received from InvoicesToATP
[2024-09-09T16:45:09.088+00:00] [oic_server1] [NOTIFICATION] [] [oracle.ics.trace.soa.bpel] [tid: 102] [userId: niall.commiskey@oracle.com] [ecid: d505d8d9-9d4e-48cb-9f6f-ee1c4a2edd04-002e7192,0] [APP: soa-infra] [partition-name: DOMAIN] [tenant-name: GLOBAL] [FlowId: 0000P7NfC8v5uXdLxe4EyW1anhva0002yu] [oci.instanceName: OICPM] [oci.identityDomain: identityDomainName]  [ICS Activity Stream Logging]: [Code:INVOICESTOATP][Version:01.00.0000][Instance:62405859][Operation:execute][ActionID:y0][ActionName:InvoicesToATP][ActionType:Return]: Integration execution has completed

However, it's not that readable.

Same applies to the oic_servern_diagnostic.log -


I'll skip the nodemanager log as that is pure weblogic.

Net, net, these logs are useful for checking out engine errors, but are not useful from a compliance perspective, e.g. these files don't help you prove that orderNr 123 was processed on a certain date.

Download the ICS Flow Log


The Structure of the downloaded zip - 











I executed the following simple integration, before running the REST request -





Now I activate the integration with trace enabled - 

I download the log file again, and now I see the payload in the log -


Net, net - the ICS flow log is useful, when you enable tracing / include payload.

Download the Audit Log

This log details who did what in the designtime -

e.g. here my activation of the integration has been audited - 

[2024-09-25 13:29:17.577] [userId: niall.commiskey@oracle.com] [niall.commiskey@oracle.com,ACTIVATE,ICS_ProjectV2,AA_SIMPLE_SYNC_WITHCHIL,AA-Simple-Sync-WithChild,01.00.0000] User niall.commiskey@oracle.com activated Integration AA-Simple-Sync-WithChild 01.00.0000
[2024-09-25 13:29:17.361] [userId: niall.commiskey@oracle.com] 

So now we have looked at what's available from OIC gen2.

Let's turn to OIC3.

OIC3 Retrieve Audit log

























Note the structured format of the response, easier to read and process, compared to OIC Gen2.

The following OIC3 api can be used to retrieve instance flow details, similar, but not the same as the OIC gen2 ICS Flow log. - 







The response is as follows - 



As you can see, even in debug mode, the request payload is not returned.

What we do see, however, is the tracking fields and their values.

So how can we retrieve the integration flow request payloads?

First, let's take a step back - 
Customers usually use the OIC gen2 log api on a daily basis, for example, run the job to download the ICS flow log on a daily basis and push the response to a monitoring / analysis tool such as Splunk.

So, from an OIC3 factory api perspective, I could do the following - 

1. Retrieve integration flow instances for the time period e.g. for the last day.

2. For each of those instances, retrieve the request payload.

Let's look at 1 - 





note the id returned - 

that from the screenshot is as follows - 
na1TEHvfEe-BH8NDEl59ew

I will now use this to retrieve the payload via the activity stream, this is task 2 -


 

 
Final step is to automate this with OIC. Here I create a scheduled integration that will invoke both apis. In my simple demo, I will write the instances + payloads to a file.


















Wednesday, September 18, 2024

#1025 OIC Healthcare - FHIR adapter

 

Introduction

So what is FHIR? 

The HL7® FHIR® (Fast Healthcare Interoperability Resources 1 ) standard defines how healthcare information can be exchanged between different computer systems regardless of how it is stored in those systems. It allows healthcare information, including clinical and administrative data, to be available securely to those who have a need to access it, and to those who have the right to do so for the benefit of a patient receiving care.

More details here.

Creating a Patient

Now the usual caveat to begin with - I am not a FHIR or healthcare expert - I just like showing how easy it is to use Oracle Integration. 

So, to our simple use case - Create Patient.

I tried this out first with an online FHIR server - kodjin from an Estonian company, Edenlab. 

I copied the request payload for use in OIC.

Next step is to create a FHIR connection in my OIC3 Project - 

I then created the following integration -

I used the request payload from kodjin as the REST trigger request body.

Now to the configuration of the FHIR invoke -  

I map the fields I see in the example request from kodjin.

 

I just return the id from the FHIR invoke response - 


Let's run it!














I create a new patient - Cathal Brugha - and copy the id returned.

I use this id to do a GET in the kodjin app - 



 

I now create a new integration - getPatient -


 
I create a new patient - Michael Davitt -

Now to the GET - 
























Monday, September 9, 2024

#1024 Introduction to OIC API Catalog & Portal

 

Introduction

Many OIC customers expose the apis of their integrations to internal, and, maybe also, external developers. Usually these integrations are REST or SOAP driven, i.e. have REST or SOAP adapter based triggers. 

The management of such apis is crucial and drives the need for -

  • The ability to manage the lifecycle of Integration APIs
  • The ability to decide which integration apis to expose to developers
  • Control over who has access to those apis
Such requirements also require a consumer/developer portal where developers can -
  • Browse/Search for apis
  • Try out/test apis
  • Provide feedback on apis
  • Get access to apis, so they can leverage them in their apps 

The Oracle Integration Cloud | API Catalog & Portal fully addresses the requirements listed above and actually does more!

So what is it?

It's a new version of digitalML's leading api management platform, ignite, which is now available exclusively for OIC. This provides api lifecycle management via the API Catalog component and developer access to apis via ignite's  Consumer Portal. This flavour of digitalML's ignite,  is available from the Oracle Cloud Marketplace.

Here is the direct link to the offering -

 

As already mentioned, this service is purely for the harvesting and management of OIC Project based integration APIs. The API Catalog allows one to define a connection to an OIC instance. Authentication is via OAuth, so one will need to define a confidential app/integration application in one's OCI Identity domain. This will generate the client id and secret, used as part of the connection definition for OIC.

From the API Catalog one can import OIC Projects and their integrations. OIC Projects can be public or private, this is achieved by applying RBAC to a project. 

Setting Can view to Everyone makes this a public project in the context of our new service. This means that I will be able to import the integrations contained in this project to the API Catalog. Private project metadata, e.g. the project name, description will be viewable in the API Catalog, but none of its integrations can be imported. 

So we have looked at how the service connects to OIC; we also looked at how Projects RBAC controls which integrations can be imported,. So with those basics addressed, let's try it out!




API Catalog 

The API Catalog is the tool for managing the lifecycle of your OIC integration apis. Within the catalog, one can also enrich the api definitions, for example, by adding supplementary documentation. The catalog admin can also decide which apis to expose to developers via the API Consumer Portal.

The following 3 options are available, when one logs into the catalog - 

  • Discover - browse existing OIC projects, i.e. those that have been previously imported. Check out the integration metadata.
  • Import - Import a Project and all its integrations, or selectively import specific integrations from a project.
  • Reporting - Get an aggregate view of the catalog contents 

 

I click Import -

There is only one option here, as you can see. Well it is the Oracle Integration Cloud | API Catalog & Portal - 

However, there is a standard version of ignite available, also on the Oracle Cloud Marketplace, which is a generic api management platform. More details on that are available here


 

Now back to our import, on clicking OIC Import, I am presented with a list of the projects in my OIC instance - 

Some are highlighted in green, indicating they have already been imported. However, this could also indicate a partial import i.e. just some integrations have been imported.

As alluded to above, one can import a project with all of its integrations, or browse a project and import specific integrations. So let's go through a couple of scenarios -
I click on a private project, AA-ERP-Project, to begin with -


As you can see, visibility is restricted, I do not see any of the project integrations. Now to importing a complete project -


Finally, importing an individual integration - here I can open the project and browse its integrations, selecting those I require to be imported.  

Now that the import, in all its facets, has been addressed, let's look at the API Catalog view of one of my OIC projects, AA-Demo-OrderProcessing - 















Note the 4 Tabs, cataloguing the 4 types of integrations we can have in OIC - REST driven, SOAP driven, Event Driven (e.g. integrations firing on Fusion ERP business events) and scheduled.

Only REST and SOAP driven integrations are interesting from a developer perspective, however, the goal here is to give the catalog admin a comprehensive overview of the OIC projects and their integrations.

Project documentation, entered in OIC, is also surfaced here, along with keywords etc.   

Let's look at the approveOrder integration in detail - 

This screen gives us 2 views, the OIC and ignite Catalog view. Forgive me, but I have to split the screenshot because of space limits -



I now click on the ignite view link - 
This is the catalog view of the integration. I will not go through all of the sidebar menu options in depth, after all this is an introductory post, and I need to leave some content for future posts. But let's look at some of them - 

Interactive Documentation


Deploy to Portal - Ability to deploy this integration api to the Consumer Portal.

Methods


the method toolbar supports the following - 

  • try it (i.e. mock server tester)
  • View Payloads
  • View Parameters
Feedback - supports communication with the consumer portal users. Developers can raise questions about the apis in the Consumer Portal; they can also make requests to get access to an api. In the other direction, the API Admin can raise notifications about apis that can be surfaced in the Consumer Portal. These notifications can also be sent via email to developers, once they register for such.

 

Attachments - the openapi spec for the api is the default attachment one sees.However, one can add other attachments, for example a document describing the integration/api in more detail. This new attachment could be marked so that it is surfaced in the Consumer Portal.




Export - downloads the openapi spec.


Policies - detail the security policy attached to the api, e.g. OAuth 

This api has already been published so let's check out the developer experience.

Consumer Portal
























Here's my approveOrder api - 

Let's go through the menu here - 

About - provides the high level details and is the default form shown -

Methods - lists the methods/verbs supported by the api, in my case, it's just POST -

Attachments - as you can see, the api admin has uploaded an attachment to this api. The developer can, naturally, download attachments from here.

 
Documentation - here the developer sees the api details and can try it out.

Download OpenAPI Document - does just that.

Contact Provider - here the developer can ask the api admin questions. She can also provide feedback on the api.

Provider Updates - this is where updates from the API Catalog admin surface.

Get API Access - here the developer can request access from the API Catalog admin.

Now that is a very high level overview of the API Catalog and Consumer Portal. Finally, let's look at the configuration features of this offering.

App Configuration

I click on the Settings icon in the API Catalog

Catalog Branding allows me to have my own look and feel, logo etc.

Jobs Queue - imports to ignite are asynchronous. The jobs queue gives me insight into progress and import status etc.

Portal Management

The admin can create "global" portal announcements. These surface in the Consumer Portal under Latest News - Announcements.

API Access Form Configuration - here you can configure the form presented to the user when they click Get API Access in the Consumer Portal.

Portal Branding - use your own logo, configure the welcome message etc.

Email Notifications - we're back in the main menu now. 

Here you can specify when emails are sent, e.g. admin creates a new notification for an api, and the developer receives an email with the details. You can also add a regular expression for email validation, if required.

The admin can create email groups - 

You can also configure ignite to use your email server -

Finally, let's look at the synchronization between OIC and ignite

I can refresh the project manually, but there is also autosync available - 
So you can decide when and how you synchronize with OIC.

Summa Summarum

This is a very compelling offering for OIC customers. It fills the API Management gap we've had and provides you with a tailored solution for managing your OIC integration apis. It is competitively priced and you can pay using Universal Credits. Try it out, here again is the direct link, and please send me your feedback!