Setup

This page takes you from an SAP system with AIF to the first answer in Joule. Plan about an hour with your SAP Basis and BTP administrators. Do the steps in order: each one is checked before the next.

Before you start

You need	Who usually has it
SAP S/4HANA with SAP AIF in use (interfaces and messages exist)	SAP Basis
SAP Joule in an SAP BTP subaccount, with the entitlement for custom Joule capabilities (Joule Studio)	BTP administrator
The SAP BTP Destination service in the Joule subaccount, and for an on-premise system the SAP Cloud Connector	BTP administrator
A user who may deploy to the Joule tenant: the Joule Studio CLI signs in with it	BTP administrator
Node.js 18 or later on the computer you deploy from	You
The capability package aif-monitor from Boidra	Boidra (contact@boidra.com)
AIF authorizations and recipient assignments for the Joule users	AIF administrator

Step 1. Publish the AIF OData service

The assistant reads AIF through the OData V4 service AIF_SRV.

1. In the SAP system, open transaction /IWFND/V4_ADMIN and check that the service group with AIF_SRV is published. If it is not, publish it for your system alias.

2. Test it in the browser (or in transaction /IWFND/GW_CLIENT) with a user that has AIF authorizations:

   https://<s4-host>:<port>/sap/opu/odata/sap/AIF_SRV/IfKeySet?$top=5

   Check: the answer is JSON with "value": [ ... ] and lists your AIF interfaces. Note the path exactly as it worked; step 3 uses it.

Step 2. Connect the system to SAP BTP

Skip this step for a system reachable from the internet (for example S/4HANA Cloud).

1. In the Cloud Connector, add (or open) the mapping of your S/4HANA system to the Joule subaccount, protocol HTTPS, with principal type X.509 certificate for principal propagation.
2. Under Resources, add the path /sap/opu/odata/sap/AIF_SRV with Path and all sub-paths.
3. Set up principal propagation between the subaccount and the system (trust in the Cloud Connector, the system certificate, and the user mapping in CERTRULE), as for any other Fiori or OData app.

Check: in the Cloud Connector the resource is green, and in the BTP cockpit (Connectivity > Cloud Connectors) the location shows as connected.

Step 3. Create the destination AIF_SRV_JOULE

In the Joule subaccount, open Connectivity > Destinations and create:

Property	On-premise (Cloud Connector)	Reachable from the internet
Name	AIF_SRV_JOULE	AIF_SRV_JOULE
Type	HTTP	HTTP
URL	http://<virtual-host>:<virtual-port>/sap/opu/odata/sap/AIF_SRV	https://<s4-host>/sap/opu/odata/sap/AIF_SRV
Proxy Type	OnPremise	Internet
Authentication	PrincipalPropagation	OAuth2SAMLBearerAssertion
Location ID	your Cloud Connector's, if it has one	—

Additional properties:

Property	Value
sap-client	your client, for example 100

The name must be exactly AIF_SRV_JOULE: the capability looks it up by that name. With a different name, change destination under system_aliases in capability/capability.sapdas.yaml of the package.

Use per-user authentication

Do not use BasicAuthentication with a technical user. Everybody in Joule would then see, restart and cancel every message that user may, whatever their own AIF authorizations say.

Check: Check Connection on the destination answers 200 (with principal propagation, the check can also answer 401 or 403; that is expected without a signed-in user).

Step 4. Install the Joule Studio CLI and sign in

npm install -g @sap/joule-studio-cli

joule --version

Sign in to the Joule tenant. Both URLs are on the Joule instance's service key (uaa.url and the API URL):

joule login --authurl https://<subdomain>.authentication.<region>.hana.ondemand.com --apiurl https://<tenant>.<region>.sapdas.cloud.sap

The CLI asks for the client ID, the client secret, your user and password. Add -i to sign in with the default identity provider instead of your company's.

joule status

Check: joule status shows you signed in to the right tenant.

Step 5. Check and deploy the capability

Unpack the aif-monitor package and run the commands from its parent folder:

aif-monitor/
  da.sapdas.yaml               the assistant: aif_monitor_native
  capability/
    capability.sapdas.yaml     the capability and its destination AIF_SRV_JOULE
    capability_context.yaml
    scenarios/                 13 scenarios
    functions/                 the dialog functions

1. Check the files:

   joule lint aif-monitor

   Check: 0 errors.

2. Compile and deploy. The first deploy creates the assistant aif_monitor_native; later deploys update it:

   joule deploy --compile aif-monitor/da.sapdas.yaml

   To add the capability to an assistant you already have, deploy it under that name instead:

   joule deploy --compile --name <your_assistant> aif-monitor/da.sapdas.yaml

3. Confirm the deployment:

   joule list

   joule get aif_monitor_native

   Check: aif_monitor_native is listed with the capability aif_monitor_native.

Step 6. Ask the first question

joule launch aif_monitor_native

In the Joule web client, ask:

1. "Show me the AIF monitoring overview for today": a list of your interfaces with their counts and health. This proves the destination, the service and your authorizations.
2. "Show me the AIF errors of the last 7 days", then "show #1": the message card with its log and business keys.
3. Optional: "restart #1" on a test message. Joule asks for a confirmation first.

Check: the overview shows the same counts as the Fiori app Message Monitoring Overview for the same period.

Update and remove

To deploy a new version of the package, or your own change:

1. Raise metadata.version in capability/capability.sapdas.yaml (for example 0.1.0 to 0.1.1). Joule only deploys a higher version.
2. Run joule lint aif-monitor and joule deploy --compile aif-monitor/da.sapdas.yaml again.

To remove the assistant from the tenant:

joule delete aif_monitor_native

Troubleshooting

What you see in Joule	Likely cause	What to do
"... failed in AIF" with HTTP status 404	The URL path of the destination is wrong, or AIF_SRV is not published	Compare the destination URL with the path that worked in step 1
HTTP status 401 or 403	Principal propagation is not set up, or the user lacks AIF authorizations	Check the Cloud Connector trust and CERTRULE mapping; test the user in the AIF Fiori apps
HTTP status 503 or a timeout	The Cloud Connector is not connected, or the resource path is missing	Step 2 checks
The overview is empty	No messages in the period, or the user is not a recipient of any interface	Try "AIF overview for the last 30 days"; check Assign Recipients to Users
Joule answers with a general reply instead of AIF data	The assistant is not deployed to the Joule you are using, or the question is too vague	joule list; start the question with "AIF"
joule deploy refuses the version	The version was deployed before	Raise metadata.version (see Update)
joule login fails	Wrong auth or API URL, or the user may not deploy	Take both URLs from the service key; ask the BTP administrator for the deploy role

Still stuck? Write to contact@boidra.com with the Joule answer and the time you asked.