Energy Field Service Integration Platform

A comprehensive API-led MuleSoft architecture for Oil & Gas field service operations integrating Salesforce Agentforce, ServiceNow, SAP S/4HANA, and Contract Management systems.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        EXPERIENCE LAYER                         │
├─────────────────────────────────────────────────────────────────┤
│  experience-energy-ops-api                                     │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │ Work Orders     │ │ Asset Context   │ │ Dispatch &      │   │
│  │ • Create        │ │ • Lookup        │ │ Estimates       │   │
│  │ • Update        │ │ • Cache         │ │ • Approval      │   │
│  │ • List/Get      │ │ • Contracts     │ │ • Assignment    │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
│  OAuth 2.0 | JWT | Rate Limiting | OWASP Policies | mTLS       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        PROCESS LAYER                            │
├─────────────────────────────────────────────────────────────────┤
│  process-field-service-orch-api                               │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │ Work Order      │ │ Asset Master    │ │ Contract        │   │
│  │ Orchestration   │ │ Sync            │ │ Resolution      │   │
│  │ • Saga Pattern  │ │ • Delta Sync    │ │ • Rate Cards    │   │
│  │ • Compensation  │ │ • Cache Refresh │ │ • SLA Terms     │   │
│  │ • Retry/Circuit │ │ • Batch Process │ │ • Geo Matching  │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
│  Anypoint MQ | Event Streaming | Error Handling | Monitoring   │
└─────────────────────────────────────────────────────────────────┘
                                │
           ┌────────────────────┼────────────────────┐
           ▼                    ▼                    ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│   SYSTEM LAYER    │ │   SYSTEM LAYER    │ │   SYSTEM LAYER    │
├───────────────────┤ ├───────────────────┤ ├───────────────────┤
│system-sap-eam-api │ │system-servicenow  │ │ system-clm-api    │
│                   │ │     -api          │ │                   │
│ ┌───────────────┐ │ │ ┌───────────────┐ │ │ ┌───────────────┐ │
│ │ Asset Master  │ │ │ │ Work Orders   │ │ │ │ Contracts     │ │
│ │ Maintenance   │ │ │ │ ITSM/Field    │ │ │ │ Rate Cards    │ │
│ │ Notifications │ │ │ │ Technicians   │ │ │ │ SLA Terms     │ │
│ │ Parts/Labor   │ │ │ │ Scheduling    │ │ │ │ Approvals     │ │
│ └───────────────┘ │ │ └───────────────┘ │ │ └───────────────┘ │
│ OData/RFC/IDoc    │ │ REST API v2       │ │ Generic REST      │
│ Circuit Breaker   │ │ OAuth 2.0         │ │ Custom Auth       │
└───────────────────┘ └───────────────────┘ └───────────────────┘
         │                        │                        │
         ▼                        ▼                        ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│   SAP S/4HANA     │ │    ServiceNow     │ │      CLM          │
│                   │ │                   │ │   (Icertis/       │
│ • Plant Maint(PM) │ │ • ITSM            │ │   DocuSign/       │
│ • Asset Hierarchy │ │ • Field Service   │ │   Agiloft)        │
│ • Work Orders     │ │ • Dispatch        │ │                   │
│ • Inventory       │ │ • Mobile Apps     │ │ • Service Contracts│
│ • Confirmations   │ │ • SLA Management  │ │ • Rate Management │
└───────────────────┘ └───────────────────┘ └───────────────────┘

🎯 Key Features

API-Led Architecture

Experience Layer: Purpose-built for Agentforce & human apps
Process Layer: Cross-system orchestration with saga patterns
System Layer: Vendor abstraction with unified contracts

Security & Governance

OAuth 2.0 client credentials for machine-to-machine
JWT validation for user contexts
mTLS between API layers
Rate limiting with SLA tiers
OWASP security policies
Idempotency keys for safe retries

Observability & Monitoring

Distributed tracing with correlation IDs
Structured JSON logging with PII masking
Anypoint Monitoring dashboards
Business metrics (MTTR, SLA compliance)
Error aggregation and alerting

Data Consistency

Event-driven architecture with Anypoint MQ
Asset cache with TTL-based refresh
Optimistic locking with ETags
Compensation patterns for failures
Replay-safe message processing

🏗️ Project Structure

energy-field-service-integration/
├── shared-models/                    # Canonical data models
│   └── src/main/resources/
│       ├── schemas/                  # JSON Schema definitions
│       │   ├── Asset.json
│       │   ├── WorkOrder.json
│       │   ├── Contract.json
│       │   └── EventEnvelope.json
│       └── dw/types/                 # DataWeave type definitions
│           ├── AssetType.dwl
│           ├── WorkOrderType.dwl
│           ├── ContractType.dwl
│           ├── EventType.dwl
│           └── ErrorType.dwl
│
├── experience-energy-ops-api/        # Experience Layer
│   ├── src/main/
│   │   ├── mule/
│   │   │   ├── app.xml              # Main API flow & APIKit
│   │   │   ├── global.xml           # Global configs & security
│   │   │   ├── work-order-flows.xml # Work order business logic
│   │   │   ├── asset-flows.xml      # Asset context & caching
│   │   │   └── dispatch-flows.xml   # Dispatch & estimation
│   │   └── resources/
│   │       ├── api/
│   │       │   └── experience-energy-ops-api.yaml
│   │       ├── config-dev.yaml
│   │       ├── config-staging.yaml
│   │       ├── config-prod.yaml
│   │       └── secure-config-${env}.yaml
│   └── src/test/munit/              # MUnit test suites
│
├── process-field-service-orch-api/   # Process Layer
│   ├── src/main/mule/
│   │   ├── orchestration-flows.xml  # Main orchestration logic
│   │   ├── saga-flows.xml           # Saga & compensation patterns
│   │   ├── event-flows.xml          # Event processing & MQ
│   │   └── integration-flows.xml    # System API calls
│   └── src/test/munit/
│
├── system-sap-eam-api/              # SAP System API
│   ├── src/main/mule/
│   │   ├── sap-asset-flows.xml      # Asset master operations
│   │   ├── sap-maintenance-flows.xml # Work order operations
│   │   └── sap-integration-flows.xml # OData/RFC/IDoc handling
│
├── system-servicenow-api/           # ServiceNow System API
│   ├── src/main/mule/
│   │   ├── snow-incident-flows.xml   # Incident/Work Order CRUD
│   │   ├── snow-dispatch-flows.xml   # Technician assignment
│   │   └── snow-integration-flows.xml # REST API v2 handling
│
├── system-clm-api/                  # Contract Management System API
│   ├── src/main/mule/
│   │   ├── clm-contract-flows.xml    # Contract operations
│   │   ├── clm-ratecard-flows.xml    # Rate management
│   │   └── clm-integration-flows.xml # Generic REST handling
│
├── deployment/                      # CI/CD & Deployment
│   ├── cloudhub2/                   # CloudHub 2.0 configs
│   ├── rtf/                         # Runtime Fabric configs
│   ├── github-actions/              # CI/CD workflows
│   └── docker/                      # Container definitions
│
└── docs/                           # Additional documentation
    ├── api-specifications/         # Complete OAS files
    ├── integration-patterns/       # Pattern documentation
    └── troubleshooting/           # Runbooks & guides

🚀 Quick Start

Prerequisites

Java 17
Maven 3.8+
Anypoint Studio 7.x
Anypoint Platform account
Access to SAP, ServiceNow, Salesforce, CLM systems

Local Development Setup

Clone and Build

git clone <repository-url>
cd energy-field-service-integration
mvn clean install

Configure Secure Properties

# Create secure configuration files
cp src/main/resources/secure-config-template.yaml src/main/resources/secure-config-dev.yaml

# Update with your credentials
# Use Anypoint CLI to encrypt sensitive values
anypoint-cli secure-properties encrypt --value "your-secret" --key "encryption-key"

Start Applications

# Start each application (in separate terminals)
cd experience-energy-ops-api && mvn mule:run
cd process-field-service-orch-api && mvn mule:run
cd system-sap-eam-api && mvn mule:run
cd system-servicenow-api && mvn mule:run
cd system-clm-api && mvn mule:run

Configuration Files

`config-dev.yaml` (Experience API)

# HTTP Configuration
http:
  host: "0.0.0.0"
  port: "8081"

# TLS Configuration  
tls:
  keystore:
    path: "keystore.jks"
    password: "!{secure::keystore.password}"
    key:
      password: "!{secure::keystore.key.password}"
  truststore:
    path: "truststore.jks"
    password: "!{secure::truststore.password}"

# API Configuration
api:
  base:
    url: "https://localhost:8081/field-service/v1"
    
# Process API Configuration
process:
  api:
    host: "localhost"
    port: "8082"
    client:
      id: "!{secure::process.api.client.id}"
      secret: "!{secure::process.api.client.secret}"
    token:
      url: "https://auth.energy.com/oauth2/token"

# Salesforce Configuration
salesforce:
  username: "!{secure::salesforce.username}"
  password: "!{secure::salesforce.password}"
  security:
    token: "!{secure::salesforce.security.token}"
  consumer:
    key: "!{secure::salesforce.consumer.key}"
    secret: "!{secure::salesforce.consumer.secret}"
  login:
    url: "https://login.salesforce.com/services/oauth2/token"

# OAuth Configuration
oauth:
  issuer: "https://auth.energy.com"

# Rate Limiting
rate:
  limit:
    requests:
      per:
        minute: 100

# Application Metadata
app:
  version: "1.0.0"
env: "dev"

# Security (for testing only)
test:
  username: "testuser"
  password: "testpass"

🔧 Key Flows Implementation

1. Create Work Order Flow (Agentforce → ServiceNow)

sequenceDiagram
    participant AF as Agentforce
    participant EXP as Experience API
    participant PROC as Process API  
    participant SAP as SAP System API
    participant CLM as CLM System API
    participant SNOW as ServiceNow API
    participant SF as Salesforce

    AF->>EXP: POST /work-orders (caseId, assetId, symptoms)
    EXP->>EXP: Validate OAuth/JWT + Rate Limit
    EXP->>EXP: Check Idempotency Key
    EXP->>PROC: GET /assets/{assetId}
    PROC->>SAP: Fetch asset context
    SAP-->>PROC: Asset details + maintenance history
    PROC-->>EXP: Enriched asset context
    
    EXP->>PROC: GET /contracts/applicable
    PROC->>CLM: Find contracts by location/vendor
    CLM-->>PROC: Rate cards + SLA terms
    PROC-->>EXP: Best-fit contract
    
    EXP->>PROC: POST /estimates/calculate
    PROC-->>EXP: Cost breakdown
    
    EXP->>PROC: POST /work-orders
    PROC->>SNOW: Create work order/incident
    PROC->>SF: Create/update Case task
    PROC->>SAP: Create maintenance notification
    PROC-->>EXP: Work order with external IDs
    
    EXP-->>AF: 201 Created + Work Order details

2. Status Sync Flow (ServiceNow → Agentforce & SAP)

sequenceDiagram
    participant SNOW as ServiceNow
    participant SNOW_API as ServiceNow API
    participant PROC as Process API
    participant SAP_API as SAP System API
    participant SAP as SAP S/4HANA
    participant SF as Salesforce
    participant MQ as Anypoint MQ

    SNOW->>SNOW_API: Work order status update webhook
    SNOW_API->>PROC: POST /work-orders/{id}/status
    PROC->>PROC: Transform to canonical WorkOrder
    
    alt Status = COMPLETED
        PROC->>SAP_API: POST /confirmations
        SAP_API->>SAP: Goods issue + time confirmation
        SAP-->>SAP_API: Success
    end
    
    PROC->>SF: Update Case/Task status
    SF-->>PROC: Success
    
    PROC->>MQ: Publish workorder.status.changed event
    MQ-->>PROC: Event published
    
    PROC-->>SNOW_API: 200 OK

3. Asset Master Sync (SAP → Experience Cache)

sequenceDiagram
    participant SCHEDULER as Anypoint Scheduler
    participant PROC as Process API
    participant SAP_API as SAP System API
    participant SAP as SAP S/4HANA
    participant CACHE as Object Store
    participant MQ as Anypoint MQ

    SCHEDULER->>PROC: Trigger asset delta sync
    PROC->>SAP_API: GET /assets/delta?since=lastSync
    SAP_API->>SAP: Query changed assets (EQUI/FUNC)
    SAP-->>SAP_API: Delta asset records
    SAP_API-->>PROC: Normalized asset list
    
    loop For each changed asset
        PROC->>PROC: Transform to canonical Asset
        PROC->>CACHE: Update asset cache
        PROC->>MQ: Publish asset.changed event
    end
    
    PROC->>PROC: Update last sync timestamp

🔐 Security Implementation

OAuth 2.0 Client Credentials Flow

<!-- OAuth Provider Configuration -->
<oauth:provider-config name="oauth-provider">
    <oauth:client-credentials-grant-type 
        clientId="${oauth.client.id}"
        clientSecret="${oauth.client.secret}"
        tokenUrl="${oauth.token.url}">
        <oauth:token-validation>
            <oauth:jwt-validation 
                issuer="${oauth.issuer}"
                audience="${oauth.audience}" />
        </oauth:token-validation>
    </oauth:client-credentials-grant-type>
</oauth:provider-config>

Rate Limiting Implementation

<!-- Rate Limiting with Object Store -->
<flow name="rate-limiting-flow">
    <set-variable variableName="clientKey" 
                 value="#[vars.clientId ++ ':' ++ attributes.remoteAddress]" />
    <set-variable variableName="rateLimitKey" 
                 value="#['rate-limit:' ++ vars.clientKey ++ ':' ++ 
                        ((now() as Number) / 60000 as Number {format: '0'})]" />
    
    <os:retrieve key="#[vars.rateLimitKey]" 
                objectStore="rate-limit-store" />
    <validation:is-true expression="#[(payload as Number + 1) <= ${rate.limit.requests.per.minute}]"
                      message="Rate limit exceeded" />
    
    <os:store key="#[vars.rateLimitKey]" 
             objectStore="rate-limit-store">
        <os:value>#[payload as Number + 1]</os:value>
    </os:store>
</flow>

📊 Monitoring & Observability

Structured Logging

<json-logger:logger config-ref="json-logger-config" 
                   message="Work Order Created">
    <json-logger:content><![CDATA[
        {
            "correlationId": "$(correlationId)",
            "workOrderId": "$(vars.workOrderId)",
            "assetId": "$(vars.assetId)",
            "priority": "$(vars.priority)",
            "estimatedCost": "$(vars.costEstimate.total)",
            "responseTime": "$((now() - vars.startTime) as Number)",
            "timestamp": "$(now())"
        }
    ]]></json-logger:content>
</json-logger:logger>

Business Metrics

Work orders created per hour/day
Mean Time to Resolution (MTTR)
SLA compliance percentage
Cost accuracy (estimated vs actual)
Asset utilization rates
Contract utilization by vendor

Key Performance Indicators

API response time < 2s (95th percentile)
System availability > 99.9%
Error rate < 0.1%
Cache hit ratio > 80%
Message processing latency < 500ms

🧪 Testing Strategy

MUnit Test Structure

<!-- Example MUnit Test -->
<munit:test name="create-work-order-test" description="Test work order creation">
    <munit:behavior>
        <munit-tools:mock-when processor="http:request" doc:name="Mock Process API">
            <munit-tools:with-attributes>
                <munit-tools:with-attribute whereValue="process-api-config" attributeName="config-ref"/>
            </munit-tools:with-attributes>
            <munit-tools:then-return>
                <munit-tools:payload value="#[{woId: 'WO0000123456', status: 'NEW'}]"/>
            </munit-tools:then-return>
        </munit-tools:mock-when>
    </munit:behavior>
    
    <munit:execution>
        <flow-ref name="create-work-order-flow"/>
    </munit:execution>
    
    <munit:validation>
        <munit-tools:assert-that expression="#[payload.woId]" 
                                is="#[MunitTools::notNullValue()]"/>
        <munit-tools:assert-equals actual="#[payload.status]" expected="NEW"/>
    </munit:validation>
</munit:test>

Test Categories

Unit Tests: Individual flow testing with mocks
Integration Tests: End-to-end API testing
Contract Tests: OAS specification validation
Load Tests: Performance under stress
Security Tests: Authentication & authorization
Chaos Tests: Resilience testing

🚢 Deployment

CloudHub 2.0 Deployment

# deployment/cloudhub2/experience-api-deployment.yaml
apiVersion: v1alpha1
kind: Application
metadata:
  name: experience-energy-ops-api
  environment: production
spec:
  image: experience-energy-ops-api:1.0.0
  replicas: 3
  resources:
    vcores: 2.0
    memory: 4Gi
  networking:
    ingress:
      enabled: true
      host: api.energy.com
      tls:
        enabled: true
  monitoring:
    enabled: true
    metrics:
      - business.metrics
      - performance.metrics

Runtime Fabric (RTF) Deployment

# Deploy to RTF
anypoint-cli runtime-fabric deploy \
  --application-name experience-energy-ops-api \
  --target production-rtf \
  --artifact-path target/experience-energy-ops-api-1.0.0-mule-application.jar \
  --replicas 3 \
  --cpu-limit 2000m \
  --memory-limit 4Gi

CI/CD Pipeline (GitHub Actions)

# .github/workflows/deploy.yml
name: Deploy Energy APIs
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          java-version: '17'
      - run: mvn clean test
      
  build-and-deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          java-version: '17'
      - run: mvn clean package -DskipTests
      - run: |
          anypoint-cli login \
            --username ${{ secrets.ANYPOINT_USERNAME }} \
            --password ${{ secrets.ANYPOINT_PASSWORD }}
          anypoint-cli cloudhub2 deploy \
            --application-name experience-energy-ops-api-prod \
            --artifact target/*.jar \
            --replicas 3

🏥 Health Checks & Monitoring

Health Check Endpoints

<!-- Health Check Flow -->
<flow name="health-check-flow">
    <http:listener path="/health" config-ref="httpListenerConfig"/>
    <choice>
        <when expression="#[attributes.queryParams.deep == 'true']">
            <parallel-foreach collection="#[['process-api', 'sap-api', 'snow-api', 'clm-api']]">
                <try>
                    <http:request method="GET" 
                                 path="/health"
                                 config-ref="#[payload ++ '-config']"/>
                    <set-payload value="#[{service: payload, status: 'UP', responseTime: vars.responseTime}]"/>
                    <error-handler>
                        <on-error-continue>
                            <set-payload value="#[{service: payload, status: 'DOWN', error: error.description}]"/>
                        </on-error-continue>
                    </error-handler>
                </try>
            </parallel-foreach>
            <set-payload value="#[{
                status: if (payload..status contains 'DOWN') 'DEGRADED' else 'UP',
                timestamp: now(),
                services: payload,
                version: '${app.version}',
                environment: '${env}'
            }]"/>
        </when>
        <otherwise>
            <set-payload value="#[{
                status: 'UP',
                timestamp: now(),
                version: '${app.version}',
                environment: '${env}'
            }]"/>
        </otherwise>
    </choice>
</flow>

📈 Performance Optimization

Caching Strategy

Asset Cache: 4-hour TTL with background refresh
Contract Cache: 24-hour TTL with change notifications
Rate Limit Cache: 1-minute sliding window
Authentication Cache: 15-minute JWT validation cache

Connection Pooling

<http:request-connection-provider name="pooled-connection-provider">
    <http:pooling-profile 
        maxActive="50"
        maxIdle="10"
        exhaustedAction="WHEN_EXHAUSTED_WAIT"
        maxWait="60000"/>
    <http:tcp-client-socket-properties 
        connectionTimeout="30000"
        keepAlive="true"/>
</http:request-connection-provider>

🐛 Troubleshooting

Common Issues

OAuth Token Expiration

Error: OAUTH:TOKEN_UNAUTHORIZED
Solution: Check token expiration and refresh logic

Rate Limit Exceeded

Error: HTTP:TOO_MANY_REQUESTS
Solution: Implement exponential backoff in client

SAP Connection Issues

Error: SAP:RFC_EXCEPTION
Solution: Check SAP gateway configuration and user permissions

ServiceNow Timeout

Error: HTTP:TIMEOUT
Solution: Increase timeout values and implement circuit breaker

Debug Endpoints

GET /health - Application health status
GET /health?deep=true - Deep health check with dependencies
GET /metrics - Performance metrics
GET /config - Configuration validation (non-sensitive only)

📚 Additional Resources

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

Contact: Field Service API Team - [email protected] Version: 1.0.0 Last Updated: January 2024

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github/workflows		.github/workflows
experience-energy-ops-api		experience-energy-ops-api
shared-models		shared-models
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
QUICK_START.md		QUICK_START.md
README.md		README.md
pom.xml		pom.xml

License

msaleme/energy-field-service-integration

Folders and files

Latest commit

History

Repository files navigation