- SAP Managed Tags:
Objective
In this tutorial we will setup a data source which will connect to one of APM services but procedure is the same to connect to any other service, even for third party services managed by other companies or customers themselves.
Goal is to import a visualization, tag it with useful metadata (in this case "Equipment ID"), create data source which will connect to an APM service, and present data in customized Viewer template. End users will just have to load visualization in specific Viewer template and click on an object. This will fetch data from AP service about selected object and show it in info card.
In our instance of APM service we have functional location with Id “WDPL-WDF-AA-01”. This functional location has number of equipment assigned to it. We want to tag our 3D model with equipment ids that match these ones in APM so that in run time when user selects any 3D object we can pass its equipment id to APM service and fetch additional data about this object.
Collect data required for setup
First step is to collect data needed to connect to APM service. This includes service endpoint URL, connection credentials and in some cases additional headers. Details about SAP services are published in SAP API hub while for third party services data must be collected from their documentation.
For this demo we will use TechnicalObjectService from APM which is documented SAP API Hub. In documentation, in section “Configuration Details” we can see that base URL is this:
https://{host}.eu20.hana.ondemand.com/TechnicalObjectService/v1Then we add endpoint name that we want to call, in our case it is TechnicalObjects so URL will be like this:
https://{host}.eu20.hana.ondemand.com/TechnicalObjectService/v1/TechnicalObjectsAdding our host (which we have received when we subscribed to APM service) the final URL will be like this:
https://api-apm.prod.apimanagement.eu20.hana.ondemand.com/TechnicalObjectService/v1/TechnicalObjects
Next step is to decide if we need any parameters in this call. In our case we want first to fetch all technical names from functional location WDPL-WDF-AA-01. According to APM documentation we can add filter to TechnicalObjects endpoint which will fetch only equipment that belong to it.
The example of URL with such filter which will retrieve list of all equipment under our functional location will look like this:
https://api-apm.prod.apimanagement.eu20.hana.ondemand.com/TechnicalObjectService/v1/TechnicalObjects?$filter=(superiorFunctionalLocation+eq+%27WDPL-WDF-AA-01%27+and+number+gt+%2710003966%27+and+number+lt+%2710004041%27)&$top=200
So we are calling our endpoint with filter which says that superiorFunctionalLocation must be equal to WDPL-WDF-AA-01, their ids must be between 10003966 and 2710004041 we want only first 200 equipment to be listed. This is just to see if we can call this service and to test data retrieval.
Note that %27 in the example above is URL encoded value for double quote symbol.
This call will return list of all equipment for given functional location. We will make this call just for testing and to get list if existing equipment numbers. To obtain details about one single equipment we have to make another call. This time we will make a call to this URL:
https://api-apm.prod.apimanagement.eu20.hana.ondemand.com/TechnicalObjectService/v1/TechnicalObjects?$filter=(number+eq+'__EQU__')
This one includes different filter. Now we are asking service to provide details about one single equipment which id is equal to __EQU__. This is special syntax in PLM Visualization which indicates that EQU is parameter which we will pass to this data source. Any name surrounded by double underscores will be treated as parameter.
Next we need to get user credentials. PLM Visualization offers several authentication methods:
- Principal Propagation
- Basic Authentication
- OAuth2 Client Credentials
- Password Grant
- No Authentication
The best way is to use Principal Propagation as this will authenticate current PLM user to that system we are connecting to. However, that requires some additional setups which are different for different systems. In our example we will use OAuth2 Client Credentials which is also known as technical user. Please note that this is not recommended way as server does not have any way to know what real user is calling it but in our example this will be sufficient. For this connection type we need client id and client secret from APM service which we have received when we subscribe to it.
Checking APM documentation again we see that they also require special header with API key. This key is also provided when APM service is subscribed.
Create Data Connection
In IPD Visualization open "Data Source" application
Now click on Add data source and we will start filling data for new data source. First give it a name, we call it APM_TechnicalObject_Details. Description is optional but it’s always good practice to write what is this data source about. In our case it will retrieve details about one single equipment - therefore Response Type will be set to “Object”.
Since we are not calling any Integrated Service (services implemented by other PL capabilities), and not SAP Netweaver Gateway services we will select “Other” for Service Type. Press “Step 2” button.
Now in URl section we will place the URL which will get all equipment, Proxy Type will be “Internet” and Authentication will be “OAuth2 Client Credentials”. HTTP Method is GET and we only need to add additional header for API key. This header is x-api-key and its value is API key from APM service subscription data.
This is all that is needed at this stage and whole setup should look like this:
Now press the Test button on right hand side and if all data is correct, we should see response in form of JSON text with list of first 200 equipment objects for our functional location.
As I said before this is just to check that our connection works and to grab list of equipment ids stored in the system. Now we can copy raw response and paste it in text editor so that we can use these numbers later.
Our data source is supposed to use service URL which will retrieve equipment details so let’s replace URL with that one:
Note that in right hand side now we have new text input field for EQU parameter and that Test button is not enabled. This parameter is needed for our testing of data source and will replace __EQU__ substring in the service URL.
Grab one of equipment IDs retrieved in previous step and place it in EQU input box. Now we can press Test button and as a result we should see details of that equipment:
This means that everything is fine and we can now press button “Save” and move on to the next step by clicking on “Step 3” button.
Here we are doing data mapping. We are mapping data retrieved from APM service about equipment to list of parameters that we want to expose from our data source. We may not want to expose all information retrieved from service, or we may want to rename some of data.
This is done by selecting what part of raw response will be taken and which of its fields will be returned when this data source is called. In our case we will specify $.value.[0] in Filter Expression field. This means that we want to start from the root of retrieved JSON content, take its property value and then first element in array of elements under this property. In raw response above you’ll see where this information is coming from. There is “value” property at root level of JSON and it has child element of type array. Since our filter will always retrieve only single element in this array, we are taking only its first element.
Note that this syntax is standard JSON path syntax which is well documented.
Clicking on select icon in Select Properties field we will see popup dialog box with list of possible parameters where we can select which ones we want to expose in this data source and if we want, we can also change their names.
After another test (click on Test button) we can save our data source, and it is now ready to be used in viewer templates and info cards.
