Showing posts with label Observability. Show all posts
Showing posts with label Observability. Show all posts

Wednesday, November 11, 2026

#1190 - Surfacing HITL Logs in Log Analytics

Introduction 


HITL is being used by lots of our customers, in conjunction with AI Agents.

Recently we released a dedicated OCI Log Analytics dashboard for monitoring your HITL driven workflows. We will delve into the dashboard later; let's start with the pre-requisites - how to get HITL logs to OCI Log Analytics. For that we need a log group, as target for the HITL logs. We also need a parser, which will interpret the log data. Some policies are required for this to function, but, once all is set up, we just need to activate the sending of logs. This we do in the OIC console page for your OIC instance. But let's begin with Log Analytics.

Parser in OCI Log Analytics

This is provided OOTB -

The parser requires a "source" log -

This is an example HITL log file, on which the parser is based.

Back in the parser - 

Here is the example log content - 

{
  "processDefinitionId": "UniqueProcessDefinitionID",
  "processDefinitionName": "UTProcess",
  "processDefinitionTitle": "UTProcess",
  "taskTitle": "User task 1",
  "processDefinitionKey": "OIC_PROJECT_1--01.00.0000--UTProcess",
  "startTime": "2026-05-25T10:49:00.188+00:00",
  "endTime": 1779708077902,
  "processInstanceState": "CREATED",
  "processInstanceId": "UniqueProcessInstanceID",
  "processDefinitionVersion": "01.00.0000",
  "processInstanceDuration": 1938110,
  "activityType": "userTask",
  "activityInstanceState": "COMPLETED",
  "activityInstanceSubState": "INITIATED",
  "activityInstanceDuration": 1936318,
  "activityInstanceId": "UniqueActivityInstanceID",
  "assigneeId": "beb0d855cf9040a3a0f16dUniqueID",
  "assigneeName": "beb0d855cf9040a3a0f16dUniqueID",
  "assigneeType": "USER",
  "activityId": "flow_UniqueActivityID",
  "activityName": "User task 1",
  "taskOutcome": "SUBMIT",
  "faultCode": "ABC123",
  "taskSubtype": "Submit",
  "taskId": "UniqueTaskID",
  "eventTimestamp": 1779708077902,
  "executionId": "UniqueExecutionID",
  "deploymentId": "UniqueDeploymentID",
  "oicProjectId": "OIC_PROJECT_1",
  "updatedTime": null,
  "inputPayload": null,
  "businessKey": "Leave Approval",
  "instanceIdentifier": "ut1",
  "userTaskOutputPayload": {
    "taskExec": {
      "approver": "beb0d855cf9040a3a0fUniqueID",
      "approverDisplayName": "user display name",
      "summary": "",
      "approvedDate": "2026-05-25T11:21:17.577Z",
      "approverComment": "null",
      "assignedDate": "2026-05-25T10:49:01.261Z"
    },
    "taskOutcome": "SUBMIT"
  },
  "outputPayload": null,
  "candidateUsersAndGroups": [
    {
      "name": "sample.user@example.com",
      "type": "USER"
    },
    {
      "name": "sample_group",
      "type": "GROUP"
    }
  ],
  "time": 1779708078285,
  "logGroupOCID": "ocid1.loganalyticsloggroup.oc1.phx.exampleuniqueid",
  "serviceInstanceOCID": "ocid1.processautomationinstance.oc1.phx.exampleuniqueid"
}

As you can see, it includes task name, approver, task outcome etc, as well as the OCID of the OPA service instance.

During the log ingestion process OIC will provide the target log group and the log source.


Create a new Log Group in Log Analytics

Then copy the ocid for future use.


Enable HITL for Log Analytics

This is simple - go to the OCI console page for your OIC instance.


Click Enable and paste the ocid of the log group you just created.

Apply Policy Permissions

Currently HITL runs as part of OPA (Oracle Process Automation). We need to allow this HITL (OPA) instance access to Log Analytics.

I have already enabled such for my OIC instances. I created a dynamic group and added the resource ids of my OIC instances.
This dynamic group will now be augmented with the HITL id. This id can be found in the OCI console for your OIC instance. The entry in the dynamic group should be in the following format -

ALL {resource.id = 'ocid1.processautomationinstance.oc1.phx.nnn'}

The dynamic group is used in a Policy - 

It takes a couple of minutes for the policy to kick in.

After a nice cup of English Breakfast tea - I run an OIC based agent that processes orders. The logic is simple; orders > $1000 need to be manually approved.

I run this a couple of times -

Then move to Log Explorer - 

Check out the HITL Logs - 

Here's the raw log data - 

HITL Dashboard

There is now a HITL dashboard in Log Analytics, let's check it out -

There my 2 tasks, back in the Task list - 

I've approved one of the tasks, let's refresh the dashboard - 

Looks good!

I have one active and one completed instance -

You can check out the queries behind each of the widgets - 

Here is the query - 'Log Source' = 'OCI Integration - HITL Activity Stream Logs' and 'Event Type' = PROCESS | rename 'Process State' as State | stats latest(State) as State by 'Process Name', Instance | stats count(Instance) as 'Instance Count' by State, 'Process Name' | where State not in (created)

Net, net - you can create your own widgets based on your own queries; you can also edit existing queries and save as a different widget.

One thing to note here - the Entity value from the filter is not used. Let's get rid of this, as it may cause confusion. To do this, I duplicate the HITL dashboard and edit the duplicate - 

The Entity is still referenced in the widgets, but we can simply remove it.

Don't enter a value, just click Save changes.


Data is now rendered in the widget - 

Do this for all the widgets - 

I open the original HITL dashboard, to check out the Tasks tab - 

There are 5 widgets - 

  • Tasks by status
  • Tasks by status and workflow
  • Pending tasks by users/groups
  • Completed tasks by approver
  • Tasks by outcome

One thing to note, these tasks are at compartment level; so, if you have 3 OIC instances in your compartment, you could potentially see the aggregation of tasks. as we've already seen there is a serviceInstanceOCID field in the HITL log which can be used to filter on HITL/OPA instance. More about that in a follow-up post.

Summa Summarum

This is a very useful dashboard for those using HITL. It can be exposed to LOB folks easily and avoids having to give them access to OIC/OPA for HITL monitoring purposes.






























 




Monday, October 19, 2026

#1186 - New OIC Dashboard filter

Introduction

The default dashboards in Log Analytics come with the following filters- 

Note the filter options - 

The log group compartment refers to the compartment for your OCI Log Analytics OIC log group. This is the activity stream logs sent from your OIC service instance to Log Analytics. These logs are parsed to retrieve the resource ids for active instances in the timeframe selected. Note, the resource ids are the more cryptic instance ocids, ergo, not the most use friendly way of selecting an OIC instance.  

Selecting the available OIC instances in this way has 2 major disadvantages - 

  • The OCID is not user friendly; customers want to see values such as OIC-Test, OIC-Dev, OIC-Prod etc.
  • Only showing OIC instances that have logs in the activity stream for the time interval selected gives us an incomplete view of my OIC real estate.

The New Filter

Here are the OIC instances in my selected compartment -

This is the list I want to see in my dashboard filter.

I begin by checking out the request used to retrieve these instances - 

https://integration.us-phoenix-1.ocp.oraclecloud.com/20190131/integrationInstances?compartmentId=yourCompartmentId

This will be the basis for my new filter - 

Here is the underlying JSON -

{
    "id": "yourSavedSearchOCID",
    "compartmentId": "yourCompartment",
    "widgetVM": "visualizations/chartWidget",
    "widgetTemplate": "visualizations/chartWidgetTemplate.html",
    "isOobSavedSearch": false,
    "description": "OIC integration instances",
    "displayName": "OIC integration instances filter",
    "providerId": "management-dashboard",
    "providerName": "Management Dashboard",
    "providerVersion": "3.0.0",
    "metadataVersion": "2.0",
    "screenImage": "...",
    "nls": {},
    "freeformTags": {},
    "definedTags": {
        "Oracle-Tags": {
            "CreatedBy": "niall.commiskey@oracle.com",
            "CreatedOn": "2026-10-15T15:33:45.480Z"
        }
    },
    "featuresConfig": {
        "crossService": {
            "shared": true
        },
        "dependencies": [],
        "serviceTypes": [
            "management-dashboard"
        ]
    },
    "dataConfig": [
        {
            "name": "ds",
            "type": "genericDataSource",
            "parameters": {
                "url": {
                    "origin": "https://integration.$(params.regionName).ocp.oraclecloud.com",
                    "path": "20190131/integrationInstances",
                    "parameters": [
                        {
                            "name": "compartmentId",
                            "value": "$(params.compartmentId)"
                        }
                    ]
                },
                "defaultTransform": {
                    "selectedFields": [
                        {
                            "field": "id",
                            "alias": "value"
                        },
                        {
                            "field": "displayName",
                            "alias": "label"
                        }
                    ]
                }
            }
        }
    ],
    "uiConfig": {
        "vizFilterType": "genericFilter",
        "filterName": "oic-instances",
        "genericFilterInfo": {
            "selectionMode": "multiple"
        },
        "defaultDataSource": "ds"
    },
    "type": "FILTER_SHOW_IN_DASHBOARD",
    "drilldownConfig": [],
    "parametersConfig": [
        {
            "name": "compartmentId",
            "displayName": "$(bundle.globalSavedSearch.COMPARTMENT)",
            "required": true,
            "defaultFilterIds": [
                "OOBSS-management-dashboard-compartment-filter"
            ],
            "valueFormat": {
                "type": "string"
            },
            "editUi": {
                "inputType": "compartmentSelect"
            }
        },
        {
            "name": "regionName",
            "displayName": "$(bundle.globalSavedSearch.REGION)",
            "required": false,
            "defaultFilterIds": [
                "OOBSS-management-dashboard-region-filter"
            ],
            "valueFormat": {
                "type": "string"
            },
            "editUi": {
                "inputType": "savedSearch",
                "filterTile": {
                    "filterId": "OOBSS-management-dashboard-region-filter",
                    "parametersMap": {
                        "selectionMode": "single"
                    }
                }
            }
        }
    ],
    "createdBy": "niall.commiskey@oracle.com",
    "timeCreated": "2026-10-15T15:33:45.582Z",
    "updatedBy": "niall.commiskey@oracle.com",
    "timeUpdated": "2026-10-15T15:43:46.903Z"
}}


Net, net - the filter is based on the request from the Developer Services --> Integration page.
This retrieves the ocid and display name - 

{
        "id": "yourInstanceOCID",
        "displayName": "OIC3Test",
        "compartmentId": "yourComartmentId",
        "integrationInstanceType": "STANDARDX",
        "timeCreated": "2026-03-05T06:57:59.670Z",
        "timeUpdated": "2026-10-08T07:54:11.322Z",
        "lifecycleState": "ACTIVE",

We need the display for the the dropdown selection list; we also require the OCID (resourceId) for the widget queries - e.g. MessagesReceivedCount[5m]{resourceId = $(params.selectedInstance)}.grouping().grouping().sum()


Note the following checkboxes -
  • Required
  • Allow multiple values
Allow multiple values is probably not appropriate for the specific dashboard I will be creating; I just wanted to highlight this option, because there will be times when you want such.

This new filter is not dependent on the activity stream logs; all it needs is a compartment id.

Using the filter in a Dashboard

I do not see any data, when I open the dashboard. This is because we need to select an OIC instance.

I select the Dev instance - 

The dashboard widgets are populated -

Summa Summarum

This new filter is simple to implement and is independent of the OIC activity stream logs. In my case, I don't need a fleet view for such metrics. I also don't need the ability to drill down to the integration level. 

A Big thanks to my esteemed OCI colleagues, Jean and Raul for their help here! 




  

Thursday, October 15, 2026

#1185 - OIC move to projects - best practices

Introduction 


There are many compelling reasons to move to OIC projects -

net, net - you get a comprehensive toolkit, not just integrations. This toolkit includes all things Agentic AI, including the recently released MCP Gateway.

You also get the ability to share many  artifacts between projects; currently, integrations, connections, OIC events and lookups can be declared sharable. The ability to share libraries is on the roadmap. This shareability, allows you to create one connection to Fusion ERP, one common logging integration and have them used in multiple projects.

Projects also give you design time RBAC, with view, edit and monitor options. Role based access control allows one to have multiple developer groups working on the same OIC instance, without seeing the work of the others. Instead of having separate OIC instances for your Fusion ERP and HCM integration developers, both groups can now work within the same instance, each within its own projects. Runtime RBAC is also planned, so do expect movement in this space over the next couple of releases.

Our AI Assistant powers projects, whether it be for natural language integration generation, project and integration documentation generation, business user friendly error messages or proactive monitoring. This is all work you no longer need to do yourself.

Projects have their own monitoring view of the world. In other words, if I'm just interested in the integrations running in project, Fusion-ERP-Accounts-Receivable, I can just monitor those within the context of the project. Naturally, I still have access to the global Observability view on what's going on.

Planning your move to projects

Project Granularity

Consider you have 100s of integrations in your OIC instance. How do you want to organize them in projects? There are some service limits that you need to consider - 

As you can see, the limits are very generous, but do you really want to max these out? 

We recommend aiming for about 20 integrations or fewer per project, particularly when starting out. This keeps the project’s assets easy to find and navigate; the right size ultimately depends on your business goals.

Some heuristics - 
  • Group integrations around a cohesive business process or capability, such as order processing.
  • Keep integrations with the same ownership and release lifecycle together.
  • Keep closely related parent/child flows together; expose reusable child integrations to other projects when needed. 

  • For many customers who use packages in OIC, the temptation may be there to just convert each package to a project. This is supported via the UI - 

    Clicking this will select the integrations in a package and move them into the project you specify.

    However, you can use this move to projects as an opportunity to organize your integrations into multiple projects, instead of dumping them into 1 humongous project. 

    Again, this is prep work you need to do. How fine grained do you want your projects to be? Which teams of developers will be working on them? There are many things to consider. 

    Artifact Sharing 

    As already mentioned, integrations, connections, lookups and OIC events can be shared between projects.

























    Consider a common project for common artifacts, be they lookups, integrations or connections.

    There may be a requirement for multiple common projects, if multiple teams need to work in isolation, but you can adopt the same modus operandi in this case.

    There may be minor changes required to leverage such in your integrations, for example, lookups - 

    Note the new Integration Cloud function - sharedLookupValue. This will require manual editing to use this, instead of lookupValue. 
     

    RBAC

    You can enable role based access control on your projects.


    Note the permissions available. The best practice is to create groups, based on your requirements. For example, if you want 2 distinct groups of integration developers to work in the same OIC instance, create an IDCS group for each - 

    Now add users (your OIC developers) to those groups.

    Finally, assign those groups to the project RBAC roles - 


    Note the role granularity - 
    • view
    • edit
    • monitor
    Plan up front which groups you require and which users should belong to each. You may require a separate group for monitoring etc. So think about design/maintenance and operational ownership.


    A Simple Demo

    Granted the following example is very basic, but it does cover many aspects of moving to projects. I have the following connections in the global space - 

    I have the following Lookups - 

    I have the following integrations - 

    AAA-ERP-AccountsReceivable which uses the ERP connection, AAA-ERP-Cloud. It uses the lookup AAA-ER-Country-Lookup and invokes the common XYZ-Logger integration. The integration has a REST trigger, based on the connection AA-REST-Trigger.

    AAA-ERP-AccountsPayable which uses the ERP connection, BBB-ERP-Cloud. It uses the lookup AAA-ER-Country-Lookup and invokes the common XYZ-Logger integration. The integration has a REST trigger, based on the connection AA-REST-Trigger.

    CCC-HCM-Onboarding which uses the HCM connection, CCC-HCM-Cloud. It uses the lookup CCC-HCMSalaryScale-Lookup and invokes the common XYZ-Logger integration. This is a scheduled integration. I apply the following schedule - 

    This is basis from which I will move to projects.

    Both HCM and ERP developer groups will be using this OIC instance and I will be applying project RBAC to keep them isolated from one another.

    I see we have global artifacts which are used by all integrations - namely, the XYZ-Logger integration. I also have common ERP artifacts - AA-REST-Trigger and AAA-ERP-Country-Lookup. We also have 2 connections pointing to the same ERP instance, so we can do some consolidation here.

    I decide on splitting the integrations into 3 functional projects -
    • CCC-HCM-Onboarding
    • AAA-ERP-AccountsPayable
    • AAA-ERP-AccountsReceivable
    I will create a common project for artifacts required by HCM and ERP
    • XYZ-Common
    I will create a common project for artifacts required by multiple ERP projects
    • AAA-ERP-Common
    I have already created the groups in IDCS, so applying RBAC will be simple.

    So that's my plan.

    However, before executing the plan, let's see what happens when I move an integration to a project -

    The above may not really relevant for a scheduled integration, but you may have clients invoking this ad-hoc.

    I open the project -

    I configure the connection - 

    I then activate the integration and run it - 

    Note the warning on activation - 
    This makes sense, as we do not want both of these running, correct?

    The global space integration has been deactivated and the schedule stopped.

    The schedule is also stopped for the project based integration - 
    So I start it - 

    I do an ad-hoc run to ensure the integration runs successfully - 

    I see the following error on the local invoke of XYZ-Logger - 

    Here, it assumes the integration is in the same project, which it is not.

    So let's fix this, by putting XYZ-Logger into a common project.

    Let's make this integration shareable - 

    I then activate - 

    Back in the CCC-HCM-OnBoarding project, I stop the integration schedule and then deactivate the integration - 

    The Map is still valid, so no need to edit it -

    I activate and run - 


    Now apply RBAC to this project - 

    The OIC project RBAC’s "Can edit" permission includes viewing and monitoring the project, so essentially I don't need to add my HCM developers group to "Can view" and "Can monitor".  

    There is a caveat to all of this though - the user’s OIC service role still limits their access. Take the case of user Harry, who has been assigned the OIC Service Monitor role for this OIC instance. He is also a member of the HCM developers group. Harry will not be able to edit resources even if assigned "Can edit" on the project, either directly or via group membership. 
    Meghan, on the other hand, has been assigned the "ServiceDeveloper" role, so she can edit.

    Schedule has been started, so we're good here.

    Now to the ERP integrations - 

    Here I explicitly create a new project - AAA-ERP-Common. This project will have RBAC applied to it, as I only want ERP developers to use its artifacts - 

    Can view only needs to be set in this case. The user niall.commiskey@oracle.com, being the only one allowed to add new artifacts etc. to this project.

    I create a new Fusion ERP connection in this project - 

    make it shareable - 

    Regarding the ERP lookup, I can export this from the global space - 

    and import it into the common ERP project, then set it to shared - 

    My plan is to have 2 ERP projects, one for accounts receivables, one for payables.

    Let's begin with receivables and moving that integration to its new home - 


    Edit the draft ERP connection to use the shared ERP connection - 

    The REST Trigger is also common for the ERP integrations, so I create it in the common ERP project and leverage it here.

    I still need to edit the integration for the local invoke and common lookup.

    The lookup currently used - 


    I change this as follows - 

    I can now delete the local lookup - 

    I activate the integration and run it - 


    Finally, apply RBAC to this project - 


    I do the same for the accounts payable integration - 


    Move versus Copy

    OIC offers these 2 options, so let's go through them in detail, so there is no ambiguity.

    Copy

    We have looked at Move in some depth, but what about Copy? When should I consider using this option?

    Copying an integration to a project results in an independent copy of the integration surfacing in the project. This may be useful for experimenting with a redesign, creating a variant for another business process, or testing a separate implementation while the original continues running.

    To summarize, with copy -
    • the original integration stays active; i.e. both can run independently
    • once activated, the integration gets a new project based endpoint URL, which clients must use

    Move

    With Move, we can retain the existing global endpoint URL, allowing clients to continue using the same URL. Once the integration is activated in the project, requests to that URL invoke the project-based integration.

    With Move, OIC does not delete the integration from the global space. However, if the project version is activated then request to the original url invoke the project based integration. If I activate the project based integration and then activate its pendant in the global space, then no redirection will take place. This provides us with great flexibility, e.g. allowing for Bug fixes in production (global space integration), during transition to projects. Net, net, activating one, deactivates the other.

    Some other best practices

    Do an inventory

    OIC projects provide dependency analysis - 

    We do not have such in the global space. So you do need to do an inventory parent/child integrations, connections, lookups, JavaScript libraries, schedules, and who the integration clients/consumers are. 

    Decide on what to share

    Every artifact does not need to be shareable. In my simple demo, it is the case. But often lookups, libraries etc. are specific to a project. For example, I have a Lookup - accountsReceivables-Lookup, it is only relevant to accounts receivables integrations, ergo it should only surface in the AAA-ERP-AccountsReceivable project, as an unshared lookup. 

    Rehearse in a lower environment

    Start with a small batch of integrations in your dev instance. Validate the steps you take and use that as your template for further batches.

    Retain the global URL initially

    After moving, do a quick sanity test from postman to ensure both endpoints (existing URL and project URL) are working. The great value add here is that it lets you migrate callers separately from the integration itself. This period of co-existence may stretch over a period of a couple of months, but, someday, you will be able to deactivate the original URL. This is a simple task - 

    I just need to uncheck Retain origin endpoint

    Project Deployments for Promotion

    Use project deployments for promotion of projects between instances. 

    The basic heuristic is to use a consistent convention that identifies the solution and the release. Here is a simple example - 

    • ORDER_FULFILLMENT_V1_0_0
    • ORDER_FULFILLMENT_V1_1_0

    The first is for the initial release, the second includes more functionality etc.

    In OIC Projects, deployments are created as follows - 

    Once created, add the relevant artifacts to the deployment - 

    These may already be added by default.

    For more detail see my post on promoting projects via deployments.


    Summa Summarum

    Moving to projects gives you the opportunity to improve how you organize, share, deploy and monitor your OIC solutions. Retaining the global endpoint URL lets existing clients continue calling your integrations while you make that transition.

    As the demo shows, a successful move involves more than clicking Move. Check your child integration calls, shared lookups, connections, schedules and access permissions. These details are what turn a moved integration into a working business solution.

    My advice? Start with one business process in a lower environment. Get the project boundaries right, validate the complete flow, and use what you learn for the next batch.

    The payoff is a more manageable integration estate, reusable common resources, clearer ownership, and access to the broader automation and AI capabilities available within projects. Pick your first business process and get moving!