| Table of Contents | ||
|---|---|---|
|
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
...
| Code Block |
|---|
{
"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:
...
| Code Block |
|---|
{
"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
}
]
} |
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
...
| Code Block |
|---|
{
"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:
| Code Block |
|---|
{
"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
}
]
} |
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
| Code Block |
|---|
{
"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:
| Code Block |
|---|
{
"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"
}
]
} |
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
| Code Block |
|---|
{
"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:
| Code Block |
|---|
{
"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"
}
]
} |
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
| Code Block |
|---|
{
"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.
...
| Code Block |
|---|
{
"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. } |
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
| Code Block |
|---|
{
"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.
...
| Code Block |
|---|
{
"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'"
} |
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
| Code Block |
|---|
{
"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.
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
| Code Block |
|---|
{
"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
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
| Code Block |
|---|
{
"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.
...
| Code Block |
|---|
{
"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'"
} |
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
| Code Block |
|---|
{
"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.
...
| Code Block |
|---|
{
"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'"
} |
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
| Code Block |
|---|
{
"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.
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
...
| Code Block |
|---|
{
"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
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
...
| Code Block |
|---|
{
"requestType":"removeGlobalOrganizationPolicies",
"globalOrgToken":"global_organization_token",
"userKey": "user_key",
"policyIds":[2,3,4,5]
} |
Response Example
...
| Code Block |
|---|
{
"removedPolicies": 4
} |
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
...
| Code Block |
|---|
{
"requestType":"removeOrganizationPolicies",
"orgToken":"organization_api_key",
"userKey": "user_key"
"policyIds":[2,3,4,5]
} |
Response Example
...
| Code Block |
|---|
{
"removedPolicies": 4
} |
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
...
| Code Block |
|---|
{
"requestType":"removeProductPolicies",
"productToken": "product_token",
"userKey": "user_key"
"policyIds":[6,7]
} |
Response Example
...
| Code Block |
|---|
{
"removedPolicies": 2
} |
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
...
| Code Block |
|---|
{
"requestType":"removeProjectPolicies",
"projectToken":"project_token",
"userKey": "user_key",
"policyIds":[6,7]
} |
Response Example
...
| Code Block |
|---|
{
"removedPolicies": 2
} |
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
| Code Block |
|---|
{
"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:
...
| Code Block |
|---|
{
"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"
}
]
} |
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
| Code Block |
|---|
{
"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.
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
...
| Code Block |
|---|
{
"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.
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
...
| Code Block |
|---|
{
"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.
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:
...
| Code Block |
|---|
"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.
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.
...
| Code Block |
|---|
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.This page is available at: https://docs.mend.io/bundle/api/page/policies_api.html