In our previous blog post How to get SAP Business ByDesign events in a loosely coupled solution we exposed three different proposals allowing you to get SAP Business ByDesign event messages on your loosely coupled solution. This second blog post covers the first option proposed, based on Output Management out of the box feature that allows you to define triggers on business documents based on a process-integrated output.
Output Management allows you to define triggers on business documents based on a process-integrated output like for example, when a document is released by the document owner or when a manager has approved the document. Multiple output channels types can be configured allowing you to fully automate the collaboration with your business partners based on xml messages. This process may differ depending on the underlying business process configuration.
The main steps to be followed in order to configure Output Management are then:
Some specific business configuration is required to fully exploit all Output Management possibilities. Please refer to the second part of this blog for configuration details.
To define an External System channel, 2 steps are required:
A Communication System represents an external system that is used for application integration. In our example the communication system is pointing to a Cloud Applications Integration flow, but you can use any other Web Service URL as soon as it can be accessed from the internet and has a valid authentication mechanism (check the help center for more details).
Enter the Host Name of your service starting with the name of the server, don’t prefix it with https://.
Set Internet as System Access Type.
Add a System Instance to your Communication System with Preferred Application Protocol 5-Web Service.
Don’t forget to Save and Activate the new Communication System.s
Communication arrangements help you to configure the electronic data exchange between the ByDesign solution and a communication partner. ByDesign provides communication scenarios for inbound and outbound communications that you can use to create communication arrangements. In our specific example we will concentrate on the outbound communication to define how business documents are sent to a communication partner that in our case is a web service.
Let’s create a Communication Arrangement (Application and User Management -> Communication Arrangements) based on the “Output Management XML Integration” Communication Scenario and we set Communication Type as “Application Integration”.
Select the Communication System instance created in the previous step.
You can limit the usage of this communication system to a specific Company ID or keep it available for all companies, I keep it empty to be set for all companies.
In the next step keep Direct Connection as Communication Method and enter the details of your external system in the Outbound Communication Basic Settings.
Regarding authentication 3 options are available:
Please check the documentation for more details.
I’m using Application Protocol “Web Service” and Authentication Method “User ID and Password”.
The Host Name is automatically filled based on the System Instance ID selected.
Choose your Authentication Method and set the required associated parameters.
Review the Communication Arrangement and press Finish.
Output settings can be configured for a business document type, for a specific business partner, or, individually, for a business document instance. Output settings are used by the system to determine which output channel and form template to use when a document is output.
Output settings execution is based on the following level of prioritization:
The system checks whether settings are available at each level in the list. If a setting exists then this is used, otherwise the next available setting in the order defined in the list is taken.
Different output channels types are available: Printer, External System, E-Mail,… In this blog post we will focus on the External System output channel.
Let’s have a look to the different options available to configure Output channels one by one.
In the Application and User Management -> Output Channel Selection view, administrators can create rules that will determine which output channels should be used for the output of a business document based on a set of conditions.
Note 1: The rules defined here will be apply if no specific rules have been defined at the Business Partner Account or specific Document instance level.
Note 2: A business document can represent a group of related document types. For example, in our case the business document Customer Invoice includes invoices, credit memos, correction invoices and down payments.
In order to check which business documents you can define output channels for, please refer to Application and User Management -> Input and Output management -> Output Channel Selection view. Some rules can be defined simply on documents creation like Customer Invoice, Customer Return, Delivery Note, Sales Order, Sales Quote,… and others will offer a more granular selection like for example Created Purchase Order, Changed Purchase Order, Canceled Purchase Order, Created RFQ,…
The screens and options provided by Output Management might differ on the business document selected but the properties to be set are similar.
Once the business document selected you can set the rules that apply to the selected business document. You can create generic rules or apply filters where you set the parameters options to create more complex rules filtering like for example for Customer Invoices a specific Business Partner. If you have created more than one rule for a document, you also define the sequence of the rules.
In the following screen capture we have defined two rules for Customer Invoices:
If we look more in detail to the second rule, we can see we have defined two output channels:
Our rule will then generate an email and will call the External System every time a new Customer Invoice is released.
Business partner-specific output settings allow you to define how business documents are sent to your accounts or suppliers.
Note1: Business Partner output settings override any output channel rule defined at Output Channel Selection level.
Navigate to Accounts -> Communication tab (select View all if not visible) -> Collaboration of the Business Partner you want to configure Output Settings. The configuration parameters are like the ones defined in the Output Channel Selection.
Note2: Keep empty this configuration if you want the Output Channel Selection output channels previously defined to be applied.
Users can change the output settings for business documents they are authorized to edit before the document is submitted for process-integrated output. These settings are only valid for the next output of the current document and override any other output settings that have been set for the type of document or the business partner.
To access the output settings configuration select You Can Also -> Edit Output Settings at the top right of your document view.
In the next screen capture we can see we have one Output Channel of type External System predefined for the Customer Invoice business document type. In this screen we can modify or add new output channels that will be valid only for our specific document.
Once the steps below completed you must create a document that will fire at least one of the rules configured, in our example I create a Customer Invoice document. As soon as the document is saved/approved/released (depends on your rule and process-integrated output associated to your document) the external system will be called, and the details of the Customer Invoice will be shared in the body in XML format.
When a business document is output from the system as process-integrated output, a record of each output is stored in the document's Output History. You can check the output history of a document to see whether its output channels have been executed successfully.
Once your document created you can check the External System execution status from the Application and User Management -> Web Service Message Monitoring view.
Select View -> Payload to see the specific payload sent to your External System:
You can of course monitor your external system and check that SAP Business ByDesign Output Management did call you.
I hope the instructions provided in this blog post are clear enough and will help you implement loosely coupled solutions interacting with SAP Business ByDesign.
The next blog post in these series is completing this Output Management step by step guide with configuration and XML formatting details, check it out!
Don't hesitate to provide feedback and share some business use cases implemented with this feature, you can reach me mariatrinidad.martinezgea or in Twitter @TrinidadMGea.
Thank you for having read until the end 😉
Output Management allows you to define triggers on business documents based on a process-integrated output like for example, when a document is released by the document owner or when a manager has approved the document. Multiple output channels types can be configured allowing you to fully automate the collaboration with your business partners based on xml messages. This process may differ depending on the underlying business process configuration.
This blog illustrates how to configure Output Management in SAP Business ByDesign to trigger an external system. The external system can be for example an external web api/app, an integration flow or if you want to receive the triggers by different systems you can call a message broadcaster. The only requirement is to provide a URL to be called from SAP Business ByDesign having a valid authentication type.
The main steps to be followed in order to configure Output Management are then:
- Create an SAP Business ByDesign External System pointing to your external application or integration flow to be called.
- Create an Output Channel for our Business Document, pointing to the External System defined in step 1.
Some specific business configuration is required to fully exploit all Output Management possibilities. Please refer to the second part of this blog for configuration details.
Let’s first have a look to a video showing the main steps, then proceed with the blog post to get detailed explanations and references on each step.
1. Create an External System channel
We will define an external system in ByDesign pointing to our application/flow URL, it will be called when one of the business documents rules are met. You can define different external systems for each one of your rules or a generic external system for all your rules. In this sample we will create a single external system that will be generic enough to handle rules for different documents.
To define an External System channel, 2 steps are required:
- Create a Communication System that represents the remote system.
- Create a Communication Arrangement that will be pointed by the External System Channel.
Create a Communication System
A Communication System represents an external system that is used for application integration. In our example the communication system is pointing to a Cloud Applications Integration flow, but you can use any other Web Service URL as soon as it can be accessed from the internet and has a valid authentication mechanism (check the help center for more details).
Enter the Host Name of your service starting with the name of the server, don’t prefix it with https://.
Set Internet as System Access Type.
Add a System Instance to your Communication System with Preferred Application Protocol 5-Web Service.
Don’t forget to Save and Activate the new Communication System.s
Create a Communication Arrangement
Communication arrangements help you to configure the electronic data exchange between the ByDesign solution and a communication partner. ByDesign provides communication scenarios for inbound and outbound communications that you can use to create communication arrangements. In our specific example we will concentrate on the outbound communication to define how business documents are sent to a communication partner that in our case is a web service.
Let’s create a Communication Arrangement (Application and User Management -> Communication Arrangements) based on the “Output Management XML Integration” Communication Scenario and we set Communication Type as “Application Integration”.
Select the Communication System instance created in the previous step.
You can limit the usage of this communication system to a specific Company ID or keep it available for all companies, I keep it empty to be set for all companies.
In the next step keep Direct Connection as Communication Method and enter the details of your external system in the Outbound Communication Basic Settings.
Regarding authentication 3 options are available:
- None
- User ID and Password
- SSL Client Certificate
Please check the documentation for more details.
I’m using Application Protocol “Web Service” and Authentication Method “User ID and Password”.
The Host Name is automatically filled based on the System Instance ID selected.
Choose your Authentication Method and set the required associated parameters.
Review the Communication Arrangement and press Finish.
2. Create an Output Channel – Configure Output Settings
Output settings can be configured for a business document type, for a specific business partner, or, individually, for a business document instance. Output settings are used by the system to determine which output channel and form template to use when a document is output.
Output settings execution is based on the following level of prioritization:
- Document Instance level
- Business Partner Account
- Output channel rules
The system checks whether settings are available at each level in the list. If a setting exists then this is used, otherwise the next available setting in the order defined in the list is taken.
Different output channels types are available: Printer, External System, E-Mail,… In this blog post we will focus on the External System output channel.
Let’s have a look to the different options available to configure Output channels one by one.
Output Channel Selection
In the Application and User Management -> Output Channel Selection view, administrators can create rules that will determine which output channels should be used for the output of a business document based on a set of conditions.
Note 1: The rules defined here will be apply if no specific rules have been defined at the Business Partner Account or specific Document instance level.
Note 2: A business document can represent a group of related document types. For example, in our case the business document Customer Invoice includes invoices, credit memos, correction invoices and down payments.
In order to check which business documents you can define output channels for, please refer to Application and User Management -> Input and Output management -> Output Channel Selection view. Some rules can be defined simply on documents creation like Customer Invoice, Customer Return, Delivery Note, Sales Order, Sales Quote,… and others will offer a more granular selection like for example Created Purchase Order, Changed Purchase Order, Canceled Purchase Order, Created RFQ,…
The screens and options provided by Output Management might differ on the business document selected but the properties to be set are similar.
Once the business document selected you can set the rules that apply to the selected business document. You can create generic rules or apply filters where you set the parameters options to create more complex rules filtering like for example for Customer Invoices a specific Business Partner. If you have created more than one rule for a document, you also define the sequence of the rules.
In the following screen capture we have defined two rules for Customer Invoices:
- The first rule is only executed for a specific Business Partner and Business Document type and the Output Channel is Printer.
- The second rule is executed for all Customer Invoices.
If we look more in detail to the second rule, we can see we have defined two output channels:
- External System
Our rule will then generate an email and will call the External System every time a new Customer Invoice is released.
Business Partner Account
Business partner-specific output settings allow you to define how business documents are sent to your accounts or suppliers.
Note1: Business Partner output settings override any output channel rule defined at Output Channel Selection level.
Navigate to Accounts -> Communication tab (select View all if not visible) -> Collaboration of the Business Partner you want to configure Output Settings. The configuration parameters are like the ones defined in the Output Channel Selection.
Note2: Keep empty this configuration if you want the Output Channel Selection output channels previously defined to be applied.
Document Instance level
Users can change the output settings for business documents they are authorized to edit before the document is submitted for process-integrated output. These settings are only valid for the next output of the current document and override any other output settings that have been set for the type of document or the business partner.
To access the output settings configuration select You Can Also -> Edit Output Settings at the top right of your document view.
In the next screen capture we can see we have one Output Channel of type External System predefined for the Customer Invoice business document type. In this screen we can modify or add new output channels that will be valid only for our specific document.
3. How to check your Output Channel execution
Once the steps below completed you must create a document that will fire at least one of the rules configured, in our example I create a Customer Invoice document. As soon as the document is saved/approved/released (depends on your rule and process-integrated output associated to your document) the external system will be called, and the details of the Customer Invoice will be shared in the body in XML format.
Document Output History
When a business document is output from the system as process-integrated output, a record of each output is stored in the document's Output History. You can check the output history of a document to see whether its output channels have been executed successfully.
Web Service Message Monitoring
Once your document created you can check the External System execution status from the Application and User Management -> Web Service Message Monitoring view.
Select View -> Payload to see the specific payload sent to your External System:
You can of course monitor your external system and check that SAP Business ByDesign Output Management did call you.
I hope the instructions provided in this blog post are clear enough and will help you implement loosely coupled solutions interacting with SAP Business ByDesign.
The next blog post in these series is completing this Output Management step by step guide with configuration and XML formatting details, check it out!
Don't hesitate to provide feedback and share some business use cases implemented with this feature, you can reach me mariatrinidad.martinezgea or in Twitter @TrinidadMGea.
Thank you for having read until the end 😉
- SAP Managed Tags:
18 Comments
