Connecting Focused Build with External DevOps API

[ernesto_villalobos]

Introduction

Exploring options and possibilities to create multiple scenarios using our DevOps tools is possible to connect Focused Build with any Continuous Integration server using the External DevOps API available. This blog explores the API public by SAP using it in a simple Azure DevOps pipeline to show a practical reference on How to use this connection. You can find all the necessary information to work with this API in the official API Business Hub: External DevOps here you can find references, response schema and the excellent option o test this API and snip the code for 7 different scenarios.

API Methods supported

Prerequisites

• SP08 ST-OST Component is installed on a 7.2. SAP Solution Manager SP13 system


• Focused Build Requirements to Deploy configuration has been completed


• SALM_FB Service activated. You can use SICF_INST to check if the services are green


• The System Alias for OData Service /SALM/EXT_DEVOPS_INTEG_SRV must exist. You can use the /n/IWFND/MAINT_SERVICE transaction to check this and add the alias if necessary. Note: The Default System flag should not be set unless you have several system aliases


• Check the Odata Interface through the transaction SEGW and click the icon ‚ Open Project you can enter /SALM/EXT_DEVOPS_INTEG as project input

/n/IWFND/MAINT_SERVICE. System Alias for OData Service

Access to this API is secured by the Internet Communication Framework of the NetWeaver stack of the SAP Solution Manager server and requires a service user. A standard role SAP_OST_FB_DEVOPS_INT is delivered as part of Focused Build SP08. For more information about how to use the standard delivered authorization roles, see the Focused Build Security Guide.

Methodology

To create this practical example I used the tools I have at hand; however, feel free to try with your own testing and CI/CD tools:

• SAP Solution Manager


• Postman


• Azure DevOps

It is essential to explore the official documentation, understand the resources and the methods (GET, POST), try them out and finally design your pipeline.

For starters, I try this API using the SAP Gateway of SAP Solution Manager, this allows me to check the syntax quickly and familiarize myself with the responses. Later on, I use Postman to test an external call and evaluate the attributes and finally I build a small pipeline to interact with my Work Items in Focused Build.

API Reference from SAP API Hub

Note: You will require a Work Item already created, this API does not have any resources to create Work Items.

Testing with SAP Gateway

To test the API I started using the /n/IWFND/GW_CLIENT transaction with the first GET method. From the documentation (available in SAP API Hub --> External DevOps API in Focused Build
Technical Guide.pdf), I know the structure of the endpoint https://:/sap/opu/odata/SALM/EXT_DEVOPS_INTEG_SRV/WorkItemSet(guid=guid’’) and the different resources ?$expand=toWIActualRelease,toWIAttachment,toWIText,toWICategory.

The WIguid is taken from the application directly.

GUID of the Work Item

You can check the correct host and port in the /nSMICM transaction and try the GET method.

Example Response Body for GET using Gateway

You can proceed to check any POST example, the gateway will manage the CSRF and cookies for you.

Creating a new text of type “S105” (Comment) in the work item

Testing with POSTMAN

Once the  API is tested in the SAP Gateway I used Postman to test the API with an external tool, the difference is the CSRF token must be fetched during the POST methods. Therefore, it is necessary to get the CSRF token with a GET request and then pass it to the POST request. To do this in Postman, you should add the key x-csrf-token with the value fetch in the header. You can read other blogs to manage the CSRF more efficiently, for example Just a single click to test SAP OData Service which needs CSRF token validation.

Fetch x-csrf-token

To add a text to your Work Item, for example, you should use the following web service endpoint:

https://:/sap/opu/odata/SALM/EXT_DEVOPS_INTEG_SRV/WorkItemSet(guid=guid’’)/toWIText

the extra header x-csrf-token generated previously and the body

{

   "textType": "S105",

   "textContent": "This is a new message"

}

HTTP POST method as part of the API using Postman

Creating a PIPELINE

Now that I've tested and understood the API I am ready to create my pipeline. I used Azure DevOps Pipelines for this example. I've created this simple code to test the principle presented in the blog, I've designed two stages to explicitly show the different methods.

# Starter pipeline

# With this API, Work Items in Focused Build can be read,

# attachments and texts can be posted and the status of the Work Item can be changed.

# E0002	In Development; E0004	To Be Tested; E0009	Successfully Tested; E0010	Withdrawn; E0011	Preliminary Import Requested; E0012	Test for Preliminary Import; E0013	Tested for Production Import; E0014	Released for Production;# E0015	Handed Over to Release; E0016	Completed; E0017	To Be Corrected



trigger:

- main



pool:

  name: Default

 

stages:

    - stage: invokeGetResponse 

      jobs:

      - job: defineVariables 

        steps:       

        - powershell: |

            $headers = @{

            'Content-Type' = 'application/json'

            'Authorization' = 'Basic <Basic Auth>'

            'x-csrf-token' = 'Fetch'

            }

            $uri = '$(Host)/WorkItemSet(guid=guid''$(WI)'')/toWIText'

            $response = Invoke-WebRequest $uri -Method Get -Headers $headers

            $token=  $response.Headers.'X-CSRF-TOKEN'

            $cookie = ($response.Headers.'Set-Cookie' -split ";" -split ",")[2]          

            echo "##vso[task.setvariable variable=CSRF_Token;isOutput=true]$token"

            echo "##vso[task.setvariable variable=Set_Cookie;isOutput=true]$cookie"

            Write-Output $response

            echo "The variables are created"           

          name: 'createToken'

          displayName: 'Generating Cookies & CSRF token'



    - stage: changeWIStatus

      jobs:

          - job: changingWIStatus

            variables:

              CSRF_Token: $[stageDependencies.invokeGetResponse.defineVariables.outputs['createToken.CSRF_Token']]

              Cookie: $[stageDependencies.invokeGetResponse.defineVariables.outputs['createToken.Set_Cookie']]

            steps:

            - script: |

                set cookie = $(Cookie)

                echo "here is the TOKEN" $(CSRF_Token)

                curl --request POST -v --url "$(Host)/ChangeStatus?userStatus='E0017'&guid=guid'$(WI)'" ^

                -H "Authorization: Basic <Basic Auth>" ^

                -H "Content-Type:application/json" ^

                -H "x-csrf-token: $(CSRF_Token)" ^

                -H "Cookie: %cookie%; sap-usercontext=sap-client=001"                

              displayName: 'Changing the WI Status'

If you want to reuse this code you should define the variables:

• $(HOST) - https://<myfbhost.com>:<port>;


• $(WI) - WI GUID

Note: <Basic Auth> represents your authorization token.

Please feel free to change or improve this example!

Conclusions

Even when we have limited methods for this API, the option to incorporate new integrations with CI/CD tools during our implementation projects with Focused Build is open with this interface. As an example the potential to expand your Continuous Integration looks like an opportunity area; incorporating a hybrid landscape with SAP BTP is another example where we can use this connection with my Requirement-to-Deploy process. Hopefully, this brief example offers clarity and new ideas for your agile journey.

 

***Please be aware that the integration on the external tool side is not delivered by SAP due to the possible number of variations (combination of different tools with different versions/setup/customizing)***