I'm guessing that if you landed here, it is because you need to mass update your Maintenance Task Lists (header and/or operation level) with new Document Info Records (DIR) assignments...but you have not found a method to do so.
You may want to update them because the DIRs in question have been revised, or maybe you have been live and using Maintenance Task Lists for some time, and you now want to enrich them with the addition of DIRs.
Your starting point may be twofold, but in both cases, it is assumed that your Maintenance Task Lists already exist in the system, and:
In this post, we will look at both ways of achieving this. In case you cannot wait for the details, as a spoiler, we will do this using existing API's and the OAuth authentication mechanism, instead of using Basic Authentication, which as you have probably found out is not working. With the former, we can use the API by testing the actual authorisations of a business user!
Foreword
Before we get into the main point of this post, I want to briefly digress and provide some context for the scenario.
Firstly, in SAP S/4HANA Cloud, public edition, support is provided to associate one or more external information sources (attachments) to many objects (both master and transactional data) in the system. For example, you may want to associate a picture of a product with the corresponding Product Master or you may want to associate a scanned copy of a Supplier Invoice with the invoice as you enter it in the system. This association could be a link (URL) or an actual upload of the document (i.e the picture or the scanned invoice) in question into your system.
Secondly, this attachment can be stored in one of two ways, depending on your settings and limitations regarding where you want to store it (header vs item level) and built-in app support for one or either storage system. It can be stored leveraging the GOS (Generic Object Services) or DMS (Document Management System). This post will assume the latter. I.e our attachment in question will be uploaded to a DIR (Document Info Record), and it is then the DIR that will be assigned to the Maintenance Task List.
Any DIR created can be viewed/managed via the app 'Manage Documents'. Beyond being able to upload an attachment to a DIR, DIRs offer the ability to create your own DIR types, they can have a lifecycle (in-work, released, revised...), they can be classified (Classification System), they can be revised (Revision Levels) and thus submitted to Engineering Change Management processes. They are ideal in engineering, regulated, audited scenarios where segregation of responsibilities, accountability, and traceability are required.
In our scenario, we will imagine that a Maintenance Safety Department within an asset-heavy company produces and maintains critical Standard Operating Procedures (SOP) that must be followed to safely carry out maintenance procedures. Rather than having obscure post-it note processes telling engineers where they can find the latest copy of a procedure, this company has chosen to create DIRs that hold the Standard Operating Procedure (a pdf copy of it). The DIRs then need to be assigned to Maintenance Tasks Lists. Maintenance Orders leveraging these Maintenance Task Lists will then readily provide immediate access to the most accurate and updated SOPs to the engineers right there on the job.
As usual, several things need to be set up in your landscape for this to work before we can jump into Postman, which is the tool we use to simulate the API. These things are:
Unfortunately, this section is going to be a quick one, as my colleague Dennis L did the heavy lifting here for me, and he just advised me it was done, although I suspect some settings were made in the IAS (Identity Authentication System) that the S/4HANA Cloud system uses to authenticate business users. But maybe, you can leave a note in the comment section, asking him what he did in detail and tempt him into writing a blog on that part 🙂
Dennis essentially advised me that OpenID Connect (OIDC) had been enabled/setup and he also provided me with two key pieces of information, that is :
We will need those later on, so make sure you have those details on hand.
This will be done in the SAP S/4HANA Cloud system. You should be familiar with the use of this application, so I will only cover those settings that are specific / of importance for our setup. For your created Communication System, maintain the following information:
in the OAuth 2.0 settings, maintain the Client Redirect URI. In this case, it is a reference to the IAS system used to authenticate the business users that connect and use the SAP S/4HANA Cloud system (it assumes that this is the chosen IAS).
This will be a URL, in the form https://yourIAS.accounts400.ondemand.com , where yourIAS is to be replaced with your own IAS.
In the identity provider section, enter:
To know more about this setup, you can check the SAP help here.
Lastly, still in the section Users for Inbound Communication, click the + (3) to add a new user and use the settings as shown in the image above. In the OAuth 2.0 client ID, paste the Client ID provided previously. Then, click OK and save.
More information on this can be found in the SAP help, here.
Depending on the scenario(s) that you want to enable, you will need to create communication arrangements, corresponding to SAP_COM_0105 (Product Lifecycle Management) and/or SAP_COM_395 (Asset Management Master Data Integration). Again, in this section, it is assumed that you are familiar with its setup and only the specific section will be covered.
Also note the Grant Type, which is Authorization Code + PKCE, as you will need it later in Postman. Save your entry.
This will reveal several important settings that you should make a note of, as you will need them in Postman when you request a token, namely:
Because, when you call a specific scope (API), we will be using a business user to authenticate and perform the action requested by the API, we have to ensure that the business user has the right authorizations, in other words, the right business catalogs assigned to his user.
To find the catalog(s) that are required to invoke a specific scope, then in the image below select the radio button (1) that corresponds to the API you will want to use, and then click on 'Granted by Business Catalogs' (2).
This will then reveal a new window showing the Business Catalog(s) (1) that will grant a business user access to the required actions when the API is called.
This will not be covered as it is assumed that you are familiar with this step. Essentially you'll need to use or create a Business Role, to which you will assign one of the business catalogs listed in the previous step, and then assign the Business Role to the business user ID that will be calling the API. You will also want to make sure that role affords the capability to create, as we are going to create data.
Now that the IAS, SAP S/4HANA Cloud and OAuth settings have been maintained, we can move on to Postman, to set up the OAuth authentication type. So fire up your Postman and create a request as you usually would.
The first thing you want to do is to set the Authorization type to OAuth 2.0 in the Authorization tab, and select Request Headers, in the Add Authorization data to section, as shown below.
You then want to move to the right of your screen and complete the details required to set up the Token request.
--> Header Prefix - Keep defaulted value - Bearer
Configure New Token. To fill this section, some of the details we will have come across previously. I have added the below image to show the correspondence of what we covered before and where it goes in Postman. The other settings that have not been covered before are:
Lastly, despite the client ID having been supplied (as shown in the above image), I received error messages that the parameter client ID had not been supplied. Adding it in the Advanced and Token Request section, as shown below resolved the issue for me. The client ID is the same as the one we used previously.
Once all of this is done, you can hold your breath and click the Get New Access Token button.
This is what should then happen.
Postman will throw a popup, advising that it is getting a new access token. At the same time, another familiar-looking window should open, asking you to authenticate as you normally would when logging on to your SAP S/4HANA Cloud system. Enter your usual business user credentials (this business user should have the role previously created assigned to him!)
Once your credentials are verified you will be asked to Allow or Decline access to the scope that corresponds to the API you are trying to invoke (remember the scope is what we saw in the Communication Arrangement). It also says that the scope is being accessed by the Application XYZ , which corresponds to the client ID that we have previously covered. Click Allow,
If all goes well, you will get a green check indicator, meaning that the authentication is allowed and complete, and a Token is now available for you to use, when you will call the API.
A window will be presented showing the details of the generated access token. Click 'Use Token'.
Note that the Authorization section has now been updated with the name (that you gave) and key of the Token. You can now use this token to perform operations using the API API_DMS_PROCESS_SRV_0001 (the scope in the request of the token !)
In the next section, we will see how we use the token to perform an API operation.
To fulfill this requirement we shall be using the API Document Info Record, for which you can find all the information you need from the SAP Business Technology Hub. This will give you the name of the communication scenario that you need to set up in your system (SAP_COM_0105), as well as the API reference information (resource --> Document_Info_record). There you want to find the operation type that will allow you to POST and create a link between a Maintenance Task List and a DIR. This might not seem evident by reading the descriptive text of this operation (i.e Creates an object link between a product and a document info record), but as we will see, I found that it worked for Maintenance Task Lists also.
As per the API specification, we need to pass as parameters (in the URL) references to the document that we want to link to our object (the maintenance task list) - this is highlighted in the image below.
And in the body of the request we need to pass the details of the object to which we want to assign the above-referenced DIR. We need to pass the Technical object type (use PMPLKO for Maintenance Task list header or PMPLPO for task list operation), and the key that uniquely identifies the Task List Header or Operation depending on your chosen assignment.
We also need to make sure that the token we previously generated will be used to take care of the authentication. For this, we go to the Authorization tab and make sure that the 'Current Token' is the one previously generated.
Before we POST the call, let's quickly check the document assignment in the SAP S/4HANA Cloud system.
As you can see, there are at this point no assignments, to any object of this document.
So let's go and POST !
We can see that we are getting a 201 response code (created) and we see in the body of the response the SAP object references we had passed.
Lastly, let's go back into SAP S/4HANA Cloud to verify that the assignment has been updated.
In the DIR we now have a reference to the Maintenance Task List.
Similarly, we can check the Maintenance Task List and verify the DIR assignment is also available there - which it is.
To fulfill this requirement we shall be using the Attachment API, for which you can find all the information you need from the SAP Business Technology Hub. This will give you the name of the communication scenario that you need to set up in your system (SAP_COM_0395), as well as the API Reference information.
The operation we will be using is /AttachmentContentSet
As you may recall, in the previous use case, we used a distinct scope, which represented the API we were going to call. As we will now be using a different API, it stands to reason that we will need to reference a different scope, and thus request a different Token for it. The scope used this time will be: API_CV_ATTACHMENT_SRV_0001 (As before you can find this information in the OAuth 2.0 details of the communication arrangement).
Once we have updated the authorization tab in Postman with this scope, we can as before, using the same information as before, request a new Token. This will not be shown here, but it works exactly the same as what we covered before, and we also gave this token a different name.
Now that we have the token, we can as before check/update the authorisation tab of the request to make sure that this token will be used. Let's see what other information we need to maintain, to process the desired action in SAP S/4HANA Cloud.
This API, takes no parameters, so the URL just points to the API and action. In the Headers tab we need to maintain the following key/value combinations:
We then reference the file we want to upload, for this, we go to the body tab and select the content type as binary, and we click 'Select File' to choose the file from our drive (please check the API help information for other content options)
Once the file has been chosen, its reference will be shown.
Now that all the information is maintained, hit POST to call the API.
As before, we get a 201 return code, meaning something has been created. If we examine the response more closely, we can see that a document (DIR) 10000000021 is created and we also see references to the SAP object PMPLPO and the object key we provided.
So let's look at this newly created document in SAP S/4HANA Cloud. We can see that it is assigned to the object we provided in the payload, and we also see that the uploaded document has inherited a name equal to the 'slug' that we provided in the headers of our message.
Lastly, let's check to see if we find the DIR assignment in the Maintenance Task List at the operation level. Indeed we do.
Hopefully, this has been instructive and has shown you how you can assign DIRs to your Maintenance Task Lists at the header and/or operation level. The trick being to use OAuth, in order to leverage the authorisations of a business user vs those of a lambda communication user.
You may want to update them because the DIRs in question have been revised, or maybe you have been live and using Maintenance Task Lists for some time, and you now want to enrich them with the addition of DIRs.
Your starting point may be twofold, but in both cases, it is assumed that your Maintenance Task Lists already exist in the system, and:
- The Document Info Record you want to assign to the Maintenance Task Lists already exists in your system, and all you need to take care of is the assignment of the DIR to the Maintenance Task List (Header and/or Operation level), or
- The Document Info Record does not yet exist in your system, and you want to handle its creation and assignment to a Maintenance Task List Header and/or Operation level in one shot.
In this post, we will look at both ways of achieving this. In case you cannot wait for the details, as a spoiler, we will do this using existing API's and the OAuth authentication mechanism, instead of using Basic Authentication, which as you have probably found out is not working. With the former, we can use the API by testing the actual authorisations of a business user!
Foreword
Before we get into the main point of this post, I want to briefly digress and provide some context for the scenario.
Firstly, in SAP S/4HANA Cloud, public edition, support is provided to associate one or more external information sources (attachments) to many objects (both master and transactional data) in the system. For example, you may want to associate a picture of a product with the corresponding Product Master or you may want to associate a scanned copy of a Supplier Invoice with the invoice as you enter it in the system. This association could be a link (URL) or an actual upload of the document (i.e the picture or the scanned invoice) in question into your system.
Secondly, this attachment can be stored in one of two ways, depending on your settings and limitations regarding where you want to store it (header vs item level) and built-in app support for one or either storage system. It can be stored leveraging the GOS (Generic Object Services) or DMS (Document Management System). This post will assume the latter. I.e our attachment in question will be uploaded to a DIR (Document Info Record), and it is then the DIR that will be assigned to the Maintenance Task List.
Any DIR created can be viewed/managed via the app 'Manage Documents'. Beyond being able to upload an attachment to a DIR, DIRs offer the ability to create your own DIR types, they can have a lifecycle (in-work, released, revised...), they can be classified (Classification System), they can be revised (Revision Levels) and thus submitted to Engineering Change Management processes. They are ideal in engineering, regulated, audited scenarios where segregation of responsibilities, accountability, and traceability are required.
In our scenario, we will imagine that a Maintenance Safety Department within an asset-heavy company produces and maintains critical Standard Operating Procedures (SOP) that must be followed to safely carry out maintenance procedures. Rather than having obscure post-it note processes telling engineers where they can find the latest copy of a procedure, this company has chosen to create DIRs that hold the Standard Operating Procedure (a pdf copy of it). The DIRs then need to be assigned to Maintenance Tasks Lists. Maintenance Orders leveraging these Maintenance Task Lists will then readily provide immediate access to the most accurate and updated SOPs to the engineers right there on the job.
System setup
As usual, several things need to be set up in your landscape for this to work before we can jump into Postman, which is the tool we use to simulate the API. These things are:
- Setting up the OAuth authentication
- Setting up a communication system
- Setting up a communication arrangement
- Setting up up business user authorisations
Setting up the OAuth authentication
Unfortunately, this section is going to be a quick one, as my colleague Dennis L did the heavy lifting here for me, and he just advised me it was done, although I suspect some settings were made in the IAS (Identity Authentication System) that the S/4HANA Cloud system uses to authenticate business users. But maybe, you can leave a note in the comment section, asking him what he did in detail and tempt him into writing a blog on that part 🙂
Dennis essentially advised me that OpenID Connect (OIDC) had been enabled/setup and he also provided me with two key pieces of information, that is :
- The client id
- The client secret
We will need those later on, so make sure you have those details on hand.
Setting up the communication system
This will be done in the SAP S/4HANA Cloud system. You should be familiar with the use of this application, so I will only cover those settings that are specific / of importance for our setup. For your created Communication System, maintain the following information:
in the OAuth 2.0 settings, maintain the Client Redirect URI. In this case, it is a reference to the IAS system used to authenticate the business users that connect and use the SAP S/4HANA Cloud system (it assumes that this is the chosen IAS).
This will be a URL, in the form https://yourIAS.accounts400.ondemand.com , where yourIAS is to be replaced with your own IAS.
In the identity provider section, enter:
- OIDC Token Issuer : Again, enter https://yourIAS.accounts400.ondemand.com , where yourIAS is to be replaced with your own IAS
- Client ID : The client id provided
- Web keys Download URI : This will be https://yourIAS.accounts400.ondemand.com/oauth2/certs , where yourIAS is to be replaced with your own IAS. In edit mode, you will have a button allowing you to import the keys from the provider.
To know more about this setup, you can check the SAP help here.
Lastly, still in the section Users for Inbound Communication, click the + (3) to add a new user and use the settings as shown in the image above. In the OAuth 2.0 client ID, paste the Client ID provided previously. Then, click OK and save.
More information on this can be found in the SAP help, here.
Setting up a Communication Arrangement
Depending on the scenario(s) that you want to enable, you will need to create communication arrangements, corresponding to SAP_COM_0105 (Product Lifecycle Management) and/or SAP_COM_395 (Asset Management Master Data Integration). Again, in this section, it is assumed that you are familiar with its setup and only the specific section will be covered.
Also note the Grant Type, which is Authorization Code + PKCE, as you will need it later in Postman. Save your entry.
This will reveal several important settings that you should make a note of, as you will need them in Postman when you request a token, namely:
- (2) the client ID, already covered previously
- (3) the token service URL
- (4) the Authorization URL
- (6) the scope ID (corresponds to the API that you will be calling)
Because, when you call a specific scope (API), we will be using a business user to authenticate and perform the action requested by the API, we have to ensure that the business user has the right authorizations, in other words, the right business catalogs assigned to his user.
To find the catalog(s) that are required to invoke a specific scope, then in the image below select the radio button (1) that corresponds to the API you will want to use, and then click on 'Granted by Business Catalogs' (2).
This will then reveal a new window showing the Business Catalog(s) (1) that will grant a business user access to the required actions when the API is called.
Setting up Business User Authorisations
This will not be covered as it is assumed that you are familiar with this step. Essentially you'll need to use or create a Business Role, to which you will assign one of the business catalogs listed in the previous step, and then assign the Business Role to the business user ID that will be calling the API. You will also want to make sure that role affords the capability to create, as we are going to create data.
Postman Setup
Now that the IAS, SAP S/4HANA Cloud and OAuth settings have been maintained, we can move on to Postman, to set up the OAuth authentication type. So fire up your Postman and create a request as you usually would.
The first thing you want to do is to set the Authorization type to OAuth 2.0 in the Authorization tab, and select Request Headers, in the Add Authorization data to section, as shown below.
You then want to move to the right of your screen and complete the details required to set up the Token request.
--> Header Prefix - Keep defaulted value - Bearer
Configure New Token. To fill this section, some of the details we will have come across previously. I have added the below image to show the correspondence of what we covered before and where it goes in Postman. The other settings that have not been covered before are:
- Token name - give it a meaningful name
- Grant Type - Authorization Code (With PKCE)
- Client secret - this should have been provided to you by your administrator
- Code challenge method - SHA-256
- State - you may get an error message saying that the parameter State is missing. If so enter random
- Client Authentication - Send as Basic Auth Header
Lastly, despite the client ID having been supplied (as shown in the above image), I received error messages that the parameter client ID had not been supplied. Adding it in the Advanced and Token Request section, as shown below resolved the issue for me. The client ID is the same as the one we used previously.
Once all of this is done, you can hold your breath and click the Get New Access Token button.
This is what should then happen.
Postman will throw a popup, advising that it is getting a new access token. At the same time, another familiar-looking window should open, asking you to authenticate as you normally would when logging on to your SAP S/4HANA Cloud system. Enter your usual business user credentials (this business user should have the role previously created assigned to him!)
Once your credentials are verified you will be asked to Allow or Decline access to the scope that corresponds to the API you are trying to invoke (remember the scope is what we saw in the Communication Arrangement). It also says that the scope is being accessed by the Application XYZ , which corresponds to the client ID that we have previously covered. Click Allow,
If all goes well, you will get a green check indicator, meaning that the authentication is allowed and complete, and a Token is now available for you to use, when you will call the API.
A window will be presented showing the details of the generated access token. Click 'Use Token'.
Note that the Authorization section has now been updated with the name (that you gave) and key of the Token. You can now use this token to perform operations using the API API_DMS_PROCESS_SRV_0001 (the scope in the request of the token !)
In the next section, we will see how we use the token to perform an API operation.
Scenario 1: DIR and Maintenance Task List already exists in the system and API is used to assign the DIR to the Maintenance Task List (at header or operation level).
To fulfill this requirement we shall be using the API Document Info Record, for which you can find all the information you need from the SAP Business Technology Hub. This will give you the name of the communication scenario that you need to set up in your system (SAP_COM_0105), as well as the API reference information (resource --> Document_Info_record). There you want to find the operation type that will allow you to POST and create a link between a Maintenance Task List and a DIR. This might not seem evident by reading the descriptive text of this operation (i.e Creates an object link between a product and a document info record), but as we will see, I found that it worked for Maintenance Task Lists also.
As per the API specification, we need to pass as parameters (in the URL) references to the document that we want to link to our object (the maintenance task list) - this is highlighted in the image below.
And in the body of the request we need to pass the details of the object to which we want to assign the above-referenced DIR. We need to pass the Technical object type (use PMPLKO for Maintenance Task list header or PMPLPO for task list operation), and the key that uniquely identifies the Task List Header or Operation depending on your chosen assignment.
We also need to make sure that the token we previously generated will be used to take care of the authentication. For this, we go to the Authorization tab and make sure that the 'Current Token' is the one previously generated.
Before we POST the call, let's quickly check the document assignment in the SAP S/4HANA Cloud system.
As you can see, there are at this point no assignments, to any object of this document.
So let's go and POST !
We can see that we are getting a 201 response code (created) and we see in the body of the response the SAP object references we had passed.
Lastly, let's go back into SAP S/4HANA Cloud to verify that the assignment has been updated.
In the DIR we now have a reference to the Maintenance Task List.
Similarly, we can check the Maintenance Task List and verify the DIR assignment is also available there - which it is.
Scenario 2: Maintenance Task List already exists in the system and API is used to upload an attachment to S/4HANA Cloud, assign it to and create a DIR, then assign the DIR to the Maintenance Task List (at header or operation level) in one operation
To fulfill this requirement we shall be using the Attachment API, for which you can find all the information you need from the SAP Business Technology Hub. This will give you the name of the communication scenario that you need to set up in your system (SAP_COM_0395), as well as the API Reference information.
The operation we will be using is /AttachmentContentSet
As you may recall, in the previous use case, we used a distinct scope, which represented the API we were going to call. As we will now be using a different API, it stands to reason that we will need to reference a different scope, and thus request a different Token for it. The scope used this time will be: API_CV_ATTACHMENT_SRV_0001 (As before you can find this information in the OAuth 2.0 details of the communication arrangement).
Once we have updated the authorization tab in Postman with this scope, we can as before, using the same information as before, request a new Token. This will not be shown here, but it works exactly the same as what we covered before, and we also gave this token a different name.
Now that we have the token, we can as before check/update the authorisation tab of the request to make sure that this token will be used. Let's see what other information we need to maintain, to process the desired action in SAP S/4HANA Cloud.
This API, takes no parameters, so the URL just points to the API and action. In the Headers tab we need to maintain the following key/value combinations:
- slug - This will be the name of the attachment once uploaded in SAP S/4HANA Cloud. In this case, it will be a .pdf document,
- Content-Type - this has to be relevant with respect to the document you will be uploading. As we will be uploading a pdf document, we use the value application/pdf,
- BusinessObjectTypeName. As before we have to reference the technical object type to which we intend to assign the attachment. Here we use PMPLPO, as we will be assigning the attachment to a Task List operation (You could also as before, use PMPLKO, to make the assignment to a Task List Header)
- LinkedSAPObjectKey. In the previous step, we said the object would be Maintenance Task List Operation, now we have to provide a specific reference to the Task List and operation.
We then reference the file we want to upload, for this, we go to the body tab and select the content type as binary, and we click 'Select File' to choose the file from our drive (please check the API help information for other content options)
Once the file has been chosen, its reference will be shown.
Now that all the information is maintained, hit POST to call the API.
As before, we get a 201 return code, meaning something has been created. If we examine the response more closely, we can see that a document (DIR) 10000000021 is created and we also see references to the SAP object PMPLPO and the object key we provided.
So let's look at this newly created document in SAP S/4HANA Cloud. We can see that it is assigned to the object we provided in the payload, and we also see that the uploaded document has inherited a name equal to the 'slug' that we provided in the headers of our message.
Lastly, let's check to see if we find the DIR assignment in the Maintenance Task List at the operation level. Indeed we do.
Conclusion
Hopefully, this has been instructive and has shown you how you can assign DIRs to your Maintenance Task Lists at the header and/or operation level. The trick being to use OAuth, in order to leverage the authorisations of a business user vs those of a lambda communication user.
- SAP Managed Tags:
1 Comment
