Policies API

Overview

The Mend HTTP API is available for Mend customers who are licensed to use it. The APIs can be accessed by the organization's administrators.

This resource represents policies. Policies define a set of rules that reflect what actions should be automatically taken when a library meets specific conditions (such as restrictive license types, high-security vulnerabilities, etc.) that are detected in the open-source libraries used by its software. Libraries are matched with the defined policies. A match type defines which criteria of the library should be checked in order to determine if a specific action should be applied to it.

Policies can be applied at the following levels:

Global organization level – All organizations related to the global account
Organizational level – All products under the organization
Product level – All projects under the product
Project level – The specific project

In order to create, edit or delete policies, users must belong to one of the following groups, depending on the policies level:

Global organization policies: Global Admin group
Organizational policies: ORG Admin group
Project and product policies: Product Admin or Admin groups

This topic showcases the API requests and responses for:

Getting all global organization-level, organization-level, product-level, project-level policies
Creating, updating, prioritizing, and removing policies

Get Policies

Get Policies - Global Organization

This API request gets all policies at the global organization level.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns a global organization’s policies.	string	Yes
globalOrgToken	API key which is a unique identifier of the global organization.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes

Request Example

{
    "requestType":"getGlobalOrganizationPolicies",
    "globalOrgToken":"global_organization_token",
    "userKey": "user_key"
}

Response Example

The response is a JSON collection of all policies with their details at the global organization level. For example:

{
    "policies": [
        {
            "id": 7,
            "name": "my policy",
            "owner": {
                "id": user_id,
                "email": "user_email",
                "name": "user_name"
            },
            "creationTime": "2016-11-23",
            "priority": 2,
            "filter": {
                "type": "VULNERABILITY_SEVERITY",
                "vulnerabilitySeverity": {
                    "scoreFrom": 7.0, 
                    "scoreTo": 10.0"
                }
                "effectiveVulnerabilitiesOnly" : true
            },
            "inclusive": false,
            "action": {
                "type": "REJECT"
            },
            "productLevel": false,
            "enabled": false
        }
    ] 
}

Get Policies - Organization

This API request gets all policies at the organization level.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns an organization’s policies.	string	Yes
orgToken	API key which is a unique identifier of the organization.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
aggregatePolicies	Whether to include policies of the global organization to which this organization belongs. false by default.	boolean	No

Request Example

{
    "requestType":"getOrganizationPolicies",
    "orgToken":"organization_api_key",
    "userKey": "user_key"   
}

Response Format

The response is a JSON collection of all policies with their details at the organization level. For example:

{
    "policies": [
        {
            "id": 11738,
            "name": "Reject effective high sev",
            "owner": {
                "id": 31927,
                "email": "user@email.com",
                "name": "user1"
            },
            "creationTime": "2020-07-29",
            "priority": 3,
            "filter": {
                "type": "VULNERABILITY_SEVERITY",
                "vulnerabilitySeverity": {
                    "scoreFrom": 7.0, 
                    "scoreTo": 10.0"
                }
                "scoreFrom": 0.0,
                "scoreTo": 0.0
             }
       ]
}

Get Policies - Product

This API request gets all policies at the product level.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns a product’s policies.	string	Yes
productToken	Unique identifier of the product.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
aggregatePolicies	Whether to include policies of the organization and global organization to which this product belongs. false by default.	boolean	No

Request Example

{
    "requestType":"getProductPolicies",
    "productToken":"product_token",
    "userKey": "user_key"
}

Response Example

The response is a JSON collection of all policies with their details at the product level. For example:

{
    "policies": [
        {
            "id": 10404,
            "name": "T_Policy",
            "owner": {
                "id": 31927,
                "email": "user@email.com",
                "name": "user"
            },
            "creationTime": "2020-06-25",
            "priority": 1,
            "filter": {
                "type": "LIBRARY_STALENESS",
                "monthsBack": 2,
                "scoreFrom": 0.0,
                "scoreTo": 0.0
            },
            "inclusive": false,
            "action": {
                "type": "REJECT"
            },
            "productLevel": false,
            "enabled": true,
            "policyContext": "PRODUCT"
        }
    ]
}

Get Policies - Project

This API request gets all policies at the project level.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns a project’s policies.	string	Yes
projectToken	Unique identifier of the project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
aggregatePolicies	Whether to include policies of the product, organization and global organization to which this project belongs. false by default.	boolean	No

Request Example

{
    "requestType":"getProjectPolicies",
    "projectToken":"project_token",
    "userKey": "user_key"
}

Response Format

The response is a JSON collection of all policies with their details at the project level. For example:

{
    "policies": [
        {
            "id": 13686,
            "name": "High vulnerability",
            "owner": {
                "id": 40909,
                "email": "user@email.com",
                "name": "Michelle"
            },
            "creationTime": "2020-11-19",
            "priority": 2,
            "filter": {
                "type": "VULNERABILITY_SEVERITY",
                "vulnerabilitySeverity": {
                    "scoreFrom": 7.0, 
                    "scoreTo": 10.0"
                }
            },
            "inclusive": false,
            "action": {
                "type": "REJECT"
            },
            "creationTime": "2020-11-19",
            "priority": 1,
            "filter": {
                "type": "LICENSE",
                "licenses": [
                    {
                        "id": 218,
                        "name": "AGPL 1.0"
                    },
                    {
                        "id": 75,
                        "name": "Apache 1.1"
                    }
                ]
           }

Add Policies

Add Policies - Global Organization

This API request adds a policy to your global organization.

Note: To add policies at the global organization level, you must be a member of the Global Admin group.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that adds a policy to a global organization.	string	Yes
globalOrgToken	API key which is a unique identifier of the global organization.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policy	Policy data object containing:	object	Yes
name	Name of the policy you want to add.	string	Yes
owner	Identification of the user that created the policy, containing:	object	Yes
id	The assigned user ID.	integer	Yes
email	The user’s email address.	string	Yes
name	The user’s full name.	string	No
filter	The policy filter defines how to match libraries (for example: By License). Comprises the following: * Match - The match type that defines which criteria of the library will be checked for licenses or security vulnerabilities in the code. * Values - The values against which the match type is evaluated. For example, for match type License Group, the values are the specific licenses against which the library license is matched. For a description of all the available match types and their values, please refer to Matching a Policy to a Library.	string	Yes
action	Type of operation that defines what to do when a library matches the policy’s filter.	object	Yes

Request Example

{
    "requestType":"addGlobalOrganizationPolicy",
    "globalOrgToken":"global_organization_token",
    "userKey": "user_key",
    "policy":{
        "name":"my policy",
        "owner":{
            "id":user_id
        },
        "filter":{
            "type":"LICENSE",
            "licenses":[
                {
                    "name":"Apache 2.0"
                }
            ]
        },
        "inclusive": true,
        "action":{
            "type":"APPROVE"
        }
    }
}

Response Example

The JSON response is the added policy. A unique ID is created for the policy after addition.

{
   "addedPolicy":{
      "id": 9,
      "name": "my policy",
      "owner":{
         "id": user_id,
         "email": "user_email",
         "name": "user_name"
      },
      "creationTime": "2016-12-21",
      "priority": 2,
      "filter":{
         "type": "LICENSE",
         "licenses": [{
            "id": 9,
            "name": "Apache 2.0"
         }]
      },
      "inclusive": true,
      "action": {
            "type": "APPROVE"
        },
      "productLevel": false,
      "enabled": true
   },
   "message": "Successfully added policy 'my policy'"
NOTE: A unique ID will be created for the policy after addition. }

Add Policies - Organization

This API request adds a policy to your organization.

Note: To add policies at the organization level, you must be a member of the ORG Admin group.

QUERY PARAMETERS

Parameter	Description	Type	Required	Default/Values
requestType	API request type that adds a policy to an organization.	string	Yes
orgToken	API key which is a unique identifier of the organization.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policy	Policy data object containing:	object	Yes
name	Name of the policy you want to add.	string	Yes
owner	Identification of the user that created the policy, containing:	object	Yes	Either the id or email property is required.
id	The assigned user ID.	integer	Yes
email	The user’s email address.	string	Yes
name	The user’s full name.	string	No
filter	The policy filter defines how to match libraries (for example: By License). Comprises the following: * Match - The match type that defines which criteria of the library will be checked for licenses or security vulnerabilities in the code. * Values - The values against which the match type is evaluated. For example, for match type License Group, the values are the specific licenses against which the library license is matched. For a description of all the available match types and their values, please refer to Matching a Policy to a Library.	string	Yes	For the LICENSE match type, if the inclusive value is set to true, the policy will perform the action when ALL the licenses in the library are matched. Boolean data type values are true or false.
action	Type of operation that defines what to do when a library matches the policy’s filter.	object	Yes	The “Action” object must contain the field “type”. Valid values for “type” are: * Approve - Automatically approve the library. * Reject - Automatically reject the library. * Reassign - Reassign the request to a designated user or group in the system which is not the default approver. * Conditions - Automatically assign conditions and open tasks on libraries. * Issue - Automatically create a ticket in the issue tracker with all relevant information. When creating an Issue Policy, the “Action” object should contain more fields. For a description of the query parameters required to create a policy of action type Issue, see Create Issue Action for a Policy.

Request Example

{
    "requestType":"addOrganizationPolicy",  
    "orgToken":"organization_api_key",
    "userKey": "user_key",
    "policy":{
        "name":"my policy",
        "owner":{
            "id":user_id
        },
        "filter":{
            "type":"LICENSE",
            "licenses":[
                {
                    "name":"Apache 2.0"
                }
            ]
        },
        "inclusive": true,
        "action":{
            "type":"APPROVE"
        }
    }
}

Response Example

The JSON response is the added policy with a unique ID.

{
   "addedPolicy":{
      "id": 8,
      "name": "my policy",
      "owner":{
         "id": user_id,
         "email": "user_email",
         "name": "user_name"
      },
      "creationTime": "2016-12-21",
      "priority": 1,
      "filter":{
         "type": "LICENSE",
         "licenses": [{
            "id": 9,
            "name": "Apache 2.0"
         }]
      },
      "inclusive": true,
      "action": {"type": "APPROVE"},
      "productLevel": false,
      "enabled": true
   },
   "message": "Successfully added policy 'my policy'"
}

Add Policies - Product

This API request adds a policy to your product.

Note: To add policies at the product level, you must be a member of the Product Admin or Admin group.

QUERY PARAMETERS

Parameter	Description	Type	Required	Default/Values
requestType	API request type that adds a policy to a product.	string	Yes
productToken	Unique identifier of the product.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policy	Policy data object containing:	object	Yes
name	Name of the policy you want to add.	string	Yes
owner	Identification of the user that created the policy, containing:	object	Yes	Either the id or email property is required.
id	The assigned user ID.	integer	Yes
email	The user’s email address.	string	Yes
name	The user’s full name.	string	No
filter	The policy filter defines how to match libraries (for example: By License). Comprises the following: * Match - The match type that defines which criteria of the library will be checked for licenses or security vulnerabilities in the code. * Values - The values against which the match type is evaluated. For example, for match type License Group, the values are the specific licenses against which the library license is matched. For a description of all the available match types and their values, please refer to Matching a Policy to a Library.	string	Yes	For the LICENSE match type, if the inclusive value is set to true, the policy will perform the action when ALL the licenses in the library are matched. Boolean data type values are true or false.
action	Type of operation that defines what to do when a library matches the policy’s filter.	object	Yes	The “Action” object must contain the field “type”. Valid values for “type” are: * Approve - Automatically approve the library. * Reject - Automatically reject the library. * Reassign - Reassign the request to a designated user or group in the system which is not the default approver. * Conditions - Automatically assign conditions and open tasks on libraries. * Issue - Automatically create a ticket in the issue tracker with all relevant information. When creating an Issue Policy, the “Action” object should contain more fields. For a description of the query parameters required to create a policy of action type Issue, see Create Issue Action for a Policy.

Request Example

{
   "requestType": "addProductPolicy",  
   "productToken": "product_token",
   "userKey": "user_key",
   "policy":{
        "name":"my policy",
        "owner":{
            "id":user_id
        },
        "filter":{
            "type":"LICENSE",
            "licenses":[
             {
              "name":"GPL 3"
             }
            ]
        },
        "inclusive": true,        
  "action":{
            "type":"APPROVE"
        }
}

Response Example

The JSON response is the added policy with a unique ID.

Add Policies - Project

This API request adds a policy to your project.

Note: To add policies at the project level, you must be a member of the Admin group.

QUERY PARAMETERS

Parameter	Description	Type	Required	Default/Values
requestType	API request type that adds a policy to a project.	string	Yes
projectToken	Unique identifier of the project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policy	Policy data object containing:	object	Yes
name	Name of the policy you want to add.	string	Yes
owner	Identification of the user that created the policy, containing:	object	Yes	Either the id or email property is required.
id	The assigned user ID.	integer	Yes
email	The user’s email address.	string	Yes
name	The user’s full name.	string	No
filter	The policy filter defines how to match libraries (for example: By License). Comprises the following: * Match - The match type that defines which criteria of the library will be checked for licenses or security vulnerabilities in the code. * Values - The values against which the match type is evaluated. For example, for match type License Group, the values are the specific licenses against which the library license is matched. For a description of all the available match types and their values, please refer to Matching a Policy to a Library.	string	Yes	For the LICENSE match type, if the inclusive value is set to true, the policy will perform the action when ALL the licenses in the library are matched. Boolean data type values are true or false.
action	Type of operation that defines what to do when a library matches the policy’s filter.	object	Yes	The “Action” object must contain the field “type”. Valid values for “type” are: * Approve - Automatically approve the library. * Reject - Automatically reject the library. * Reassign - Reassign the request to a designated user or group in the system which is not the default approver. * Conditions - Automatically assign conditions and open tasks on libraries. * Issue - Automatically create a ticket in the issue tracker with all relevant information. When creating an Issue Policy, the “Action” object should contain more fields. For a description of the query parameters required to create a policy of action type Issue, see Create Issue Action for a Policy.

Request Example

{
    "requestType":"addProjectPolicy",
    "projectToken":"project_token",
    "userKey": "user_key",
    "policy":{
        "name":"my policy",
        "owner":{
            "id":user_id
        },
        "filter":{
            "type":"LICENSE",
            "licenses":[
                {
                    "name":"GPL 3"
                }
            ]
        },
        "inclusive": true,
        "action":{
            "type":"APPROVE"
        }
    }
}

Response Example

The JSON response is the added policy with a unique ID.

Update Policy

Update Policy - Global Organization

This API request updates a policy in your global organization.

Note: To update policies at the global organization level, you must be a member of the Global Admin group.

QUERY PARAMETERS

Following are the query parameters that define the API request to update a policy in a global organization. Note that apart from the unique ID of the policy which is mandatory, you only need to specify the fields and values that you want to update.

Parameter	Description	Type	Required	Default/Values
requestType	API request type that updates a policy in a global organization.	string	Yes
globalOrgToken	API key which is a unique identifier of the global organization. Used to identify the global organization in plugins.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policy	Policy data object containing:	object	Yes
id	Unique ID of the policy.	integer	Yes
name	Name of the policy you want to update.	string	Yes
owner	Identification of the user that created the policy, containing:	object	Yes	Either the id or email property is required.
id	The assigned user ID.	integer	Yes
email	The user’s email address.	string	Yes
name	The user’s full name.	string	No
filter	The policy filter defines how to match libraries (for example: By License). Comprises the following: * Match - The match type that defines which criteria of the library will be checked for licenses or security vulnerabilities in the code. * Values - The values against which the match type is evaluated. For example, for match type License Group, the values are the specific licenses against which the library license is matched. For a description of all the available match types and their values, please refer to Matching a Policy to a Library.	string	No	For the LICENSE match type, if the inclusive value is set to true, the policy will perform the action when ALL the licenses in the library are matched. Boolean data type values are true or false.
action	Type of operation that defines what to do when a library matches the policy’s filter.	object	No	The “Action” object must contain the field “type”. Valid values for “type” are: * Approve - Automatically approve the library. * Reject - Automatically reject the library. * Reassign - Reassign the request to a designated user or group in the system which is not the default approver. * Conditions - Automatically assign conditions and open tasks on libraries. * Issue - Automatically create a ticket in the issue tracker with all relevant information. When creating an Issue Policy, the “Action” object should contain more fields. For a description of the query parameters required to create a policy of action type Issue, see Create Issue Action for a Policy.

Request Example

{
    "requestType":"updateGlobalOrganizationPolicy",
    "globalOrgToken":"global_organization_token",
    "userKey": "user_key",
    "policy":{
        "id":1
        "name":"my policy",
        "owner":{
            "id":user_id
        },
        "filter":{
            "type":"LICENSE",
            "licenses":[
                {
                    "name":"GPL 3.0"
                }]
        },
        "inclusive": true,
        "action":{
            "type":"REJECT"
        }
    }
}

Response Example

The JSON response is the updated policy. Note that a new policy ID is assigned.

{
   "updatedPolicy": {
      "id": 8,
      "name": "my policy",
      "owner": {
         "id": user_id,
         "email": "user_email",
         "name": "user_name"
      },
      "creationTime": "2016-12-21",
      "priority": 1,
      "filter":       {
         "type": "LICENSE",
         "licenses": [         {
            "id": 1,
            "name": "GPL 3.0"
         }]
      },
      "inclusive": true,
      "action": {
            "type": "REJECT"
        },
      "productLevel": false,
      "enabled": true
   },
   "message": "Successfully updated policy 'my policy'"
}

Update Policy - Organization

This API request updates a policy in your organization.

Note: To update policies at the organization level, you must be a member of the ORG Admin group.

QUERY PARAMETERS

Following are the query parameters that define the API request to update a policy in an organization. Note that apart from the unique ID of the policy which is mandatory, you only need to specify the parameters and values that you want to update.

Parameter	Description	Type	Required	Default/Values
requestType	API request type that updates a policy in an organization.	string	Yes
orgToken	API key which is a unique identifier of the organization. Used to identify the organization in plugins.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policy	Policy data object containing:	object
id	Unique ID of the policy.	integer	Yes
name	Name of the policy you want to update.	string	Yes
owner	Identification of the user that created the policy, containing:	object	Yes	Either the id or email property is required.
id	The assigned user ID.	integer	Yes
email	The user’s email address.	string	Yes
name	The user’s full name.	string	No
filter	The policy filter defines how to match libraries (for example: By License). Comprises the following: * Match - The match type that defines which criteria of the library will be checked for licenses or security vulnerabilities in the code. * Values - The values against which the match type is evaluated. For example, for match type License Group, the values are the specific licenses against which the library license is matched. For a description of all the available match types and their values, please refer to Matching a Policy to a Library.	string	No	For the LICENSE match type, if the inclusive value is set to true, the policy will perform the action when ALL the licenses in the library are matched. Boolean data type values are true or false.
action	Type of operation that defines what to do when a library matches the policy’s filter.	object	No	The “Action” object must contain the field “type”. Valid values for “type” are: * Approve - Automatically approve the library. * Reject - Automatically reject the library. * Reassign - Reassign the request to a designated user or group in the system which is not the default approver. * Conditions - Automatically assign conditions and open tasks on libraries. * Issue - Automatically create a ticket in the issue tracker with all relevant information. When creating an Issue Policy, the “Action” object should contain more fields. For a description of the query parameters required to create a policy of action type Issue, see Create Issue Action for a Policy.

Request Example

{
    "requestType":"updateOrganizationPolicy",
    "orgToken":"organization_api_key",
    "userKey": "user_key",
    "policy":{
        "id":1
        "name":"my policy",
        "owner":{
            "id":user_id
        },
        "filter":{
            "type":"LICENSE",
            "licenses":[
                {
                    "name":"GPL 3.0"
                }]
        },
        "inclusive": true,
        "action":{
            "type":"REJECT"
        }
    }
}

Response Example

The JSON response is the updated policy. Note that a new policy ID is assigned.

{
   "updatedPolicy":    {
      "id": 8,
      "name": "my policy",
      "owner":       {
         "id": user_id,
         "email": "user_email",
         "name": "user_name"
      },
      "creationTime": "2016-12-21",
      "priority": 1,
      "filter":       {
         "type": "LICENSE",
         "licenses": [         {
            "id": 1,
            "name": "GPL 3.0"
         }]
      },
      "inclusive": true,
      "action": {"type": "REJECT"},
      "productLevel": false,
      "enabled": true
   },
   "message": "Successfully updated policy 'my policy'"
}

Update Policy - Product

This API request updates a policy in your product.

Note: To update policies at the product level, you must be a member of the Product Admin or Admin group.

QUERY PARAMETERS

Following are the query parameters that define the API request to update a policy in a product. Note that apart from the unique ID of the policy which is mandatory, you only need to specify the parameters and values that you want to update.

Parameter	Description	Type	Required	Default/Values
requestType	API request type that updates a policy in a product.	string	Yes
productToken	Unique identifier of the product.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policy	Policy data object containing:	object	Yes
id	Unique ID of the policy.	integer	Yes
name	Name of the policy you want to update.	string	Yes
owner	Identification of the user that created the policy, containing:	object	Yes	Either the id or email property is required.
id	The assigned user ID.	integer	Yes
email	The user’s email address.	string	Yes
name	The user’s full name.	string	No
filter	The policy filter defines how to match libraries (for example: By License). Comprises the following: * Match - The match type that defines which criteria of the library will be checked for licenses or security vulnerabilities in the code. * Values - The values against which the match type is evaluated. For example, for match type License Group, the values are the specific licenses against which the library license is matched. For a description of all the available match types and their values, please refer to Matching a Policy to a Library.	string	No	For the LICENSE match type, if the inclusive value is set to true, the policy will perform the action when ALL the licenses in the library are matched. Boolean data type values are true or false.
action	Type of operation that defines what to do when a library matches the policy’s filter.	object	No	The “Action” object must contain the field “type”. Valid values for “type” are: * Approve - Automatically approve the library. * Reject - Automatically reject the library. * Reassign - Reassign the request to a designated user or group in the system which is not the default approver. * Conditions - Automatically assign conditions and open tasks on libraries. * Issue - Automatically create a ticket in the issue tracker with all relevant information. When creating an Issue Policy, the “Action” object should contain more fields. For a description of the query parameters required to create a policy of action type Issue, see Create Issue Action for a Policy.

Request Example

{
    "requestType":"updateProductPolicy",
    "productToken": "product_token",
    "userKey": "user_key",
    "policy":{
        "name":"my policy",
        "owner":{
            "id":user_id
        },
        "filter":{
            "type":"LICENSE",
            "licenses":[
                {
                    "name":"GPL 3.0"
                }]
        },
        "inclusive": true,
        "action":{
            "type":"REJECT"
        }
    }
}

Response Example

The JSON response is the updated policy with a new policy ID.

Update Policy - Project

This API request updates a policy in your project.

Note: To update policies at the project level, you must be a member of the Admin group.

QUERY PARAMETERS

Following are the query parameters that define the API request to update a policy in a project. Note that apart from the unique ID of the policy which is mandatory, you only need to specify the parameters and values that you want to update.

Parameter	Description	Type	Required	Default/Values
requestType	API request type that updates a policy in a project.	string	Yes
projectToken	Unique identifier of the project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policy	Policy data object containing:	object	Yes
id	Unique ID of the policy.	integer	Yes
name	Name of the policy you want to update.	string	Yes
owner	Identification of the user that created the policy, containing:	object	Yes	Either the id or email property is required.
id	The assigned user ID.	integer	Yes
email	The user’s email address.	string	Yes
name	The user’s full name.	string	No
filter	The policy filter defines how to match libraries (for example: By License). Comprises the following: * Match - The match type that defines which criteria of the library will be checked for licenses or security vulnerabilities in the code. * Values - The values against which the match type is evaluated. For example, for match type License Group, the values are the specific licenses against which the library license is matched. For a description of all the available match types and their values, please refer to Matching a Policy to a Library.	string	No	For the LICENSE match type, if the inclusive value is set to true, the policy will perform the action when ALL the licenses in the library are matched. Boolean data type values are true or false.
action	Type of operation that defines what to do when a library matches the policy’s filter.	object	No	The “Action” object must contain the field “type”. Valid values for “type” are: * Approve - Automatically approve the library. * Reject - Automatically reject the library. * Reassign - Reassign the request to a designated user or group in the system which is not the default approver. * Conditions - Automatically assign conditions and open tasks on libraries. * Issue - Automatically create a ticket in the issue tracker with all relevant information. When creating an Issue Policy, the “Action” object should contain more fields. For a description of the query parameters required to create a policy of action type Issue, see Create Issue Action for a Policy.

Request Example

{
    "requestType":"updateProjectPolicy",
    "projectToken":"project_token",
    "userKey": "user_key",
    "policy":{
        "name":"my policy",
        "owner":{
            "id":user_id
        },
        "filter":{
            "type":"LICENSE",
            "licenses":[
                {
                    "name":"GPL 3.0"
                }]
        },
        "inclusive": true,
        "action":{
            "type":"REJECT"
        }
    }
}

Response Format

The JSON response is the updated policy with a new policy ID.

Remove Policies

Remove Policies - Global Organization

This API request removes specific policies from your global organization.

Note: To remove policies at the global organization level, you must be a member of the Global Admin group.

QUERY PARAMETERS

Following are the mandatory query parameters that define the API request to remove policies from a global organization according to their specific IDs.

Parameter	Description	Type	Required
requestType	API request type that removes policies from a global organization.	string	Yes
globalOrgToken	API key which is a unique identifier of the global organization.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policyIds	IDs of the policies that you want to remove.	array of integers	Yes

Request Example

{
    "requestType":"removeGlobalOrganizationPolicies",
    "globalOrgToken":"global_organization_token",
    "userKey": "user_key",
    "policyIds":[2,3,4,5]
}

Response Example

{
    "removedPolicies": 4
}

Remove Policies - Organization

This API request removes specific policies from your organization.

Note: To remove policies at the organization level, you must be a member of the ORG Admin group.

QUERY PARAMETERS

Following are the mandatory query parameters that define the API request to remove policies from an organization according to their specific IDs.

Parameter	Description	Type	Required
requestType	API request type that removes policies from an organization.	string	Yes
orgToken	API key which is a unique identifier of the organization.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policyIds	IDs of the policies that you want to remove.	array of integers	Yes

Request Example

{
    "requestType":"removeOrganizationPolicies",
    "orgToken":"organization_api_key",
    "userKey": "user_key",
    "policyIds":[2,3,4,5]
}

Response Example

{
    "removedPolicies": 4
}

Remove Policies - Product

This API request removes specific policies from your product.

Note: To remove policies at the product level, you must be a member of the Product Admin or Admin group.

QUERY PARAMETERS

Following are the mandatory query parameters that define the API request to remove policies from a product according to their specific IDs.

Parameter	Description	Type	Required
requestType	API request type that removes policies from a product.	string	Yes
productToken	Unique identifier of the product.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policyIds	IDs of the policies that you want to remove.	array of integers	Yes

Request Example

{
    "requestType":"removeProductPolicies",
    "productToken": "product_token",
    "userKey": "user_key",
    "policyIds":[6,7]
}

Response Example

{
    "removedPolicies": 2
}

Remove Policies - Project

This API request removes specific policies from your project.

Note: To remove policies at the project level, you must be a member of the Admin group.

QUERY PARAMETERS

Following are the mandatory query parameters that define the API request to remove policies from a project according to their specific IDs.

Parameter	Description	Type	Required
requestType	API request type that removes policies from a project.	string	Yes
projectToken	Unique identifier of the project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policyIds	IDs of the policies that you want to remove.	array of integers	Yes

Request Example

{
    "requestType":"removeProjectPolicies",
    "projectToken":"project_token",
    "userKey": "user_key",
    "policyIds":[6,7]
}

Response Example

{
    "removedPolicies": 2
}

Update Policy Priorities

Update Policy Priorities - Global Organization

This API request updates the priorities of policies in your global organization. Policies are checked by order of priority; note that 1 is the lowest priority.

Note: To update the priority of policies at the global organization level, you must be a member of the Global Admin group.

QUERY PARAMETERS

Following are the mandatory query parameters that define the API request to change the priority of policies in a global organization.

Parameter	Description	Type	Required
requestType	API request type to reorder the priorities of policies in a global organization.	string	Yes
globalOrgToken	API key which is a unique identifier of the global organization.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policyPriorities	Policy prioritization data object containing:	array	Yes
policyId	ID of the policy that you want to reprioritize.	integer	Yes
priority	An integer that defines the priority that you want to assign the policy.	integer	Yes

Request Example

{
    "requestType":"reorderGlobalOrganizationPolicyPriorities",
    "globalOrgToken":"global_organization_token",
    "userKey": "user_key",
    "policyPriorities":[
        {
            "policyId":3053,
            "priority":1
        },
        {
            "policyId":3052,
            "priority":2
        }]
}

Response Example

The response is a JSON collection of all global organization-level policies with the updated priorities. For example:

{
   "policies":[
      {
         "id":3052,
         "name":"my policy",
         "owner":{
            "id":user_id,
            "email":"user_email",
            "name":"user_name"
         },
         "creationTime":"2018-01-16",
         "priority":2,
         "filter":{
            "type":"LICENSE",
            "licenses":[
               {
                  "id":9,
                  "name":"Apache 2.0"
               }],
            "scoreFrom":0,
            "scoreTo":0
         },
         "inclusive":true,
         "action":{
            "type":"APPROVE"
         },
         "productLevel":false,
         "enabled":true,
         "policyContext":"GLOBAL_ACCOUNT"
      },
      {
         "id":3053,
         "name":"policy2",
         "owner":{
            "id":2458,
            "email":"user_email",
            "name":"user_name"
         },
         "creationTime":"2018-01-16",
         "priority":1,
         "filter":{
            "type":"LICENSE",
            "licenses":[
               {
                  "id":9,
                  "name":"Apache 2.0"
               }],
            "scoreFrom":0,
            "scoreTo":0
         },
         "inclusive":true,
         "action":{
            "type":"REJECT"
         },
         "productLevel":false,
         "enabled":true,
         "policyContext":"GLOBAL_ACCOUNT"
      }
   ]
}

Update Policy Priorities - Organization

This API request updates the priorities of policies in your organization. Policies are checked by order of priority; note that 1 is the lowest priority.

NOTE: To update the priority of policies at the organization level, you must be a member of the ORG Admin group.

QUERY PARAMETERS

Following are the mandatory query parameters that define the API request to change the priority of policies in an organization.

Parameter		Description	Type	Required
requestType		API request type to reorder the priorities of policies in an organization.	string	Yes
orgToken		API key which is a unique identifier of the organization.	string	Yes
userKey		The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policyPriorities		Policy prioritization data object containing:	array	Yes
	policyId	ID of the policy that you want to reprioritize.	integer	Yes
	priority	An integer that defines the priority that you want to assign the policy.	integer	Yes

Request Example

{
    "requestType":"reorderOrganizationPolicyPriorities",
    "orgToken":"organization_api_key",
    "userKey": "user_key",
    "policyPriorities":[
        {
            "policyId":7,
            "priority":1
        },
        {
            "policyId":8,
            "priority":2
        }
    ]
}

Response

The response is a JSON collection of all organization-level policies with the updated priorities.

Update Policy Priorities - Product

This API request updates the priorities of policies in your product. Policies are checked by order of priority; note that 1 is the lowest priority.

Note: To update the priority of policies at the product level, you must be a member of the Product Admin or Admin group.

QUERY PARAMETERS

Following are the mandatory query parameters that define the API request to change the priority of policies in a product.

Parameter	Description	Type	Required
requestType	API request type to reorder the priorities of policies in a product.	string	Yes
productToken	Unique identifier of the product.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policyPriorities	Policy prioritization data object containing:	array	Yes
policyId	ID of the policy that you want to reprioritize.	integer	Yes
priority	An integer that defines the priority that you want to assign the policy.	integer	Yes

Request Example

{
    "requestType":"reorderProductPolicyPriorities",
    "productToken": "product_token",
    "userKey": "user_key",
    "policyPriorities":[
        {
            "policyId":10,
            "priority":1
        },
        {
            "policyId":11,
            "priority":2
        }
    ]
}

Response

The response is a JSON collection of all product-level policies with the updated priorities.

Update Policy Priorities - Project

This API request updates the priorities of policies in your project. Policies are checked by order of priority; note that 1 is the lowest priority.

Note: To update the priority of policies at the project level, you must be a member of the Admin group.

QUERY PARAMETERS

Following are the mandatory query parameters that define the API request to change the priority of policies in a project.

Parameter	Description	Type	Required
requestType	API request type to reorder the priorities of policies in a project.	string	Yes
projectToken	Unique identifier of the project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
policyPriorities	Policy prioritization data object containing:	array	Yes
policyId	ID of the policy that you want to reprioritize.	integer	Yes
priority	An integer that defines the priority that you want to assign the policy.	integer	Yes

Request Example

{
    "requestType":"reorderProjectPolicyPriorities",
    "projectToken":"project_token",
    "userKey": "user_key",
    "policyPriorities":[
        {
            "policyId":10,
            "priority":1
        },
        {
            "policyId":11,
            "priority":2
        }
    ]
}

Response

The response is a JSON collection of all project-level policies with the updated priorities.

Change Policy Owner

This API finds all the policies in the organization that was created by the user with the email specified in "currentPolicyOwnerEmail", and reassigns them to the user with the email specified in "newPolicyOwnerEmail".

Note: To reassign the policy owner across your organization , you must be a member of the Organization Administrator group.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that changes the policy owner for all policies in an organization.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in mend.	string	Yes
orgToken	API token key which uniquely identifies the organization.	string	Yes
currentPolicyOwnerEmail	Email address of current policy owner.	string	Yes
newPolicyOwnerEmail	Email address of new policy owner for the organization.	string	Yes

Request Example

{
  "requestType":"changeOrganizationPolicyOwner",
  "userKey": "user_key", 
  "orgToken":"org_token",
  "currentPolicyOwnerEmail":"Owner.email@mendsoftware.com",
  "newPolicyOwnerEmail" : "newOwner.email@mendsoftware.com"
}

Response

{
    "message": "Successfully changed policy owners in the organization"
}

Create Issue Action for a Policy (Legacy)

This API creates a policy action of type Issue which works with the native Jira or Work Items integration.

Note: This is a Legacy integration that will be deprecated in the near future.

Mend policies can integrate with Issue Tracking Systems (such as Jira or Work Items), enabling the automatic creation of tickets for tracking issues externally to mend. When an Issue policy is created, an issue is automatically created in the Issue tracker with all related information.

Note: To create an Issue request, you must have admin permissions in the scope in which you create the policy.

QUERY PARAMETERS

Following are the query parameters that are required for defining an action of type “CREATE_ISSUE” when adding or updating a policy:

Parameter	Description	Type	Required	Default/Values
action	Data object for the Action API request.	object	Yes
type	The type of policy action that defines what to do when a library matches the policy's filter: i.e., CREATE_ISSUE	string	Yes
issueSettings	Data object containing all information regarding the created Issue action type:	object	Yes
summary	Summary that will be written when the issue is created.	string	Yes
description	Description that will be written when the issue is created.	string	Yes
issueTrackerType	Type of Issue Tracker used for the issue.	string	Yes	JIRA or WORK_ITEMS
issueAssignee	Display name of the user to which you want to assign the issue, as displayed in the Issue Tracker Settings.	string	Yes	For a JIRA project, the value of this field is case sensitive.
issueProject	The project key or name assigned to the issue.	string	Yes	JIRA project: The project key for the JIRA Issue (case sensitive). WORK_ITEMS project: The project name.
issueType	The type of issue as it appears in the Name field.	string	Yes	For a JIRA project, the value of this field is case sensitive. Can be one of the following: * Bug * Improvement * Task * New feature * Epic * Story For a WORK_ITEMS project, the value of this field can be one of the following: * Bug * Code Review Request * Test Case * Shared Steps * Epic * Task * Feature * Code Review Response * Feedback Request * Feedback Response * Test Plan * User Story * Shared Parameter * Test Suite * Issue
issuePriorityInfo	The priority that is assigned to the issue.	string	Yes	Can have one of the following values: * Highest * High * Medium * Low * Lowest NOTE: For a JIRA project, the value of this field is case sensitive.
requiredFieldsInfo	Mandatory fields that are required in the Issue type of the project.	string	Yes	Supported fields are: * Reporter * Labels * Components * Parent

Request Example

Following is an example of the “action” object which is part of the “add policy” requests, for creating a CREATE ISSUE policy in the Legacy Issue Tracker integration:

"action":{
    "type": "CREATE_ISSUE",
    "issueSettings": {
        "summary": "test summary",
        "description": "test description",
        "issueTrackerType": "JIRA",
        "issueAssignee": {
            "displayName": "Lewis Grove"
        },
        "issueProject": {
            "key": "Proj"
        },
        "issueType": {
            "name": "Bug"
        },
        "issuePriorityInfo": {
            "name": "High"
        },
        "requiredFieldsInfo": {
            "Parent": {
                "value": "TEST-123"
            },
            "Reporter": {
                "value": "Name Here"
            },
            "Components": {
                "value": "My Component"
            },
            "Labels": {
                "value": "My Label"
            },
            "My Custom Field": {
                "value": "Component values"
            }
        }
    }
}

Create Issue Action for a Policy (Issue Tracker Plugins)

This API creates a policy action of type Issue which works with the new Issue Tracker Plugins set.

Note: In the near future, this will replace the Legacy Jira/Work Items native integration.

Mend policies can integrate with Issue Tracking Systems (such as Jira, Work Items, or Jira Plugin), enabling the automatic creation of tickets for tracking issues externally to mend. When an Issue policy is created, an issue is automatically created in the Issue tracker with all related information.

Note: To create an Issue request, you must have admin permissions in the scope in which you create the policy.

QUERY PARAMETERS

Following are the query parameters that are required for defining an action of type “CREATE_ISSUE” when adding or updating a policy:

Parameter	Description	Type	Required	Default/Values
action	Data object for the Action API request.	object	Yes
type	The type of policy action that defines what to do when a library matches the policy's filter: i.e., CREATE_ISSUE	string	Yes
issueSettings	Data object containing all information regarding the created Issue action type:	object	Yes
summary	Summary that will be written when the issue is created.	string	Yes
description	Description that will be written when the issue is created.	string	Yes
issueTrackerType	Type of Issue Tracker used for the issue - i.e., Jira Plugin	string	Yes	JIRA, WORK_ITEMS, or Jira Plugin.

Request Example

Following is an example of the “action” object which is part of the “add policy” requests, for creating a CREATE ISSUE policy in the Jira Plugin Issue Tracker integration.

action":{
    "type": "CREATE_ISSUE",
    "issueSettings": {
        "summary": "This field is meaningless and is only supported for backward compatibility",
        "description": "This field is meaningless and is only supported for backward compatibility",
        "issueTrackerType": "COMMON_ISSUE_TRACKER"
    }
}