Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Setting up your organization structure

Updated on April 12, 2021

The Pega platform supports a three-level organization hierarchy for you to model your business. Set up your hierarchy at the start of your project so that as your application develops, your users, queues and work groups are easy to fit into the correct place in the hierarchy.

Task IDTask-040101
Primary roleLead System Architect
Secondary roleN/A
Tertiary roleN/A

Understanding organization structure

In Pega applications, organizations are modelled on a three-level structure:

  1. Organization
  2. Division
  3. Organization Unit

The structure that you create affects many parts of your Pega application such as the management reports, statistics, and rules that are available to users in that organization.

The organization structure can affect how and where work is routed, and who can access which parts of a system. It can be used to determine which calendars users see, and which queues work is routed to.

It is good practice to get your organization structure set up as soon as possible in the project, and not leave it until the end.

Each user, via the Operator ID record, is associated with one Organization, Division and Organization Unit, and this places the users into the correct part of the organization.

A correct organization structure can help you implement common functionality without requiring custom development. For example:

  • Providing access to certain functionality based on a user’s position within the hierarchy.
  • Restricting access to certain functionality based on the user’s hierarchy position.
  • Routing of work items – which queue should work be placed into, based on the owner of that work, and his or her position in the hierarchy.
  • Reporting and division of data on reports.

Organization structure is configured at Org & Security > Organization. The Lead System Architect, or any of the project’s System Architects will set up the initial organisation structure. Your project may have a user story specifically to create the structure, or you may choose to let it grow from the default as and when required by implementing user stories.

Configuring your organization structure

  1. Create one Organization record for your organization. On the Definition tab:
    1. Add the CFO Operator ID only if this is relevant for your application
    2. Only enter other information if relevant to your application. Generally, the rest is left until later in the project if development requires it.
  2. Create the default Division for your organization. During initial development, you will likely only have one Division, but if you need more than one, set them all up.
    1. Consider whether it makes sense for you to structure your divisions by geography or by function. This will generally reflect your own business structure.
    2. Only add Cost Center and Cost Center Manager if your application requires it.
  3. Create the default Organization Unit for your organization, or create more Units if they are relevant at this time in your project.
    1. Add one or more reporting to Organization Units only if this is relevant in your organization. This has no bearing on default functionality in Pega, so you can leave this empty if you prefer.
    2. Add a Manager if the Unit’s manager is an operator within Pega and expects to have work assigned to him or her.
    3. Add a model user if you choose to have Organization-Structure model users for your single sign-on functionality.
    4. Only fill in the Cost Centre properties if these have meaning in the application you are building.


Although there may not be an immediate need for any of the Organization Structure settings, it is best practice to have a realistic default set at the start of your project. This gives a solid foundation on which to build, and makes it possible to enhance and expand throughout the project.

It is good discipline to use the work-routing features of Pega by leveraging the out-of-the-box features around the Organization Structure. When configuring your workflow and security access, always consider if you can do so by referring to the organisation structure.

Frequently asked questions about your organization structure

Should I model the organization structure to match my real organization, or a subset of it?

At the start of the project, it can be difficult to decide how you want to model the structure. You could model the structure that exactly matches your organization in the real-world, or you could choose to model it in such a way that it makes implementing the security model in Pega simpler. If in doubt, it is a good practice to model the real-world organization, but only the parts that directly affect your project. This could be one branch or one division within a larger organization.

Remember though: the Pega designations of unit, division, or organization do not necessarily coincide with the official organizational chart of the company. Instead, organization rules refer to the work that users perform and the levels of access they have in Pega applications.

What if I need more or less than the three levels?

If your organization is so simple that you don’t need the three levels, model the Organization and use defaults for the levels you don’t need, such as ACME > Default Division > Default Unit, or ACME > Europe > Default Unit.

Although unusual, if you need more than three levels, it is possible to add any number of additional Organization Units as children of Organization Units. For example ACME > EMEA > UK > North > Darlington.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us