Triggering via Destinations
Prerequisites
- A CAP application in place with the destination service configured
- A deployed BPA process
- A service instance and service key created for SAP Build Process Automation (SBPA)
Without Principal Propagation
Follow these steps to trigger a BPA process without principal propagation:
1. Create a destination to the BPA instance using OAuth2ClientCredentials:
- In your subaccount, navigate to Destinations and create a new destination.
- Enter the required details such as Name, Type (HTTP), base URL, and select OAuth2ClientCredentials as the Authentication Method.
- Provide the necessary Client ID, Client Secret, and Token Service URL.
2. Set up the destination in package.json:
- Define the destination in your CAP application's package.json under the cds.requires section.
"cds": {
"requires": {
"bpa_destination": {
"kind": "rest",
"credentials": {
"destination": "<destinationname>"
}
}
}
}
3. Connect to the destination via cds.connect.to(destinationname):
- Use the following code snippet in your CAP service or handler file to connect to the destination:
const { cds } = require('@sap/cds');
const bpa_destination = await cds.connect.to("<destinationname>");
4. Call the API: Use the connection to make a POST request to the BPA API endpoint:
let payload = {
definitionId: "<myProcessID>",
context: {
<StringName1>: "<InputString1>",
<IntegerName2>: <SampleInteger>
}
};
let oResult = await bpaService.tx(req).post('/v1/workflow-instances', payload);
if (response.status !== 201) {
throw new Error('Failed to trigger the process.');
}
Note: Adding the URL suffix is optional if the full URL is provided in the destination or in the destination configuration inside the package.json
Using Principal Propagation
If you need to propagate user information:
1a. Set up trust between subaccounts (if BPA and CAP are in different subaccounts):
- See SAP Help Documentation for establishing trust between subaccounts.
1b. Create a destination with OAuth2UserTokenExchange:
Similar to the OAuth2ClientCredentials setup, but select OAuth2UserTokenExchange as the Authentication Method.
1. Verify API call with principal propagation:
- Ensure the API call is made with the propagated user context from the request body.
2. Coding remains the same as without principal propagation:
- Follow the same code snippet as above.
Note: When making changes to the destination, it can take a few minutes until the changes are active. To shorten this timeframe, you can delete and re-create the destination.
Triggering via Event Mesh
Before trying to trigger events, ensure that the Event Mesh service is correctly set up, including creating a client, service descriptor and at least one queue which subscribes to a topic.
Triggering via Event Mesh
1. Create custom event specification for SAP Build Process Automation
To create a custom event you need to create an event specification that complies with the CloudEvents specification. This file needs to be stored as a .json file. Here is a generic sample of how this event specification could look like:
{
"asyncapi": "2.0.0",
"info": {
"title": "Generic Event",
"version": "1.0",
"description": "This event is triggered by a generic rule engine using custom rules."
},
"x-api-type": "EVENT",
"x-shortText": "Informs a subscriber about a relevant event for a process.",
"x-stateInfo": { "state": "active" },
"channels": {
"generic/event/channel": {
"subscribe": {
"message": {
"description": "myMessageDescription",
"$ref": "#/components/messages/generic_event_v1"
}
}
}
},
"components": {
"messages": {
"generic_event_v1": {
"name": "myMessageName",
"summary": "mySummary",
"description": "myDescription",
"headers": {
"properties": {
"type": {
"const": "<messageType>"
},
"datacontenttype": { "const": "application/json" }
}
},
"payload": {
"$ref": "#/components/schemas/generic_event_v1"
},
"traits": [{ "$ref": "#/components/messageTraits/CloudEventContext" }]
}
},
"schemas": {
"generic_event_v1": {
"type": "object",
"properties": {
"PROPERTY_1": { "type": "string" },
"PROPERTY_2": { "type": "string" },
"PROPERTY_3": { "type": "string" }
}
}
},
"messageTraits": {
"CloudEventContext": {
"headers": {
"type": "object",
"properties": {
"specversion": {
"type": "string",
"enum": ["1.0"]
},
"type": {
"description": "Type of occurrence which has happened. Often this property is used for routing, observability, policy enforcement, etc.",
"type": "string",
"minLength": 1
},
"source": { "type": "string" },
"subject": { "type": "string" },
"id": { "type": "string" },
"time": {
"type": "string",
"format": "date-time"
},
"datacontenttype": {
"description": "Describe the data encoding format",
"type": "string",
"const": "application/json"
}
},
"required": ["id", "specversion", "source", "type"]
}
}
}
}
}
2. Create custom event trigger inside SAP Build Process Automation
To create a custom event in BPA, you have to perform the following steps:
1. Open the SAP Build lobby.
2. Open Connectors > Actions in the menu.
3. Click the Create button and upload your previously created .json file.
4. Release and publish your event
5. Set your new event as a trigger for your process inside the process editor
Setup Event Mesh webhook:
To set up the connection between Event Mesh and SAP Build Process Automation, you need to set up a webhook. Webhooks are POST calls that are automatically triggered for each event inside the queue.
The following steps are necessary to set up your webhook:
1. Open the client inside your Event Mesh instance.
2. Click on the webhooks tab.
3. Create a new webhook by providing a name, inserting the webhook URL (your BPA endpoint URL in your service key + "/internal/be/v1/events") and the authentication type OAuth2ClientCredentials using the client key and the client secret from the BPA service key.
4. Exempt the handshake and resume the webhook.
Trigger events in CAP using messaging.emit():
Use the messaging.emit() function to emit events from CAP to Event Mesh.
const messaging = await cds.connect.to('messaging');
await messaging.emit({
event: '<eventName>',
data: <inputDataObject>,
headers: { type: '<messageType>' },
});
Note: The data object needs to comply with the CloudEvents standard.
Testing Event Trigger via REST-Client
To test the Event Mesh and Event Trigger setup we can test via REST-Clients (such as Postman). This needs to be configured accordingly:
1. Use the following endpoint for Event Mesh
- Endpoint: <yourEventMeshEndpoint>
You can find the endpoint in your Event Mesh instance service key under messaging. Make sure it contains the pubsub part and that it looks similar to this one: https://enterprise-messaging-pubsub.cfapps.<region>.hana.ondemand.com/messagingrest/v1/messages
2. Set the following headers:
- Content-Type: application/cloudevents+json
- x-qos: 1
- x-address: queue:<queueName>
3. Fetch a Bearer Token for authentication:
- Ensure you have a valid Bearer Token for authorization. Get one using the grant type Authorization Code.
4. Send a POST request with the CloudEvent payload:
- Construct and send a POST request to the Event Mesh endpoint.
{
"specversion": "1.0",
"type": "<messageType>",
"source": "<queue>/manual",
"id": "740f8e3e-6b99-40ae-bdc3-375277cc2edb",
"time": "2024-01-01T12:00:00Z",
"data": {
// Your SAP Build Process Automation context here
},
"datacontenttype": "application/json"
}
By following these guidelines, you can trigger SAP Build Process Automation processes from a SAP CAP application using various methods. This approach can greatly enhance the integration and automation capabilities within a SAP landscape.
No comments:
Post a Comment