Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 50 Next »

Overview

The WhiteSource HTTP API is available for WhiteSource 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

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 WhiteSource.

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": "HIGH",
                "effectiveVulnerabilitiesOnly" : true
            },
            "inclusive": false,
            "action": {
                "type": "REJECT"
            },
            "productLevel": false,
            "enabled": false
        }
    ] 
}

Back to top.

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 WhiteSource.

string

Yes

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": "HIGH",
                "scoreFrom": 0.0,
                "scoreTo": 0.0
             }
       ]
}

Back to top.

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

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

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"
        }
    ]
}

Back to top.

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

API key which is a unique identifier of the project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

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": "HIGH",
                "scoreFrom": 0.0,
                "scoreTo": 0.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"
                    }
                ]
           }

Back to top.

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

Default/Values

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 WhiteSource.

string

Yes

policy

Policy data object containing:

string

Yes

name

Name of the policy you want to add.

string

Yes

owner

Identification of the user that created the policy.

integer

Yes

Valid values: user ID, name, or email.

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.

string

Yes

Valid values 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.  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":"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. }

Back to top.

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 WhiteSource.

string

Yes

policy

Policy data object containing:

string

Yes

name

Name of the policy you want to add.

string

Yes

owner

Identification of the user that created the policy.

integer

Yes

Valid values: user ID, name, or email.

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.

string

Yes

Valid values 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. 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'"
}

Back to top.

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

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

policy

Policy data object containing:

string

Yes

name

Name of the policy you want to add.

integer

Yes

owner

Identification of the user that created the policy.

string

Yes

Valid values: user ID, name, or email.

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.

string

Yes

Valid values 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. 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.

Back to top.

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

API key which is a unique identifier of the project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

policy

Policy data object containing:

string

Yes

name

Name of the policy you want to add.

string

Yes

owner

Identification of the user that created the policy.

integer

Yes

Valid values: user ID, name, or email.

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.

string

Yes

Valid values 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. 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.

Back to top.

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 WhiteSource.

string

Yes

policy

Policy data object containing:

string

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.

integer

Yes

Valid values: user ID, name, or email.

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.

string

No

Valid values 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. 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'"
}

Back to top.

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 WhiteSource.

string

Yes

policy

Policy data object containing:

string

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.

integer

Yes

Valid values: user ID, name, or email.

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.

string

No

Valid values 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. 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'"
}

Back to top.

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

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

policy

Policy data object containing:

string

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.

integer

Yes

Valid values: user ID, name, or email.

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.

string

No

Valid values 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. 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.

Back to top.

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

API key which is a unique identifier of the project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

policy

Policy data object containing:

string

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.

integer

Yes

Valid values: user ID, name, or email.

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.

string

No

Valid values 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. For a description of the query parameters required to create a policy of 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.

Back to top.

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 WhiteSource.

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
}

Back to top.

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 WhiteSource.

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
}

Back to top.

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

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

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
}

Back to top.

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

API key which is a unique identifier of the project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

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
}

Back to top.

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 WhiteSource.

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"
      }
   ]
}

Back to top.

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 WhiteSource.

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.

Back to top.

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

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

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.

Back to top.

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

API key which is a unique identifier of the project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

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.

Back to top.

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.

WhiteSource policies can integrate with Issue Tracking Systems (such as Jira or Work Items), enabling the automatic creation of tickets for tracking issues externally to WhiteSource. 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.

string

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:

string

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"
            }
        }
    }
}

Back to top.

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.

WhiteSource 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 WhiteSource. 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.

string

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:

string

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"
    }
}

Back to top.

  • No labels

Copyright © 2024 Mend.io (White Source Ltd.) | All rights reserved.