Skip to Content
Technical Articles
Author's profile photo Mio Yasutake

Transporting role collections between BTP subaccounts Part1 : Custom tool


In this blog, I’m going to introduce a tool which I developed for transporting role collections between BTP subaccounts. Keep in mind that this is just a PoC and not intended for productive use.
The code is available at GitHub.

While writing this blog post, I learned that it is possible to transport role collections with xs-security.json even if the roles used are not from the same xsuaa service instance.
Anyway, I’m sharing this content to introduce what I’ve developed. Also, I’ve decided to write another blog post for demonstrating how transporting role collections can be achieved by standard approach.


The tool


The idea is to use Authorization and Trust management Service API to create and update role collections in a target subaccount. Based on the role collection settings of the source subaccount, the tool will create or update a role collection with the same settings in the target subaccount.


The diagram blow shows the architecture of this tool.

  • UI5 app and CAP are running behind a standalone approuter
  • Destinations pointing to Authorization and Trust Management API in source and target subaccounts are registered
  • CAP calls
    • the API in the source subaccount to extract the definition of role collections to be transported
    • the API in the target subaccount to create or update role collections there


Solution architecture


  • All the roles included in role collections to be transported have to be in the target subaccount.
  • Role collections in the source subaccount have to be maintained manually.
  • HANA Cloud instance has been created in the source subaccount. (tutorial link)


Initial Setup

1. Clone the code from GitHub, build and deploy to Cloud Foundry

You will find the approuter in subaccont space.



2.  Create xsuaa service instances with plan “apiaccess” in source and target subaccounts

cf create-service xsuaa apiaccess <access_name>


3. Create service keys for the service instances you just created

cf create-service-key <access_name> <key_name>


4. Create destinations pointing to Authorization and Trust Management API referencing the service keys

Property Value
Name Destination Name (Any)
URL “apiurl” in the service key
Proxy Type Internet
Client ID “clientid” in the service key
Client Secret “clientsecret” in the service key
Token Service URL “url” int the service key + /oautn/token




5. Check application identifier suffix in each subaccount

You can see the suffix in any role registered in the subaccount. The suffix starts with “!” and varies by subaccount.

Please note that this approach works only for custom roles created with xs-security.json. Standard roles such as WorkflowAdmin get their own application identifiers and this identifier varies depending on the service. Therefore, role collections comprising of standard roles cannot be transported with this tool.




How to use

Now the initial setup is done, let’s start using the tool!

1. Open the approuter URL
You will see below screen.


Home screen


2. Maintain destinations

Go to Settings>Maintain Destinations. Here you register combinations of destination and suffix.


Maintain destinations

3. Start Transport

Go to Transport>Role Collections.

First, select source and target destinations.


Select destinations


Second, specify role collections you want to transport. You can input multiple role collections separated by line breaks.


Input role collections

Finally, confirm the role collections and press “transport”.



The following screen will be displayed. Transport may take a few minutes.


Transport in progress

When the transport is complete, you will see below message.


Transport success


What the tool does

Let me explain what the tool does behind the scenes. I’m using Postman to show how APIs are called.

1. Extract definition of the role collection to be transported from the source subaccount.


Extract role collection definition from the source subaccount


2. Replace the suffix in the definition with the suffix of the target subaccount.

As roles get suffix which is unique to the subaccount, we have to replace it with that of the target subaccount before sending the definition to the target subaccount.


Replace suffix


3. Post the role collection to the target subaccount.


Post role collection

If the role collection already exists in the target subaccount, the tool updates it according to the definition in the source subaccount.

Rooms for improvement

The current status of the tool is a Minimum Viable Product (MVP) and there is much room for improvement. The following is a list of those that come to mind.

  • Keeping transport logs
  • Adding authentication and authorization checks
  • Validation of destinations
    • check if they exist in the source subaccount
  • Validation of roles when role collections are entered
    • check if roles included in the role collections exist in the target subaccount
  • Selecting role collections from a list


In this blog post, I’ve introduced a custom tool for transporting role collections.
In the upcoming blog post, I will demonstrate how to transport role collections with MTA and Cloud Transport Management Service.

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Yogananda Muthaiah
      Yogananda Muthaiah

      Well articulated Mio Yasutake !!

      Author's profile photo Mio Yasutake
      Mio Yasutake
      Blog Post Author

      Thank you Yogananda Muthaiah for reading and leaving a comment!

      Author's profile photo DEO DEO
      DEO DEO

      Hello Mio ,

      Why you have added standalone app router



      Author's profile photo Mio Yasutake
      Mio Yasutake
      Blog Post Author

      Hi DEO DEO.

      Thanks for your comment.

      This tool is meant to be for administrators, so I thought using a standalone approuter, rather than launchpad service would be suitable.


      Author's profile photo DEO DEO
      DEO DEO


      Can you explain suffix can be taken as "User defined any name?

      After replacing we are getting below error using POST man.

      "name": "ztransport",
      "description": "",
      "roleReferences": [
      "roleTemplateAppId": "btprolecollection5!t64770",
      "roleTemplateName": "Viewer",
      "name": "Viewer",
      "description": "Viewer"
      "isReadOnly": false

      {"error":"An unexpected error has occurred. Exception executing POST on /sap/rest/authorization/v2/rolecollections (RequestRejectedException). Error was: The request was rejected because the parameter name \"{\n \"name\": \"ztransport\",\n \"description\": \"\",\n \"roleReferences\": [\n {\n \"roleTemplateAppId\": \"btprolecollection5!t64770\",\n \"roleTemplateName\": \"Viewer\",\n \"name\": \"Viewer\",\n \"description\": \"Viewer\"\n }\n ],\n \"isReadOnly\": false\n}\" is not allowed."}


      Any hints?




      Author's profile photo Mio Yasutake
      Mio Yasutake
      Blog Post Author

      Hi DEO DEO,

      Suffix is assigned at each subaccount automatically, so you cannot set arbitrary name on it.

      You can find suffix in any custom role in the target subaccount. Note that standard roles get different suffix than custom roles, so try to look at custom roles.



      Best regards,


      Author's profile photo DEO DEO
      DEO DEO

      Hello Mio Yasutake,

      Thanks for your quick response. if it is a matter of custom roles and Suffix is generated automatically, does it require to use suffix? when we transport custom role collection, because in custom role collection we need to assign the standard roles or roles can be created from code level in case. In my case what to store in suffix for custom roles or we keep it as blank? How i can test the use case lets i have created one custom role collection manually in BTP cockpit (transport) and assign some role template and try to transport into QA account then how i will proceed? Please suggest.




      Author's profile photo Mio Yasutake
      Mio Yasutake
      Blog Post Author

      The prerequisite is the custom roles to be included in the role collection already exist in the target subaccount. So you can check the role in the target subaccount and get the target suffix.

      If your custom role collection includes both custom roles and standard roles, you only have to replace the suffix for custom roles, because for standard roles suffixes stay the same across different subaccounts.