Skip to main content

Script API

Warning

As of release 3.21.2, the Groovy scripting engine is disabled by default as a security best practice. This affects Groovy scripts as used through the REST API and scheduled tasks.

This is a powerful scripting API that provides methods to simplify provisioning and executing other complex tasks in the repository manager. These APIs can be invoked from scripts that are published to the repository manager and executed within the application server.

Enabling Scripting

While keeping scripting disabled is a security best practice, you can enable it when necessary.

To temporarily allow adding/editing a script source, take the following steps:

  1. Add the following property to $data-dir/etc/nexus.properties and restart the server.

    nexus.scripts.allowCreation=true

  2. As a user with appropriate privileges, add/edit a script or task. Test the script if desired.

  3. Remove or comment out (add a leading "#" character) the property that allowed script editing.

  4. Restart Sonatype Nexus Repository.

Endpoints

Add Script

POST /service/rest/v1/script

This endpoint allows us to create a utility script within the repository manager.

As an example, let's create a simple script that simply logs "Hello, World!":

curl -u admin:admin123 -X POST --header 'Content-Type: application/json' \
 http://localhost:8081/service/rest/v1/script \
 -d @helloWorld.json

The JSON document we send includes the unique name of the script, the contents of the script itself, and the language type of the script (in this case groovy).

helloWorld.json

{
  "name": "helloWorld",
  "content": "log.info('Hello, World!')",
  "type": "groovy"
}

If you are using Windows and want to use Powershell to add a script you can use the following commands:

$bytes = [System.Text.Encoding]::UTF8.GetBytes("admin:admin123")
$cred = [System.Convert]::ToBase64String($bytes)
$uri = "http://localhost:8081/service/rest/v1/script"
$jsonPath = "c:\test\helloWorld.json" 
Invoke-RestMethod -Uri $uri -Method POST -Headers @{"Authorization"="Basic $cred"} -ContentType "application/json" -InFile $jsonPath

List Scripts

GET /service/rest/v1/script

This endpoint allows us to get a listing of all the scripts currently defined in the repository manager.

curl -u admin:admin123 -X GET http://localhost:8081/service/rest/v1/script

Building on the example from above, we only have the one script that we just created:

Example Response

[ {
  "name" : "helloWorld",
  "content" : "log.info('Hello, World!')",
  "type" : "groovy"
} ]

Get Script

GET /service/rest/v1/script/{name}

This endpoint allows us to get the details for an individual script by its name.

Let's get the details for the helloWorld script that we defined earlier:

curl -u admin:admin123 -X GET http://localhost:8081/service/rest/v1/script/helloWorld

Example Response

{
  "name" : "helloWorld",
  "content" : "log.info('Hello, World!')",
  "type" : "groovy"
}

Update Script

PUT /service/rest/v1/script/{name}

This endpoint allows us to update the contents of an existing script.

Let's update our script to log "Hello, Nexus!" instead of "Hello, World!":

curl -u admin:admin123 -X PUT --header 'Content-Type: application/json' \
 http://localhost:8081/service/rest/v1/script/helloWorld \
 -d @helloNexus.json

helloNexus.json

{
  "name": "helloWorld",
  "content": "log.info('Hello, Nexus!')",
  "type": "groovy"
}

Run Script

POST /service/rest/v1/script/{name}/run

This endpoint allows us to run a script that we have already defined in the repository manager.

Let's run our helloWorld script:

curl -u admin:admin123 -X POST --header 'Content-Type: text/plain' \
 http://localhost:8081/service/rest/v1/script/helloWorld/run

The JSON response tells us which script ran and the returned result from the script:

Example Response

{
  "name" : "helloWorld",
  "result" : "null"
}

We should also see something like the following in the console log:

2018-01-22 16:28:55,495+0000 INFO  [qtp74765809-267] admin org.sonatype.nexus.script.plugin.internal.rest.ScriptResource$$EnhancerByGuice$$99ce415 - Hello, Nexus!

To run a script, a user needs to have the nx-script-${script-name}-run privilege. A user with the nx-script-*-run privilege can run all scripts. Note that they will also need privileges assigned to them which allow them to perform the actions that the script does.

Delete Script

DELETE /service/rest/v1/script/{name}

This enpoint allows us to delete scripts once they are no longer needed.

Let's delete our helloWorld script:

curl -u admin:admin123 -X DELETE http://localhost:8081/service/rest/v1/script/helloWorld

A successfull deletion returns no content:

Example Response

HTTP/1.1 204 No Content
Date: Mon, 22 Jan 2018 22:58:03 GMT
...