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 POST`	Disable Structure for projects
`/permissions GET`	Get Structure's global permissions
`/permissions PUT`	Update Structure's global permissions
`/permissions/{key} GET`	Get a particular global permission
`/permissions/{key} PUT`	Update a particular global permission
`/permissions/{key}/add POST`	Grant a global permission to user groups or project roles
`/permissions/{key}/remove POST`	Revoke 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:

Key	Permission
`use`	Use Structure. See Who Has Access to the Structure.
`createStructure`	Create new structures. See Changing Permission to Create New Structures.
`synchronization`	Configure synchronizers.
`automation`	Configure automation (generators and effectors). See Changing Permission to Access Automation.
`configureGenerators`	Configure generators. The "automation" permission is also required.
`configureEffectors`	Configure effectors. The "automation" permission is also required. See Changing Permissions to Configure and Run Effectors.
`executeEffectors`	Execute effectors.
`executeEffectorsOnQueries`	Execute effectors on query results.

Top

Permission Configuration Objects

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

Field	Type	Description
`allowedForAnyone`	boolean	Indicates that a permission is granted to anyone.
`subjects`	array of objects	The 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:

Field	Type	Description
`subject`	string	The type of the subject. Must be either `"group"` or `"projectRole"`. Required.
`groupId`	string	Group name. Required for user groups.
`roleId`	number	Project role ID. Required for project roles.
`projectId`	number	Project 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