Skip to main content
Skip table of contents

Configuration Resource

This page describes resources which allow you to manage the list of projects for which Structure is enabled and the global permissions of the Structure app.

Only logged in Jira administrators can access this resource.

Configuration resource belongs to version 2.0 of the API, its path is /rest/structure/2.0/configuration. It contains the following resources:

/projects GET

Get the list of projects for which Structure is enabled

/projects PUT

Update the list of projects for which Structure is enabled

/projects/add POST

Enable Structure for projects
/projects/remove POSTDisable Structure for projects
/permissions GETGet Structure's global permissions
/permissions PUTUpdate Structure's global permissions
/permissions/{key} GETGet a particular global permission
/permissions/{key} PUTUpdate a particular global permission
/permissions/{key}/add POSTGrant a global permission to user groups or project roles
/permissions/{key}/remove POSTRevoke a global permission from user groups and project roles

Quick navigation:

Project Resources

GET /projects

Returns a JSON object which contains:

  • a flag telling whether Structure is enabled for all projects, and 
  • the list of project IDs for which Structure is enabled.

Please note that even when Structure is enabled for all projects, the list of selected project IDs is still stored in the app configuration and returned by this resource. 

CODE
GET $baseUrl/rest/structure/2.0/configuration/projects

A successful request returns a JSON object with two fields, for example:

CODE
{
  "enabledForAllProjects": false,
  "pickedProjectIds": [10000, 10100]
}

Top

PUT /projects

Updates the "enabled for all projects" flag and/or the list of projects for which Structure is enabled.

CODE
PUT $baseUrl/rest/structure/2.0/configuration/projects

Accepts a JSON object with the following fields, at least one of which must be present:

  • enabledForAllProjects – a boolean indicating whether Structure is enabled for all projects. If omitted, the setting is not changed.
  • pickedProjectIds – an array of numbers with the IDs of the projects for which Structure is enabled. If omitted, the list of projects is not changed.

Please note that when Structure is enabled for all projects, the list of projects has no effect, but it is still stored in the app configuration and can be updated.

Example 1. Enable Structure for only two projects with IDs 10000 and 10100:

JS
PUT $baseUrl/rest/structure/2.0/configuration/projects


{
  "enabledForAllProjects": false,
  "pickedProjectIds": [10000, 10100]
}

Example 2. Enable structure for all projects, don't change the list of projects:

JS
PUT $baseUrl/rest/structure/2.0/configuration/projects


{ "enabledForAllProjects": true }

A successful request returns an "empty" JSON object:

JS
{ "empty": true }

Top

POST /projects/add

Adds one or more projects to the list of projects for which Structure is enabled.

PERL
POST $baseUrl/rest/structure/2.0/configuration/projects/add

Accepts a JSON array of numbers, all of which must be existing project IDs. At least one project ID must be supplied.

Please note that when Structure is enabled for all projects, the list of projects has no effect, but it is still stored in the app configuration and can be updated.

Example. Add project with IDs 10200 and 10300 to the list of projects:

JS
POST $baseUrl/rest/structure/2.0/configuration/projects/add


[10200,10300]

A successful request returns a JSON object with a single boolean flag indicating whether the list of projects was updated (i.e. it did not contain at least one of the passed project IDs before the call):

JS
{ "updated": true }

Top

POST /projects/remove

Removes one or more projects from the list of projects for which Structure is enabled.

PERL
POST $baseUrl/rest/structure/2.0/configuration/projects/remove

Accepts a JSON array of numbers. Non-existent project IDs are allowed. At least one project ID must be supplied.

Please note that when Structure is enabled for all projects, the list of projects has no effect, but it is still stored in the app configuration and can be updated.

Example. Remove project with ID 10200 from the list of projects:

JS
POST $baseUrl/rest/structure/2.0/configuration/projects/remove


[10200]

A successful request returns a JSON object with a single boolean flag indicating whether the list of projects was updated (i.e. it contained at least one of the passed project IDs before the call):

JS
{ "updated": true }

Top

Permission Resources

Permission Keys

The following global permissions are available:

KeyPermission
useUse Structure. See Who Has Access to the Structure.
createStructureCreate new structures. See Changing Permission to Create New Structures.
synchronizationConfigure synchronizers.

automation

Configure automation (generators and effectors). See Changing Permission to Access Automation.

configureGenerators

Configure generators. The "automation" permission is also required.
configureEffectorsConfigure effectors. The "automation" permission is also required. See Changing Permissions to Configure and Run Effectors.
executeEffectorsExecute effectors.
executeEffectorsOnQueriesExecute effectors on query results.

Top

Permission Configuration Objects

The configuration of each global permission is represented by a JSON object with two fields:

FieldTypeDescription
allowedForAnyonebooleanIndicates that a permission is granted to anyone.
subjectsarray of objectsThe list of permission subjects to which the permission is granted.

The flag and the list are stored independently. If a permission is granted to anyone, the list of permission subjects has no effect, but it is still stored in the Structure app configuration and can be updated.

Also, even if a global permission is granted to anyone, there can be other permission-specific restrictions. For example, to configure generators in a structure, a user needs the "Automate" access level to that structure.

Top

Permission Subjects

Global permissions can be granted to user groups and project roles. Each permission subject is represented by a JSON object with the following fields:

FieldTypeDescription
subjectstringThe type of the subject. Must be either "group" or "projectRole". Required.
groupIdstringGroup name. Required for user groups.
roleIdnumberProject role ID. Required for project roles.
projectIdnumberProject ID. Required for project roles. 0 means "any project".

Example 1. The jira-administrators group:

JS
{
  "subject": "group",
  "groupId": "jira-administrators"
}

Example 2. Role with ID 10002 in any project:

JS
{
  "subject": "projectRole",
  "projectId": 0,
  "roleId": 10002
}

Top

GET /permissions

Returns all global permissions as a JSON object.

PERL
GET $baseUrl/rest/structure/2.0/configuration/permissions

In the returned JSON object, keys are permission keys and values are permission configuration objects. Example:

JS
{
  "use": {
    "allowedForAnyone": true,
    "subjects": []
  },
  "createStructure": {
    "allowedForAnyone": false,
    "subjects": [
      {
        "subject": "group",
        "groupId": "jira-software-users"
      }
    ]
  },
  "synchronization": {
    "allowedForAnyone": false,
    "subjects": [
      {
        "subject": "group",
        "groupId": "jira-administrators"
      }
    ]
  },
  "automation": {
    "allowedForAnyone": false,
    "subjects": [
      {
        "subject": "group",
        "groupId": "jira-administrators"
      },
      {
        "subject": "projectRole",
        "projectId": 0,
        "roleId": 10002
      }
    ]
  },
  "configureGenerators": {
    "allowedForAnyone": true,
    "subjects": []
  },
  "configureEffectors": {
    "allowedForAnyone": true,
    "subjects": []
  },
  "executeEffectors": {
    "allowedForAnyone": false,
    "subjects": [
      {
        "subject": "projectRole",
        "projectId": 10000,
        "roleId": 10100
      },
      {
        "subject": "projectRole",
        "projectId": 10100,
        "roleId": 10100
      }
    ]
  },
  "executeEffectorsOnQueries": {
    "allowedForAnyone": false,
    "subjects": [
      {
        "subject": "group",
        "groupId": "jira-administrators"
      },
      {
        "subject": "projectRole",
        "projectId": 0,
        "roleId": 10002
      }
    ]
  }
}

Top

PUT /permissions

Updates one or more global permissions.

PERL
PUT $baseUrl/rest/structure/2.0/configuration/permissions

Accepts a JSON object where keys are permission keys and values are permission configuration objects. Omitted global permissions are not changed. For each permission, either field can be omitted, but at least one field must be supplied.

Example. Allow anyone to use Structure, but allow only the "jira-software-users" group to create new structures:

JS
PUT $baseUrl/rest/structure/2.0/configuration/permissions


{
  "use": {
    "allowedForAnyone": true 
  },
  "createStructure": {
    "allowedForAnyone": false,
    "subjects": [
      {
        "subject": "group",
        "groupId": "jira-software-users"
      }
    ]
  }
}

A successful request returns an "empty" JSON object:

JS
{ "empty": true }

Top

GET /permissions/{key}

Returns a permission configuration object for the given permission key.

PERL
GET $baseUrl/rest/structure/2.0/configuration/permissions/$key

Example. Get the configuration object for the permission to create new structures:

JS
GET $baseUrl/rest/structure/2.0/configuration/permissions/createStructure

{
  "allowedForAnyone": false,
  "subjects": [
   {
      "subject": "group",
      "groupId": "jira-software-users"
    }
  ]
}

Top

PUT /permissions/{key}

Updates the configuration of the given permission key.

PERL
PUT $baseUrl/rest/structure/2.0/configuration/permissions/$key

Accepts a permission configuration object. Either field can be omitted, but at least one field must be supplied.

Example 1. Allow anyone to use Structure:

JS
PUT $baseUrl/rest/structure/2.0/configuration/permissions/use

{
  "allowedForAnyone": true 
}

Example 2. Allow only Jira administrators and project administrators (role ID 10002) in any project to configure automation:

JS
PUT $baseUrl/rest/structure/2.0/configuration/permissions/automation

{
  "allowedForAnyone": false,
  "subjects": [
    {
      "subject": "group",
      "groupId": "jira-administrators"
    },
    {
      "subject": "projectRole",
      "projectId": 0,
      "roleId": 10002
    }
  ]
}

A successful request returns an "empty" JSON object:

JS
{ "empty": true }

Top

POST /permissions/{key}/add

Adds user groups and/or project roles to the list of permission subjects for the given permission key.

PERL
POST $baseUrl/rest/structure/2.0/configuration/permissions/$key/add

Accepts a JSON array of one or more permission subjects. If the permission is granted to anyone, the list of permission subjects has no effect, but it is still stored in the Structure app configuration and can be updated.

Example. Grant project administrators (role ID 10002) in any project the permission to execute effectors on query results:

JS
POST $baseUrl/rest/structure/2.0/configuration/permissions/executeEffectorsOnQueries/add

[
  {
    "subject": "projectRole",
    "projectId": 0,
    "roleId": 10002
  }
]

A successful request returns a JSON object with a single boolean flag indicating whether the list of permission subjects was updated (i.e. it did not contain at least one of the passed subjects before the call):

JS
{ "updated": true }

Top

POST /permissions/{key}/remove

Removes user groups and/or project roles from the list of permission subjects for the given permission key.

PERL
POST $baseUrl/rest/structure/2.0/configuration/permissions/$key/remove

Accepts a JSON array of one or more permission subjects. If the permission is granted to anyone, the list of permission subjects has no effect, but it is still stored in the Structure app configuration and can be updated.

Example. Revoke the global permission to configure synchronizers from Jira Software users:

JS
POST $baseUrl/rest/structure/2.0/configuration/permissions/synchronization/remove

[
  {
    "subject": "group",
    "groupId": "jira-software-users"
  }
]

A successful request returns a JSON object with a single boolean flag indicating whether the list of permission subjects was updated (i.e. it contained at least one of the passed subjects before the call):

JS
{ "updated": true }

Top

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.