When do your integrations require workspace administrator privileges?

ryan_kohn
ryan_kohn
edited February 2023 in Best Practices

Generally, you don’t need to have Workspace Administrator (WSA) privileges to run integrations; however, there are still some specific instances when they are required. This guide will provide an overview of when your integration user requires WSA privileges. 

Anaplan user types involved in integrations 

First off, let us look at some different user roles that are related to integrations and how they differ from the integration user. 

  • Integration User: An integration user is an Anaplan user account used to run automated integrations. You may have multiple integration users in your tenant. An integration user will need to be added as a user to any model where integrations need to be run. 
  • Model Builder: A model builder is a user that assists in configuring Anaplan. In the context of integration, these users are responsible for creating and managing actions within an Anaplan model. These are the actions that will be run by the integration user(s). Model builders will also manage any import data sources within Anaplan, configure the privacy level on files, and set any production imports. These model builders may be part of the business team or part of IT. The model builder must have WSA privileges. 
  • Integration Administrator: The Integration Admin is a tenant-level role that enables you to manage connections, integrations, and notifications in CloudWorks. The Integration Admin, integration user, and model builder roles are not mutually exclusive – you can be assigned to one, all, or none of the roles. For example, you can be an Integration Admin without being set as a WSA, in which case your integrations will run as a regular (non-WSA) user. 
    • CloudWorks User. This is a special user type that shows up as “Internal (Full Access)” in your models, and is the user that runs any CloudWorks integrations configured by the Integration Admin. You can consider this the “integration user” for CloudWorks. 

You will likely also have some user types outside of Anaplan that own the configuration of any external systems required for integration. 

Building and testing Integrations 

During your implementations, it is usually simpler to test integrations with your own model builder account, as opposed to testing with a dedicated integration user. In practice, this means that most integrations get tested with only WSA privileges, which is not sufficient to ensure that integrations will work properly when executed by non-WSA integration users. Similar to how you need to test your models as an end user, always be sure to test your integrations as an integration user. 

Which Anaplan API calls require WSA privileges? 

Note that all integration tools that interface with Anaplan leverage the Anaplan API. This includes Anaplan Connect and third-party ETL tools (e.g. MuleSoft, Informatica, Boomi, SnapLogic, etc.). This article does not explicitly outline which API calls are used by those tools. The list below is not actively maintained and is only intended to provide general guidance. Consult Anapedia for the most accurate information on the permissions required for any API calls.

This section will provide guidance on which Anaplan API calls require the integration user to have WSA privileges. 

Authentication API 

WSA is not required for the authentication APIs. 

  • Authentication Service API 
  • OAuth2 Service API 

Tenant-level APIs 

These are APIs that support administration at the tenant level and require specific tenant-level roles to use. WSA privileges are not relevant for these APIs. 

  • Anaplan SCIM API 
  • CloudWorks API 
  • Audit API 

Workspace and Model APIs 

These APIs are the standard APIs for integration data to and from Anaplan. 

  • Integration API 2.0. This is also the API used by Anaplan Connect 3+. 
    • Bulk API: WSA is not required for any Bulk API call. This includes imports, exports, processes, and delete actions. This is the API used to import and export data using files. 
    • Transactional API: WSA is required for many, but not all, transactional API calls. More detail is provided below. 
  • ALM API: WSA is required for all the ALM API calls. 

Transactional API Detail 

Note that there are only a limited number of transactional API endpoints that are accessible by a non-WSA. If you plan to leverage the transactional API, it is highly likely that your integration user will require WSA privileges. 

The table below is provided at a summary level only and does not include every single endpoint. You can assume that all the "branches" for an endpoint require WSA if the main endpoint requires WSA (e.g. /items requires WSA, as does /items/{itemId}). However, you should still consult the documentation directly for more details. 

image.png

*The specific details that are returned may also depend on your tenant-level role. 

Setting up permissions for integration users 

In general, you will configure the permissions for the integration user in the same way that you configure permissions for any other user. While WSAs can run any action regardless of their assigned role, a non-WSA user must have a Model Role that grants access to any actions they want to run. 

For further information, you can also read about access constraints in model-to-model imports. 

Other considerations for integration user permissions 

There are some additional situations where the integration user requires WSA privileges: 

Note that from an API standpoint, a non-WSA user is still allowed to attempt to run the above processes using the Bulk API. However, the API will return an error if the user does not have the correct permissions. 

** When an export from the User list is triggered, a file is generated regardless of user permissions. However, there will only be user data if the integration user is a WSA. If the integration user is a non-WSA, then the generated file will not include any users.

File Privacy and Exports

Note that any generated file still respects file privacy. From the Anapedia page on file privacy:

Export files shared with Everyone are available to all users in your Anaplan environment via the Anaplan API. When a workspace administrator generates an export, the export ignores selective access. This means, if you do not limit access to administrators, non-workspace administrators could download data they cannot access to in the model.

Further Reading 

Tagged:

Categories