SAP Business ByDesign Output Management – part 1
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.
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:
- 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 here or in Twitter @TrinidadMGea.
Thank you for having read until the end 😉
Thank You for the blog!
Do You know if it's possible to use External System output with a communication arrangement based
on a Custom Scenario with Custom outbound services?
It seems that when adding a Output Channel Rule for Customer Invoice with External System, Bydesign only allows to choose Communication Systems that are in an arrangement which is based on the Scenario "Output Management XML Integration".
If a Communication System is used in an arrangement which is based on custom Scenario, the system wont show the communication system as an option.
Maybe You have tried it out and have a solution for this?
Thank You again!
You cannot use custom Output Channel Rules for Output Management External System. The Communication Arrangement has to be based on the “Output Management XML Integration” Communication Scenario and the Communication Type has to be “Application Integration”.
This note is talking about it:
2985057 - No Communication System Available to be Selected in Output Channel Selection
Thank You for the response!
I also created a ticket for this and after processing SAP created the note regarding this.
So currently the only way is to use an integration tool like Cloud Platform Integration Suite, Cloud Platform - enterprise messaging etc.
You are right, you will need an intermediate application or integration scenario in order to extract and decode the formatted xml from the <OutputDataXML>.
If this is a requirement for your company please vote for this request in SAP Customer Influence:
Dear Maria, regarding Siim-Joonas Räim question about external system, would it be possible to create a custom BO, and create a web service on that custom BO that could work as the target of our communication arrangement ? So that way the transformed XML would be sent to our custom business object and from there we can format it the way its needed and send it to external web services ?
If that is even possible, how would the call work ? How would I have to format my custom inbound web service so that it accepts the transformed XML ? Do you have any documentation on how the request looks when it is generated and sent automatically to external system trough output management as you describe in this and the second blog post about output management ?
Best regards, Josip
When you create a WebService or OData service for your custom BO the metadata is fixed based on your object structure.
The request sent by Output Management is also fixed and the formatted XML you can define (based on your XSLT) is just inside the <OutputDataXML> element.
In order for your idea to work the structure of your custom BO should exactly correspond to the default XML sent by Output Management. I find it somehow difficult to be able to get ByD to accept the exact format sent by Output Management. In this blog for example they show the format required to create a SalesOrder. In my previous blog I shared a sample of the payload generated by Output Management. You could give it a try but I’m not sure you will get it to work.
I think would be much easier to get it formatted by an external side-by-side application.
Keep us updated in your findings.
Due to time constraints I dont know how much time I will be able to spend investigating, Im in need of a solution fast, and I want it to be tightly coupled without the need for additional products and costs, such as another cloud solution would be.
If I understood you correctly the XML data gets created for customer invoice when it is released. So if theres is a way to get to that transformed XML that is generated during output, then I could create some sort of custom solution ? Do you perhaps know where the XML is stored ? I cant find it trought repository explorer
Can you please create a question in the SAP Community for this topic and share the link here? The blog comments are becoming too long.
Link to the community question
Could You also share the settings on the CPI side of this scenario?
The CPI scenario I call from Output Management is nothing else than a very simple HTTPs CPI scenario, not doing anything but logging the payload received. The samples provided in the blog SAP Cloud Platform Integration for SMBs, samples will show you how to create it.
If you want to learn more about CPI and how to connect to ByD I recommend you the following blogs: SAP Cloud Platform Integration for SAP Business ByDesign webinar and SAP Cloud Platform Integration for SMBs, samples.
I followed your instructions but it's not working fine for me. I created the communication system and the communication arrangment and it seems okay. However, when I try to create a new output channel rule for customer invoices with my new system, I have an error message saying "Enter a valid communication system". Do you have any clue about this error message and how to solve it ?
I have checked all boxes of the second part of this blog but I still have this issue.
I found a workaround to this problem. The workaround is to change the system instance ID, so the communication system ID and the system instance ID are the same and save it in the Communication Systems UI.
Please check if this helps with your problem.
We are facing the same error which Julian Boissinot is facing. We were successfully able to create the communication system and the communication arrangement. When we checked Outbound Communication Service with "Check Service" tab, it was successful. And when we used "Check Connection" tab the ping was successful to our CPI Iflow. But we are facing same error ("Enter a valid Communication System") when we create Output Channel selection rule for customer invoice. Could you please help us with this?
Thanks and Regards
Thanks for sharing your knowledge.
I was hoping for clarification on the "Output Management XML Integration." Is this a scenario that needs to be built? I don't have that scenario available in my instance of ByD.
Thank you again for the helpful blog!
I have a question about using "Output management XML Integration" scenario. We have successfully implemented that some time ago. Now there is a need to also send a PDF file with the same scenario.
Right now, the output channel settings are using the external system for customer invoices. We also have a need to add a pdf file to the same scenario. I have not found a way to do it in a standard solution.
The only thing I can do is use the webservice "querydocumentoutputrequest" and find the PDF files from the invoice document.
But the problem is that the Output Management XML integration will not generate a PDF file when only this is used.
Would you have any idea to solve this problem?
the basic idea of the output channel "External system" (XMS) is to delegate the output management to a specialized output management application or service. Hence the output message contains the document raw information as xml, such that the external system gets all relevant data and can decide on the further processing (incl. compiling a pdf).
Therefore the output channel "External system" does not compile a pdf.
Nevertheless, there are some options which may address your requirements:
Some information about the APIs: