(Click to enlarge.)
If you have no idea what to blog about, just take a look at the collection of ideas in SAP's Customer Influence program. There you will find an endless number of product improvement ideas. One of them is the following feature request for SAP CPI: "Value mapping from SAP PO to SAP CPI". The request asks for an automatic/simple import function to transfer value mappings from SAP PO to CPI.
But hey - why wait when everything you need is already available? In this blogpost I would like to show how to import (after a short setup phase) any value mappings from SAP PI/PO into SAP CPI (SAP BTP Integration Suite, Cloud Integration) with just one click.
Since SAP PO provides an API to read value mappings (see here) and SAP CPI provides an API to upload value mappings, we have everything we need to automate the process. Instead of developing an external tool, I simply built an IFlow - after all, addressing APIs and mapping between different formats is the core domain of the CPI - so why not?
In the first part of the blog post, I show you how you can use the IFlow for yourself. (This includes the initial setup as well as the later execution.) In the second part of the blog, I'll go into the logic of the IFlow (for the techies among you). So let's start...
The first thing to do is to upload the IFlow in the CPI. You can download the "ready to use" artifact from Github via the following link:
(If you are interested, the source code of the flow can be viewed here.)
Open the target package in edit mode (1), then click "Add" and "Integration Flow" (2) to upload the previously downloaded artifact. Next, open the "Configure" (3) view, to proceed with the IFlow's setup.
The following table explains how to fill the individual configuration parameters. If you have any questions, feel free to post a comment below this blog.
That's it for the initial setup. Now let's check on how to use the IFlow to transport your SAP PO value mappings into the SAP CPI (Cloud Integration).
The IFlow contains multiple parameters to control the import/transport process. Those parameters can be set via the IFlow's "Configure" section and should be adjusted before each transfer/transport.
The following table explains the parameters and teaches you how to use them:
If you have configured the runtime parameters as defined above, you can execute the import process by simply deploying the IFlow. The import will run exactly once per deployment. So if you want to import multiple value mappings, just change the runtime parameters and re-deploy the IFlow another time. That's it!
For those who not only want to execute, but also understand, I explain below step by step what the IFlow does. If you have any questions, please feel free to leave a comment below this blog.
A more detailed description of the process above is certainly possible, but would go beyond the scope of this blog here. Nevertheless, I am happy to answer any follow up questions in the comments section.
As with my last blog, the idea for this blog once again came from the SAP Influence Program. What does it teach us? On the one hand, you can find a lot of really good ideas for product improvements there, and on the other hand, some of the features you need can already be implemented today (without necessarily having to wait for an official solution).
So I can only recommend to everyone: participate in the Influence Program. Let your ideas flow in or let yourself be inspired by the suggestions that have already been set up. Maybe you will also find an idea for which you already have a solution proposal today! I look forward to your blogs 😉
But hey - why wait when everything you need is already available? In this blogpost I would like to show how to import (after a short setup phase) any value mappings from SAP PI/PO into SAP CPI (SAP BTP Integration Suite, Cloud Integration) with just one click.
The target picture
Since SAP PO provides an API to read value mappings (see here) and SAP CPI provides an API to upload value mappings, we have everything we need to automate the process. Instead of developing an external tool, I simply built an IFlow - after all, addressing APIs and mapping between different formats is the core domain of the CPI - so why not?
In the first part of the blog post, I show you how you can use the IFlow for yourself. (This includes the initial setup as well as the later execution.) In the second part of the blog, I'll go into the logic of the IFlow (for the techies among you). So let's start...
How to setup?
The first thing to do is to upload the IFlow in the CPI. You can download the "ready to use" artifact from Github via the following link:
Download SapPO_to_SapCPI_ValueMappingTransfer-Flow
(If you are interested, the source code of the flow can be viewed here.)
Open the target package in edit mode (1), then click "Add" and "Integration Flow" (2) to upload the previously downloaded artifact. Next, open the "Configure" (3) view, to proceed with the IFlow's setup.
The following table explains how to fill the individual configuration parameters. If you have any questions, feel free to post a comment below this blog.
| Parameter | How to fill |
| CPI_HOSTNAME (Receiver/SapCpi/Http) | Fill in the hostname (without protocol and path) as seen in the url bar when logged-in into CPI.  |
| Credential Name (Receiver/SapCpi/Http) | The name of a "Security material" (credential pair) which contains the user credentials to access the CPI. (e.g. S-User/E-Mail and password.) The user should have sufficient roles to edit CPI packages and create value mappings. |
| Credential Name (Receiver/SapPo/SOAP) | The name of a "Security material" (credential pair) which contains the user credentials to access the SAP PO. (e.g. SAP PO username and password.) The user should have at least the roles SAP_XI_API_DISPLAY_J2EE and SAP_XI_API_DEVELOP_J2EE. |
(More) | The base address of the SAP PO system including protocol and port as it was made available via Cloud Connector. (e.g. http://my-sap-po.company.local:50000) Note: The SAP PO system has to be exposed via Cloud Connector first. If you haven't already setup your PO system in Cloud Connector, the following article shows you how to expose SAP PO to the SAP BTP: https://blogs.sap.com/2018/11/26/how-to-connect-cpi-and-pi-system-to-import-mappings-via-sap-cloud-c... |
| CPI_ARTIFACT_NAME (More) | Will be explained in the next paragraph of this blog. |
| CPI_PACKAGE_ID (More) | Will be explained in the next paragraph of this blog. |
| VM_MODE (More) | Will be explained in the next paragraph of this blog. |
| VM_GROUPNAME (More) | Will be explained in the next paragraph of this blog. |
| VM_AGENCY (More) | Will be explained in the next paragraph of this blog. |
| VM_SCHEME (More) | Will be explained in the next paragraph of this blog. |
That's it for the initial setup. Now let's check on how to use the IFlow to transport your SAP PO value mappings into the SAP CPI (Cloud Integration).
How to use?
The IFlow contains multiple parameters to control the import/transport process. Those parameters can be set via the IFlow's "Configure" section and should be adjusted before each transfer/transport.
The following table explains the parameters and teaches you how to use them:
| CPI_ARTIFACT_NAME (More) | The value entered into this property will be used as name for the CPI Value Mapping artifact that is created by the IFlow. Thus the name should be unique and shouldn't be used for any other artifact on your CPI. |
| CPI_PACKAGE_ID (More) | Enter the package id (id != name) of the CPI package, you want the value mapping artifact to be created in. Note: You can find out the id of a package easily, by opening it in a webbrowser and copy the package's id from the url bar. |
| VM_MODE (More) | This parameter controls the mode to be used, when importing SAP PO value mappings. Set it to one of the following values:
|
| VM_GROUPNAME (More) | If VM_MODE=GROUPNAME, enter the name of a SAP PO value mapping group into this field. The IFlow will then select all value mappings from SAP PO with the given group name and import them to CPI. |
| VM_AGENCY (More) | If VM_MODE=REPRESENTATION, you can set an agency to be selected here. The IFlow will import all Value Mappings that match the given agency / scheme into one CPI Value Mapping artifact. Note: You can use * as wildcard operator. |
| VM_SCHEME (More) | If VM_MODE=REPRESENTATION, you can set a scheme to be selected here. The IFlow will import all Value Mappings that match the given agency / scheme into one CPI Value Mapping artifact. Note: You can use * as wildcard operator. |
If you have configured the runtime parameters as defined above, you can execute the import process by simply deploying the IFlow. The import will run exactly once per deployment. So if you want to import multiple value mappings, just change the runtime parameters and re-deploy the IFlow another time. That's it!
Explanation step by step - for the interested
For those who not only want to execute, but also understand, I explain below step by step what the IFlow does. If you have any questions, please feel free to leave a comment below this blog.
- The content modifier is used to read all the externalized parameters (see "Configure" section/table above) into SAP CPI message properties. This allows us to access them later in the process.
- The graphical mapping creates the "Query" message XML for SAP PO's value mapping webservice called "ValueMappingInService". The datatypes/XSDs used in the graphical mapping were imported from the webservice's WSDL file. (You can read more on the value mapping service and how to access it, in the section "Directory API" of the following blog.)
The ValueMappingInService works in a two-step mode. First a "Query" request has to be send, to select Value Mappings. The reponse (used in steps 4 and 5) contains technical ids that are used to read the actual value mappings (and their contents.) - Via request-reply step and a SOAP channel (that is also configured via SAP PI's WSDL file) we request the technical value mapping ids.
- This graphical mapping maps the QueryReponse (which contains the technical value mapping ids) to the ReadRequest message (which is needed to pull the actual value mapping data from SAP PO). Both message definitions QueryReponse as also ReadRequest were imported from SAP PO's ValueMappingInService WSDL.
- Via request-reply step and a SOAP channel (that is also configured via SAP PI's WSDL file) we request the actual value mappings/-data.
- This mapping maps the value mapping content from the SAP PO format (ReadResponse) to the SAP CPI value mapping XML format. The XSD for the ReadReponse type was taken from SAP PO's WSDL. For the SAP CPI side I manually created a Value Mapping, then downloaded it, unzipped it and opened the value_mapping.xml from the zip-file. Then I used Freeformatter's XSD Generator to generate a XSD file out of the sample XML.
- This groovy script is the "heart" of the IFlow. It takes the value_mapping.xml (from the step before) as also as all other text-based files that are part of a CPI value mapping artifact zip-file and builds a fresh, new .zip-File in memory. Then it takes the zip file's bytes, encodes them as Base64 and writes the to a message property and the body.
Why do we do so? We'll later use CPI's Value Mapping upload api. This API expects a value mapping zip-file with the same content/structure as if you would download a Value Mapping artifact from CPI. Thus we have to go this "extra mile" to generate a zip-file. - This Content Modifier clears all headers (which could lead problem in the following HTTP requests) and sets the X-CSRF-TOKEN header with value "FETCH" which is necassary to retrieve an X-CSRF token. (Which again is necessary to run a POST request towards CPI's api.)
- Via request-reply step and a HTTP channel (that is configured according to the service description) we request a X-CSRF token via http GET request.
- This Content Modifier step reads X-CSRF token returned by the CPI api and writes it to a message property.
- This Content Modifier step set the X-CSRF token header, the Content-Type (=application/json) header and sets the message body to the target JSON format. (The JSON structure can be checked out in SAP API Hub >> Value Mappings >> POST ValueMappingDesigntimeArtifacts.)
- Via request-reply step and a HTTP channel (that is configured according to the service description) we send out the value mapping data to SAP CPI's api.
- In case of an error, we try to parse the HTTP error response text for a specific error message and then re-throw the Exception. Why? That way we can get more specific error texts into SAP CPI's monitoring, which should make error tracing easier.
A more detailed description of the process above is certainly possible, but would go beyond the scope of this blog here. Nevertheless, I am happy to answer any follow up questions in the comments section.
Conclusion
As with my last blog, the idea for this blog once again came from the SAP Influence Program. What does it teach us? On the one hand, you can find a lot of really good ideas for product improvements there, and on the other hand, some of the features you need can already be implemented today (without necessarily having to wait for an official solution).
And the moral of the blog? Check the influence program, 'cause it does rock.
So I can only recommend to everyone: participate in the Influence Program. Let your ideas flow in or let yourself be inspired by the suggestions that have already been set up. Maybe you will also find an idea for which you already have a solution proposal today! I look forward to your blogs 😉
- SAP Managed Tags:
4 Comments
